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
- 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 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 |
