UniMate API Reference for C Language - Revision history

Bao: Readded Android specific details

2016-08-10T00:43:03Z

Readded Android specific details

← Older revision		Revision as of 11:43, 10 August 2016
Line 2:		Line 2:

	== UniMate Mobile Certificate API Reference ==		== UniMate Mobile Certificate API Reference ==
			This document generally refers to the use of the C language with Android systems, however, there are some function headers and such listed in here that are specific to Windows. If so, it will be noted above.

	=== Relative Convention ===		=== Relative Convention ===

			==== Character Encoding ====

			All string parameters use the UTF-8 coding standard.

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

	All return values from functions are of type unsigned long.		All return values from functions are of type long and type unsigned long for WIndows.

	0 refers to success, whereas a value < 0 indicates an error.		0 refers to success, whereas a value < 0 indicates an error.
Line 22:		Line 27:
	</pre>		</pre>

	as defined by the struct:		<b>Windows Only:</b> as defined by the struct:

	<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">		<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">
Line 40:		Line 45:
	} PUB_KEY, *PUB_KEY_PTR;		} PUB_KEY, *PUB_KEY_PTR;
	</source>		</source>

			==== Hash Algorithm Identification ====

			<code>pHashOID</code> is the identification string of each hash algorithm, and the specific algorithm IDs are listed in the following table.

			<table class="wikitable">
			<tr>
			<th>ID</th>
			<th>Specification</th>
			</tr>
			<tr>
			<td>1.3.14.3.2.26</td>
			<td>SHA1 Algorithm</td>
			</tr>
			<tr>
			<td>2.16.840.1.101.3.4.2.1</td>
			<td>SHA256 Algorithm</td>
			</tr>
			</table>

	==== Ease of Use Convention ====		==== Ease of Use Convention ====
	<!--Review-->		<!--Review-->
	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.		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. This library should support Android v2.1 and later.

	==== Relative Development ====		==== Relative Development ====
Line 50:		Line 78:
	# Interfaces with binary returns, such as <code>SignData</code>, 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.		# Interfaces with binary returns, such as <code>SignData</code>, 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.
	# All passed <code>char *</code> type parameters shall be ended with ‘\0’ (null character), and the length can be calculated directly.		# All passed <code>char *</code> 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 ====		==== Type Definition ====

			<b>Android</b>
			<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">
			typedef unsigned char byte;
			typedef byte *pbyte;
			</source>

			<b>Windows</b>
	<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">		<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">
	typedef unsigned long DHANDLE, *DHANDLE_PTR;		typedef unsigned long DHANDLE, *DHANDLE_PTR;
Line 66:		Line 105:

	<!-- Consider changing to denote the C function headers as defined in the sample, but as they don't mirror each other, wait for a description of each function and go from there -->		<!-- Consider changing to denote the C function headers as defined in the sample, but as they don't mirror each other, wait for a description of each function and go from there -->
	Here are the C function headers as defined in the UniMate.h file in the UniMate STD SDK Windows Device Samples. For the function descriptions below, these headers, ~~the~~ Android ~~header file can be used as a guide~~.		Here are the C function headers as defined in the UniMate.h file in the UniMate STD SDK Windows Device Samples. For the function descriptions below, these headers, they are defined for Android systems.

	<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">		<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">

Bao: Added function headers from win samples folder on UniMate STD SDK, didn't add descriptions though.

2016-08-10T00:33:46Z

Added function headers from win samples folder on UniMate STD SDK, didn't add descriptions though.

@@ Line 4: / Line 4: @@
 === Relative Convention ===
 ==== Return Value ====
@@ Line 44: / Line 40: @@
 } PUB_KEY, *PUB_KEY_PTR;
 </source>
 ==== Ease of Use Convention ====
 <!--Review-->
 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.
 ==== Relative Development ====
-<!-- Which C Standard -->
+<!-- Which C Standard (at minimum it would probably be C89/90 due to Windows) -->
 # Functions, variables, et al. shall comply with the C standard.
 # Interfaces with binary returns, such as <code>SignData</code>, 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.
 # All passed <code>char *</code> type parameters shall be ended with ‘\0’ (null character), and the length can be calculated directly.
 ==== Type Definition ====
-<pre>
+<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">
-typedef	unsigned char	byte;
+typedef unsigned long  DHANDLE,  *DHANDLE_PTR;
-typedef	byte		*pbyte;
+typedef unsigned char  CK_BYTE,  *CK_BYTE_PTR;
-</pre>
+typedef unsigned short CK_FID;
 === Interface Definition ===
 ==== Check Device Connection Status ====

Bao: /* Public Key Format */

2016-08-09T23:36:29Z

Public Key Format

@@ Line 17: / Line 17: @@
 ==== Public Key Format ====
-<code>pPublicKey</code> is compatible with the RFC 3447 specification.
+<code>PUB_KEY</code> is compatible with the RFC 3447 specification.
 <pre>
@@ Line 25: / Line 25: @@
+}
 </pre>
 ==== Hash Algorithm Identification ====

Bao: /* Return Value */

2016-08-09T23:28:57Z

Return Value

← Older revision		Revision as of 10:28, 10 August 2016
Line 11:		Line 11:
	==== Return Value ====		==== Return Value ====

	All return values from functions are of type long.		All return values from functions are of type unsigned long.

	0 refers to success, whereas < 0 indicates an error ~~code~~.		0 refers to success, whereas a value < 0 indicates an error.

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

Bao: Adjusted tables

2016-07-06T05:11:29Z

Adjusted tables

← Older revision		Revision as of 16:11, 6 July 2016
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>

Bao: Spaced function headers apart one line

2016-07-05T05:27:35Z

Spaced function headers apart one line

← Older revision		Revision as of 16:27, 5 July 2016
Line 108:		Line 108:
	</tr>		</tr>
	</table>		</table>


	==== Generate RSA Key Pair ====		==== Generate RSA Key Pair ====
Line 153:		Line 154:
	</tr>		</tr>
	</table>		</table>


	==== Import Public Key Certificate ====		==== Import Public Key Certificate ====
Line 194:		Line 196:
	</tr>		</tr>
	</table>		</table>


	==== Decrypt Digital Envelope ====		==== Decrypt Digital Envelope ====
Line 255:		Line 258:
	</tr>		</tr>
	</table>		</table>


	==== Sign Data ====		==== Sign Data ====
Line 322:		Line 326:
	</tr>		</tr>
	</table>		</table>


	==== Change Password ====		==== Change Password ====
Line 371:		Line 376:
	</tr>		</tr>
	</table>		</table>


	==== Get DER Code of Public Key Certificate ====		==== Get DER Code of Public Key Certificate ====
Line 416:		Line 422:
	</tr>		</tr>
	</table>		</table>


	==== Get the Remaining Number of Password Login Attempts ====		==== Get the Remaining Number of Password Login Attempts ====
Line 461:		Line 468:
	</tr>		</tr>
	</table>		</table>


	==== Get Device Serial Number ====		==== Get Device Serial Number ====

Bao: /* Get Device Serial Number */

2016-07-05T05:23:01Z

Get Device Serial Number

← Older revision		Revision as of 16:23, 5 July 2016
Line 480:		Line 480:
	</tr>		</tr>
	<tr>		<tr>
	<td>~~[out]~~ lpDeviceSNLen</td>		<td>lpDeviceSNLen</td>
	<td>[out] Length of device serial number</td>		<td>[out] Length of device serial number</td>
	</tr>		</tr>

Bao: /* Get the Remaining Number of Password Login Attempts */

2016-07-05T05:22:04Z

Get the Remaining Number of Password Login Attempts

← Older revision		Revision as of 16:22, 5 July 2016
Line 434:		Line 434:
	<tr>		<tr>
	<td>lCertificateLen</td>		<td>lCertificateLen</td>
	<td>Public key length. If inputting the device password, ignore this parameter</td>		<td>[in] Public key length. If inputting the device password, ignore this parameter</td>
	</tr>		</tr>
	<tr>		<tr>

Bao: /* Change Password */

2016-07-05T05:21:32Z

Change Password

← Older revision		Revision as of 16:21, 5 July 2016
Line 340:		Line 340:
	<tr>		<tr>
	<td>lCertificateLen</td>		<td>lCertificateLen</td>
	<td>[in] Public key length, ~~and~~ if pCertificate is the device's password~~, ignore this parameter~~</td>		<td>[in] Public key length, ignore this parameter if pCertificate is the device's password</td>
	</tr>		</tr>
	<tr>		<tr>

Bao: /* Get the Remaining Number of Password Login Attempts */

2016-07-05T05:20:46Z

Get the Remaining Number of Password Login Attempts

← Older revision		Revision as of 16:20, 5 July 2016
Line 419:		Line 419:
	==== Get the Remaining Number of Password Login Attempts ====		==== Get the Remaining Number of Password Login Attempts ====

	<code>long GetPwdCanRetries(pbyte pCertificate, long lCertificateLen, int*ipRemaining);</code>		<code>long GetPwdCanRetries(pbyte pCertificate, long lCertificateLen, int *ipRemaining);</code>

	'''Parameters'''		'''Parameters'''