UniMate API Reference for C Language

UniMate Mobile Certificate API Reference

Relative Convention

Return Value

All return values from functions are of type unsigned long.

0 refers to success, whereas a value < 0 indicates an error.

Public Key Format

PUB_KEY is compatible with the RFC 3447 specification.

RSAPublicKey ::= SEQUENCE {
    modulus 		INTEGER -- n
    publicExponent 	INTEGER -- e
}

as defined by the struct:

typedef unsigned char CK_BYTE, *CK_BYTE_PTR;

#define TLV_L_MAX     256;

typedef struct _TLV {
    CK_BYTE t;
    CK_BYTE l;
    CK_BYTE v[TLV_L_MAX];
} TLV, *TLV_PTR;

typedef struct _pub_key {
    TLV n; // Modulus.
    TLV e; // Public exponent.
} PUB_KEY, *PUB_KEY_PTR;

Ease of Use Convention

As the speed of reading a certificate is slow, an initiation mechanism shall be established, that is after the content of a public key is read for the first time when inserting a key, the public key and the information regarding the corresponding private key; such as container name, container ID, etc, shall be stored together in a configuration file (this configuration file will be created automatically: such as "company name.config") to ensure that when next run, the public key and private key-pair can be established just by reading the private ID in the key. Improving the speed at which a certificate is read, and allowing the private key to be found quicker when signing or decrypting a digital envelope.

Relative Development

1. Functions, variables, et al. shall comply with the C standard.
2. Interfaces with binary returns, such as SignData, shall be called twice, that is, first get the length of data, externally apply for memory, and then on the second call return the requested data.
3. All passed char * type parameters shall be ended with ‘\0’ (null character), and the length can be calculated directly.

Type Definition

typedef unsigned long  DHANDLE,  *DHANDLE_PTR;
typedef unsigned char  CK_BYTE,  *CK_BYTE_PTR;
typedef unsigned short CK_FID;
typedef unsigned long  CK_ULONG, *CK_ULONG_PTR;
typedef CK_ULONG       CK_RV;
typedef CK_ULONG       CK_ALG;
typedef short          CK_SHORT, *CK_SHORT_PTR;

Interface Definition

Here are the C function headers as defined in the UniMate.h file in the UniMate STD SDK Windows Device Samples. For the function descriptions below, these headers, the Android header file can be used as a guide.

CK_RV s2u(CK_SHORT sc_error);
CK_RV UT_Initialize();
CK_RV UT_Finalize();
CK_RV UT_Find(DHANDLE handle[MAX_DEVICE_COUNT], CK_ULONG_PTR count);
CK_RV UT_GetID(DHANDLE handle,  CK_BYTE_PTR id);
CK_RV UT_GetSN(DHANDLE handle,  CK_ULONG sn[2]);
CK_RV UT_GetCOSVersion(DHANDLE handle, CK_ULONG_PTR version);
CK_RV UT_GetSpace(DHANDLE handle, CK_ULONG_PTR space);
CK_RV UT_OpenFID(DHANDLE handle, CK_FID fid);
CK_RV UT_ReadFile(DHANDLE handle, CK_ULONG addr, CK_ULONG len, CK_BYTE_PTR buf);
CK_RV UT_WriteFile(DHANDLE handle, CK_ULONG addr, CK_ULONG len, CK_BYTE_PTR buf);
CK_RV UT_GetRecord(DHANDLE handle, CK_ULONG index, CK_BYTE_PTR buf, CK_ULONG len);
CK_RV UT_AppendRecord(DHANDLE handle, CK_BYTE_PTR buf, CK_ULONG buf_len);
CK_RV UT_SoftReset(DHANDLE handle);
CK_RV UT_ChangePIN(DHANDLE handle, CK_BYTE_PTR ARCCoded, CK_RV ARCCodedLen, 
	CK_BYTE_PTR UTCCoded, CK_RV UTCCodedLen);
CK_RV UT_VerifyPIN(DHANDLE handle, CK_BYTE_PTR PIN, CK_ULONG PINLen);
CK_RV UT_VerifyPIN_ADMIN(DHANDLE handle, CK_BYTE_PTR PIN, CK_ULONG PINLen);
CK_RV UT_GetAttempt(DHANDLE handle, CK_ULONG_PTR max_attempt, CK_ULONG_PTR attempt);
CK_RV UT_ReloadPIN(DHANDLE handle, CK_BYTE_PTR pin, CK_ULONG pinLen);
CK_RV UT_GenRSA(DHANDLE handle, CK_FID pub_fid, CK_FID pri_fid, CK_ULONG bit);
CK_RV UT_GetRSAPubKey(DHANDLE handle, CK_FID fid, PUB_KEY_PTR pubkey);
CK_RV UT_SelectRSA(DHANDLE handle, CK_FID pub_fid, CK_FID pri_fid);
CK_RV UT_RSASign(DHANDLE handle, CK_BYTE_PTR digest, CK_ULONG digest_len, 
	CK_BYTE_PTR sign,  CK_ULONG_PTR sign_len);
CK_RV UT_RSAVerify(DHANDLE handle, CK_BYTE_PTR sign, CK_ULONG sign_len, 
    CK_BYTE_PTR digest,  CK_ULONG_PTR digest_len);
CK_RV UT_RSADecrypt(DHANDLE handle, CK_BYTE_PTR cipher, CK_ULONG cipher_len, 
	CK_BYTE_PTR plain, CK_ULONG_PTR plain_len);
CK_RV UT_RSAEncrypt(DHANDLE handle, CK_BYTE_PTR plain, CK_ULONG plain_len, 
	CK_BYTE_PTR cipher, CK_ULONG_PTR cipher_len);
CK_RV UT_GetRandom(DHANDLE handle, CK_BYTE_PTR random, CK_ULONG random_len);
CK_RV UT_Hash(DHANDLE handle, CK_ALG alg, CK_BYTE_PTR data, CK_ULONG data_len);
CK_RV UT_HashFinalize(DHANDLE handle, CK_BYTE_PTR digest, CK_ULONG_PTR digest_len);
CK_RV UT_Encrypt(DHANDLE handle, CK_ALG alg, CK_ULONG mode, CK_BYTE_PTR iv, CK_ULONG iv_len, 
    CK_BYTE_PTR plain, CK_ULONG plain_len, CK_BYTE_PTR cipher, CK_ULONG_PTR cipher_len);
CK_RV UT_Decrypt(DHANDLE handle, CK_ALG alg, CK_ULONG mode, CK_BYTE_PTR iv, CK_ULONG iv_len, 
	CK_BYTE_PTR cipher, CK_ULONG cipher_len, CK_BYTE_PTR plain, CK_ULONG_PTR plain_len);

Check Device Connection Status

long IsConnected(bool *bConnected);

Parameters

Parameter	Description
bConnected	[out] Device connection status

Return values

Result	Value	Description
0	S_OK	Success
< 0	Error code	See error code description

Generate RSA Key Pair

long CreateRSAKey(char *pPassword, long lPublicKeyLen, pbyte ppPublicKey);

Parameters

Parameter	Description
pPassword	[in] Device Password
lPublicKeyLen	[in] Length of public key: 1024 or 2048 bits
ppPublicKey	[out] Public key of the generated key-pair (format complies with the coding specification described in this document)

Return values

Result	Value	Description
0	S_OK	Success
< 0	Error code	See error code description

Import Public Key Certificate

long ImportX509Certificate(pbyte pCertificate, long lCertificateLen);

Parameters

Parameter	Description
pCertificate	[in] DER coded X509 public key certificate
lCertificateLen	[in] Public key length

Return values

Result	Value	Description
0	S_OK	Success
< 0	Error code	See error code description

Decrypt Digital Envelope

long DecryptEnvelopeData(pbyte pCertificate, long lCertificateLen , char *pPassword, pbyte pInData, long lInDataLen, pbyte ppOutData, long *lOutDataLen);

Parameters

Parameter	Description
pCertificate	[in] Public key certificate corresponding to the private key; the decrypting certificate
lCertificateLen	[in] Public key length
pPassword	[in] Device password
pInData	[in] Cipher text of digital envelope (includes PKCS7 and CMS formats)
lInDataLen	[in] Length of cipher text of digital envelope
ppOutData	[out] Plain text of digital envelope
lOutDataLen	[out] Length of plain text of digital envelope

Return values

Result	Value	Description
0	S_OK	Success
< 0	Error code	See error code description

Sign Data

Includes explicit key signature, ordinary signature, SSL handling, and P10 signature.

long SignData(pbyte pCertificate, long lCertificateLen, char *pPassword, pbyte pSrcData, long lSrcDataLen, char *pHashOID, pbyte ppOutData, long *lpOutDataLen);

Parameters

Parameter	Description
pCertificate	[in] Public key certificate corresponding to the private key. If using RSA generated key pairs, use the public key value returned from the CreateRSAKey function.
lCertificateLen	[in] Public key length
pPassword	[in] Device password
pSrcData	[in] Source data to be signed
pSrcDataLen	[in] Length of source data to be signed
pHashOIDHash	[in] Hash algorithm identification
ppOutData	[out] Signed data (PKCS#1 format)
lpOutDataLen	[out] Length of signed data (PKCS#1 format)

Return values

Result	Value	Description
0	S_OK	Success
< 0	Error code	See error code description

Change Password

long ChangePassword(pbyte pCertificate, long lCertificateLen, char *pOldPwd, char *pNewPwd);

Parameters

Parameter	Description
pCertificate	[in] Public key certificate. If inputting device password, ignore this parameter
lCertificateLen	[in] Public key length, ignore this parameter if pCertificate is the device's password
oldPwd	[in] Old password
newPwd	[in] New password

Return values

Result	Value	Description
0	S_OK	Success
< 0	Error code	See error code description

Get DER Code of Public Key Certificate

long GetX509Certificates(int *ipCertificates, long **lppCertificateLen, pbyte *ppCertificates);

Parameters

Parameter	Description
ipCertificates	[in, out] Number of public keys (the return value of the function called the first time)
lppCertificateLen	[in, out] Length of each public key (the return value of the function called the second time)
ppCertificates	[out] The two-dimensional array of DER encoded public keys (the return value of the function called the third time)

Return values

Result	Value	Description
0	S_OK	Success
< 0	Error code	See error code description

Get the Remaining Number of Password Login Attempts

long GetPwdCanRetries(pbyte pCertificate, long lCertificateLen, int *ipRemaining);

Parameters

Parameter	Description
pCertificate	[in] Public key certificate. If inputting the device password, ignore this parameter
lCertificateLen	[in] Public key length. If inputting the device password, ignore this parameter
ipRemaining	[out] Remaining number of password attempts

Return values

Result	Value	Description
0	S_OK	Success
< 0	Error code	See error code description

Get Device Serial Number

The serial number is the device's unique ID.

long GetDeviceSerialNumber(char *ppDeviceSN, long *lpDeviceSNLen);

Parameters

Parameter	Description
ppDeviceSN	[out] Device serial number
lpDeviceSNLen	[out] Length of device serial number

Return values

Result	Value	Description
0	S_OK	Success
< 0	Error code	See error code description