IdAM supports the following two message types corresponding to its default configuration:

  • Request Status

  • Request Certificate

The messages are expected to be sent via HTTP requests and mime-type application/json to the integrated HTTP web server within the Device Adapter.

The following sections describe the detailed structure and contents of the Request Status and Request Certificate messages.

request_status

The request_status message allows checking if IdAM is available and reachable without trying to request any certificate. With IdAM version 1.0, a default response is generated and send back and future versions will include further checks, for example, availability of the corresponding CA, configurable via the user interface Rule Chains.

The request_status message can optionally be sent before any request_certificate message, to check availability before trying to request an actual certificate.

Example Configuration

In the following example configuration, IdAM expects the request_status message to have the following (case sensitive) structure.

request_status message

{
   "method": "request_status",
   "params": {
      "rule_chain": "demo",
   }
}
XML

If IdAM is available and the corresponding Rule Chain is configured (named demo in the following example), the following response is expected.

request_status response

{
   "method": "request_status",
   "params": {
      "rule_chain": "demo",
      "payload": {
         "status_code": "200",
         "status_message": "Status Idle, waiting for requests."
      },
      "error": false,
      "error_code": null,
      "error_message": null,
      "error_text": null
   }
}
XML

To check if the response is valid, it is sufficient to check the value of params.rule_chain = “demo”, params.payload.status_code = “200”, and params.error = false.

Should an error occur that prevents the adapter from relaying it to the Rule Chains (for example, an incorrect message structure), params.payload will be null and the corresponding error fields are set (the error_text is optional).

Once you have configured IdAM for your special use case, replace the rule_chain name demo with a relevant name.

request_certificate

The request_certificate message allows requesting an actual certificate.

Example Configuration

In the following example configuration, IdAM expects the request_certificate message to have the following (case sensitive) structure.

request_certificate message

{
   "method": "request_certificate",
   "params": {
      "rule_chain": "demo",
      "payload": {
         "common_name": "PrimeProduct",
         "macs": [
            "00:80:41:AE:FD:01",
            "00:80:41:AE:FD:02",
            "00:80:41:AE:FD:03"
         ],
         "public_key": "<pub_key>"
      }
   }
}
XML

This will invoke a certificate request using the configured CA Profile corresponding to the rule_chain, in the above example named demo.

The params.payload is optional. Arbitrary keys are allowed with strings and lists of strings as values, intended to be used for information that is unique for every request, provided by the end entity (or control computer). The keys will be handled and integrated with the request within the corresponding Rule Chain.

The “public_key”: “<pub_key>” entry is required as IdAM does not yet support generating keys by itself. IdAM supports an elliptic curve public key (p256v1/secp256r1) with formats PEM, DER as a hexadecimal string, or base64 encoded DER, specified within the Rule Chain.

If the certificate was successfully requested and generated, the following response is expected.

request_certificate response

{
   "method": "request_certificate",
   "params": {
      "rule_chain": "demo",
      "payload": {
         "certificate": "<certificate>"
      },
      "error": false,
      "error_code": null,
      "error_message": null,
      "error_text": null
   }
}
XML

The format of the received certificate depends on the configuration in the corresponding Rule Chain. Available formats are PEM, DER as a hexadecimal string, and base64 encoded DER.

If the certificate request failed, params.payload will be null and the corresponding error fields are set (the error_text is optional).