Filter results by

AWS Lambda: Just-in-time Registration

AWS Lambda functions are discrete computing packages that are destined for deployment either in the AWS cloud or on a remote device such as an ARTIK module. In the AWS Greengrass article, we referenced an AWS article on how to deploy a simple lambda function on an ARTIK module. Here, we will provide a practical example of how to create a lambda function for use in the AWS cloud.

This specific project is for use with AWS IoT just-in-time (JIT) registration. The lambda function gets triggered when a pre-provisioned ARTIK module tries to connect to AWS cloud for the first time as described in the AWS IoT article.

Prerequisites

  • If you haven't already, start by following the introductory article to:

    – Set up an AWS account

    – Install the AWS CLI on your ARTIK board.

  • Follow the one-time registration procedure to register a CA Certificate with AWS IoT.

  • You'll be using these AWS services in the procedures that follow.

    – AWS IoT
    – IAM
    – Lambda
    – DynamoDB

Usage Model

In the application we present here, we show one approach to registering individual ARTIK modules with AWS. It assumes that all keys, certificates, and associated serial numbers are generated in bulk on a secure Linux-based factory floor console, which is also used to compile a whitelist of serial numbers using an AWS DynamoDB database.

On the first network connection of the module, the certificate and its embedded serial number will become known to AWS IoT, which:

  • verifies the certificate validity
  • generates a certificateId that is forevermore associated with this certificate
  • generates a connect event.

An AWS Lambda function, which we provide here, services the connect event. It checks the serial number against the DynamoDB whitelist; if valid, the Lambda function enables the device for regular MQTT communication with AWS IoT.

Bulk Provisioning

To prepare an ARTIK Linux module for eventual connection to AWS IoT, you need to give it a certificate based on a secret key stored in the Secure Element of the module, as we described in the AWS IoT article. Both the key and certificate will be device-unique.

The manufacturer typically generates key and certificate sets in bulk (for example, 100 sets for an initial test run of 100 devices), and installs a set on each ARTIK module during device provisioning (typically during initial testing and burn-in).

We'll be referencing a "whitelist" in this article. For the purposes of our application, the whitelist is a list of just the serial numbers of the certificates. When a known device is connected, the AWS event message will contain the serial number that can be checked against the whitelist.

CLI

Because we ask you to install and use the AWS CLI on the ARTIK board during setup as a prerequisite for most AWS tutorials, it is convenient to simply use the same ARTIK board to send CLI commands to AWS – essentially emulating the factory floor Linux console. This arrangement is for demonstration only.

In an actual production environment, it is unlikely that the ARTIK board would be used for this purpose. The AWS CLI can instead be installed on your development PC, or whatever system you choose to act as your factory floor console machine.

Preparation

The file bundle contains code and JSON files to set up various aspects of this project. Download it to your ARTIK board root directory.

AWS IoT JITR Lambda code

Unzip the software bundle using unzip (you can install it with apt install unzip). In the newly created aws-iot-sample-master directory you should find:

  • TestEvent.json
  • Whitelist-DynamoDB.json – sample response from creating a Dynamo DB table
  • externalTest.js
  • index.js
  • package.json
  • role_policy.json

AWS DynamoDB Whitelist

AWS provides the DynamoDB database tool that is both simple and powerful. With it, you'll set up a whitelist for your bulk-provisioned devices. From your AWS Dashboard, under Services, select DynamoDB.

The Lambda function checks the JIT-registered certificate against a whitelist stored in DynamoDB, where we'll utilize one table with two attributes:

  • IssuerCN – the Common Name of the certificate's Issuer
  • SerialNumber – the Serial Number of the certificate

Create table

The easiest way to create the table is to use the AWS CLI from your ARTIK board. Just enter the Python virtual environment, then copy and paste the command below (or your modified version of it) to create the table.

aws dynamodb create-table \
--table-name Whitelist2 \
    --attribute-definitions \
        AttributeName=IssuerCN,AttributeType=S \
        AttributeName=SerialNumber,AttributeType=S \
    --key-schema \
        AttributeName=IssuerCN,KeyType=HASH \
        AttributeName=SerialNumber,KeyType=RANGE \
    --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5

Save the ARN value from the response – you'll need it later for your Lambda Function code.

Enter items

Just to see how it looks, use the DynamoDB Dashboard to insert some items in the newly created table for whitelisted certificates.

In the actual whitelisting script you would create, you might instead use a CLI command to automate the entry of an entire list. You simply create JSON format information. It looks like this for a single item:

aws dynamodb put-item \
--table-name Whitelist2  \
--item \
'{"IssuerCN": {"S": "marks-iot"}, "SerialNumber": {"S": "12345"}}' \
--return-consumed-capacity TOTAL  

or like this to reference a file:

aws dynamodb put-item \
--table-name Whitelist2  \
--item file://_your_filename.json_ \
--return-consumed-capacity TOTAL  

Refer to the Accessing AWS DynamoDB instructions for details on using the CLI as well as the API.

AWS Lambda Function

You'll first need to create a package to send to AWS Lambda, and then you'll create the function using the AWS Lambda console.

Create the Lambda deployment package

On your ARTIK board, go to the root directory where you unzipped the file bundle and run the commands:

apt install zip (if not already installed)
npm install
zip -r ../lambda-deployment.zip .

These steps create an archive lambda-deployment.zip in the parent directory that contains the associated node module fidm/x509 needed for this Lambda function.

Use scp or other means to transfer this file to your development PC for uploading to AWS.

Create the Lambda function

Create a Lambda function for whitelisting the JIT registered certificates.

  1. From your AWS Dashboard, click the Services pull-down and select Lambda (it's under Compute).

  2. On the Lambda page of your console, click [Create function]. You'll be using "Author from scratch".

  3. Give a name to the function – here we'll use WhitelistedJITRegistration

  4. Select 'Node.js 6.10' or above as the Runtime

  5. For the Role, select 'Create a custom role'.
    1. In the Role Summary, create a new IAM Role, and name it lambda_iot_dynamodb_execution
    2. Click [Allow]
  6. Click [Create function]

Configure the Lambda function

Within your WhitelistedJITRegistration function, you should see boxes 1  2  3 as indicated below.

  1. In the "Add triggers" column, click on AWS IoT.

    The "Configure triggers" window opens below.

    1. Select Custom IoT rule, and pick JITRegistrationRule created earlier in AWS IoT. You should now see the Rule query statement you put in earlier.

    2. Click [Add]

  2. Click the WhitelistedJITRegistration box (showing the Lambda icon).

    The "Function code" window opens below.

    1. Select "Code entry type" as Upload a .zip file
    2. As "Function package" click Upload and specify the lambda-deployment.zip file you copied over from your ARTIK board.
    3. You can leave "Handler" at its default of index.handler
  3. Click [Save]

In the "Function code" window, you now have an editing environment for all the files in the zip package.

  1. Open role_policy.json and change the "Resource" value to the ARN of your DynamoDB table that you saved in Create table.

AWS IoT

Create JIT Rule

Create a Rule to act on newly detected certificates associated with the CA certificate during the JIT registration process.

  1. Go to the AWS IoT Dashboard and select Act.

  2. Click the [Create] button.

  3. In the Name box, copy and paste JITRegisttrationRule

  4. Copy the line below to the "Rule query statement" box.

    SELECT * FROM '$aws/events/certificates/registered/#'

  5. Click [Add action], and then within the "Select an action" list:

    1. Select "Invoke a Lambda function…"
    2. Click [Configure action]
    3. For the Function name select WhitelistedJITRegistration
    4. Click [Add action]

Test the Lambda function

When you click [Test], you will have an opportunity to create a test message. Use one of the MQTT messages you received when you tried connecting your ARTIK board in the Trigger the event message portion of the AWS IoT article. As before, it looks like this, but you need it to contain legitimate account and certificate values.

{
  "certificateId": "852c2b92cda889ad8bdadb96012ada9b5520a14460fb63ebcaa187b42155199c",
  "caCertificateId": "605324c6cbbce99455bfa9b781b22c3b9bbe80a9c4df51b2b5ff81022f53a8ee",
  "timestamp": "2018-08-20T22:50:13.000Z",
  "certificateStatus": "PENDING_ACTIVATION",
  "awsAccountId": "612346207641",
  "certificateRegistrationTimestamp": "2018-08-20T22:50:13.000Z"
}

Now you're ready to test the Lambda function with the JSON 'event'. If you see no errors, your function is ready to be used to register JIT certificates.

Last updated on: