UniMate API Reference for Objective-C Language: Difference between revisions

From SecuTech Wiki
Jump to navigationJump to search
Newer edit →

Joseph (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 are using utf-8 coding..."
 
Joseph (talk | contribs)
0 edits
No edit summary
Line 7: Line 7:
==== Character Coding ====
==== Character Coding ====


All string parameters are using utf-8 coding standard.
All string parameters use the UTF-8 coding standard.


==== Return Value ====
==== Return Value ====


All return values from functions are long. 0 means success，and < 0 indicates an error code.
All return values from functions are of type long.
 
0 refers to success, whereas < 0 indicates an error code.


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


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


<pre>
<pre>
RSAPublicKey ::= SEQUENCE {
RSAPublicKey ::= SEQUENCE {
     modulus INTEGER -- n
     modulus INTEGER -- n
     publicExponent INTEGER -- e
     publicExponent INTEGER -- e
}
}
</pre>
</pre>
Line 30: Line 32:
<table border="1">
<table border="1">
<tr>
<tr>
<th>
<th>ID</th>
ID
<th>Specification</th>
</th>
<th>
Specification
</th>
</tr>
</tr>
<tr>
<tr>
<td>
<td>1.3.14.3.2.26</td>
1.3.14.3.2.26
<td>SHA1 Algorithm</td>
</td>
<td>
SHA1 Algorithm
</td>
</tr>
</tr>
<tr>
<tr>
<td>
<td>2.16.840.1.101.3.4.2.1</td>
2.16.840.1.101.3.4.2.1
<td>SHA256 Algorithm</td>
</td>
<td>
SHA256 Algorithm
</td>
</tr>
</tr>
</table>
</table>


==== Ease of Use Convention ====
==== Ease of Use Convention ====
 
<!--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 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 ====
==== Third Party Encrypt Library ====


If using encrypt library, please use Openssl(openssl1.0.0e) library file compiled by SecuTech.
If using encrypt library, please use OpenSSL (openssl1.0.0e) library file compiled by SecuTech.


==== Relative Development ====
==== Relative Development ====


Add “Company_product ID” into the name of code file in OC; add “Company_product ID” into the name of C and C++ source code file, function, and global variable to avoid conflict with other companies’ products in the upper compiled.
Add "Company_product ID" into the name of code file in OC; add "Company_product ID" into the name of C and C++ source code file, function, and global variable to avoid conflict with other companies’ products in the upper compiled.


Realize the main function of the protocol function, and if it has a return value which is released automatically (not alloc), retain must be added.
Realize the main function of the protocol function, and if it has a return value which is released automatically (not alloc), retain must be added.
Line 71: Line 61:
==== Development Tools ====
==== Development Tools ====


* XCODE tools version 4.0 or higher;
* XCODE tools version 4.0 or higher.
* System default LLVM compiler 3.0;
* System default LLVM compiler 3.0.
* Support iOS SDK version 4.2 or higher (iOS deployment Target: iOS 4.2);
* Support iOS SDK version 4.2 or higher (iOS deployment Target: iOS 4.2).
* Active Architecture: arm v6.
* Active Architecture: ARM v6.


=== Interface Definitation ===
=== Interface Definition ===


==== Check a Device Connection Status ====
==== Check a Device Connection Status ====
Line 82: Line 72:
<code>-(long ) isConnected:(bool *) pConnected;</code>
<code>-(long ) isConnected:(bool *) pConnected;</code>


Parameters:
'''Parameters'''
[out] pConnected If device is connected or not


Returns:
<table border="1">
S_OK Success
<tr>
< 0 Fail, return error code
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>pConnected</td>
<td>[out] If device is connected or not.</td>
</tr>
<table border="1">
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
 
'''Return values'''
 
<table border="1">
<tr>
<th>Result</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>0</td>
<td>S_OK</td>
<td>Success</td>
</tr>
<tr>
<td>< 0</td>
<td>Error code</td>
<td>See error code description</td>
</tr>
</table>


==== Generate a Key-pair ====
==== Generate a Key-pair ====
Line 93: Line 113:
<code>-(long ) createRSAKey:(NSString *) pPassword publicKeyLength:( NSInteger)publicKeyLength ppPublicKey:(NSData **) ppPublicKey</code>
<code>-(long ) createRSAKey:(NSString *) pPassword publicKeyLength:( NSInteger)publicKeyLength ppPublicKey:(NSData **) ppPublicKey</code>


Parameters:
'''Parameters'''
[in] pPassword Device password
 
[in] publicKeyLength Length of public key (bit), 1024 or 2048
<table border="1">
[out] ppPublicKey Public key of the generated key-pair (format comply with the
<tr>
coding specification described in this document)
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>pPassword</td>
<td>[in] Device password</td>
</tr>
<tr>
<td>publicKeyLength</td>
<td>[in] Length of public key (bit), 1024 or 2048</td>
</tr>
<tr>
<td>ppPublicKey</td>
<td>[out] Public key of the generated key-pair (format comply with the coding specification described in this document)</td>
</tr>
</table>
 
'''Return values'''


Returns:
<table border="1">
S_OK Success
<tr>
<0 Fail, return error code.
<th>Result</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>0</td>
<td>S_OK</td>
<td>Success</td>
</tr>
<tr>
<td>< 0</td>
<td>Error code</td>
<td>See error code description</td>
</tr>
</table>


==== Import a Public Key Certificate ====
==== Import a Public Key Certificate ====
Line 107: Line 158:
<code>-(long )importX509Certificate:(NSData *) pCertificate;</code>
<code>-(long )importX509Certificate:(NSData *) pCertificate;</code>


Parameters:
'''Parameters'''
[in] pCertificate Der coded X509 public key certificate
 
<table border="1">
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>pCertificate</td>
<td>[in] Der coded X509 public key certificate</td>
</tr>
</table>
 
'''Return values'''


Returns:
<table border="1">
S_OK Success
<tr>
<0 Fail, return error code.
<th>Result</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>0</td>
<td>S_OK</td>
<td>Success</td>
</tr>
<tr>
<td>< 0</td>
<td>Error code</td>
<td>See error code description</td>
</tr>
</table>


==== Decrypt Digital Envelope ====
==== Decrypt Digital Envelope ====
Line 121: Line 198:
ppOutData:(NSData**) ppOutData;</code>
ppOutData:(NSData**) ppOutData;</code>


Parameters:
'''Parameters'''
[in] pCertificate Public key certificate corresponding to the private key, which is the
decrypting certificate
[in] pPassword Device password
[in] inData Cipher text of digital envelope
[out] ppOutData Original text of digital envelope


Returns:
<table border="1">
S_OK Success
<tr>
<0 Fail, return error code.
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>pCertificate</td>
<td>[in] Public key certificate corresponding to the private key, which is the</td>
</tr>
<tr>
<td>decrypting certificate</td>
</tr>
<tr>
<td>pPassword</td>
<td>[in] Device password</td>
</tr>
<tr>
<td>inData</td>
<td>[in] Cipher text of digital envelope</td>
</tr>
<tr>
<td>ppOutData</td>
<td>[out] Original text of digital envelope</td>
</tr>
</table>
 
'''Return values'''
 
<table border="1">
<tr>
<th>Result</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>0</td>
<td>S_OK</td>
<td>Success</td>
</tr>
<tr>
<td>< 0</td>
<td>Error code</td>
<td>See error code description</td>
</tr>
</table>


==== Digital Sign (including explicit key signature, ordinary signature, SSL handling, and P10 signature) ====
==== Digital Sign (including explicit key signature, ordinary signature, SSL handling, and P10 signature) ====
Line 140: Line 254:
ppOutData:(NSData**) ppOutData;</code>
ppOutData:(NSData**) ppOutData;</code>


Parameters:
'''Parameters'''
[in] pCertificate Public key certificate corresponding to private key, and if RSA
key pairs are just generated, use the public key value returned
from createRSAkey function.
[in] pPassword Device password
[in] srcData Source data to be signed
[in] pHashOID Hash algorithm identification
[out] ppOutData Signed data(PKCS1 format，without adding complementing bits)


Returns:
<table border="1">
S_OK Success
<tr>
<0 Fail, return error code
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<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>
</tr>
<tr>
<td>pPassword</td>
<td>[in] Device password</td>
</tr>
<tr>
<td>srcData</td>
<td>[in] Source data to be signed</td>
</tr>
<tr>
<td>pHashOID</td>
<td>[in] Hash algorithm identification</td>
</tr>
<tr>
<td>ppOutData</td>
<td>[out] Signed data(PKCS1 format&#65292;without adding complementing bits)</td>
</tr>
</table>
 
'''Return values'''
 
<table border="1">
<tr>
<th>Result</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>0</td>
<td>S_OK</td>
<td>Success</td>
</tr>
<tr>
<td>< 0</td>
<td>Error code</td>
<td>See error code description</td>
</tr>
</table>


==== Change a Device Password ====
==== Change a Device Password ====


<code>-(long ) changePassword:(NSData *)pCertificate oldPwd:(NSString *) oldPwd newPwd:(NSString
<code>-(long ) changePassword:(NSData *)pCertificate oldPwd:(NSString *) oldPwd newPwd:(NSString*)newPwd;</code>
*)newPwd;</code>


Parameters:
'''Parameters'''
[in] pCertificate Public key certificate, and if it’s device password, ignore this
parmeters.
[in] oldPwd Old password
[in] newPwd New password


Returns:
<table border="1">
S_OK Success
<tr>
<0 Fail, return error code
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>pCertificate</td>
<td>[in] Public key certificate, and if it’s device password, ignore this parmeters.</td>
</tr>
<tr>
<td>oldPwd</td>
<td>[in] Old password</td>
</tr>
<tr>
<td>newPwd</td>
<td>[in] New password</td>
</tr>
</table>
 
'''Return values'''
 
<table border="1">
<tr>
<th>Result</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>0</td>
<td>S_OK</td>
<td>Success</td>
</tr>
<tr>
<td>< 0</td>
<td>Error code</td>
<td>See error code description</td>
</tr>
</table>


==== Get DER Code of Public Key Certificate ====
==== Get DER Code of Public Key Certificate ====
<code>-(long ) getX509Certificates:(NSArray **) ppCertificates;</code>
<code>-(long ) getX509Certificates:(NSArray **) ppCertificates;</code>


Parameters:
'''Parameters'''
[out] ppCertificates Public key certificate DER coded NSData array
 
<table border="1">
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>ppCertificates</td>
<td>[out] Public key certificate DER coded NSData array</td>
</tr>
</table>


Returns:
'''Return values'''
S_OK Success
 
<0 Fail, return error code
<table border="1">
<tr>
<th>Result</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>0</td>
<td>S_OK</td>
<td>Success</td>
</tr>
<tr>
<td>< 0</td>
<td>Error code</td>
<td>See error code description</td>
</tr>
</table>


==== Get the Remaining Number of Password Attempts ====
==== Get the Remaining Number of Password Attempts ====
Line 182: Line 388:
<code>-(long ) getPwdCanRetries: (NSData *) pCertificate pRemaining :(int *) pRemaining;</code>
<code>-(long ) getPwdCanRetries: (NSData *) pCertificate pRemaining :(int *) pRemaining;</code>


Parameters:
'''Parameters'''
[in] pCertificate Public key certificate, and if it’s the device password, ignore this
 
parameter.
<table border="1">
[out] pRremaining The remaining number of password attempts
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>pCertificate</td>
<td>[in] Public key certificate, and if it’s the device password, ignore this parameter.</td>
</tr>
<tr>
<td>pRremaining</td>
<td>[out] The remaining number of password attempts</td>
</tr>
</table>
 
'''Return values'''


Returns:
<table border="1">
S_OK Success
<tr>
<0 Fail, return error code
<th>Result</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>0</td>
<td>S_OK</td>
<td>Success</td>
</tr>
<tr>
<td>< 0</td>
<td>Error code</td>
<td>See error code description</td>
</tr>
</table>


==== Get a Device ID (the unique ID of a device) ====
==== Get a Device ID (the unique ID of a device) ====
Line 195: Line 429:
<code>-(long ) getDeviceSerialNumber:(NSString **)ppDeviceSN;</code>
<code>-(long ) getDeviceSerialNumber:(NSString **)ppDeviceSN;</code>


Parameters:
'''Parameters'''
[out] ppDeviceSN Device ID
 
<table border="1">
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>ppDeviceSN</td>
<td>[out] Device ID</td>
</tr>
</table>
 
'''Return values'''
 
<table border="1">
<tr>
<th>Result</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>0</td>
<td>S_OK</td>
<td>Success</td>
</tr>
<tr>
<td>< 0</td>
<td>Error code</td>
<td>See error code description</td>
</tr>
</table>
 
=== Error Code Table ===


Returns:
<table border="1">
S_OK Success
<tr>
<0 Fail, return error code
<th>Error Code</th>
2.10 Error Code Table
<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>
</table>

Revision as of 14:20, 28 August 2012


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 OpenSSL (openssl1.0.0e) library file compiled by SecuTech.

Relative Development

Add "Company_product ID" into the name of code file in OC; add "Company_product ID" into the name of C and C++ source code file, function, and global variable to avoid conflict with other companies’ products in the upper compiled.

Realize the main function of the protocol function, and if it has a return value which is released automatically (not alloc), retain must be added.

Development Tools

  • XCODE tools version 4.0 or higher.
  • System default LLVM compiler 3.0.
  • Support iOS SDK version 4.2 or higher (iOS deployment Target: iOS 4.2).
  • Active Architecture: ARM v6.

Interface Definition

Check a Device Connection Status

-(long ) isConnected:(bool *) pConnected;

Parameters

Parameter Description
pConnected [out] If device is connected or not.
Return values
Parameter Description
Result Value Description
0 S_OK Success
< 0 Error code See error code description

Generate a Key-pair

-(long ) createRSAKey:(NSString *) pPassword publicKeyLength:( NSInteger)publicKeyLength ppPublicKey:(NSData **) ppPublicKey

Parameters

Parameter Description
pPassword [in] Device password
publicKeyLength [in] Length of public key (bit), 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 a Public Key Certificate

-(long )importX509Certificate:(NSData *) pCertificate;

Parameters

Parameter Description
pCertificate [in] Der coded X509 public key certificate

Return values

Result Value Description
0 S_OK Success
< 0 Error code See error code description

Decrypt Digital Envelope

-(long ) decryptEnvelopeData: (NSData *) pCertificate pPassword:(NSString *) pPassword inData:( NSData *) inData ppOutData:(NSData**) ppOutData;

Parameters

Parameter Description
pCertificate [in] Public key certificate corresponding to the private key, which is the
decrypting certificate
pPassword [in] Device password
inData [in] Cipher text of digital envelope
ppOutData [out] Original text 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: (NSData *) pCertificate pPassword:(NSString *) pPassword srcData:( NSData *) srcData pHashOID:( NSString *) pHashOID ppOutData:(NSData**) ppOutData;

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.
pPassword [in] Device password
srcData [in] Source data to be signed
pHashOID [in] Hash algorithm identification
ppOutData [out] Signed data(PKCS1 format，without adding complementing bits)

Return values

Result Value Description
0 S_OK Success
< 0 Error code See error code description

Change a Device Password

-(long ) changePassword:(NSData *)pCertificate oldPwd:(NSString *) oldPwd newPwd:(NSString*)newPwd;

Parameters

Parameter Description
pCertificate [in] Public key certificate, and if it’s device password, ignore this parmeters.
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:(NSArray **) ppCertificates;

Parameters

Parameter Description
ppCertificates [out] Public key certificate DER coded NSData array

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: (NSData *) pCertificate pRemaining :(int *) pRemaining;

Parameters

Parameter Description
pCertificate [in] Public key certificate, and if it’s the device password, ignore this parameter.
pRremaining [out] The remaining number of password attempts

Return values

Result Value Description
0 S_OK Success
< 0 Error code See error code description

Get a Device ID (the unique ID of a device)

-(long ) getDeviceSerialNumber:(NSString **)ppDeviceSN;

Parameters

Parameter Description
ppDeviceSN [out] Device ID

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