A tool for dealing with AWS IoT certificates
Project description
THIS REPOSITORY IS A WORK IN PROGRESS
IF YOU SEE THIS MESSAGE DO NOT UNDER ANY CIRCUMSTANCE DELETE INFRASTRUCTURE HOPING THAT WINTERGREEN CAN REBUILD IT We're working on it.
Purpose
Automate device registry in AWS IoT because it sucks. wintergreen
is a command line utility that provides mechanisms to automate cumbersome tasks related to signing and registering AWS IoT Thing device certificates.
Install
This project uses poetry to manage and install dependencies.
poetry install
This will install the required dependencies as well as the wintergreen
cli, which can be invoked by running poetry run wintergreen
Using with direnv
Follow this layout_poetry example
Run
Initialize
Initialization means
- Creating a ThingType
- Creating a RootCA cert/key pair
- Registering that RootCA with AWS
- Creating a Just-in-time Provisioning role
Example:
poetry run wintergreen init -t my-cool-thing
Check your ~/.wintergreen
directory to see a subdirectory for my-cool-thing
$ wintergreen init --help
Usage: wintergreen init [OPTIONS]
Creates a custom root CA and registers it with the cloud provider for
automatic provisioning.
Options:
-t, --thing-type TEXT AWS IoT thing type [required]
-c, --country TEXT Country code (2-letter) to use for provisioning
certs i.e. US [required]
-f, --fqdn TEXT Domain of the organization to use in the CA e.g.
verypossible.com
-o, --organization TEXT Organization name i.e. Very
-s, --state TEXT State or Province code (2-letter) to use for
provisioning certs i.e. TN
-l, --locality TEXT Locality to use for provisioning certs i.e.
Chattanooga
-u, --unit TEXT Organizational unit to use for provisioning
certs i.e. Engineering
-d, --root-ca-days INTEGER Days until CA will expire [default: 365]
-k, --key-size INTEGER [default: 2048]
--log-level TEXT
--help Show this message and exit.
Outputs:
{
jitpRoleArn: "arn:to:role",
rootCACertPath: "${HOME}/.wintergreen/things/Widget/rootCA.crt",
rootCAKeyPath: "${HOME}/.wintergreen/things/Widget/rootCA.key",
certificateArn:"arn:aws:iot:account:region:cacert/1234"
}
Provision a new device
Provisioning a device means generating a certificate/key pair to be used for the device to authenticate with AWS IoT.
$ wintergreen provision --help
Usage: wintergreen provision [OPTIONS]
Creates a new device key and certificate that is signed by a custom root
CA.
Options:
-t, --thing-type TEXT Same as the thing-type that was chosen in the
`init` step.
--root-ca-path PATH Required if thing-type from a previous run of
`init` is not provided.
--root-ca-key-path PATH Required if thing-type from a previous run of
`init` is not provided.
-c, --common-name TEXT Defaults to a UUIDv4
-c, --country TEXT [required]
-o, --organization TEXT
-s, --state TEXT
-l, --locality TEXT
-u, --unit TEXT
-d, --days INTEGER Days until certificate will expire [default: 365]
-k, --key-size INTEGER [default: 2048]
-n, --number Number of certificates to provision
--help Show this message and exit.
Outputs:
{
deviceCert: "-----BEGIN CERTIFICATE-----....",
deviceCertPlusCACert: "-----BEGIN CERTIFICATE-----....",
deviceKey: "------BEGIN RSA PRIVATE KEY----...",
commonName: "thing-name"
}
These will be written as files scoped by date into your .wintergreen
directory. If you use the -n
argument, it will generate a unique uuid for each cert and put all of the certs generated in their own folder. You'll also see an output.csv which contains a table of all the certs generated on this run.
Example provisioning cert example (AWS)
After running the provision
command the cert/key will be saved in a directory named after the thing-type as deviceCertPlusCACert-{common_name}.crt
and deviceKey-{common_name}.key
You'll also need to grab the aws-root-ca.pem
from AWS Trust.
Lastly to test, you'll need to get your ATS endpoint by running aws iot describe-endpoint --endpoint-type iot:Data-ATS --region us-east-1
If you have an mqtt client (brew install mosquitto
) installed, you can verify that a generated device will provision correctly by running something like
mosquitto_pub --cafile aws-root-ca.pem \
--cert path/to/deviceCertPlusCACert-my-thing-common-name.crt \
--key path/to/deviceKey-my-thing-common-name.key \
-h your-endpoint-for-ats.iot.us-east-1.amazonaws.com \
--tls-version tlsv1.2 \
-p 8883 \
-q 1 \
-t /my-thing-type/my-thing-common-name/events \
-I anyclientID -m "{Hello}" -d
Eventually, you will see a device my-thing-common-name
in the Things menu.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for wintergreen-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e054702ee161d939255fecdeb05850db2c8b4902718ea0d66bf6cb271fcc60d2 |
|
MD5 | 4dd9f32a927563d20178042d43aa2369 |
|
BLAKE2b-256 | dab0cda9b46c9b5f856bdd0d77bec4c288154e43739fa26efa9d8a6837b092f3 |