UniMate API Reference for C Language: Difference between revisions

From SecuTech Wiki
Jump to navigationJump to search
← Older editNewer edit →

Bao (talk | contribs)

0 edits
Bao (talk | contribs)
0 edits
m Spaced function headers apart one line
Bao (talk | contribs)
0 edits
m Adjusted tables
Line 30: Line 30:
<code>pHashOID</code> is the identification string of each hash algorithm, and the specific algorithm IDs are listed in 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 78: Line 78:
'''Parameters'''
'''Parameters'''


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


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 116: Line 116:
'''Parameters'''
'''Parameters'''


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


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 162: Line 162:
'''Parameters'''
'''Parameters'''


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


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 204: Line 204:
'''Parameters'''
'''Parameters'''


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


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 268: Line 268:
'''Parameters'''
'''Parameters'''


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


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 334: Line 334:
'''Parameters'''
'''Parameters'''


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


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 384: Line 384:
'''Parameters'''
'''Parameters'''


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


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 430: Line 430:
'''Parameters'''
'''Parameters'''


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


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>
Line 478: Line 478:
'''Parameters'''
'''Parameters'''


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


<table border="1">
<table class="wikitable">
<tr>
<tr>
<th>Result</th>
<th>Result</th>

Revision as of 16:11, 6 July 2016


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
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=2600"