Self-managed certificate signing using Amazon IoT Core certificate provider

You can create an Amazon IoT Core certificate provider to sign certificate signing requests (CSRs) in Amazon IoT fleet provisioning. A certificate provider references a Lambda function and the CreateCertificateFromCsr MQTT API for fleet provisioning. The Lambda function accepts a CSR and returns a signed client certificate.

When you don't have a certificate provider with your Amazon Web Services account, the CreateCertificateFromCsr MQTT API is called in fleet provisioning to generate the certificate from a CSR. After you create a certificate provider, the behavior of the CreateCertificateFromCsr MQTT API will change and all calls to this MQTT API will invoke the certificate provider to issue the certificate.

With Amazon IoT Core certificate provider, you can implement solutions that utilize private certificate authorities (CAs) such as Amazon Private CA, other publicly trusted CAs, or your own Public Key Infrastructure (PKI) to sign the CSR. In addition, you can use certificate provider to customize your client certificate's fields such as validity periods, signing algorithms, issuers, and extensions.

How self-managed certificate signing works in fleet provisioning

Key concepts

The following concepts provide details that can help you understand how self-managed certificate signing works in Amazon IoT fleet provisioning. For more information, see Provisioning devices that don't have device certificates using fleet provisioning.

Diagram

The following diagram is a simplified illustration of how self-certificate signing works in Amazon IoT fleet provisioning.

Certificate provider Lambda function input

Amazon IoT Core sends the following object to the Lambda function when a device registers with it. The value of certificateSigningRequest is the CSR in Privacy-Enhanced Mail (PEM) format that's provided in the CreateCertificateFromCsr request. The principalId is the ID of the principal used to connect to Amazon IoT Core when making the CreateCertificateFromCsr request. clientId is the client ID set for the MQTT connection.

{
	"certificateSigningRequest": "string",
	"principalId": "string",
	"clientId": "string"
}

Certificate provider Lambda function return value

The Lambda function must return a response that contains the certificatePem value. The following is an example of a successful response. Amazon IoT Core will use the return value (certificatePem) to create the certificate.

{
	"certificatePem": "string"
}

If the registration is successful, CreateCertificateFromCsr will return the same certificatePem in the CreateCertificateFromCsr response. For more information, see the response payload example of CreateCertificateFromCsr.

Example Lambda function

Before creating a certificate provider, you must create a Lambda function to sign a CSR. The following is an example Lambda function in Python. This function calls Amazon Private CA to sign the input CSR, using a private CA and the SHA256WITHRSA signing algorithm. The returned client certificate will be valid for one year. For more information about Amazon Private CA and how to create a private CA, see What is Amazon Private CA? and Creating a private CA.

import os
import time
import uuid
import boto3

def lambda_handler(event, context):
    ca_arn = os.environ['CA_ARN']
    csr = (event['certificateSigningRequest']).encode('utf-8')

    acmpca = boto3.client('acm-pca')
    cert_arn = acmpca.issue_certificate(
        CertificateAuthorityArn=ca_arn, 
        Csr=csr,
        Validity={"Type": "DAYS", "Value": 365}, 
        SigningAlgorithm='SHA256WITHRSA',
        IdempotencyToken=str(uuid.uuid4())
    )['CertificateArn']
    
    # Wait for certificate to be issued
    time.sleep(1)    
    cert_pem = acmpca.get_certificate(
        CertificateAuthorityArn=ca_arn,
        CertificateArn=cert_arn
    )['Certificate']
    
    return {
        'certificatePem': cert_pem
    }

The following resource-based policy example for Lambda grants Amazon IoT the permission to invoke the Lambda function:

{
	"Version": "2012-10-17",
	"Id": "InvokePermission",
	"Statement": [
		{
			"Sid": "LambdaAllowIotProvider",
			"Effect": "Allow",
			"Principal": {
				"Service": "iot.amazonaws.com"
			},
			"Action": "lambda:InvokeFunction",
			"Resource": "arn:aws:lambda:us-east-1:123456789012:function:my-function",
			"Condition": {
				"StringEquals": {
					"AWS:SourceAccount": "123456789012"
				},
				"ArnLike": {
					"AWS:SourceArn": "arn:aws:iot:us-east-1:123456789012:certificateprovider:my-certificate-provider"
				}
			}
		}
	]
}

Self-managed certificate signing for fleet provisioning

You can choose self-managed certificate signing for fleet provisioning using Amazon CLI or Amazon Web Services Management Console.

aws iot create-certificate-provider \
                --certificateProviderName my-certificate-provider \
                --lambdaFunctionArn arn:aws:lambda:us-east-1:123456789012:function:my-function-1 \
                --accountDefaultForOperations CreateCertificateFromCsr

{
	"certificateProviderName": "my-certificate-provider",
	"certificateProviderArn": "arn:aws:iot:us-east-1:123456789012:certificateprovider:my-certificate-provider"
}

Amazon CLI commands for certificate provider

Create certificate provider

To create a certificate provider, use the CreateCertificateProvider API operation or the create-certificate-provider CLI command.

aws iot create-certificate-provider \
                --certificateProviderName my-certificate-provider \
                --lambdaFunctionArn arn:aws:lambda:us-east-1:123456789012:function:my-function-1 \
                --accountDefaultForOperations CreateCertificateFromCsr

The following shows an example output for this command:

{
	"certificateProviderName": "my-certificate-provider",
	"certificateProviderArn": "arn:aws:iot:us-east-1:123456789012:certificateprovider:my-certificate-provider"
}

For more information, see CreateCertificateProvider from the Amazon IoT API Reference.

Update certificate provider

To update a certificate provider, use the UpdateCertificateProvider API operation or the update-certificate-provider CLI command.

aws iot update-certificate-provider \
                --certificateProviderName my-certificate-provider \
                --lambdaFunctionArn arn:aws:lambda:us-east-1:123456789012:function:my-function-2 \
                --accountDefaultForOperations CreateCertificateFromCsr

The following shows an example output for this command:

{
	"certificateProviderName": "my-certificate-provider",
	"certificateProviderArn": "arn:aws:iot:us-east-1:123456789012:certificateprovider:my-certificate-provider"
}

For more information, see UpdateCertificateProvider from the Amazon IoT API Reference.

Describe certificate provider

To describe a certificate provider, use the DescribeCertificateProvider API operation or the describe-certificate-provider CLI command.

aws iot describe-certificate-provider --certificateProviderName my-certificate-provider

The following shows an example output for this command:

{
	"certificateProviderName": "my-certificate-provider",
	"lambdaFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function",
	"accountDefaultForOperations": [
		"CreateCertificateFromCsr"
	],
	"creationDate": "2022-11-03T00:15",
	"lastModifiedDate": "2022-11-18T00:15"
}

For more information, see DescribeCertificateProvider from the Amazon IoT API Reference.

Delete certificate provider

To delete a certificate provider, use the DeleteCertificateProvider API operation or the delete-certificate-provider CLI command. If you delete the certificate provider resource, the behavior of CreateCertificateFromCsr will resume, and Amazon IoT will create certificates signed by Amazon IoT from a CSR.

aws iot delete-certificate-provider --certificateProviderName my-certificate-provider

This command doesn't produce any output.

For more information, see DeleteCertificateProvider from the Amazon IoT API Reference.

List certificate provider

To list the certificate providers within your Amazon Web Services account, use the ListCertificateProviders API operation or the list-certificate-providers CLI command.

aws iot list-certificate-providers

The following shows an example output for this command:

{
	"certificateProviders": [
		{
			"certificateProviderName": "my-certificate-provider",
			"certificateProviderArn": "arn:aws:iot:us-east-1:123456789012:certificateprovider:my-certificate-provider"
		}
	]
}

For more information, see ListCertificateProvider from the Amazon IoT API Reference.