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 the 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 IDs are listed in 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 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.

Third Party Encrypt Library

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

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.

Development Tools

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

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, 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
[out] lpDeviceSNLen	[out] Length of device serial number

Return values

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