Filter results by

AWS IoT Device Registration

You can create an ecosystem in which your ARTIK modules auto-register with AWS on initial connection – based on the unique keys and certificates with which you have provisioned the modules.

Your cloud-based code checks against your "whitelist" to decide whether the device may safely be connected. The initial communication takes place over an SSL/TLS-secured channel, with an unhackable key in ARTIK Secure Storage.

This tutorial describes how to use AWS and OpenSSL to create and install the keys and certificates needed. It is designed for use with the ARTIK 530 or 710 board with the Ubuntu OS installed.

References

Just In Time Registration of Device Certificates on AWS IoT

Deploy Fleets Easily with AWS IoT Device Management services

Use Your Own Certificate

OpenSSL Essentials - Digital Ocean

Prerequisites

Follow the introductory article to set up your AWS account, the CLI, and your credentials.

One-time CA Cert Registration

You'll need to register a CA certificate with AWS. Typically, you might do this once for each type of device you plan to use with AWS IoT.

Start here by creating an intermediate CA certificate. Later in the process you'll derive a second certificate, uniquely identifying a single one of your devices, and put both on the device.

For the purposes of this tutorial, you will be acting as a Certificate Authority. You'll need access to the CA private key to act on a certificate signing request. For background on this topic, refer to create your own "mini CA". In this example, we'll use ECC instead RSA for the CA certificate.

  • Begin by entering into the Python virtual environment. You'll need to be in Python 3.5 whenever you need to use the AWS CLI.
    source ~/cli-ve/bin/activate
    You'll use
    deactivate
    to leave the environment and return to normal Python 2.7 operation, which (for example) you'll need to do for AWS Greengrass operations.

  • Make sure you are connected to a network before issuing any AWS CLI commands.

Request an AWS registration code

As you may know, during a TLS handshake, the certificate Common Name gets transmitted to the server. By using an AWS-generated registration code as Common Name, AWS will receive this information on every attempt at secure connection (even if the process is not completed).

In the following procedures, you'll use an AWS registration code as the certificate Common Name when assembling a Certificate Signing Request (CSR). Run the code request command now.

aws iot get-registration-code

Copy the response – you'll use it shortly.

Obtain or Create a CA certificate

Normally you'd start with a CA certificate signed by the root provider of your choice, but here you will simply generate one as your own mini CA.

Generate your CA private key and public certificate using ECC parameters.

openssl ecparam -out sampleCACertificate.key -name prime256v1 -genkey

openssl req -x509 -new -nodes -key sampleCACertificate.key -sha256 -days 365 -out sampleCACertificate.pem

For the purposes of this article, we'll consider sampleCACertificate.pem to be a valid intermediate CA certificate.

You could instead have chosen to make an

Generate RSA intermediate CA certificate

openssl genrsa -out rsaCACertificate.key 2048

openssl req -x509 -new -nodes -key rsaCACertificate.key -sha256 -days 365 -out rsaCACertificate.pem

Register the CA certificate

Starting from a valid intermediate CA certificate, we'll register it with AWS IoT.

  1. Create a privateKeyVerification key that will be used to sign the CSR. Here we create ECC keys so that the CSR can be signed by our ECC CA.

    openssl ecparam -out privateKeyVerification.key -name prime256v1 -genkey

  2. Create a certificate signing request using the key.

    openssl req -new -key privateKeyVerification.key -out privateKeyVerification.csr

    During the ensuing interrogation, copy in the AWS registration code you got earlier as the Common Name (CN). When you get to the challenge password, just hit enter to skip through.

  3. Create a submission package containing both the CA certificate and privateKeyVerification certificate inside a single file.

    openssl x509 -req -in privateKeyVerification.csr -CA sampleCACertificate.pem -CAkey sampleCACertificate.key -CAcreateserial -out privateKeyVerification.crt -days 365 -sha256

  4. Register the CA and privateKeyVerification certificates with AWS. An example response is shown.

    aws iot register-ca-certificate --ca-certificate file://sampleCACertificate.pem --verification-certificate file://privateKeyVerification.crt
    { "certificateId": "2d12b5bb2574dab95d54d98bfa07a20fb8a81d23208ffddf58b77971ec0d4025", "certificateArn": "arn:aws:iot:us-west-2:759497405763:cacert/2d12b5bb2574dab95d54d98bfa07a20fb8a81d23208ffddf58b77971ec0d4025" }

Your CA certificate for your product is now "on file" with AWS IoT.

You could instead have chosen to register an

Register CA Certificate using RSA instead of ECC

  1. Create a privateKeyVerification key.
    openssl genrsa -out rsaPrivate.key 2048
  2. Create a certificate signing request using the AWS registration code you received earlier.
    openssl req -new -key rsaPrivate.key -out rsaPrivate.csr
  3. Create a submission package.
    openssl x509 -req -in rsaPrivate.csr -CA rsaCACertificate.pem -CAkey rsaCACertificate.key -CAcreateserial -out rsaPrivate.crt -days 365 -sha256
  4. Register with AWS.
    (cli-ve) [root@artik ~]# aws iot register-ca-certificate --ca-certificate file://rsaCACertificate.pem --verification-certificate file://rsaPrivate.crt

    { "certificateId": "15ce939dcbd415769b1fd3dcac665d370cbd822c68957e8758c76e0c79526fd0", "certificateArn": "arn:aws:iot:us-west-2:759497405763:cacert/15ce939dcbd415769b1fd3dcac665d370cbd822c68957e8758c76e0c79526fd0"

A new RSA CA cert is now registered with AWS.

CA key and cert:
– rsaCACertificate.key
– rsaCACertificate.pem

Take a look at the output from your submission to see that both your CA common name and the AWS IoT registration code are bound together.

openssl x509 -in _your_cert_name_.crt -noout -text

Review, activate certificate, enable device auto-registration

A small amount of setup is required to activate your certificate. Here we'll show you the quick way to do it.

  1. Go to the AWS IoT dashboard and select Secure » CAs.

  2. Click on the certificate corresponding to the certificate ID you just saw in the ARTIK board CLI. You'll see that the ID matches.

  3. Click Actions (upper right corner) and select "Activate".

  4. Click Actions again and select "Enable auto-registration".

Your certificate is now configured to accept connection requests from ARTIK.

You could instead have chosen to make these configuration changes directly from the AWS CLI. For details, click to

Register Using CLI

Verify status. Use this command to show the certificate and its status.

aws iot describe-ca-certificate --certificate-id <certificateId>

For example:

(cli-ve) [root@artik ~]# aws iot describe-ca-certificate --certificate-id 2d12b5bb2574dab95d54d98bfa07a20fb8a81d23208ffddf58b77971ec0d4025

{
    "certificateDescription": {
    "creationDate": 1533917086.702,
    "status": "INACTIVE",
    "certificateId": "2d12b5bb2574dab95d54d98bfa07a20fb8a81d23208ffddf58b77971ec0d4025",
    "autoRegistrationStatus": "DISABLE",
    "ownedBy": "759497405763",
    "certificateArn": "arn:aws:iot:us-west-2:759497405763:cacert/2d12b5bb2574dab95d54d98bfa07a20fb8a81d23208ffddf58b77971ec0d4025",
    "certificatePem": "-----BEGIN CERTIFICATE-----\n
MIICaDCCAg2gAwIBAgIJAOoTEQt/sIu+MAoGCCqGSM49BAMCMIGPMQswCQYDVQQG\n
EwJVUzELMAkGA1UECAwCQ0ExETAPBgNVBAcMCFNhbiBKb3NlMRAwDgYDVQQKDAdT\n
YW1zdW5nMQ4wDAYDVQQLDAVTLUxTSTESMBAGA1UEAwwJbWFya3MtaW90MSowKAYJ\n
KoZIhvcNAQkBFhttYS53aWxsaWFtc0Bzc2kuc2Ftc3VuZy5jb20wHhcNMTgwODEw\n
MTU0ODU0WhcNMTkwODEwMTU0ODU0WjCBjzELMAkGA1UEBhMCVVMxCzAJBgNVBAgM\n
AkNBMREwDwYDVQQHDAhTYW4gSm9zZTEQMA4GA1UECgwHU2Ftc3VuZzEOMAwGA1UE\n
CwwFUy1MU0kxEjAQBgNVBAMMCW1hcmtzLWlvdDEqMCgGCSqGSIb3DQEJARYbbWEu\n
d2lsbGlhbXNAc3NpLnNhbXN1bmcuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcD\n
QgAE0VzPToBtE7POu+TisgnUqMOo4j6l5B6baItslLrZ11t6WVLydJQB1ZL0kq31\n
MqkL2cqJ3oFLcL4Djo6p989bt6NQME4wHQYDVR0OBBYEFKbUWc69BcL5xjGzJujR\n
/h/xvCWJMB8GA1UdIwQYMBaAFKbUWc69BcL5xjGzJujR/h/xvCWJMAwGA1UdEwQF\n
MAMBAf8wCgYIKoZIzj0EAwIDSQAwRgIhANW4eu9RrFQYVFTq43oEYI9vJquXQB9h\n
EzG8dQ1+G+S0AiEA7rH+xRdWPYAKiEndRtGQsaeq42mmQ38gt/hHuacL6F0=\n
-----END CERTIFICATE-----\n"
    }
}
(cli-ve) [root@artik ~]#

Activation. By default, the CA certificate that is registered is in inactive state, so you need activate the registered CA using AWS CLI. If the CA certificate is not in active state, AWS IoT will not register any device (client) certificates.

Activate the CA certificate by updating the CA status to ACTIVE through the AWS CLI.

aws iot update-ca-certificate --certificate-id <certificateId> --new-status ACTIVE


(cli-ve) [root@artik ~]# aws iot update-ca-certificate --certificate-id 2d12b5bb2574dab95d54d98bfa07a20fb8a81d23208ffddf58b77971ec0d4025 --new-status ACTIVE
(cli-ve) [root@artik ~]#

Auto registration. Optionally, devices can be registered automatically the first time they connect to AWS IoT. This feature defaults to disabled after initial certificate activation. Opt in for auto-registration of device certificates by enabling auto-registration status for the CA, using the CLI.

aws iot update-ca-certificate --certificate-id <certificateId> --new-auto-registration-status ENABLE

Verify updated status. This time, you'll see the changes you've made.

(cli-ve) [root@artik ~]# aws iot describe-ca-certificate --certificate-id 2d12b5bb2574dab95d54d98bfa07a20fb8a81d23208ffddf58b77971ec0d4025

{
  "certificateDescription": {
  "certificatePem": "-----BEGIN CERTIFICATE-----\n
  MIICaDCCAg2gAwIBAgIJAOoTEQt/sIu+MAoGCCqGSM49BAMCMIGPMQswCQYDVQQG\n
  . . .
  EzG8dQ1+G+S0AiEA7rH+xRdWPYAKiEndRtGQsaeq42mmQ38gt/hHuacL6F0=\n
  -----END CERTIFICATE-----\n",
        "creationDate": 1533917086.702,
        "status": "ACTIVE",
        "certificateId": "2d12b5bb2574dab95d54d98bfa07a20fb8a81d23208ffddf58b77971ec0d4025",
        "ownedBy": "759497405763",
        "certificateArn": "arn:aws:iot:us-west-2:759497405763:cacert/2d12b5bb2574dab95d54d98bfa07a20fb8a81d23208ffddf58b77971ec0d4025",
        "autoRegistrationStatus": "ENABLE"
    }
}

Provisioning Each Device

For each device unit you expect to connect to AWS IoT, you must provision that device with its own key.

Here, using the CA certificate we created previously and registered with AWS IoT, we will generate a device certificate (client certificate) and key that uniquely identify this individual unit.

This time, the Common Name (CN) and other information refer to your own device, so you don't use the registration code here.

The serial number of the certificate will be used to prepare a "white list" of devices that are approved for eventual registration, as discussed in the next article. You can read it from the certificate as shown. AWS IoT can provide this value upon initial connection to check against your list.

openssl x509 -in rsaDevCert.crt -noout -text

In the following sections, we give you two options: External ECC keys or internal RSA keys. You can choose either, or do both for comparison.

Provision with ECC

This procedure creates an ECC key externally.

  1. Generate an ECC private key.

    openssl ecparam -out deviceCert.key -name prime256v1 -genkey

  2. Use it to create a certificate signing request (CSR). Replace the subject information as you choose.

    openssl req -new -key deviceCert.key -out deviceCert.csr -subj "/O=company/OU=team/CN=marks-iot/C=US"

  3. Submit the CSR to your CA for signing, to create a device-unique certificate.

    openssl x509 -req -in deviceCert.csr -CA sampleCACertificate.pem -CAkey sampleCACertificate.key -out deviceCert.crt -days 365 -sha256 -set_serial 0x123456

  4. Concatenate it with your CA certificate.

    cat deviceCert.crt sampleCACertificate.pem > deviceCertAndCACert.crt

    You now have a client device certificate chain deviceCertAndCACert.crt that will be sent to AWS as part of the TLS handshake process.

Provision with RSA, place in Secure Storage

This procedure creates an RSA key externally and puts it in Secure Storage for later secure access.

  1. Generate an RSA private key.

    openssl genrsa -out rsaDevCert.key 2048

  2. Convert it to DER format and put it in Secure Storage.

    openssl rsa -in rsaDevCert.key -outform DER -out rsaDevCert.der
    see_test -K set-key -a 4097 -k rsaDevCert.key -I rsaDevCert.der

  3. Use the key to create a certificate signing request (CSR). Replace the subject information as you choose.

    openssl req -new -key rsaDevCert.key -out "filename.csr" -subj "/O=company/OU=team/CN=marks-iot/C=US"

    You can view the CSR if you want.

    openssl req -text -noout -verify -in filename.csr

  4. Submit the CSR to your CA for signing, to create a device-unique certificate.

    openssl x509 -req -in filename.csr -CA rsaCACertificate.pem -CAkey rsaCACertificate.key -out rsaDevCert.crt -days 365 -sha256 -set_serial 0x123456

  5. Concatenate it with your CA certificate.

    cat rsaDevCert.crt rsaCACertificate.pem > rsaDevCertAndCACert.crt

You now have a client device certificate chain rsaDevCertAndCACert.crt that will be sent to AWS as part of the TLS handshake process.

Initial Testing and Connect Event

Your ARTIK board is now ready to communicate with AWS IoT. At this stage, we want you to see that you can make a connection to the AWS IoT MQTT broker, that it will attempt to connect through TLS, but will reject the connection. However, it will also trigger an event that you can act on in the cloud.

When a device with a previously unknown cert (issued by registered CA) connects to AWS IoT for the first time, it will be auto-registered in PENDING_ACTIVATION state. Any device that is in PENDING_ACTIVATION state will fail to connect after the TLS handshake.

Set up viewing of event message on AWS IoT Console

Here you'll be switching to an AWS IoT test console that will allow you to see the event message that results from your connect attempt.

The MQTT messaging path here is UNRELATED to the MQTT command you are sending from your ARTIK board.

The event message is published to an MQTT topic that is serviced in the cloud and does not involve ARTIK. That is, ANY method by which you connect on the ARTIK board to AWS IoT (WebSockets, HTTPS, MQTTS) would still result in the same event message published to the same topic at a separate MQTT endpoint.

  1. Go to the AWS IoT Console, under Test.

  2. Select "Subscribe to a topic".

  3. Enter the following subscription topic, where # indicates that a message based on any certificate will be accepted.

    $aws/events/certificates/registered/#

  4. Click the [Subscribe to topic] button.

The console jumps to a "Publish" page, but you will only be looking for incoming subscription messages below that.

Trigger event – ECC device cert and key

You'll be using a command line MQTT client to publish a message to AWS IoT. You could instead use Node-RED, the Kura portal integrated MQTT console, ARTIK SDK, or other means that you find more convenient.

  1. Install the mosquitto client on your ARTIK board.
    apt install mosquitto-clients

  2. The AWS Root CA certificate should come in the standard bundle on your board. To be sure, find it here, copy it into the file indicated, and reference it as --cafile.

    vi root.cert

  3. Copy and paste this command line into your ARTIK console, but don't hit Enter yet.

    [root@artik ~]# mosquitto_pub --cafile root.cert --cert deviceCertAndCACert.crt --key deviceCert.key -h _your_custom_endpoint_.amazonaws.com -p 8883 -q 1 -t foo/bar -i anyclientID --tls-version tlsv1.2 -m "Hello" -d

  4. Go to the AWS IoT Console, under Settings, and copy the Custom Endpoint for your account. It will look something like this:

    abcdefgh1234567.iot.us-west-2.amazonaws.com

  5. Replace _your_custom_endpoint_.amazonaws.com in the command line with your own copied endpoint.

Trigger the event message. On your ARTIK console, hit Enter. You should see:

Client anyclientID sending CONNECT
Error: The connection was lost.

indicating that the connection was made but then rejected.

Now look at the AWS IoT console. You should see the event message published, indicating that a new device has tried to connect and needs attention.

{
  "certificateId": "4c4d5d97687eb429ccda703664155164bf1c388d0dd714bbf8526b79a25d4b6b",
  "caCertificateId": "2d12b5bb2574dab95d54d98bfa07a20fb8a81d23208ffddf58b77971ec0d4025",
  "timestamp": 1534527652433,
  "certificateStatus": "PENDING_ACTIVATION",
  "awsAccountId": "123456123456",
  "certificateRegistrationTimestamp": "1534527528642"
}

That was it! You can see that AWS IoT has securely recognized the device as one of your own, and is giving you the opportunity to either activate it or take other action.

We'll assemble a cloud-based AWS Lambda function in the next section to automatically take care of these events in the future.

Trigger event – RSA cert and secured key

The ECC method used an exposed key file. To create a connect event securely, you can instead use the RSA key you copied into ARTIK Secure Storage.

Because this phase of testing requires only an initial connection attempt, an MQTT client is not required; instead, you can use a simple openssl connection to trigger the event.

  1. Go to the AWS IoT Console, under Settings, and copy the Custom Endpoint for your account. It will look something like this:

    abcdefgh1234567.iot.us-west-2.amazonaws.com

  2. Replace _your_custom_endpoint_.amazonaws.com in the command line with your own copied endpoint.

openssl s_client -connect _your_custom_endpoint_.amazonaws.com:8883 -engine artiksee -cert rsaDevCertAndCACert.crt -keyform e -key rsa2048://rsaDevCert.key --cipher "ECDHE-ECDSA-AES256-GCM-SHA384"

Trigger the event message. When you hit Enter on your ARTIK console, you should see full details of the connection process.

Now look at the AWS IoT MQTT broker console. You should see the event message published (as shown for ECC), indicating that a new device has tried to connect and needs attention.

Servicing the event

Now that AWS IoT has become aware of the connecting device, it's time to service the event. We'll be using the Just-In-Time Registration (JITR) feature of AWS IoT to determine, based on the device ID, exactly how to validate, register, and configure it.

Normally, when you manually connect a device to AWS IoT for the first time, you would need to:

With JITR, these steps can all be taken care of in the cloud, by the AWS Lambda function that receives the connect event notification. We put links above for your reference, but we'll be automating the process in the next article.

» Create JITR Lambda Function

Last updated on: