UniMate API Reference for C Language: Difference between revisions

From SecuTech Wiki
Jump to navigationJump to search

Bao (talk | contribs)

0 edits
Joseph (talk | contribs)
0 edits
Created page with "category:UniMate API == UniMate Mobile Certificate API Reference == === Relative Convention === ==== Character Coding ==== All string parameters use the UTF-8 coding s..."
 
Bao (talk | contribs)
0 edits
m Readded Android specific details
 
(28 intermediate revisions by 2 users not shown)
Line 2: Line 2:


== UniMate Mobile Certificate API Reference ==
== UniMate Mobile Certificate API Reference ==
This document generally refers to the use of the C language with Android systems, however, there are some function headers and such listed in here that are specific to Windows. If so, it will be noted above.


=== Relative Convention ===
=== Relative Convention ===


==== Character Coding ====
==== Character Encoding ====


All string parameters use the UTF-8 coding standard.
All string parameters use the UTF-8 coding standard.
Line 11: Line 12:
==== Return Value ====
==== Return Value ====


All return values from functions are of type long.
All return values from functions are of type long and type unsigned long for WIndows.


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


==== Public Key Format ====
==== Public Key Format ====


<code>pPublicKey</code> is compatible with RFC 3447 specification.
<code>PUB_KEY</code> is compatible with the RFC 3447 specification.


<pre>
<pre>
Line 25: Line 26:
}
}
</pre>
</pre>
<b>Windows Only:</b> as defined by the struct:
<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">
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;
</source>


==== Hash Algorithm Identification ====
==== Hash Algorithm Identification ====


pHashOID is the identification string of each hash algorithm, and the specific algorithm ID are as the following table.
<code>pHashOID</code> is the identification string of each hash algorithm, and the specific algorithm IDs are listed in the following table.


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>ID</th>
<th>ID</th>
Line 47: Line 67:
==== Ease of Use Convention ====
==== Ease of Use Convention ====
<!--Review-->
<!--Review-->
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.
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 ====
==== 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.
If using the encrypt library, please use libCrypto.so in the Android system. This library should support Android v2.1 and later.  


==== Relative Development ====
==== Relative Development ====
 
<!-- Which C Standard (at minimum it would probably be C89/90 due to Windows) -->
# Functions, variables and etc. shall comply with C standard.
# Functions, variables, et al. shall comply with the 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.
# Interfaces with binary returns, such as <code>SignData</code>, 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’, and the length can be calculated directly
# All passed <code>char *</code> type parameters shall be ended with ‘\0’ (null character), and the length can be calculated directly.


==== Development Tools ====
==== Development Tools ====


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


==== Type Definition ====
==== Type Definition ====


<pre>
<b>Android</b>
Typedef unsigned char byte;
<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">
Typedef byte *pbyte;
typedef unsigned char byte;
</pre>
typedef byte         *pbyte;
</source>
 
<b>Windows</b>
<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">
typedef unsigned long  DHANDLE,  *DHANDLE_PTR;
typedef unsigned char  CK_BYTE,  *CK_BYTE_PTR;
typedef unsigned short CK_FID;
typedef unsigned long  CK_ULONG, *CK_ULONG_PTR;
typedef CK_ULONG      CK_RV;
typedef CK_ULONG      CK_ALG;
typedef short          CK_SHORT, *CK_SHORT_PTR;
</source>


=== Interface Definition ===
=== Interface Definition ===
<!-- Consider changing to denote the C function headers as defined in the sample, but as they don't mirror each other, wait for a description of each function and go from there -->
Here are the C function headers as defined in the UniMate.h file in the UniMate STD SDK Windows Device Samples. For the function descriptions below, these headers, they are defined for Android systems.
<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">
CK_RV s2u(CK_SHORT sc_error);
CK_RV UT_Initialize();
CK_RV UT_Finalize();
CK_RV UT_Find(DHANDLE handle[MAX_DEVICE_COUNT], CK_ULONG_PTR count);
CK_RV UT_GetID(DHANDLE handle,  CK_BYTE_PTR id);
CK_RV UT_GetSN(DHANDLE handle,  CK_ULONG sn[2]);
CK_RV UT_GetCOSVersion(DHANDLE handle, CK_ULONG_PTR version);
CK_RV UT_GetSpace(DHANDLE handle, CK_ULONG_PTR space);
CK_RV UT_OpenFID(DHANDLE handle, CK_FID fid);
CK_RV UT_ReadFile(DHANDLE handle, CK_ULONG addr, CK_ULONG len, CK_BYTE_PTR buf);
CK_RV UT_WriteFile(DHANDLE handle, CK_ULONG addr, CK_ULONG len, CK_BYTE_PTR buf);
CK_RV UT_GetRecord(DHANDLE handle, CK_ULONG index, CK_BYTE_PTR buf, CK_ULONG len);
CK_RV UT_AppendRecord(DHANDLE handle, CK_BYTE_PTR buf, CK_ULONG buf_len);
CK_RV UT_SoftReset(DHANDLE handle);
CK_RV UT_ChangePIN(DHANDLE handle, CK_BYTE_PTR ARCCoded, CK_RV ARCCodedLen,
CK_BYTE_PTR UTCCoded, CK_RV UTCCodedLen);
CK_RV UT_VerifyPIN(DHANDLE handle, CK_BYTE_PTR PIN, CK_ULONG PINLen);
CK_RV UT_VerifyPIN_ADMIN(DHANDLE handle, CK_BYTE_PTR PIN, CK_ULONG PINLen);
CK_RV UT_GetAttempt(DHANDLE handle, CK_ULONG_PTR max_attempt, CK_ULONG_PTR attempt);
CK_RV UT_ReloadPIN(DHANDLE handle, CK_BYTE_PTR pin, CK_ULONG pinLen);
CK_RV UT_GenRSA(DHANDLE handle, CK_FID pub_fid, CK_FID pri_fid, CK_ULONG bit);
CK_RV UT_GetRSAPubKey(DHANDLE handle, CK_FID fid, PUB_KEY_PTR pubkey);
CK_RV UT_SelectRSA(DHANDLE handle, CK_FID pub_fid, CK_FID pri_fid);
CK_RV UT_RSASign(DHANDLE handle, CK_BYTE_PTR digest, CK_ULONG digest_len,
CK_BYTE_PTR sign,  CK_ULONG_PTR sign_len);
CK_RV UT_RSAVerify(DHANDLE handle, CK_BYTE_PTR sign, CK_ULONG sign_len,
    CK_BYTE_PTR digest,  CK_ULONG_PTR digest_len);
CK_RV UT_RSADecrypt(DHANDLE handle, CK_BYTE_PTR cipher, CK_ULONG cipher_len,
CK_BYTE_PTR plain, CK_ULONG_PTR plain_len);
CK_RV UT_RSAEncrypt(DHANDLE handle, CK_BYTE_PTR plain, CK_ULONG plain_len,
CK_BYTE_PTR cipher, CK_ULONG_PTR cipher_len);
CK_RV UT_GetRandom(DHANDLE handle, CK_BYTE_PTR random, CK_ULONG random_len);
CK_RV UT_Hash(DHANDLE handle, CK_ALG alg, CK_BYTE_PTR data, CK_ULONG data_len);
CK_RV UT_HashFinalize(DHANDLE handle, CK_BYTE_PTR digest, CK_ULONG_PTR digest_len);
CK_RV UT_Encrypt(DHANDLE handle, CK_ALG alg, CK_ULONG mode, CK_BYTE_PTR iv, CK_ULONG iv_len,
    CK_BYTE_PTR plain, CK_ULONG plain_len, CK_BYTE_PTR cipher, CK_ULONG_PTR cipher_len);
CK_RV UT_Decrypt(DHANDLE handle, CK_ALG alg, CK_ULONG mode, CK_BYTE_PTR iv, CK_ULONG iv_len,
CK_BYTE_PTR cipher, CK_ULONG cipher_len, CK_BYTE_PTR plain, CK_ULONG_PTR plain_len);
</source>


==== Check Device Connection Status ====
==== Check Device Connection Status ====


<code>long  IsConnected(bool* bConnected);</code>
<code>long  IsConnected(bool *bConnected);</code>


'''Parameters'''
'''Parameters'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Parameter</th>
<th>Parameter</th>
Line 91: Line 167:
'''Return values'''
'''Return values'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 109: Line 185:
</table>
</table>


==== Generate a Key-pair ====


<code>long CreateRSAKey(char* pPassword,long lPublicKeyLen, pbyteppPublicKey);</code>
==== Generate RSA Key Pair ====
 
<code>long CreateRSAKey(char *pPassword, long lPublicKeyLen, pbyte ppPublicKey);</code>


'''Parameters'''
'''Parameters'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Parameter</th>
<th>Parameter</th>
Line 126: Line 203:
<tr>
<tr>
<td>lPublicKeyLen</td>
<td>lPublicKeyLen</td>
<td>[in] Specify public key length: 1024 or 2048</td>
<td>[in] Length of public key: 1024 or 2048 bits</td>
</tr>
</tr>
<tr>
<tr>
<td>ppPublicKey</td>
<td>ppPublicKey</td>
<td>[out] Public key of the generated key-pair (format comply with the coding specification described in this document)</td>
<td>[out] Public key of the generated key-pair (format complies with the coding specification described in this document)</td>
</tr>
</tr>
</table>
</table>
Line 136: Line 213:
'''Return values'''
'''Return values'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 153: Line 230:
</tr>
</tr>
</table>
</table>


==== Import Public Key Certificate ====
==== Import Public Key Certificate ====
Line 160: Line 238:
'''Parameters'''
'''Parameters'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Parameter</th>
<th>Parameter</th>
Line 167: Line 245:
<tr>
<tr>
<td>pCertificate</td>
<td>pCertificate</td>
<td>[in] Der coded X509 public key certificate</td>
<td>[in] DER coded X509 public key certificate</td>
</tr>
</tr>
<tr>
<tr>
Line 177: Line 255:
'''Return values'''
'''Return values'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 194: Line 272:
</tr>
</tr>
</table>
</table>


==== Decrypt Digital Envelope ====
==== Decrypt Digital Envelope ====


<code>long DecryptEnvelopeData(pbyte pCertificate, long lCertificateLen , char * pPassword, pbyte pInData, long lInDataLen, pbyte ppOutData, long* lOutDataLen);</code>
<code>long DecryptEnvelopeData(pbyte pCertificate, long lCertificateLen , char *pPassword, pbyte pInData, long lInDataLen, pbyte ppOutData, long *lOutDataLen);</code>


'''Parameters'''
'''Parameters'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Parameter</th>
<th>Parameter</th>
Line 208: Line 287:
<tr>
<tr>
<td>pCertificate</td>
<td>pCertificate</td>
<td>[in] Public key certificate corresponding to the private key, which is the decrypting certificate</td>
<td>[in] Public key certificate corresponding to the private key; the decrypting certificate</td>
</tr>
</tr>
<tr>
<tr>
Line 220: Line 299:
<tr>
<tr>
<td>pInData</td>
<td>pInData</td>
<td>[in] Cipher text of digital envelope (include PKCS7 format and CMS format)</td>
<td>[in] Cipher text of digital envelope (includes PKCS7 and CMS formats)</td>
</tr>
</tr>
<tr>
<tr>
<td>lInDataLen</td>
<td>lInDataLen</td>
<td>[in] length of cipher text of digital envelope</td>
<td>[in] Length of cipher text of digital envelope</td>
</tr>
</tr>
<tr>
<tr>
<td>ppOutData</td>
<td>ppOutData</td>
<td>[out] Original text of digital envelope</td>
<td>[out] Plain text of digital envelope</td>
</tr>
</tr>
<tr>
<tr>
<td>lOutDataLen</td>
<td>lOutDataLen</td>
<td>[out] length of original data of digital envelope</td>
<td>[out] Length of plain text of digital envelope</td>
</tr>
</tr>
</table>
</table>
Line 238: Line 317:
'''Return values'''
'''Return values'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 256: Line 335:
</table>
</table>


==== Digital Sign (including explicit key signature, ordinary signature, SSL handling, and P10 signature) ====


<code>long SignData(pbyte pCertificate, long lCertificateLen, char* pPassword, pbyte pSrcData, long lSrcDataLen, char* pHashOID, pbyte ppOutData, long* lpOutDataLen);</code>
==== Sign Data ====
 
Includes explicit key signature, ordinary signature, SSL handling, and P10 signature.
 
<code>long SignData(pbyte pCertificate, long lCertificateLen, char *pPassword, pbyte pSrcData, long lSrcDataLen, char *pHashOID, pbyte ppOutData, long *lpOutDataLen);</code>


'''Parameters'''
'''Parameters'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Parameter</th>
<th>Parameter</th>
Line 269: Line 351:
<tr>
<tr>
<td>pCertificate</td>
<td>pCertificate</td>
<td>[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.</td>
<td>[in] Public key certificate corresponding to the private key. If using RSA generated key pairs, use the public key value returned from the <code>CreateRSAKey</code> function.</td>
</tr>
</tr>
<tr>
<tr>
Line 281: Line 363:
<tr>
<tr>
<td>pSrcData</td>
<td>pSrcData</td>
<td>[in] Source data to be signed</td>
</tr>
<tr>
<td>srcData</td>
<td>[in] Source data to be signed</td>
<td>[in] Source data to be signed</td>
</tr>
</tr>
<tr>
<tr>
<td>pSrcDataLen</td>
<td>pSrcDataLen</td>
<td>[in] length of source data to be signed</td>
<td>[in] Length of source data to be signed</td>
</tr>
</tr>
<tr>
<tr>
Line 297: Line 375:
<tr>
<tr>
<td>ppOutData</td>
<td>ppOutData</td>
<td>[out] Signed data (PKCS1 format)</td>
<td>[out] Signed data (PKCS#1 format)</td>
</tr>
</tr>
<tr>
<tr>
<td>lpOutDataLen</td>
<td>lpOutDataLen</td>
<td>[out]length of signed data (PKCS1 format)</td>
<td>[out] Length of signed data (PKCS#1 format)</td>
</tr>
</tr>
</table>
</table>
Line 307: Line 385:
'''Return values'''
'''Return values'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 324: Line 402:
</tr>
</tr>
</table>
</table>


==== Change Password ====
==== Change Password ====


<code>longChangePassword(pbyte pCertificate,long lCertificateLen, char* pOldPwd, char* pNewPwd);</code>
<code>long ChangePassword(pbyte pCertificate, long lCertificateLen, char *pOldPwd, char *pNewPwd);</code>


'''Parameters'''
'''Parameters'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Parameter</th>
<th>Parameter</th>
Line 338: Line 417:
<tr>
<tr>
<td>pCertificate</td>
<td>pCertificate</td>
<td>[in] Public key certificate, and if it’s device password, ignore this parmeters.</td>
<td>[in] Public key certificate. If inputting device password, ignore this parameter</td>
</tr>
</tr>
<tr>
<tr>
<td>lCertificateLen</td>
<td>lCertificateLen</td>
<td>[in] Public key length, and if it’s device password, ignore this parameter</td>
<td>[in] Public key length, ignore this parameter if pCertificate is the device's password</td>
</tr>
</tr>
<tr>
<tr>
Line 356: Line 435:
'''Return values'''
'''Return values'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 373: Line 452:
</tr>
</tr>
</table>
</table>


==== Get DER Code of Public Key Certificate ====
==== Get DER Code of Public Key Certificate ====
<code>longGetX509Certificates(int* ipCertificates, long** lppCertificateLen, pbyte* ppCertificates);</code>
 
<code>long GetX509Certificates(int *ipCertificates, long **lppCertificateLen, pbyte *ppCertificates);</code>


'''Parameters'''
'''Parameters'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Parameter</th>
<th>Parameter</th>
Line 386: Line 467:
<tr>
<tr>
<td>ipCertificates</td>
<td>ipCertificates</td>
<td>[in, out] Number of public key (the return value of the function that is called at the first time)</td>
<td>[in, out] Number of public keys (the return value of the function called the first time)</td>
</tr>
</tr>
<tr>
<tr>
<td>lppCertificateLen</td>
<td>lppCertificateLen</td>
<td>[in,out] Length of every public key (the return value of function that is called at the second time)</td>
<td>[in, out] Length of each public key (the return value of the function called the second time)</td>
</tr>
</tr>
<tr>
<tr>
<td>ppCertificates</td>
<td>ppCertificates</td>
<td>[out] The two-dimension array of public key DER encoded(the return value of the function that is called at the third time)</td>
<td>[out] The two-dimensional array of DER encoded public keys (the return value of the function called the third time)</td>
</tr>
</tr>
</table>
</table>
Line 400: Line 481:
'''Return values'''
'''Return values'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 418: Line 499:
</table>
</table>


==== Get the Remaining Number of Password Attempts ====


<code>long GetPwdCanRetries(pbyte pCertificate, long lCertificateLen, int*ipRemaining);</code>
==== Get the Remaining Number of Password Login Attempts ====
 
<code>long GetPwdCanRetries(pbyte pCertificate, long lCertificateLen, int *ipRemaining);</code>


'''Parameters'''
'''Parameters'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Parameter</th>
<th>Parameter</th>
Line 431: Line 513:
<tr>
<tr>
<td>pCertificate</td>
<td>pCertificate</td>
<td>[in] Public key certificate, and if it’s the device password, ignore this parameter.</td>
<td>[in] Public key certificate. If inputting the device password, ignore this parameter</td>
</tr>
</tr>
<tr>
<tr>
<td>lCertificateLen</td>
<td>lCertificateLen</td>
<td>Public key length, and if it’s device password, ignore this parameter</td>
<td>[in] Public key length. If inputting the device password, ignore this parameter</td>
</tr>
</tr>
<tr>
<tr>
<td>ipRemaining</td>
<td>ipRemaining</td>
<td>[out] The remaining number of password attempts</td>
<td>[out] Remaining number of password attempts</td>
</tr>
</tr>
</table>
</table>
Line 445: Line 527:
'''Return values'''
'''Return values'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 463: Line 545:
</table>
</table>


==== Get Device Serial Number (the unique device serial number) ====


<code>long GetDeviceSerialNumber(char* ppDeviceSN, long* lpDeviceSNLen);</code>
==== Get Device Serial Number ====
 
The serial number is the device's unique ID.
 
<code>long GetDeviceSerialNumber(char *ppDeviceSN, long *lpDeviceSNLen);</code>


'''Parameters'''
'''Parameters'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Parameter</th>
<th>Parameter</th>
Line 476: Line 561:
<tr>
<tr>
<td>ppDeviceSN</td>
<td>ppDeviceSN</td>
<td>[out] Device Device serial number</td>
<td>[out] Device serial number</td>
</tr>
</tr>
<tr>
<tr>
<td>[out] lpDeviceSNLen</td>
<td>lpDeviceSNLen</td>
<td>[out] Length of device serial number</td>
<td>[out] Length of device serial number</td>
</tr>
</tr>
Line 486: Line 571:
'''Return values'''
'''Return values'''


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 501: Line 586:
<td>Error code</td>
<td>Error code</td>
<td>See error code description</td>
<td>See error code description</td>
</tr>
</table>
=== Error Code Table ===
<table border="1">
<tr>
<th>Error Code</th>
<th>Macro Definition</th>
<th>Description</th>
</tr>
<tr>
<td>0 </td>
<td>S_OK </td>
<td>Success</td>
</tr>
<tr>
<td>-1 </td>
<td>S_DEVICE_FAILURE </td>
<td>No connection</td>
</tr>
<tr>
<td>-2 </td>
<td>S_INVALID_PASSWORD </td>
<td>Verify password failed</td>
</tr>
<tr>
<td>-3 </td>
<td>S_DEVICE_LOCK </td>
<td>Device Locked</td>
</tr>
<tr>
<td>-4 </td>
<td>S_NOT_ENOUGH_MEMORY </td>
<td>Insufficient memory</td>
</tr>
<tr>
<td>-5 </td>
<td>S_INVALID_CERTIFICATE </td>
<td>Invalid format of Certificate</td>
</tr>
<tr>
<td>-6 </td>
<td>S_INVALID_ALGORITHM </td>
<td>Invalid algorithm</td>
</tr>
<tr>
<td>-7 </td>
<td>S_INVALID_PARAMETER </td>
<td>Invalid parameter</td>
</tr>
<tr>
<td>-8 </td>
<td>S_UNKOWN_ERROR </td>
<td>Unknown error</td>
</tr>
<tr>
<td>-9 </td>
<td>S_USER_CANCEL </td>
<td>Canceled by user</td>
</tr>
</tr>
</table>
</table>

Latest revision as of 11:43, 10 August 2016


UniMate Mobile Certificate API Reference

This document generally refers to the use of the C language with Android systems, however, there are some function headers and such listed in here that are specific to Windows. If so, it will be noted above.

Relative Convention

Character Encoding

All string parameters use the UTF-8 coding standard.

Return Value

All return values from functions are of type long and type unsigned long for WIndows.

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
}

Windows Only: 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. This 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

Android 

typedef unsigned char byte;
typedef byte          *pbyte;

Windows 

typedef unsigned long  DHANDLE,  *DHANDLE_PTR;
typedef unsigned char  CK_BYTE,  *CK_BYTE_PTR;
typedef unsigned short CK_FID;
typedef unsigned long  CK_ULONG, *CK_ULONG_PTR;
typedef CK_ULONG       CK_RV;
typedef CK_ULONG       CK_ALG;
typedef short          CK_SHORT, *CK_SHORT_PTR;

Interface Definition

Here are the C function headers as defined in the UniMate.h file in the UniMate STD SDK Windows Device Samples. For the function descriptions below, these headers, they are defined for Android systems. 

CK_RV s2u(CK_SHORT sc_error);
CK_RV UT_Initialize();
CK_RV UT_Finalize();
CK_RV UT_Find(DHANDLE handle[MAX_DEVICE_COUNT], CK_ULONG_PTR count);
CK_RV UT_GetID(DHANDLE handle,  CK_BYTE_PTR id);
CK_RV UT_GetSN(DHANDLE handle,  CK_ULONG sn[2]);
CK_RV UT_GetCOSVersion(DHANDLE handle, CK_ULONG_PTR version);
CK_RV UT_GetSpace(DHANDLE handle, CK_ULONG_PTR space);
CK_RV UT_OpenFID(DHANDLE handle, CK_FID fid);
CK_RV UT_ReadFile(DHANDLE handle, CK_ULONG addr, CK_ULONG len, CK_BYTE_PTR buf);
CK_RV UT_WriteFile(DHANDLE handle, CK_ULONG addr, CK_ULONG len, CK_BYTE_PTR buf);
CK_RV UT_GetRecord(DHANDLE handle, CK_ULONG index, CK_BYTE_PTR buf, CK_ULONG len);
CK_RV UT_AppendRecord(DHANDLE handle, CK_BYTE_PTR buf, CK_ULONG buf_len);
CK_RV UT_SoftReset(DHANDLE handle);
CK_RV UT_ChangePIN(DHANDLE handle, CK_BYTE_PTR ARCCoded, CK_RV ARCCodedLen, 
	CK_BYTE_PTR UTCCoded, CK_RV UTCCodedLen);
CK_RV UT_VerifyPIN(DHANDLE handle, CK_BYTE_PTR PIN, CK_ULONG PINLen);
CK_RV UT_VerifyPIN_ADMIN(DHANDLE handle, CK_BYTE_PTR PIN, CK_ULONG PINLen);
CK_RV UT_GetAttempt(DHANDLE handle, CK_ULONG_PTR max_attempt, CK_ULONG_PTR attempt);
CK_RV UT_ReloadPIN(DHANDLE handle, CK_BYTE_PTR pin, CK_ULONG pinLen);
CK_RV UT_GenRSA(DHANDLE handle, CK_FID pub_fid, CK_FID pri_fid, CK_ULONG bit);
CK_RV UT_GetRSAPubKey(DHANDLE handle, CK_FID fid, PUB_KEY_PTR pubkey);
CK_RV UT_SelectRSA(DHANDLE handle, CK_FID pub_fid, CK_FID pri_fid);
CK_RV UT_RSASign(DHANDLE handle, CK_BYTE_PTR digest, CK_ULONG digest_len, 
	CK_BYTE_PTR sign,  CK_ULONG_PTR sign_len);
CK_RV UT_RSAVerify(DHANDLE handle, CK_BYTE_PTR sign, CK_ULONG sign_len, 
    CK_BYTE_PTR digest,  CK_ULONG_PTR digest_len);
CK_RV UT_RSADecrypt(DHANDLE handle, CK_BYTE_PTR cipher, CK_ULONG cipher_len, 
	CK_BYTE_PTR plain, CK_ULONG_PTR plain_len);
CK_RV UT_RSAEncrypt(DHANDLE handle, CK_BYTE_PTR plain, CK_ULONG plain_len, 
	CK_BYTE_PTR cipher, CK_ULONG_PTR cipher_len);
CK_RV UT_GetRandom(DHANDLE handle, CK_BYTE_PTR random, CK_ULONG random_len);
CK_RV UT_Hash(DHANDLE handle, CK_ALG alg, CK_BYTE_PTR data, CK_ULONG data_len);
CK_RV UT_HashFinalize(DHANDLE handle, CK_BYTE_PTR digest, CK_ULONG_PTR digest_len);
CK_RV UT_Encrypt(DHANDLE handle, CK_ALG alg, CK_ULONG mode, CK_BYTE_PTR iv, CK_ULONG iv_len, 
    CK_BYTE_PTR plain, CK_ULONG plain_len, CK_BYTE_PTR cipher, CK_ULONG_PTR cipher_len);
CK_RV UT_Decrypt(DHANDLE handle, CK_ALG alg, CK_ULONG mode, CK_BYTE_PTR iv, CK_ULONG iv_len, 
	CK_BYTE_PTR cipher, CK_ULONG cipher_len, CK_BYTE_PTR plain, CK_ULONG_PTR plain_len);

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
Retrieved from "https://esecutech.com/wiki/index.php?title=UniMate_API_Reference_for_C_Language&oldid=2604"