UniMate API Reference for Objective-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 are using utf-8 coding..."
 
Bao (talk | contribs)
0 edits
mNo edit summary
 
(28 intermediate revisions by 2 users not shown)
Line 5: Line 5:
=== Relative Convention ===
=== Relative Convention ===


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


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 function return values are of type long.
 
0 refers to success, whereas < 0 indicates some error has occurred.


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


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


<pre>
<pre>
RSAPublicKey ::= SEQUENCE {
RSAPublicKey ::= SEQUENCE {
     modulus INTEGER -- n
     modulus INTEGER -- n
     publicExponent INTEGER -- e
     publicExponent INTEGER -- e
}
}
</pre>
</pre>
Line 26: Line 28:
==== 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>
<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 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 Openssl(openssl1.0.0e) library file compiled by SecuTech.
If using the encrypt library, please use the 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 the code file in Objective-C, add "Company_product ID" into the name of the C and C++ source code file, function, and global variable to avoid conflict with any other company's products during compilation.


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.
Consider the main function of the prototype function, and if it has a return value which is released automatically (not alloc'ed), if so, retain must be added.


==== 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 Device Connection Status ====


<code>-(long ) isConnected:(bool *) pConnected;</code>
<code>-(long) isConnected:(bool *) pConnected;</code>


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


Returns:
<table class="wikitable">
S_OK Success
<tr>
< 0 Fail, return error code
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>pConnected</td>
<td>[out] Device connection status</td>
</tr>
</table>


==== Generate a Key-pair ====
'''Return values'''


<code>-(long ) createRSAKey:(NSString *) pPassword publicKeyLength:( NSInteger)publicKeyLength ppPublicKey:(NSData **) ppPublicKey</code>
<table class="wikitable">
<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>


Parameters:
[in] pPassword Device password
[in] publicKeyLength Length of public key (bit), 1024 or 2048
[out] ppPublicKey Public key of the generated key-pair (format comply with the
coding specification described in this document)


Returns:
==== Generate RSA Key Pair ====
S_OK Success
<0 Fail, return error code.


==== Import a Public Key Certificate ====
<code>-(long) createRSAKey:(NSString *) pPassword publicKeyLength:(NSInteger) publicKeyLength ppPublicKey:(NSData **) ppPublicKey;</code>


<code>-(long )importX509Certificate:(NSData *) pCertificate;</code>
'''Parameters'''


Parameters:
<table class="wikitable">
[in] pCertificate Der coded X509 public key certificate
<tr>
<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: 1024 or 2048 bits</td>
</tr>
<tr>
<td>ppPublicKey</td>
<td>[out] Public key of the generated key-pair (format complies with the coding specification described in this document)</td>
</tr>
</table>


Returns:
'''Return values'''
S_OK Success
 
<0 Fail, return error code.
<table class="wikitable">
<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>
 
 
==== Import Public Key Certificate ====
 
<code>-(long) importX509Certificate:(NSData *) pCertificate;</code>
 
'''Parameters'''
 
<table class="wikitable">
<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'''
 
<table class="wikitable">
<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>


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


<code>-(long ) decryptEnvelopeData: (NSData *) pCertificate
<code>-(long) decryptEnvelopeData:(NSData *) pCertificate
pPassword:(NSString *) pPassword
pPassword:(NSString *) pPassword
inData:( NSData *) inData
inData:(NSData *) inData
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 class="wikitable">
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; the 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] Plain text of digital envelope</td>
</tr>
</table>


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


<code>-(long ) signData: (NSData *) pCertificate
<table class="wikitable">
<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>
 
==== Sign Data ====
 
Includes explicit key signature, ordinary signature, SSL handling, and P10 signature.
 
<code>-(long) signData:(NSData *) pCertificate
pPassword:(NSString *) pPassword
pPassword:(NSString *) pPassword
srcData:( NSData *) srcData
srcData:(NSData *) srcData
pHashOID:( NSString *) pHashOID
pHashOID:(NSString *) pHashOID
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 class="wikitable">
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. If using RSA generated key pairs, use the public key value returned from the 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 (PKCS#1 format, without adding complementing bits)</td>
</tr>
</table>


==== Change a Device Password ====
'''Return values'''


<code>-(long ) changePassword:(NSData *)pCertificate oldPwd:(NSString *) oldPwd newPwd:(NSString
<table class="wikitable">
*)newPwd;</code>
<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 Password ====
 
<code>-(long) changePassword:(NSData *) pCertificate oldPwd:(NSString *) oldPwd newPwd:(NSString *) newPwd;</code>


Parameters:
'''Parameters'''
[in] pCertificate Public key certificate, and if it’s device password, ignore this
 
parmeters.
<table class="wikitable">
[in] oldPwd Old password
<tr>
[in] newPwd New password
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>pCertificate</td>
<td>[in] Public key certificate. If inputting device password, ignore this parameter</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 class="wikitable">
<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>


Returns:
S_OK Success
<0 Fail, return error code


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


Parameters:
<code>-(long) getX509Certificates:(NSArray **) ppCertificates;</code>
[out] ppCertificates Public key certificate DER coded NSData array


Returns:
'''Parameters'''
S_OK Success
<0 Fail, return error code


==== Get the Remaining Number of Password Attempts ====
<table class="wikitable">
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>ppCertificates</td>
<td>[out] Public key certificate DER coded NSData array</td>
</tr>
</table>
 
'''Return values'''
 
<table class="wikitable">
<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>


<code>-(long ) getPwdCanRetries: (NSData *) pCertificate pRemaining :(int *) pRemaining;</code>


Parameters:
==== Get the Remaining Number of Password Login Attempts ====
[in] pCertificate Public key certificate, and if it’s the device password, ignore this
parameter.
[out] pRremaining The remaining number of password attempts


Returns:
<code>-(long) getPwdCanRetries:(NSData *) pCertificate pRemaining:(int *) pRemaining;</code>
S_OK Success
<0 Fail, return error code


==== Get a Device ID (the unique ID of a device) ====
'''Parameters'''


<code>-(long ) getDeviceSerialNumber:(NSString **)ppDeviceSN;</code>
<table class="wikitable">
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>pCertificate</td>
<td>[in] Public key certificate. If inputting the device password, ignore this parameter</td>
</tr>
<tr>
<td>pRremaining</td>
<td>[out] Remaining number of password attempts</td>
</tr>
</table>


Parameters:
'''Return values'''
[out] ppDeviceSN Device ID


Returns:
<table class="wikitable">
S_OK Success
<tr>
<0 Fail, return error code
<th>Result</th>
2.10 Error Code Table
<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 Serial Number ====
 
The serial number is the device's unique ID.
 
<code>-(long) getDeviceSerialNumber:(NSString **) ppDeviceSN;</code>
 
'''Parameters'''
 
<table class="wikitable">
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>ppDeviceSN</td>
<td>[out] Device serial number</td>
</tr>
</table>
 
'''Return values'''
 
<table class="wikitable">
<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 a Random Number ====
Provide a randomly generated number.
 
<code>-(long) getRandomNumber:(NSString **) randomNum ran_len:(unsigned long) ran_len;</code>
 
'''Parameters'''
 
<table class="wikitable">
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>ran_len</td>
<td>[in] Random number length</td>
</tr>
<tr>
<td>randomNum</td>
<td>[out] Random number generated</td>
</tr>
</table>
 
'''Return values'''
 
<table class="wikitable">
<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>

Latest revision as of 13:54, 10 August 2016


UniMate Mobile Certificate API Reference

Relative Convention

Character Encoding

All string parameters use the UTF-8 coding standard.

Return Value

All function return values are of type long.

0 refers to success, whereas < 0 indicates some error has occurred.

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

Relative Development

Add "Company_product ID" into the name of the code file in Objective-C, add "Company_product ID" into the name of the C and C++ source code file, function, and global variable to avoid conflict with any other company's products during compilation.

Consider the main function of the prototype function, and if it has a return value which is released automatically (not alloc'ed), if so, 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 Device Connection Status

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

Parameters

Parameter Description
pConnected [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:(NSString *) pPassword publicKeyLength:(NSInteger) publicKeyLength ppPublicKey:(NSData **) ppPublicKey;

Parameters

Parameter Description
pPassword [in] Device password
publicKeyLength [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:(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; the decrypting certificate
pPassword [in] Device password
inData [in] Cipher text of digital envelope
ppOutData [out] 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:(NSData *) pCertificate pPassword:(NSString *) pPassword srcData:(NSData *) srcData pHashOID:(NSString *) pHashOID ppOutData:(NSData **) ppOutData;

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

Return values

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

Change Password

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

Parameters

Parameter Description
pCertificate [in] Public key certificate. If inputting 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:(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 Login Attempts

-(long) getPwdCanRetries:(NSData *) pCertificate pRemaining:(int *) pRemaining;

Parameters

Parameter Description
pCertificate [in] Public key certificate. If inputting the device password, ignore this parameter
pRremaining [out] Remaining number of password attempts

Return values

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

Get a Device Serial Number

The serial number is the device's unique ID.

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

Parameters

Parameter Description
ppDeviceSN [out] Device serial number

Return values

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

Get a Random Number

Provide a randomly generated number.

-(long) getRandomNumber:(NSString **) randomNum ran_len:(unsigned long) ran_len;

Parameters

Parameter Description
ran_len [in] Random number length
randomNum [out] Random number generated

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_Objective-C_Language&oldid=2561"