README.md

Connected Mobility Solution on AWS - Provisioning Module

Connected Mobility Solution on AWS | 🚧 Feature request | 🐛 Bug Report | ❓ General Question

Note: If you want to use the solution without building from source, navigate to the AWS Solution Page.

Table of Contents

• Connected Mobility Solution on AWS - Provisioning Module
  • Table of Contents
  • Solution Overview
  • Architecture Diagram
  • Sequence Diagrams
  • AWS CDK and Solutions Constructs
  • Customizing the Module
  • Prerequisites
    • MacOS Installation Instructions
    • Clone the Repository
    • Install Required Dependencies
    • Unit Test
    • Local Testing
    • Build the Module
    • Upload Assets to S3
    • Deploy on AWS
    • Delete
  • Usage
  • Cost Scaling
  • Collection of Operational Metrics
  • License

Solution Overview

CMS Vehicle Provisioning is a deployable module within Connected Mobility Solution on AWS (CMS) that enables vehicles to connect to IoT core using TLS-based mutual authentication. Vehicles must be provisioned with Amazon Trust Services Root Certificate Authority (CA). A customer may also elect to use their own private CA. The provisioning process encompasses generating a unique public/private key pair, and assembling and signing an X.509 certificate. Ideally, the vehicle should have a pre-programmed or generatable private/public key pair in order for the private key to be stored on their secure storage (TPM/HS, Secure enclave, etc.). Best security practice recommends that private keys shall never be transmitted over any communication channels. However, this is not always possible. In this case, the vehicle must be registered using the fleet provisioning process before it can access CMS provided services.

For more information and a detailed deployment guide, visit the CMS Vehicle Provisioning Implementation Guide page.

Architecture Diagram

Sequence Diagrams

AWS CDK and Solutions Constructs

AWS Cloud Development Kit (AWS CDK) and AWS Solutions Constructs make it easier to consistently create well-architected infrastructure applications. All AWS Solutions Constructs are reviewed by AWS and use best practices established by the AWS Well-Architected Framework.

In addition to the AWS Solutions Constructs, the solution uses AWS CDK directly to create infrastructure resources.

Customizing the Module

Prerequisites

• Python 3.12+
• NVM
• NPM 8+
• Node 18+
• Pipenv

MacOS Installation Instructions

Pyenv Github Repository

brew install pyenv
pyenv install 3.12

Pipenv Github Repository

pip install --user pipenv
pipenv sync --dev

NVM Github Repository

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

NPM/Node Official Documentation

nvm install 18
nvm use 18

Clone the Repository

git clone https://github.com/aws-solutions/connected-mobility-solution-on-aws.git
cd connected-mobility-solution-on-aws/source/modules/cms_provisioning/

Install Required Dependencies

make install

Unit Test

After making changes, run unit tests to make sure added customization pass the tests:

make test

Local Testing

For manual local testing, a test script is provided in the test_scripts directory:

• provisioning_by_claim.py
  • Fetches a claim certificate and corresponding private key from Amazon CA. Then generates new credentials (private key and certificate) and uses those credentials to execute the vehicle provisioning flow. After execution, the vehicle and certificate will be registered in IoT Core and stored in DynamoDB. After provisioning, it posts a message to the vehicleactive MQTT topic, triggering the initial detection flag for a vehicle connecting for the first time.

This script relies on these AWS account credentials:

• .aws/config
• .aws/credentials

Run these scripts from outside the test_scripts folder:

python -m test_scripts.provisioning_by_claim

Build the Module

The build script manages dependencies, builds required assets (e.g. packaged lambdas), and creates the AWS Cloudformation templates.

make build

Upload Assets to S3

make upload

Deploy on AWS

make deploy

Delete

make destroy

Usage

Each vehicle connecting to IoT Core for use with CMS on AWS must be provisioned as a valid ‘thing’ within IoT Core:

• A vehicle must have its unique X.509 Certificate
• A valid IoT policy must be attached to said Certificate
• A vehicle must be registered in IoT device registry

The device public key infrastructure (PKI) consists of Certificate Authorities (CAs) that issue and sign X.509 device certificates to establish a source of trust for a device. A customer may elect between:

• IoT Core generated certificates using AWS CA.
  • Option 1: A private key is also generate by AWS. Once generated, the private key and device certificate must be securely downloaded and copied to a vehicle.
  • Option 2: A vehicle already has a private key, so a certificate signing request (CSR) is sent to AWS IoT core.
• Private CA. This is more suitable for larger enterprise customers.
• Third-party CA

Cost Scaling

Cost will be dependent on the numbers of vehicles provisioned and data stored.

• AWS IoT Core Cost
• Amazon DynamoDB Cost

For more details, see the implementation guide.

Collection of Operational Metrics

This solution collects anonymized operational metrics to help AWS improve the quality and features of the solution. For more information, including how to disable this capability, please see the implementation guide.

License

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.