Using Local signing - API - Transaction (text) signing using NetID Access

Overview

To use the API, two methods must be called. The first API method call is to trigger the signing. This will return a transaction ID value. The second API method call will poll the status of the signing. The API client must poll until a status=COMPLETE or an error is returned.

Prerequisites

- PhenixID Signing Service Transaction Signing API configured

- NetID Access client

- NetID Access certificate enrolled

- If PhenixID Signing Service Transaction Signing API is protected with client certificate authentication: Client certificate (p12)

- If PhenixID Signing Service Transaction Signing API is protected with basic authentication: Username and password

Trigger signing - data to be fetched before api call

To trigger signing, the api client must fetch these values:

- UserID (UserID, matching the Subject-serialnumber of the certificate enrolled)

- Data to be signed that should be displayed to the user

For more information about signatures, formats etc, please view SecMaker NetID Access documentation.

Trigger signing - api call

Request

Method: HTTP PUT

Endpoint: /api/sign/NIASStartSign

Headers:

Name Value
Mandatory Comment
Content-Type application/json Yes
tenant t1 Yes Value must be given to you by PhenixID Signing Service admin, it might differ depending on the environment.
Authorization <basic_auth_value> No If applicable, username and password must be given to you by PhenixID Signing Service admin.

Body:

The body must contains a json structure.

{
"userid":"..",
"userVisibleData":".."
} 

Json structure properties:

Name Value Mandatory Comment
userid <user identification> Yes UserID. Must match the value of the subject-serial of the certificate enrolled.
userVisibleData
<Data to be signed that will be displayed to the user in the NetID Access client> Yes Please view Secmaker NetID Access documentation for recommendations.

Example request (Please note that authorization data is not included in this example).

 

PUT /api/sign/NIASStartSign HTTP/1.1
Host: example.org
Content-Type: application/json
tenant: t1 

Cache-Control: no-cache
{
  "userid":"191212121212", 
  "userVisibleData": "This is the data to be signed that will be displayed in the NIAS client" 
}

Response

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3900
{
  "transactionID":"829b3b56-5a0a-449f-8dc8-50e6772c076f"
}

Collect signature - use transactionID

The API client must fetch the transactionID returned by the Trigger sign call.

The API client must call the Collect Signature API method periodically until it returns a status OK or an error message.

Collect signature - api call

Request

Method: HTTP PUT

Endpoint: /api/sign/niascollect

Headers:

Name Value Mandatory Comment
Content-Type application/json Yes
tenant t1 Yes This value must be given to you by the PhenixID Signing Service admin.
Authorization <basic_auth_value> No Basic authentication username and password must be given to you by PhenixID Signing Service admin.

Body:

The body must contains a json structure.

{"transactionID":"..."} 

Json structure properties:

Name Value Mandatory Comment
transactionID <Value_returned_from_trigger_sign> Yes

Example request (Please note that authorization data is not included in this example).

PUT /api/sign/niascollect HTTP/1.1
Host: example.org
Content-Type: application/json
tenant: t1
 
Cache-Control: no-cache
{"transactionID":"829b3b56-5a0a-449f-8dc8-50e6772c076f"}

Response

Response

The response body JSON structure properties:

 

Name Possible values Comment
status COMPLETE
OUTSTANDING_TRANSACTION
USER_SIGN
USER_CANCEL
SIGN_VALIDATION_FAILED
INTERNAL_ERROR
UNKNOWN_USER
OUTSTANDING_TRANSACTION or USER_SIGN -> Continue to poll
Other status -> Stop polling
signature
The signature data. Only available if status=COMPLETE.
ocspResponse
The OCSP Response. Only available if status=COMPLETE.
name
Full name of certificate holder. Only available if status=COMPLETE.
givenName
Given name (first name) of certificate holder. Only available if status=COMPLETE.
surName
Last name of certificate holder. Only available if status=COMPLETE.
message
Error message. Only available if status=INTERNAL_ERROR.
details
Detailed error message. Only available if status=INTERNAL_ERROR.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3295
{
  "surName" : "Berg",
  "signature" : "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",
  "ocspResponse" : "",
  "givenName" : "Anders",
  "name" : "Anders Berg",
  "status" : "COMPLETE"
}

Common errors

Common errors will result in a HTTP Status 500 with a body containing the error message:

{”message”:”<error explained>”}