Menu
AWS IoT
Developer Guide

Use Your Own Certificate

To use your own X.509 certificates, you must register a CA certificate with AWS IoT. The CA certificate can then be used to sign device certificates. You can register up to 10 CA certificates with the same subject field per AWS account per region. This allows you to have more than one CA sign your device certificates.

Note

Device certificates must be signed by the registered CA certificate. It is common for a CA certificate to be used to create an intermediate CA certificate. If you are using an intermediate certificate to sign your device certificates, you must register the intermediate CA certificate. Use the AWS IoT root CA certificate when you connect to AWS IoT even if you register your own root CA certificate. The AWS IoT root CA certificate is used by a device to verify the identity of the AWS IoT servers.

If you do not have a CA certificate, you can use OpenSSL tools to create one.

To create a CA certificate

  1. Generate a key pair.

    openssl genrsa -out rootCA.key 2048
  2. Use the private key from the key pair to generate a CA certificate.

    openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem

Registering Your CA Certificate

To register your CA certificate, you must:

  • Get a registration code from AWS IoT.

  • Sign a private key verification certificate with your CA certificate.

  • Pass your CA certificate and a private key verification certificate to the register-ca-certificate CLI command.

    The Common Name field in the private key verification certificate must be set to the registration code generated by the get-registration-code CLI command. A single registration code is generated per AWS account. You can use the register-ca-certificate command or the AWS IoT console to register CA certificates.

Note

A CA certificate cannot be registered to more than one account in the same region. However, a CA certificate can be registered to more than one account if the accounts are in different regions.

To register a CA certificate

  1. Get a registration code from AWS IoT. This code is used as the Common Name of the private key verification certificate.

    aws iot get-registration-code
  2. Generate a key pair for the private key verification certificate.

    openssl genrsa -out verificationCert.key 2048
  3. Create a CSR for the private key verification certificate. Set the Common Name field of the certificate to your registration code.

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

    You are prompted for some information, including the Common Name, for the certificate.

    Country Name (2 letter code) [AU]: State or Province Name (full name) []: Locality Name (for example, city) []: Organization Name (for example, company) []: Organizational Unit Name (for example, section) []: Common Name (e.g. server FQDN or YOUR name) []:XXXXXXXXXXXXMYREGISTRATIONCODEXXXXXX Email Address []:
  4. Use the CSR to create a private key verification certificate.

    openssl x509 -req -in verificationCert.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out verificationCert.pem -days 500 -sha256
  5. Register the CA certificate with AWS IoT. Pass in the CA certificate and the private key verification certificate to the register-ca-certificate CLI command.

    aws iot register-ca-certificate --ca-certificate file://rootCA.pem --verification-cert file://verificationCert.pem
  6. Use the update-certificate CLI command to activate the CA certificate.

    aws iot update-ca-certificate --certificate-id xxxxxxxxxxx --new-status ACTIVE

Creating a Device Certificate Using Your CA Certificate

You can use a CA certificate registered with AWS IoT to create a device certificate. The device certificate must be registered with AWS IoT before use.

To create a device certificate

  1. Generate a key pair.

    openssl genrsa -out deviceCert.key 2048
  2. Create a CSR for the device certificate.

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

    You are prompted for some information, as shown here.

    Country Name (2 letter code) [AU]: State or Province Name (full name) []: Locality Name (for example, city) []: Organization Name (for example, company) []: Organizational Unit Name (for example, section) []: Common Name (e.g. server FQDN or YOUR name) []: Email Address []:
  3. Create a device certificate from the CSR.

    openssl x509 -req -in deviceCert.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out deviceCert.pem -days 500 -sha256

    Note

    You must use the CA certificate registered with AWS IoT to create device certificates. If you have more than one CA certificate (with the same subject field and public key) registered in your AWS account, you must specify the CA certificate used to create the device certificate when you register your device certificate.

  4. Register a device certificate.

    aws iot register-certificate --certificate-pem file://deviceCert.pem --ca-certificate-pem file://rootCA.pem
  5. Use the update-certificate CLI command to activate the device certificate.

    aws iot update-certificate --certificate-id xxxxxxxxxxx --new-status ACTIVE

Registering a Device Certificate

You must use the CA certificate registered with AWS IoT to sign device certificates. If you have more than one CA certificate (with the same subject field and public key) registered in your AWS account, you must specify the CA certificate used to sign the device certificate when you register your device certificate. You can register each device certificate manually, or you can use automatic registration, which allows devices to register their certificate when they connect to AWS IoT for the first time.

Registering Device Certificates Manually

Use the following CLI command to register a device certificate:

aws iot register-certificate --certificate-pem file://deviceCert.crt --ca-certificate-pem file://caCert.crt

Using Automatic/Just-in-Time Registration for Device Certificates

To register device certificates automatically when devices first connect to AWS IoT, you must enable automatic registration for your CA certificate. This registers any device certificate signed by your CA certificate when it connects to AWS IoT.

Enable Automatic Registration

Use the update-ca-certificate API to set the auto-registration-status of the CA certificate to ENABLE:

$ aws iot update-ca-certificate --certificate-id caCertificateId --new-auto-registration-status ENABLE

You can also set the auto-registration-status to ENABLE when you use the register-ca-certificate API to register your CA certificate:

aws iot register-ca-certificate --ca-certificate file://rootCA.pem --verification-cert file://privateKeyVerificationCert.crt --allow-auto-registration

When a device first attempts to connect to AWS IoT, as part of the TLS handshake, it must present a registered CA certificate and a device certificate. AWS IoT recognizes the CA certificate as a registered CA certificate and automatically registers the device certificate and sets its status to PENDING_ACTIVATION. This means that the device certificate was automatically registered and is awaiting activation. A certificate must be in the ACTIVE state before it can be used to connect to AWS IoT. When AWS IoT automatically registers a certificate or when a certificate in PENDING_ACTIVATION status connects, AWS IoT publishes a message to the following MQTT topic:

$aws/events/certificates/registered/caCertificateID

Where caCertificateID is the ID of the CA certificate that issued the device certificate.

The message published to this topic has the following structure:

{ "certificateId": "certificateID", "caCertificateId": "caCertificateId", "timestamp": timestamp, "certificateStatus": "PENDING_ACTIVATION", "awsAccountId": "awsAccountId", "certificateRegistrationTimestamp": "certificateRegistrationTimestamp" }

You can create a rule that listens on this topic and performs some actions. We recommend that you create a Lambda rule that verifies the device certificate is not on a certificate revocation list (CRL), activates the certificate, and creates and attaches a policy to the certificate. The policy determines which resources the device is able to access. For more information about how to create a Lambda rule that listens on the $aws/events/certificates/registered/caCertificateID topic and performs these actions, see Just-in-Time Registration.

Deactivate the CA Certificate

When you register a device certificate, AWS checks if the associated CA certificate is ACTIVE. If the CA certificate is INACTIVE, AWS IoT does not allow the device certificate to be registered. By marking the CA certificate as INACTIVE, you prevent any new device certificates issued by the compromised CA to be registered in your account. You can use the update-ca-certificate API to deactivate the CA certificate:

$ aws iot update-ca-certificate --certificate-id certificateId --new-status INACTIVE

Note

Any registered device certificates that were signed by the compromised CA certificate continue to work until you explicitly revoke them.

Use the ListCertificatesByCA API to get a list of all registered device certificates that were signed by the compromised CA. For each device certificate signed by the compromised CA certificate, use the UpdateCertificate API to revoke the device certificate to prevent it from being used.

Revoke the Device Certificate

If you detect suspicious activity on a registered device certificate, you can use the update-certificate API to revoke it:

$ aws iot update-certificate --certificate-id certificateId --new-status REVOKED

If any error or exception occurs during the auto-registration of the device certificates, AWS IoT sends events or messages to your logs in CloudWatch Logs. For more information about setting up the logs for your account, see the Amazon CloudWatch documentation.