@softchef/cdk-iot-security
Advanced tools
This is a AWS CDK construct package surrounding the topic of the AWS IoT Device registration, mainly implementing the functionalities of JITP, JITR, and Fleet-Provisioning.
cdk-iot-security is a project surrounding the topic of the AWS IoT Device registration. In order to utilize the AWS IoT services securely, we might need to maintain our device certificates and the relative resources. AWS IoT holds an organized architecture allowing us to register multiple certificates to it, and provides APIs for fetching information supporting our management. This project focuses on the autherization work flows of AWS IoT, provides CDK constructs which satisfy the requirements of Just-in-time registration, Just-in-time provisioning, and Fleet-provisioning. Utilizing cdk-iot-security, you do not need to implement the resource provisioning flow by yourself, and can focus on other functionalities of your IoT products.
npm install @softchef/cdk-iot-security
yarn add @softchef/cdk-iot-security
JITR work flow is usually applied in a situation that the devices are able to generate their own certificates. The scenario would probably like the following: the service provider deploy the JITR construct; the service provider create registered CA; the service provider make a copy of the CA certificate on a device and provide the device for the user client; an user client turn on the device and the device generate its certificate; the device connect to the AWS IoT through MQTT connection. The AWS IoT JITR service will be triggered and the JITR MQTT message will be passed through the topic rule, the SQS queue, eventually reach the Device Activator. Finally, the Device Activator verifies and activates the device certificate, and provision the AWS IoT resources for the device certificate.
The NodeJS Lambda Function with the functionality of activating a device certificate requesting for JITR.
The NodeJS Lambda Function with the functionality of registering a CA certificate on AWS IoT.
The NodeJS Lambda Function with the functionality of returning the names of the verfifiers.
The AWS IoT Topic Rule with the functionality of collecting the MQTT message originating from the JITR request.
The SQS queue with the functionality of recepting the MQTT message collected by the JITP Topic Rule and pass to the Device Activation for further review.
The S3 Bucket provided by the user for storing the created CA certificate secerts, including certificate, private key, and public key, also the CA certificate ID and ARN.
The Lambda Function provided by the user for device verification. If must return a payload with the following format:
{
...
"verified": "true", // or false
}
If it returns {"verified": "true"}, the Device Activator would complete the provision. Otherwise, the process is interrupted.
You can integrate your own API to the CA registrator and Verifiers Fetcher for utilization.
The process of applying JITR is mainly consist of the following steps:
Initialize the JITR construct.
Create CA through calling the CA Registrator.
Create the device certificate with the device.
Connect the device to the AWS IoT.
Some details informations of those three steps are discussed in the following sections. For step-by-step guide, please read the JITR demonstration files.
import { JustInTimeRegistration } from '@softchef/cdk-iot-security';
import * as cdk from '@aws-cdk/core';
import * as s3 from '@aws-cdk/aws-s3';
import * as lambda from '@aws-cdk/aws-lambda';
const app = new cdk.App();
const id = 'JitrDemo';
const stack = new cdk.Stack(app, id);
const anotherStack = new cdk.Stack(app, 'anotherStack');
new JustInTimeRegistration(stack, id, {
vault: {
bucket: new s3.Bucket(anotherStack, 'myVault2'),
prefix: 'my/ca/path',
},
verifiers: [
new lambda.Function(anotherStack, 'verifier1', {
code: lambda.Code.fromInline('exports.handler = async (_event) => { return JSON.stringify({ verified: true }); }'),
handler: 'handler',
runtime: lambda.Runtime.NODEJS_12_X,
}),
new lambda.Function(anotherStack, 'verifier2', {
code: lambda.Code.fromInline('exports.handler = async (event) => { return JSON.stringify({ verified: event? true : false }); }'),
handler: 'handler',
runtime: lambda.Runtime.NODEJS_12_X,
})
]
});
You call the CA Registrator to registrate a new CA on the AWS IoT before generating a device certificate.
CA Registrator assumes receiving an event object with the following format:
event = {
...
"body": {
"csrSubjects": {
"commonName": "myName",
"countryName": "TW",
"stateName": "TP",
"localityName": "TW",
"organizationName": "Soft Chef",
"organizationUnitName": "web"
},
"verifierName": "verifier_name",
}
}
Since the event is mainly a HTTP POST request, it has a body section containing attached information. The body consist of three parts, CSR subjects, verifier name, and template body.
CSR subjects define the information to fill up the subject fields of the CA certificate. CSR subjects are optional. If some of the fields are leaved blank, those fields will be fill up with empty string. Mandated by the AWS, the common name field would be replaced by the registration code, thus is unnecessary.
Verifier name specifies the verifier applied in the device verification. Verifier name is Optional.
You can checkout the names of the verifiers through the Verifiers Fetcher when you forget the names.
Verifiers Fetcher assumes receiving an event object with the following format:
event = {
...
body: {}
}
Since the event is mainly a HTTP GET request, no body content is expected. However, no matter what the request content is, the Verifiers Fetcher always return all the verifiers' name.
To trigger the JITR and the provisioning of resources, the deivce has to send a MQTT message to the AWS IoT. You need to have the basic knowledge about the MQTT. You can complete this step with either a pure MQTT connection, or aws-iot-deivce-sdk. For the former, please read mqtt-connect.js, for the later, please read device.js
JITP work flow is usually applied in a situation that the devices are not able to generate their own certificates. The scenario would probably like the following: the service provider deploies the JITP construct and provides the API for the user client; the service provider creates registered CA; an user client get the generated device certificate through the API; the user client pass the device certificate to the device; the device connect to the AWS IoT through MQTT connection. Finally, the AWS IoT JITP service will be triggered and provision the expected resources.
The NodeJS Lambda Function with the functionality of registering a CA certificate on AWS IoT.
The NodeJS Lambda Function with the functionality of returning the names of the verfifiers.
The NodeJS Lambda Function with the functionality of generating the device certificate.
The S3 Bucket provided by the user for storing the created CA certificate secerts, including certificate, private key, and public key, also the CA certificate ID and ARN.
The Lambda Function provided by the user for device verification. If must return a payload with the following format:
{
...
"verified": "true", // or false
}
If it returns {"verified": "true"}, the Device Certificate Generator would complete the device certificate generation. Otherwise, the process is interrupted.
You can integrate your own API to the CA registrator, Device Certificate Generator, and Verifiers Fetcher for further utilization.
The process of applying JITP is mainly consist of the following steps:
Initialize the JITP construct.
Create CA through calling the CA Registrator.
Create Device Certificate through calling the Device Certificate Generator.
Connect the device to the AWS IoT.
Some details informations of those four steps are discussed in the following sections. For step-by-step guide, please read the JITP demonstration files.
import { JustInTimeProvision } from '@softchef/cdk-iot-security';
import { Bucket } from '@aws-cdk/aws-s3';
import * as cdk from '@aws-cdk/core';
const app = new cdk.App();
const id = 'JitpDemo';
const stack = new cdk.Stack(app, id);
const justInTimeProvision = new JustInTimeProvision(stack, id, {
vault: {
bucket: new Bucket(stack, 'myVault'),
},
verifiers: [
new lambda.Function(anotherStack, 'verifier1', {
code: lambda.Code.fromInline('exports.handler = async (_event) => { return JSON.stringify({ verified: true }); }'),
handler: 'handler',
runtime: lambda.Runtime.NODEJS_12_X,
}),
new lambda.Function(anotherStack, 'verifier2', {
code: lambda.Code.fromInline('exports.handler = async (event) => { return JSON.stringify({ verified: event? true : false }); }'),
handler: 'handler',
runtime: lambda.Runtime.NODEJS_12_X,
})
],
});
You call the CA Registrator to registrate a new CA on the AWS IoT before generating a device certificate.
CA Registrator assumes receiving an event object with the following format:
event = {
...
"body": {
"csrSubjects": {
"commonName": "myName",
"countryName": "TW",
"stateName": "TP",
"localityName": "TW",
"organizationName": "Soft Chef",
"organizationUnitName": "web"
},
"verifierName": "verifier_name",
"templateBody": "{ \"Parameters\" : { \"AWS::IoT::Certificate::Country\" : { \"Type\" : \"String\" }, \"AWS::IoT::Certificate::Id\" : { \"Type\" : \"String\" } }, \"Resources\" : { \"thing\" : { \"Type\" : \"AWS::IoT::Thing\", \"Properties\" : { \"ThingName\" : {\"Ref\" : \"AWS::IoT::Certificate::Id\"}, \"AttributePayload\" : { \"version\" : \"v1\", \"country\" : {\"Ref\" : \"AWS::IoT::Certificate::Country\"}} } }, \"certificate\" : { \"Type\" : \"AWS::IoT::Certificate\", \"Properties\" : { \"CertificateId\": {\"Ref\" : \"AWS::IoT::Certificate::Id\"}, \"Status\" : \"ACTIVE\" } }, \"policy\" : {\"Type\" : \"AWS::IoT::Policy\", \"Properties\" : { \"PolicyDocument\" : \"{\\\"Version\\\": \\\"2012-10-17\\\",\\\"Statement\\\": [{\\\"Effect\\\":\\\"Allow\\\",\\\"Action\\\": [\\\"iot:Connect\\\",\\\"iot:Publish\\\"],\\\"Resource\\\" : [\\\"*\\\"]}]}\" } } } }"
}
}
}
Since the event is mainly a HTTP POST request, it has a body section containing attached information. The body consist of three parts, CSR subjects, verifier name, and template body.
CSR subjects define the information to fill up the subject fields of the CA certificate. CSR subjects are optional. If some of the fields are leaved blank, those fields will be fill up with empty string. Mandated by the AWS, the common name field would be replaced by the registration code, thus is unnecessary.
Verifier name specifies the verifier applied in the device verification. Verifier name is Optional.
Template body is a string defining the resources provisioned for the device. Template body is Optional. If no template body being specified, a default template body will be applied. See more information about defining a template body from here.
You call the Device Certificate Generator to generate a device certificate after register a CA on AWS IoT.
Device Certificate Generator assumes receiving an event object with the following format:
event = {
...
body: {
"caCertificateId": "myCaCertificateId",
"csrSubjects": {
"commonName": "myThingName", // data in this field would be the thing name
"countryName": "TW",
"stateName": "TP",
"localityName": "TW",
"organizationName": "Soft Chef",
"organizationUnitName": "web"
},
"deviceInfo": {
...
},
}
}
Since the event is mainly a HTTP POST request, it has a body section containing attached information. The body consist of three parts, CA certificate ID, CSR subjects, and device information.
CA certificate ID is the ID of the CA created by the CA Registrator. CA certificate ID is required by the Device Certificate Generator. The CA will authenticate the device certificate.
CSR subjects define the information to fill up the subject fields of the device certificate. CSR subjects are optional. If some of the fields are leaved blank, those fields will be fill up with empty string. The string data in the common name field will be set as the name of the AWS IoT Thing. Thing name is the desirable name you give to the AWS IoT thing provisioned for the device certificate. If no thing name is specified, the thing name would be an UUID.
Device information is the information provided by the device for verification. Whether it is required or not and its form depends on your configuration of the verifiers.
You can checkout the names of the verifiers through the Verifiers Fetcher when you forget the names.
Verifiers Fetcher assumes receiving an event object with the following format:
event = {
...
body: {}
}
Since the event is mainly a HTTP GET request, no body content is expected. However, no matter what the request content is, the Verifiers Fetcher always return all the verifiers' name.
To trigger the JITP and the provisioning of resources, the deivce has to send a MQTT message to the AWS IoT. You need to have the basic knowledge about the MQTT. You can complete this step with either a pure MQTT connection, or aws-iot-deivce-sdk. For the former, please read this file, for the later, please read this file.
The NodeJS Lambda Function with the functionality of registering a Fleet-Provisioning Template and a Provisioning Claim Certificate on AWS IoT.
The S3 Bucket provided by the user for storing the created Provisioning Claim Certificate secerts, including certificate, private key, and public key, also the Provisioning Claim Certificate ID and ARN.
You can integrate your own API to the Fleet Generator for further utilization.
The process of applying Fleet-Provision is mainly consist of the following steps:
Initialize the Fleet-Provision construct.
Create the Fleet-Provisioning Template and Provisioning Claim Certificate through calling the Fleet Generator.
Connect the device to the AWS IoT with Provisioning Claim Certificate and save the formal device certificates in the device.
Some details informations of those three steps are discussed in the following sections. For step-by-step guide, please read the Fleet-Provision demonstration files.
import * as apigateway from '@aws-cdk/aws-apigateway';
import * as s3 from '@aws-cdk/aws-s3';
import * as cdk from '@aws-cdk/core';
import { FleetProvision } from '@softchef/cdk-iot-security';
const app = new cdk.App();
const id = 'FleetProvisionDemo';
const stack = new cdk.Stack(app, id);
const vault = new s3.Bucket(stack, 'myVault');
const fleetProvision = new FleetProvision(stack, id, {
vault: {
bucket: vault,
},
// Decomment the following line to apply the Greengrass V2 mode
// greengrassV2: true,
});
You call the Fleet Generator to generate a new Fleet-Provisioning Template and Provisioning Claim Certificate on the AWS IoT.
Fleet Generator assumes receiving an event object with the following format:
event = {
...
"body": {
"templateName": "myTemplateName",
}
}
Since the event is mainly a HTTP POST request, it has a body section containing attached information. The body consist of the template name.
To trigger the Fleet-Provision, the deivce has to send a MQTT message to the AWS IoT. You can complete this step with aws-iot-deivce-sdk-v2. Please read this file for detail.
FAQs
This is a AWS CDK construct package surrounding the topic of the AWS IoT Device registration, mainly implementing the functionalities of JITP, JITR, and Fleet-Provisioning.
We found that @softchef/cdk-iot-security demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.