Login

Signing

Table of Contents

1. Introduction

This is a general walk-through for getting start iAM Smart APIs development of Signing use case.

Developers of Online Services adopting iAM Smart may find this guide useful when designing and developing application flows for digital signing adopting iAM Smart functions.

In this guide we will provide guides on: 

  • Setting up your iAM Smart development environment
  • Request Signing
  • Open iAM Smart Mobile App for Getting Context
  • Online Service Acknowledge Signing Result

2. User Journey

3. Flow

Please find below the sequence diagram for the whole digital signing process:

4. Request Signing

4.1 Click sign by “iAM Smart”

UI Display

Online service shall display the following buttons:

Digital Signing
Traditional Chinese智方便數碼簽署
Simplified Chinese智方便数码签署
EnglishSigning with iAM Smart
Sample Button for Digital Signing
Traditional Chinese
Simplified Chinese
English
Open “iAM Smart”
UsageThe button for user open specific authorisation page in “iAM Smart” mobile app.
Traditional Chinese開啟智方便
Simplified Chinese开启智方便
EnglishOpen iAM Smart
Sample Button for Open iAM Smart
Traditional Chinese
Simplified Chinese
English

Tip

Please note that the request shall be initiated after the user clicked the “Signing with iAM Smart” button.

Online service is required to add a link / button, “More info” or “了解更多” in the initiation page. The link / button shall be linked to the “iAM Smart” thematic webpage based on language preference of user.  The initiation page refers to the page that initiates the “iAM Smart” service, which user clicks the “iAM Smart” button to initiate the interaction with “iAM Smart” mobile application.

Language

Link

English

https://www.iamsmart.gov.hk/en/

Traditional Chinese

https://www.iamsmart.gov.hk/tc/

Simplified Chinese

https://www.iamsmart.gov.hk/sc/

4.2 Composing Request Body

ParameterTypePresenceDescription
businessIDStringRequiredbusinessID is a unique identifier for online service to differentiate different request. It should be ASCII string with length less than or equal to 36 chars.
accessTokenStringRequiredaccessToken value
openIDStringRequiredTokenised ID value
sourceStringRequiredRequest initiator. The supported source values can be found in part 0 of the Appendix in this specification.
redirectURIStringRequiredcallback URI.
stateStringOptionalIf state parameter is presented in the request message, the same state value will be returned to online service during callback. It is used to prevent the CSRF attack. The value of state is defined by online service and it should be a secure random value. It can be an ASCII string of any length less than or equal to 36 (UUID string length). Only ASCII letters, numbers, underscore and hyphen are accepted.
hashCodeStringRequiredThe document hash to be signed. Online service should compute the hash and send this hash to iAM Smart System for signing. The value should be Base64 encoded.
sigAlgoStringOptional

signature algorithm to be used.  Online service can specify either SHA256withRSA or NONEwithRSA. The default value is SHA256withRSA.

While using NONEwithRSA, hashCode provided must be hashed with SHA256.

HKICHashStringOptional

Signing request will only be processed when the hash of the HKIC number of the iAM Smart user is matched with the HKICHash provided by online service. Online service should convert the HKIC number into hash value using SHA256 before sending to iAM Smart System.  

Only the identifier of HKIC number will be hashed, no check digit is needed e.g. A123456.

The value should be Base64 encoded.

departmentStringOptionalthe department that initiates the signing request
serviceNameStringRequiredThe service name
documentNameStringRequiredThe document name that the user is going to sign

Your request body should look something like this:

				
					{
    "businessID": "bbb8aae57c104cda40c93843ad5e6db8",
    "accessToken": "xxxa42e76bf4cb0846a68e6d83d6096",
    "openID": "liR14%2BvX%2F5hSum5uf4ERczu0KcDnIJA5BM7FoM1ag9c%3D",
    "source": "Android_Chrome",
    "redirectURI": "https://<rp_domain>/<rp_context>/<call_back_endpoint>",
    "state": "eddd527b6",
    "hashCode": " 965e638fda4c70f667efc2d68c40c6111e5965bfc82356d",
    "HKICHash": " 6ea37e641260714009a880a8057032a414009a80f667efc",
"department": " Office of the Government Chief Information Officer",
    "serviceName": "OnlinOnline Service1",
    "documentName": "Doc0001"
}

As an additional layer of data encryption will be applied to all APIs POST request, please follow section 4.5.1.1(Login with iAM Smart) to construct the encrypted request header and request body.

Upon success you should receive the encrypted response:

				
					{
  "txID": "<T=938ffb193b4b4370b6c2584372c6a588>",
  "code": "D00000",
  "message": "SUCCESS",
"content":"AAAADLzOxAK6KCtIQgl/BJRVECazUaNiaf13rfcGNApA3K0BI0qZkB5pMWAjcTF0z0PLOnsCyxCtVUytAbA/cm2U5W83FrRXvtZZ74SrCWY4cQiAlq38TLSeOY9B418Tc5dUr1JnbCVeHe8HNrEY81QyI3r7JMZfXGaWgRoz0os8C7zbzty88vPGPSmBE7WqZF5I84IJ7wzwpRs+ifz9DfpFqWzj55mftTHQERWDhcKRALgdZECoFCqtmNhRFERxAm+MrIkypZG/JAdcho0cLyIGTkw7KLqKT0/NmQgQ3vsi6IxGOF4u8gPfLHfRkLopZkU7sXXHNC5hVtEmGXz0zrp+Pq9diKIX6MyrAtwjhIxxKu5iI9MO7XB272hpeonpJYWA0dvh0F882tjNnN6oRJrQ1ZxPXfeA"

Decryption

Please refer to section 4.5.2.1 for decryption of the content data, and you should get the following result:

				
					{
  "txID": "<T=938ffb193b4b4370b6c2584372c6a588>",
  "code": "D00000",
  "message": "SUCCESS",
  "content": {
    "authByQR": true
  }
}

Calculate identification code

After submitting signing request by sending access token, hash and tokenized ID, iAM Smart core system will acknowledge signing request and send response to Online Service server. When iAM Smart user has logged in the Online Service, both Online Service and iAM Smart System will compute and display a 4-digit identification code using the Document Hash and the hash of Tokenised ID of the iAM Smart.

4-digit identification code generation algorithm is as follows:

  1. Concatenate the Document Hash and the Tokenised ID hash value (calculated with SHA-512), and perform the digital digest for the concatenation result with SHA-512.
  2. Perform the MD5 calculation to obtain a unique MD5 hash value.
  3. Divide the 128-bit MD5 hash value into four groups of 4 bytes binary value and then extract the first byte from each group as a data sample.
  4. Perform 4-bit unsigned right shift to each byte of the result obtained above for the hexadecimal data.
  5. Perform the modulo operation on each byte (modulo 10) to obtain a number of 0-9.
  6. Assemble the 4 numbers obtained above as a 4-digit identification code.

You may refer the pseudo code below for the calculation of identification code:

private static final char hexDigits[] = {‘0’, ‘1’, ‘2’, ‘3’, ‘4’, ‘5’, ‘6’, ‘7’, ‘8’, ‘9’};

public static String getSignCode (String hashCode, String openlD) {

// Assume Document Hash is BASE64 encoded and perform decode

byte[] hashCodeBytes = Base64Util.base64Decode(hashCode);

// Calculate SHA-512 hashcode of Tokenised ID

byte[] openlDBytes = DigestUtil.digestToByte(openlD, Alg.SHA512);             

char code[] = new char [4];

byte[] source = new byte[hashCodeBytes.length + openlDBytes.length];

System.arraycopy(hashCodeBytes, 0, source, 0, hashCodeBytes.length);

System.arraycopy(openlDBytes, 0, source, hashCodeBytes.length, openlDBytes.length);

// Calculate SHA-512 hashcode from concatenated Document Hash and 

// SHA-512 hashed Tokenised ID

byte[] inData = DigestUtil.digestToByte(source, Alg.SHA512);                         

// Calculate MD% hashcode 

byte[] digestMD5Data = DigestUtil.digestToByte(inData, Alg.MD5);              

// Convert MD5 value 4-digit identification code 

for (int i = 0; i < 4; i++) {

code[i] = hexDigits[(digestMD5Data[i * 4] >>> 4 & 0xf) ％ 10];

return new String(code);

}

 

				
					private static final char hexDigits[] = {‘0’, ‘1’, ‘2’, ‘3’, ‘4’, ‘5’, ‘6’, ‘7’, ‘8’, ‘9’};
public static String getSignCode (String hashCode, String openlD) {
// Assume Document Hash is BASE64 encoded and perform decode
byte[] hashCodeBytes = Base64Util.base64Decode(hashCode);
// Calculate SHA-512 hashcode of Tokenised ID
byte[] openlDBytes = DigestUtil.digestToByte(openlD, Alg.SHA512);             
char code[] = new char [4];
byte[] source = new byte[hashCodeBytes.length + openlDBytes.length];
System.arraycopy(hashCodeBytes, 0, source, 0, hashCodeBytes.length);
System.arraycopy(openlDBytes, 0, source, hashCodeBytes.length, openlDBytes.length);
// Calculate SHA-512 hashcode from concatenated Document Hash and 
// SHA-512 hashed Tokenised ID
byte[] inData = DigestUtil.digestToByte(source, Alg.SHA512);                         
// Calculate MD% hashcode 
byte[] digestMD5Data = DigestUtil.digestToByte(inData, Alg.MD5);              
// Convert MD5 value 4-digit identification code 
for (int i = 0; i < 4; i++) {
	code[i] = hexDigits[(digestMD5Data[i * 4] >>> 4 & 0xf) ％ 10];
return new String(code);
}
Note
Please note that the pseudo code ONLY aims for reference and shall provide NO SUPPORT for any issue on the pseudo code.

Instruction Page for requesting signing

After Online Service sends the initiate signing request to “iAM Smart” system, Online Service is required to instruct to open the “iAM Smart” app in his/her mobile phone. Please refer to the table below for different scenarios.

Online service name
Document name
Identification code
Traditional Chinese識別碼: [9999]
Simplified Chinese识别码: [9999]
EnglishIdentification code: [9999]
Instructions
Traditional Chinese

請按照以下步驟:

  1. 記錄上述文件資料及識別碼
  2. 開啟手機上的「智方便」
  3. 核對「智方便」內顯示的文件資料及識別碼，然後完成數碼簽署

請按照以下步驟:

  1. 記錄上述文件資料及識別碼
  2. 開啟手機上的「智方便」並掃描二維碼
  3. 核對「智方便」內顯示的文件資料及識別碼，然後完成數碼簽署
Simplified Chinese

请按照以下步骤：

  1. 记录上述文件资料及识别码
  2. 开启手机上的「智方便」
  3. 核对「智方便」内显示的文件资料及识别码，然后完成数字签署

请按照以下步骤：

  1. 记录上述文件资料及识别码
  2. 开启手机上的「智方便」并扫描二维码
  3. 核对「智方便」内显示的文件资料及识别码，然后完成数字签署
English

Please follow the steps below:

  1. Record the above information and identification code
  2. Open “iAM Smart” in mobile device
  3. Check the document information and identification code in “iAM Smart” and complete the digital signing

Please follow the steps below:

  1. Record the above information and identification code
  2. Open “iAM Smart” in mobile device and scan the QR code
  3. Check the document information and identification code in “iAM Smart” and complete the digital signing
Example 

5. Open iAM Smart Mobile App for Getting Context

When iAM Smart Mobile App is opened, Online Service Website should keep synchronising with Online Service for signing processing result, such as polling. Online Service Website/app invokes iAM Smart Mobile App using URL Scheme with “ticketID” (set <Context> as “hash-sign or “pdf-sign” in URL Scheme).

Construct the URL Scheme

Parameter

Type

Presence

Description

ticketID

String

Required

TicketID is a unique identifier provided by iAM Smart Core System, Online Service retrieve ticketID while requesting the context (Profile / Signing / Form Filling / Re-authentication). It is ASCII string with length less than or equal 36 chars. 

source

String

Required

(Conditional)

This parameter is required only in anonymous form filling or anonymous signing workflows. 

Request initiator (App_Scheme, App_Link).

The detail of supported source values can be found in Appendex B of this specification. 

redirectURI

String

Required

(Conditional)

callback redirect URI. This parameter is required only in anonymous form filling or anonymous signing workflows and its value should be URL encoded.

state

String

Required

(Conditional)

If state parameter is presented in the request message, the same state value will be returned to Online Service during callback. It is used to prevent the CSRF attack. The value of state is defined by Online Service and it should be a secure random string of any length less than or equal to 36 (UUID string length). Only ASCII letters, numbers, underscore and hyphen are accepted.

You request scheme should be something as following:

				
					hk.gov.ogcio://hash-sign
?ticketID=bbb8aae57c104cda40c93843ad5e6db8

6. Callback to Receive Signing Result

After iAM Smart user logs in iAM Smart Mobile App, reviews the signing authorisation request (e.g. continue or reject the request) and verify the 4-digit identification code with Online Service Website/app. iAM Smart user follows the instructions in iAM Smart Mobile App to complete signing operation. iAM Smart System invokes Online Service callback API to return the result with “businessID” of the signing request to Online Service server.

Callback Parameters

Parameter

Type

Presence

Description

businessID

String

Required

businessID is a unique identifier for Online Service to differentiate different request. Online Service can use the businessID to relate the callback message with the original request.

state

String

Optional

If the state parameter has been present in the request message, the exact value of state will be returned. It is used to prevent the CSRF attack. The value of state is defined by Online Service and it should be a secure random value.

hashCode

String

Optional

The document hash submitted by Online Service in the API request 

timestamp

Long

Optional

Timestamp in milliseconds since January 1, 1970 00:00:00 GMT. iAM Smart System will provide this to Online Service only when signing is successful.

signature

String

Optional

Base64-encoded signature result string. iAM Smart System will provide this to Online Service only when signing is successful.

cert

String

Optional

Base64-encoded DER format certificate for the iAM Smart user. iAM Smart System will provide this to Online Service only when the signing is successful.

Upon success you should receive the encrypted response:

				
					{
  "txID": "<T=938ffb193b4b4370b6c2584372c6a588>",
  "code": "D00000",
  "message": "SUCCESS",
  "content": {
"businessID": "2YotnFZFEjr1zCsicMWpAA",
"state": "unesidkd",
"hashCode": "tGzv3JOkF0XG5Qx2TlKWIA",
"timestamp": 1556450176000,
"signature": "nnoadisauflanefhykdjf",
"cert": "sdfGSDGsdfaGDEHfjslgGQG……GSGjljlkjwmh",
  }
}

Decryption

Please refer to section 4.5.2.1 for decryption of the content data, and you should get the following result:

				
					{
  "txID": "<T=938ffb193b4b4370b6c2584372c6a588>",
  "code": "D00000",
  "message": "SUCCESS",
  "content": {
"businessID": "2YotnFZFEjr1zCsicMWpAA",
"state": "unesidkd",
"hashCode": "tGzv3JOkF0XG5Qx2TlKWIA",
"timestamp": 1556450176000,
"signature": "nnoadisauflanefhykdjf",
"cert": "sdfGSDGsdfaGDEHfjslgGQG……GSGjljlkjwmh",
  }
}

7. Online Service Acknowledge Signing Result

Online Service Server completes the document signing process, verify the result and acknowledges iAM Smart System the signing result using iAM Smart API with the same “businessID” of the signing request.

You may refer the pseudo code below for the verification of signing result:

				
					public static boolean verifySignature(PublicKey publicKey, String algName, byte[] signatureByte, byte[] hash) {
        boolean isCorrect = false;
        try {
            Signature signature = Signature.getInstance(algName);
            signature.initVerify(publicKey);
            signature.update(hash);
            isCorrect = signature.verify(signatureByte);
        } catch (NoSuchAlgorithmException | InvalidKeyException | SignatureException e) {
            e.printStackTrace();
        } 
        return isCorrect;
    }

Composing Request body

Parameter

Type

Presence

Description

businessID

String

Required

businessID is a unique identifier for Online Service to differentiate different request. It should be ASCII string with length less than or equal to 36 chars.

signingResult

String

Required

“SR001”: digital signature is accepted

“SR002”: digital signature is rejected

“SR003”: no digital signature was received

Your request body should look something like this:

				
					https://<iAM_Smart_domain>/api/v1/account/signing/ackResult 
// Request Headers
clientID: "edae2e2529ff46228af1e4d18c8405d1"
signatureMethod: "HmacSHA256"
signature: "5X42Y1B7MEd8Mm%2BonwjiQz9VCZkkrntADskXsYntavU%3D"
timestamp: 1557048906183
nonce: "e893647dc4204eb9b7b8eddd527b687c"
// Request Body
{
"businessID": "bbb8aae57c104cda40c93843ad5e6db8",
"signingResult": "SR001",
}

As an additional layer of data encryption will be applied to all APIs POST request, please follow section 4.5.1.1(Login with iAM Smart) to construct the encrypted request header and request body.

Upon success you should receive the encrypted response:

				
					{
  "txID": "<T=938ffb193b4b4370b6c2584372c6a588>",
  "code": "D00000",
  "message": "SUCCESS"
}

Decryption

Please refer to section 4.5.2.1 for decryption of the content data, and you should get the following result:

				
					{
  "txID": "<T=938ffb193b4b4370b6c2584372c6a588>",
  "code": "D00000",
  "message": "SUCCESS"
}

Online Service Server matches the result using the “businessID” and shows the signing result in corresponding Online Service Website.