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 encrypt library, please use libCrypto.so in Android system. When the library is called, it should support Android v2.1 and later.
Relative Development
- Functions, variables and etc. shall comply with C standard.
- 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.
- 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 a Key-pair
long CreateRSAKey(char* pPassword,long lPublicKeyLen, pbyteppPublicKey);
Parameters
| Parameter | Description |
|---|---|
| pPassword | [in] Device Password |
| lPublicKeyLen | [in] Specify public key length: 1024 or 2048 |
| ppPublicKey | [out] Public key of the generated key-pair (format comply 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, which is 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 |
Digital Sign (including 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 private key, and if RSA key pairs are just generated, use the public key value returned from 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
longChangePassword(pbyte pCertificate,long lCertificateLen, char* pOldPwd, char* pNewPwd);
Parameters
| Parameter | Description |
|---|---|
| pCertificate | [in] Public key certificate, and if it’s device password, ignore this parmeters. |
| 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
longGetX509Certificates(int* ipCertificates, long** lppCertificateLen, pbyte* ppCertificates);
Parameters
| Parameter | Description |
|---|---|
| ipCertificates | [in, out] Number of public key (the return value of the function that is called at the first time) |
| lppCertificateLen | [in,out] Length of every public key (the return value of function that is called at the second time) |
| ppCertificates | [out] The two-dimension array of public key DER encoded(the return value of the function that is called at 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 Attempts
long GetPwdCanRetries(pbyte pCertificate, long lCertificateLen, int*ipRemaining);
Parameters
| Parameter | Description |
|---|---|
| pCertificate | [in] Public key certificate, and if it’s the device password, ignore this parameter. |
| lCertificateLen | Public key length, and if it’s device password, ignore this parameter |
| ipRemaining | [out] The 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 unique device serial number)
long GetDeviceSerialNumber(char* ppDeviceSN, long* lpDeviceSNLen);
Parameters
| Parameter | Description |
|---|---|
| ppDeviceSN | [out] Device 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 |
