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 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;
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
- Functions, variables, et al. shall comply with the C standard.
- 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. - 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 |
| lpDeviceSNLen | [out] Length of device serial number |
Return values
| Result | Value | Description |
|---|---|---|
| 0 | S_OK | Success |
| < 0 | Error code | See error code description |
