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 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