Interface Specification

The interface specification covers the interface between the IdAM and the PrimeProduct in the context of issuing certificates and describes the methods passed between the PrimeProduct and Device Adapter. 

Communication Structure

The following communication structure and parameters are defined based on the Certificate Profiles, see Configure Certificates.

In principle, the communication interface is a REST API for communication between the PrimeProduct and IdAM. IdAM receives HTTP post requests with the mime-type application/json via the URL http://host:port/json.

The JSON format messages are structured in the following format:

{
	"method": "<method-name>", "params": {
	"optional param 0": "value 0",
	"optional param 1": "value 1",
	...
	}
}

The message consists of the following parameters:

  • method: Defines the main function for the request, and thus determines the Rule Chain. The parameter 'method' consists of exactly one variable of the type string.
  • param: Passes on the corresponding specific information. The parameter 'params' can contain any number of parameters depending on the context.

Communication Flow

The Communication Flow triggering the issuing of a Certificate via the IdAM is based on three HTTP requests:

  • Status Request and Response
  • Certificate Request and Response
  • Certificate Final Request and Response

The PrimeProduct is responsible for providing the necessary information to generate the Certificate Issuing Requests on the IdAM. 

The following provides an overview of the main communication.

PrimeProduct

Message

IdAM

PrimeProduct starts communication and triggers IdAM to get its status.

{ 
	"method": "STATUS_REQ",
 	"params": {
	"method": "CERT_REQ", 
	"rule_chain": "<rule_chain>"
	}
}



{
	"method": "STATUS_RESP", "params": {
	"status_code": "<status_code>", 
	"status_message": "<status_message>"
	}
}

IdAM response with actual status corresponding to the task specified.

PrimeProduct triggers Certificate Request via IdAM.

{
	"method": "CERT_REQ",
	"params": {
		See 4.2 'CERT_REQ'
	}
}



{
	"method": "CERT_RESP", 
	"params": { "certificate": "<cert>",
	"status_code": "<status_code>", 
	"status_message": "<status_message>"
	}
}

IdAM generates and performs CMP Request and Response with the Certificate.

Final message, if a certificate was received and stored properly.

{
	"method": "CERT_FINAL_REQ", "params": {
	"status_code": "<status_code>", 
	"status_message": 	"<status_message>", 
	"serial_number": "<serial_number>", 
	"rule_chain": "<rule_chain>", 
	"text_message": "<text_message>"
	}
}



{
	"method": "CERT_FINAL_RESP",
	"params": {
	"status_code": "<status_code>", 
	"status_message": 	"<status_message>"
	}
}

Final response message.

Status Request and Response

Messageformat Method: STATUS-REQ and STATUS-RESP

Status Request

To start the communication with the IdAM, the PrimeProduct asks the IdAM if it is operating and can perform the given task. This is performed by the STATUS method.

Direction: PP → IdAM

The following lists the method and parameters of the status request.

Method

Description

STATUS_REQ

Asks the IdAM if it is in an operating state and can
perform the given task.

Parameters

Value

Description

method

CERT_REQ
(UTF-8 String)

Certificate Request

rule_chain

(UTF-8 String)

What (sub-)task to perform, that is what (sub-)rule_chain
to use.

Status Response

Direction: IdAM → PP

The following lists the method and parameters of the status response from IdAM to PrimeProduct.

Method

Description

STATUS-RESP

Response to the 'STATUS' request.

Parameters

Value

Description

status_message

UTF-8 String

Status message and code of the IdAM as follows:
200 Status Idle, waiting for requests.
500 IdAM Internal Error.

status_code

UTF-8 String

Status message and code of the IdAM as follows:
200 Status Idle, waiting for requests.
500 IdAM Internal Error.

Certificate Request and Response

Message format Method: CERT_REQ and CERT_RESP

Certificate Request

To start the certificate issuing process with the IdAM, the PrimeProduct triggers the IdAM via the CERT_REQ method.

Direction: PP → IdAM

The following lists the method and parameters of the certificate request.

Method

Description

CERT_REQ

Trigger certificate issuing process via lRP

Parameters

Value

Description

rule_chain

UTF-8 String

Defines what kind of 'CERT_REQ'. Defines the context of the Cert Request.

signature_algorithm

UTF-8 String

"1.2.840.10045.4.3.4". Oid for ecdsa-with-sha512

cert_format

UTF-8 String

PEM or B64_DER. Specifies the format which the new certificate will have. B64_DER is Base64 encoded DER bytes.

client_public_key

UTF-8 String

Device-public-key in selected format.

client_key_format

UTF-8 String

PEM or B64_DER. B64_DER is Base64 encoded DER bytes.

client_key_algorithm

UTF-8 String

"1.2.840.10045.2.1". Oid for elliptic curve crypto.

client_key_params

UTF-8 String or if more than 1, Dictionary/Mapping

"1.2.840.10045.3.1.7". Specifying P- 256

article_type

UTF-8 String

Article Type (based on ERP), e.g. "PrimeProduct-109x"

mlfb

UTF-8 String

Machine readable ID of the PrimeProduct board, e.g. „PP-456- 1008-911"

serial_number

UTF-8 String

Unique serial number

mac_addresses

List of UTF-8 Strings or empty

MAC addresses if needed. Format like "00-A0-03-11-95-2E".
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="017d0cd6-e36e-4cb2-b25a-1731a508d189"><ac:plain-text-body><![CDATA[Hence, as list: ["00-A0-03-11-95-
]]></ac:plain-text-body></ac:structured-macro>
2E", …, …]

Certificate Response

Direction: IdAM → PP

The following lists the method and parameters of the certificate response from IdAM to PrimeProduct.

Method

Description

CERT_RESP

Response of certificate issuing process from IdAM

Parameters

Value

Description

status_message

UTF-8 String

Status Code of the IdAM according to:
200 SUCCESS, Certificate attached.
300 No connection to TrustService.

  1. Bad Request.
  2. Parameter Missing: ArticleType.
  3. Parameter Missing: MLFB.
  4. Parameter Missing: SerialNumber.
  5. Parameter Missing: MACAddresses.
  6. Error: Key Not Valid.
    500 IdAM Internal Error.

status_code

UTF-8 String


certificate

UTF-8 String

Certificate for Device in selected format.
(optional only if 'status_code' == 200)

Certificate Final Request and Response

Message format Method: CERT_FINAL_REQ and CERT_FINAL_RESP

Certificate Final Request

To allow the IdAM to acknowledge if the certificate was received and stored properly by the PrimeProduct, the PrimeProduct sends a final message via CERT_FINAL_REQ.

Direction: PP → IdAM

The following lists the method and parameters of the certificate final request.

Method

Description

CERT_FINAL_REQ

Final message to IdAM.

Parameters

Value

Description

serial_number

UTF-8 String

Serial number of the corresponding certificate

status_message

UTF-8 String

Status message

status_code

UTF-8 String

Status code

rule_chain

UTF-8 String

Defines what kind of 'CERT_REQ'

text_message

UTF-8 String

Arbitrary message text message.

Certificate Final Response

Direction: IdAM → PP

The following lists the method and parameters of the certificate final response from IdAM to PrimeProduct.

Method

Description

CERT_FINAL_RESP

Final message response

Parameters

Value

Description

serial_number

UTF-8 String

Serial number of the corresponding
certificate

status_message

UTF-8 String

Status message and code of the IdAM as follows:
200 SUCCESS, Certificate delivered.
500 IdAM Internal Error.

status_code

UTF-8 String

Status message and code of the lRP as follows:
200 SUCCESS, Certificate delivered.
500 IdAM Internal Error.

Next Step: IdAM Installation

For an example Request Certificate script for implementation on the device site, see Example Request Certificate Script.

Now when you have the Trust Service with its Certificates Profiles and CMP configuration in place as well as the interface between the device and the IdAM and the sequence diagram to guide you through the process development, continue with installing the IdAM.