Skip to content

Creating the JITR Lambda Function

Jump to bottom
Ben Udall edited this page Jan 25, 2017 · 3 revisions

Introduction

Signing modules can be registered with AWS as a Certificate Authority (CA) using the Bring Your Own Certificate BYOC capability (see Use Your Own Certificates). AWS devices that have certificates signed by this CA will be registered upon first use.

In addition to this Just-In-Time-Registration, the following is also required before the certificates can be used:

  • Attach a policy to the certificate
  • Activate the certificate

These requirements can be accomplished with a Lambda function attached to a rule.

The instructions below will show how to:

  • Create a Lambda Function that gets executed upon registration of the device certificate
  • Attach this Lambda Function to a Rule

Device Certificate Registration Event and Action

The following is an excerpt from the blog: Just-in-Time Registration of Device Certificates on AWS IoT

When a device attempts to connect with an X.509 certificate that is not known to AWS IoT but was signed by a CA that was registered with AWS IoT, the device certificate will be auto-registered by AWS IoT in a new PENDING_ACTIVATION state. PENDING_ACTIVATION means that the device certificate was auto-registered and is awaiting activation. Only AWS IoT can mark the status of a certificate as PENDING_ACTIVATION. If you connect with a certificate in PENDING_ACTIVATION state, a TLS handshake failure will occur because only ACTIVE certificates are authenticated with AWS IoT. For this reason, you need to change the status of the registered certificate from PENDING_ACTIVATION to ACTIVE so that it can be successfully authenticated.

When AWS IoT auto-registers a certificate or when a certificate in PENDING_ACTIVATION status connects, it publishes a message to the following MQTT topic:

$aws/events/certificates/registered/<caCertificateID>

where the 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 subscribe or attach any AWS IoT rule to the registration topic. The attached AWS IoT rules can then take some action based on the messages received. For example, an AWS IoT rule in your account can listen on the $aws/events/certificates/registered/+ topic to build an Amazon DynamoDB table of all the registered certificates. The general recommendation is to attach an AWS IoT rules engine action to the registration topic that will perform the bootstrapping or provisioning steps (like consulting your CRLs) and then activate/deactivate/revoke the certificate, create and attach the policies to the certificate, and so on.

In the following example, we will create a topic rule with an AWS Lambda action on the registration topic that will activate the certificate and create and attach a policy.

Use the AWS Lambda console to create the AWS Lambda function:

  1. Sign in to the AWS Management Console and open the AWS Lambda console at https://console.aws.amazon.com/lambda/home?region=us-east-1.

  2. Choose Create an AWS Lambda function.

  3. On the Configure function page, type a name and description for the AWS Lambda function. In Runtime, choose Node.js 4.3.

  4. Scroll down to the AWS Lambda function code section of the page. Replace the existing code with this sample code.

  5. Scroll down to the AWS Lambda function handler and role section of the page.
    For Role, choose Create a custom role. When the IAM console opens, you can create an IAM role that AWS Lambda can assume when executing the AWS Lambda function.

  6. In the navigation pane, choose Create New Role.

  7. For Role name, type a role name. To edit the role’s policy to give it permission to update the certificate and create and attach the policy:

    1. Choose View Policy Document.

    2. Replace the policy document with the following:

       {  
     "Version":"2012-10-17",  
     "Statement":[  
        {   
            "Effect":"Allow",  
            "Action":[    
                "logs:CreateLogGroup",  
                "logs:CreateLogStream",  
                "logs:PutLogEvents"  
            ],  
            "Resource":"arn:aws:logs:*:*:*"  
        },  
        {    
            "Effect":"Allow",  
            "Action":[    
                "iot:UpdateCertificate",  
                "iot:CreatePolicy",  
                "iot:AttachPrincipalPolicy"  
            ],  
            "Resource":"*"  
        }  
     ]  
 }

    3. Choose Allow.

  8. Leave the settings on the Advanced settings page at their defaults, and choose Next.

  9. On the Review page, choose Create function.

##Creating an AWS Lambda Rule

Now that you have created an AWS Lambda function, you can create a rule that invokes the function.

  1. In the AWS IoT console, choose Create a resource.
  2. Choose Create a rule.
  3. Type a name and description for the rule.
  4. Enter the following settings for the rule:
    SQL version: 2016-03-23-beta
    Attribute: *
    Topic filter: $aws/events/certificates/registered/#
    Note: The # can be replaced by the ID of a registered CA certificate to restrict the rule to that certificate.
  5. For Choose an action, choose Insert this message into a code function and execute it (AWS Lambda).
  6. From Function name, choose your AWS Lambda function name, and then choose Add action.
  7. Choose Create to create your AWS Lambda function.

You also need to grant permissions to the AWS IoT service principal to invoke the AWS Lambda function on your behalf when the MQTT message is published on the registration topic.

Note: If you created the rule through the AWS IoT console, you can skip this step. The console does this for you when you create the AWS Lambda rule.

You will use the AWS Lambda AddPermission API to grant permissions:

aws lambda add-permission --function-name <lambda-function-name>
--region us-east-1 --principal iot.amazonaws.com 
--source-arn <rule-arn> --source-account <your-aws-account>
--statement-id Id-123 --action "lambda:InvokeFunction"

Wiki Home

User Guide

Clone this wiki locally