UniMate API Reference for C Language

UniMate Mobile Certificate API Reference

Relative Convention

Character Coding

All string parameters use the UTF-8 coding standard.

Return Value

All return values from functions are of type long.

0 refers to success, whereas < 0 indicates an error code.

Public Key Format

pPublicKey is compatible with RFC 3447 specification.

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

Hash Algorithm Identification

pHashOID is the identification string of each hash algorithm, and the specific algorithm ID are as the following table.

ID	Specification
1.3.14.3.2.26	SHA1 Algorithm
2.16.840.1.101.3.4.2.1	SHA256 Algorithm

Ease of Use Convention

As the speed of reading a certificate is low, an initiation mechanism shall be established, that is after the content of a public key is read at the first time of inserting a key, the public key and the information of the corresponding private key, such as container name, container ID and etc, shall be stored together in a configure file (the configure file will be created automatically: such as "company name.config") to ensure that at the next time, the public key and private key-pair can be established by just reading the private ID in the key. Through this method, the speed of certificate reading will be improved, and meanwhile the private key can be found very fast when signing or decrypting digital envelope.

Third Party Encrypt Library

If using the encrypt library, please use libCrypto.so in Android system. The library should support Android v2.1 and later.

Relative Development

1. Functions, variables and etc. shall comply with C standard.
2. Interfaces with binary returns, such as SignData, shall be called twice, that is, at the first time, get the length of data, after applying for memory space externally, return specific data at the second time.
3. All passed char* type parameters shall be ended with ‘\0’, and the length can be calculated directly.

Development Tools

Use NDK built-in tools version 1.6 or later as the compiler tools.

Type Definition

Typedef	unsigned char	byte;
Typedef	byte		*pbyte;

Interface Definition

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, pbyteppPublicKey);

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 (include PKCS7 format and CMS format)
lInDataLen	[in] Length of cipher text of digital envelope
ppOutData	[out] Original text of digital envelope
lOutDataLen	[out] Length of original data 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 generated RSA 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
srcData	[in] Source data to be signed
pSrcDataLen	[in] length of source data to be signed
pHashOIDHash	[in] Hash algorithm identification
ppOutData	[out] Signed data (PKCS1 format)
lpOutDataLen	[out]length of signed data (PKCS1 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 parmeter
lCertificateLen	[in] Public key length, and if it’s device password, ignore this parameter
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-dimension array of public key DER encoded (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	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
[out] lpDeviceSNLen	[out] Length of device serial number

Return values

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

Error Code Table

Error Code	Macro Definition	Description
0	S_OK	Success
-1	S_DEVICE_FAILURE	No connection
-2	S_INVALID_PASSWORD	Verify password failed
-3	S_DEVICE_LOCK	Device Locked
-4	S_NOT_ENOUGH_MEMORY	Insufficient memory
-5	S_INVALID_CERTIFICATE	Invalid format of Certificate
-6	S_INVALID_ALGORITHM	Invalid algorithm
-7	S_INVALID_PARAMETER	Invalid parameter
-8	S_UNKOWN_ERROR	Unknown error
-9	S_USER_CANCEL	Canceled by user