UniMate API Reference for Objective-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 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. |
| 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 |
