Credentials API Specification

The Credentials API is used by Protocol Adapters to retrieve credentials used to authenticate Devices connecting to the adapter. In particular, the API supports to look up shared secrets which are often used by IoT devices by means of username/password based authentication schemes.

Credentials are of a certain type which indicates which authentication mechanism the credentials can be used with. Each set of credentials also contains an authentication identity which is the identity claimed by the device during authentication. This authentication identity is usually different from the device-id the device has been registered under. A device may have multiple sets of credentials, using arbitrary authentication identities.

The Credentials API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.

Preconditions for invoking the Credentials API

1. Client has established an AMQP connection with the Credentials service.
2. Client has established an AMQP link in role sender on the connection using target address credentials/${tenant_id}. This link is used by the client to send commands to the Credentials service.
3. Client has established an AMQP link in role receiver on the connection using source address credentials/${tenant_id}/${reply-to} where reply-to may be any arbitrary string chosen by the client. This link is used by the client to receive responses to the requests it has sent to the Credentials service. This link’s source address is also referred to as the reply-to address for the request messages.

Get Credentials

Protocol adapters use this command to look up credentials of a particular type for a device identity.

Message Flow

Request Message Format

The following table provides an overview of the properties a client needs to set on an get credentials message.

The body of the request MUST consist of a single Data section containing a UTF-8 encoded string representation of a single JSON object having the following members:

The client-certificate property MAY be used by the service implementation for auto-provisioning of devices. To do so, the device registry needs to create credentials (and registration data) for the device if they do not already exist.

Additionally, the body MAY contain arbitrary properties that service implementations can use to determine a device’s identity.

The following request payload may be used to look up the hashed password for a device with the authentication identifier sensor1:

{
  "type": "hashed-password",
  "auth-id": "sensor1"
}

The following request payload may be used to look up or create x509-cert credentials for a device with the authentication identifier CN=device-1,O=ACME Corporation:

{
  "type": "x509-cert",
  "auth-id": "CN=device-1,O=ACME Corporation",
  "client-certificate": "DeviceCert=="
}

Response Message Format

A response to a get credentials request contains the following properties:

The response message payload MUST contain credential information as defined in Credentials Format if the status is 200 or 201.

The response message’s status property may contain the following codes:

For status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred. In this case, the response message’s content-type property SHOULD be set accordingly.

Delivery States

The Credentials service uses the following AMQP message delivery states when receiving request messages from clients:

Credentials Format

Credential data is carried in the body of an AMQP message as part of a single Data section. The message’s content-type property must be set to application/json.

The credential data is contained in the Data section as a UTF-8 encoded string representation of a single JSON object. It is an error to include payload that is not of this type.

The table below provides an overview of the standard members defined for the JSON object:

For each set of credentials the combination of auth-id and type MUST be unique within a tenant.

The device registry may choose to not return information which is not suitable for authentication a device. This includes for example the enabled property. If set to false, then the device registry may choose to treat this request as if no credentials would be found. For secrets for example, this could mean that the device registry does not return secrets which are not valid at the current point in time.

Secrets Format

Each set of credentials may contain arbitrary secrets scoped to a particular validity period during which the secrets may be used for authenticating a device. The validity periods MAY overlap in order to support the process of changing a secret on a device that itself doesn’t support the definition of multiple secrets for gapless authentication across adjacent validity periods.

The table below contains the properties used to define the validity period of a single secret:

Examples

Below is an example for a payload containing a hashed password for device 4711 with auth-id sensor1 using SHA512 as the hashing function with a 4 byte salt (Base64 encoding of 0x32AEF017). Note that the payload does not contain a not-before property, thus it may be used immediately up until X-mas eve 2017.

{
  "device-id": "4711",
  "type": "hashed-password",
  "auth-id": "sensor1",
  "enabled": true,
  "secrets": [{
    "not-after": "2017-12-24T19:00:00+0100",
    "pwd-hash": "AQIDBAUGBwg=",
    "salt": "Mq7wFw==",
    "hash-function": "sha-512"
  }]
}

The next example contains two pre-shared keys with overlapping validity periods for device myDevice with PSK identity little-sensor2.

{
  "device-id": "myDevice",
  "type": "psk",
  "auth-id": "little-sensor2",
  "enabled": true,
  "secrets": [{
    "not-after": "2017-07-01T00:00:00+0100",
    "key": "cGFzc3dvcmRfb2xk"
  },{
    "not-before": "2017-06-29T00:00:00+0100",
    "key": "cGFzc3dvcmRfbmV3"
  }]
}

Credential Verification

Protocol Adapters are responsible for authenticating devices when they connect. The Credentials API provides the Get Credentials operation to support Protocol Adapters in doing so as illustrated below:

The following sequence diagram illustrates the flow of messages involved in a Protocol Adapter authenticating a device. This is shown for the MQTT Protocol Adapter as example how a device authenticates with a username and a hashed-password. The mechanism can be transferred to other protocols in a similar manner.

Protocol adapters MUST comply with the following rules when verifying credentials presented by a device:

• Credentials that have their enabled property set to false MUST NOT be used for authentication.

• Adapters MUST only consider secrets for authentication which

  • have their not-before property set to either null or the current or a past point in time and
  • have their not-after property set to either null or the current or a future point in time.

Standard Credential Types

The following sections define some standard credential types and their properties. Applications are encouraged to make use of these types. However, the types are not enforced anywhere in Hono and clients may of course add application specific properties to the credential types.

Common Properties

All credential types used with Hono MUST contain device-id, type, auth-id, enabled and secrets properties as defined in Credentials Format.

Hashed Password

A credential type for storing a (hashed) password for a device.

Example:

{
  "device-id": "4711",
  "type": "hashed-password",
  "auth-id": "sensor1",
  "secrets": [{
    "pwd-hash": "AQIDBAUGBwg=",
    "salt": "Mq7wFw==",
    "hash-function": "sha-512"
  }]
}

The table below describes the hash functions supported by Hono and how they map to the secret structure.

Pre-Shared Key

A credential type for storing a Pre-shared Key as used in (D)TLS handshakes.

Example:

{
  "device-id": "4711",
  "type": "psk",
  "auth-id": "little-sensor2",
  "secrets": [{
    "key": "AQIDBAUGBwg="
  }]
}

X.509 Certificate

A credential type for storing the RFC 2253 formatted subject DN of a client certificate that is used to authenticate the device as part of a (D)TLS handshake.

Example:

{
  "device-id": "4711",
  "type": "x509-cert",
  "auth-id": "CN=device-1,O=ACME Corporation",
  "secrets": [{}]
}

Raw Public Key

A credentials type for storing a public key as used in the JSON Web Token based Authentication to authenticate a device.

Example with public key:

{
  "device-id": "4711",
  "type": "rpk",
  "auth-id": "sensor1",
  "secrets": [
    {
      "key": "MIIBIjANBgkqhki...yn7qGrzgQIDAQAB"
    }
  ]
}

Example with X.509 certificate:

{
  "device-id": "4711",
  "type": "rpk",
  "auth-id": "sensor1",
  "secrets": [
    {
      "cert": "MIIDezCCAmOgAwI...GCfMrYD6dnpbg=="
    }
  ]
}