Fleet Provisioning by Claim

Some devices do not have the capability to accept credentials over a secure transport, and the manufacturing supply chain is not equipped to customize devices at manufacturing time. AWS IoT provides a path for these devices to receive a unique identity when they are deployed.

Device makers must load each device with a shared claim certificate in firmware. This claim certificate should be unique per batch of devices. The firmware containing the claim certificate is loaded by the contract manufacturer without the need to perform any customization. When the device establishes a connection with AWS IoT for the first time, it exchanges the claim certificate for a unique X.509 certificate signed by the AWS certificate authority and a private key.

Initial Registration

Devices that want to register to Factbird Clouds using the Fleet Provisioning service are required to register at production time, in order to establish a white-list of allowed devices. This registration mechanism is also the only way to obtain the required claim credentials.

This registration is done through an API request to our registration service with a Factbird provided API Key with a payload containing:

{
	uuid: 'unique device ID',
	public_key: 'Base64 encoded public key used for signing',
	device_type: 'Device type given by Factbird',
}

This information is then stored by Factbird and used to verify that the device is allowed to exchange its claim credentials for unique device credentials.

The service will then respond with a response payload of the form:

{
	certificate_id: 'String identifying the certificate',
	certificate_pem: 'PEM encoded X.509 claim certificate',
	private_key: 'Private key of the claim certificate',
}

And the claim certificate, private key and uuid will be stored in the device for obtaining and rotating device specific credentials.

The claim certificate and private key returned by this step may be identical, as the same claim credentials can be issued a number of times depending on Factbird settings. It is important to use the claim certificate returned from the corresponding register request, as this will be checked as part of the device validation.

Device Logic

Devices must implement the logic necessary to publish and subscribe to Fleet Provisioning MQTT topics, accept the permanent credentials, and write the credentials to secure storage.

The entire provisioning flow is done through a TLS 1.2 encrypted connection.

Provisioning Flow

For the standard AWS Fleet Provisioning part, more info can be found at AWS Docs: https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html

Topic & Payload Descriptions

GetEndpoint

Checks if a device is claimed by a company and obtain the IoT endpoints related to the company if this is the case.

GetEndpoint request

Publish a message on endpoint/v1/<uuid>.

{
    "uuid": "string",
    "signature": "string"
}

uuid

The unique device id of the device.

signature

The result of signing the uuid with the signing private key created at the Initial Registration step.

GetEndpoint response

Subscribe to endpoint/v1/<uuid>/accepted.

{
	"iotDataEndpoint": "string",
	"iotCredentialsEndpoint": "string"
}

iotDataEndpoint

The data endpoint of the mqtt broker in the cloud where the device should connect. This is the equivalent of https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html with iot:Data-ATS.

iotCredentialsEndpoint

The credentials endpoint of AWS IoT in the cloud where the device should connect. This is the equivalent of https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html with iot:CredentialProvider. This is most likely not needed in most applications.

GetEndpoint error

To receive error responses, subscribe to endpoint/v1/<uuid>/rejected.

{
	"code": int,
	"message": "string"
}

code

The status code.

message

The error message.

CreateKeysAndCertificate

Creates new keys and a certificate. AWS IoT provides client certificates that are signed by the Amazon Root certificate authority (CA). The new certificate has a PENDING_ACTIVATION status. When you call RegisterThing to provision a thing with this certificate, the certificate status changes to ACTIVE or INACTIVE as described in the template.

CreateKeysAndCertificate request

Publish a message on $aws/certificates/create/json with an empty message payload.

CreateKeysAndCertificate response

Subscribe to $aws/certificates/create/json/accepted.

{
    "certificateId": "string",
    "certificatePem": "string",
    "privateKey": "string",
    "certificateOwnershipToken": "string"
}

certificateId

The certificate ID.

certificatePem

The certificate data, in PEM format.

privateKey

The private key.

certificateOwnershipToken

The token to prove ownership of the certificate during provisioning.

CreateKeysAndCertificate error

To receive error responses, subscribe to $aws/certificates/create/json/rejected.

{
    "statusCode": int,
    "errorCode": "string",
    "errorMessage": "string"
}

statusCode

The status code.

errorCode

The error code.

errorMessage

The error message.

RegisterThing

Provisions a thing using a pre-defined template.

RegisterThing request

Publish a message on $aws/provisioning-templates/<templateName>/provision/json.

templateName

The provisioning template name. Provided by Factbird.

{
    "certificateOwnershipToken": "string",
    "parameters": {
        "string": "string",
        ...
    }
}

certificateOwnershipToken

The token to prove ownership of the certificate. The token is generated by AWS IoT when you create a certificate over MQTT.

parameters

Optional. Key-value pairs from the device that are used by the pre-provisioning hooks to evaluate the registration request.

RegisterThing response

Subscribe to $aws/provisioning-templates/<templateName>/provision/json/accepted.

templateName

The provisioning template name. Provided by Factbird.

{
    "deviceConfiguration": {
        "string": "string",
        ...
    },
    "thingName": "string"
}

deviceConfiguration

The device configuration defined in the template.

thingName

The name of the IoT thing created during provisioning.

RegisterThing error response

To receive error responses, subscribe to $aws/provisioning-templates/<templateName>/provision/json/rejected.

templateName

The provisioning template name. Provided by Factbird.

{
    "statusCode": int,
    "errorCode": "string",
    "errorMessage": "string"
}

statusCode

The status code.

errorCode

The error code.

errorMessage

The error message.