pyawsutils package¶

Multi-Account Registration¶

AWS multi account registration (MAR)

class pyawsutils.mar.aws_mar(aws_profile='default')¶

Bases: object

AWS Multi Account Registration

Parameters:: aws_profile (str) – AWS profile to be used.

activate_certificate(certificate_arn)¶

Activate a certificate in AWS

Parameters:: certificate_arn (str) – AWS ARN for the certificate

combine_everything(thing_name, policy_name, certificate_arn)¶

Attach policy to certificate and certificate to thing.

Parameters:

thing_name (str) – Name of the thing where the certificate should be attached to
policy_name (str) – Name of the policy that should be attached to the certificate
certificate_arn (str) – Amazon Resource Name (ARN) of the certificate

create_cert_fingerprint(certificate)¶

Create a fingerprint of a certificate.

Parameters:: certificate (str) – Certificate in PEM format
Returns:: Certificate fingerprint (SHA256 of DER encoded certificate). ASCII encoded hex string with 40 lower case characters
Return type:: str

create_device(certificate_file, policy_name='zt_policy', thing_type=None, thing_name_source='ski')¶

Register a device in AWS IoT by using multi account registration (MAR)

Parameters:

certificate_file (str) – Certificate file name including path
policy_name (str, optional) – Name of the policy that should be attached
thing_type – Thing type that should be attached
thing_name_source (str, optional) – What to use as thing name in AWS from the certificate ski=Subject Key identifier or scn=Subject Common Name

create_thing(thing_name, thing_type=None)¶

Create a thing in AWS IoT

Parameters:

thing_name (str) – Name for the thing
thing_type (str) – Thing type to assign the thing to. Will create the type if it does not exist.

register_certificate(certificate, status='ACTIVE')¶

Registers a device certificate in AWS by using MAR.

Parameters:

certificate (str) – Device certificate in PEM format.
status (str, optional) – Certificate status that should be set e.g. ACTIVE, INACTIVE …

pyawsutils.mar.mar_cli_handler(args)¶: Entry point for MAR command of CLI

AWS CloudFormation¶

Methods to use AWS Cloudformation

pyawsutils.aws_cloudformation.check_status(cf_client, stack_name)¶

Check status of Cloudformation stacks

Parameters:

cf_client (boto3 client object) – cloud formation client
stack_name (str) – name of stack to check

Returns:

status: “CREATE_COMPLETE”, “IN_PROGRESS” or “STACK_DELETED”

Return type:

str

pyawsutils.aws_cloudformation.create_cloudformation_stack(pc_template_file, stackname, zipname='', force=False, aws_profile='default')¶

Create Cloudformation stack based on JSON template Update lambda function with zip deployment package

Parameters:

pc_template_file (str) – Cloudformation template file
stackname (str) – Cloudformation stack name
zipname (str, optional) – Name of zip containing lambda function, defaults to “”
force (bool, optional) – Force stack re-creation, defaults to False
aws_profile (str, optional) – Name of AWS profile to use, defaults to ‘default’

pyawsutils.aws_cloudformation.jitr_cli_handler(args)¶: Entry point for JITR command of CLI

pyawsutils.aws_cloudformation.setup_aws_jitr_account(force, aws_profile='default')¶

Setup AWS account for JITR, using Cloudformation and uploading Lambda pack with JITR code

Parameters:

aws_profile (str, optional) – Name of profile to use, defaults to ‘default’
force (boolean) – force stack creation again if it already exists

Lambda functions¶

AWS Lambda Function utility

pyawsutils.aws_lambda.update_lambda_function(zip_file, stackname, aws_profile='default')¶

Update lambda function with ZIP deployment package

Parameters:

zip_file (str) – full path to zip file to use
stackname (str) – name of stack to update
aws_profile (str, optional) – Name of AWS profile to use, defaults to ‘default’

Policy functions¶

AWS IoT policy helper functions.

class pyawsutils.policy.Policy(aws_profile='default')¶

Bases: object

AWS policy generator

Parameters:: aws_profile (str) – AWS profile to be used.

build_policy(policy_template)¶

Build a policy document from a template.

Substitutes $(account_id) and $(region) in the policy template with the account ID and region from the AWS profile.

Parameters:: policy_template (str) – Template with placeholders for substituting AWS region and account ID
Returns:: Policy document
Return type:: str

create_policy(policy_name, policy_template)¶

Registers a policy in AWS

Parameters:

policy_name – Name of the policy
policy_template (str) – Policy template

create_policy_version(policy_name, policy_template, make_default=True)¶

Create a new policy version

Parameters:

policy_name (str) – Name for he policy
policy_template (str) – Policy template
make_default (Boolean, optional) – True if the new policy version should be set as default/active version, otherwise false

get_policy(policy_name)¶

Get policy ARN

Parameters:: policy_name (str) – Policy name

policy_exists(policy_name)¶

Check if a policy exists in AWS account

Parameters:: policy_name (str) – Name of the policy

pyawsutils.policy.create_policy_mar(profile)¶

Creates policy for MAR in AWS cloud

Parameters:: profile (str) – AWS profile name

pyawsutils.policy.policy_cli_handler(args)¶: Entry point for policy action of CLI

Amazon root CA certificate retrieval¶

Get the Amazon root CA certificate (bundle) The file “aws_ca_bundle” is the bundle of CA certs recommended by Amazon for TLS server authentication. The individual certificates are also available as separate files.

pyawsutils.aws_ca_cert.aws_get_root_ca_cert(name='aws_ca_bundle')¶: Get the AWS root CA certificate (bundle) :param name: Name of certificate (bundle) The default is the Amazon recommended bundle. :returns: Certificate as a string in PEM format

pyawsutils.aws_ca_cert.aws_get_root_ca_cert_filename(name='aws_ca_bundle')¶: Get root CA certificate (bundle) filename :param name: Name of certificate (bundle). The default is the Amazon recommended bundle. :returns: Certificate file absolute pathname

Signer registration¶

This module enables registering a signer in the AWS cloud

pyawsutils.register_signer.register_signer(signer_ca_key_path, signer_ca_cert_path, signer_ca_ver_cert_path, aws_profile='default')¶

Register signer in the AWS cloud

Parameters:

signer_ca_key_path (str) – Signer CA key file (full path)
signer_ca_cert_path (str) – Signer CA certificate file (full path)
signer_ca_ver_cert_path (str) – Signer CA verification certificate (full path)
aws_profile (str, optional) – AWS profile to use, defaults to ‘default’

Account cleaning¶

AWS Cleaner utility

class pyawsutils.clean.AccountCleaner(aws_profile='default')¶

Bases: object

AWS account cleanup helper tool

Parameters:: aws_profile (str) – AWS profile to be used

cleanup()¶: Delete things, certificates and policies

delete_certificates(bulk_delete_size=20)¶

Delete all certificates from current AWS account

A certificate cannot be deleted if it has a policy or IoT thing attached to it or if its status is set to ACTIVE.

Parameters:: bulk_delete_size (int, optional) – bulk size, defaults to 20

delete_policies(bulk_delete_size=20)¶

Delete all iot policies from current AWS account

Parameters:: bulk_delete_size (int, optional) – bulk size, defaults to 20

delete_things(bulk_delete_size=20)¶

Deleta all the things

Parameters:: bulk_delete_size (int, optional) – bulk size, defaults to 20

detach_policies_from_certificate(certificateArn, bulk_detach_size=20)¶

Detach all policies from a certificate

Parameters:

certificateArn (str) – Arn for the certificate
bulk_detach_size – bulk size, defaults to 20

detach_policy_from_certificates(policyName='zt_policy')¶

Detach policy from all certificates

Parameters:: policyName (str) – optional; default is “zt_policy”

detach_principals_from_thing(thingName)¶

Detaches the specified principal from the specified thing

Parameters:: thingName (str) – Name for the thing

fast_cleanup()¶: Detach policy from certificates. Delete things and certificates

pyawsutils.clean.clean_cli_handler(args)¶: Entry point for clean command of CLI

pyawsutils¶

pyawsutils - Python AWS utilities¶

pyawsutils is a collection of utilities for interacting with Amazon Web Services. It can be used as a library by instantiating any of the contained classes.

Supported kits are:

AVR-IOT (all variants)
PIC-IOT (all variants)

Overview¶

pyawsutils is available:

install using pip from pypi: https://pypi.org/project/pyawsutils
browse source code on github: https://github.com/microchip-pic-avr-tools/pyawsutils
read API documentation on github: https://microchip-pic-avr-tools.github.io/pyawsutils
read the changelog on github: https://github.com/microchip-pic-avr-tools/pyawsutils/blob/main/CHANGELOG.md

Usage example 1: Multi-Account Registration (MAR)¶

from pyawsutils.mar import aws_mar
from pyawsutils.policy import Policy

device_cert_file = "my_device.crt"
my_policy = "my_policy"
templatefile = "my_policytemplate.json"

# Read policy template file
with open(templatefile, "r") as myfile:
    policy_template = myfile.read()

# Create AWS policy
aws_policy_tool = Policy()
aws_policy_tool.create_policy(my_policy, policy_template)

# Register device certificate without CA for custom provisioning with MAR.
aws_mar_tool = aws_mar()
aws_mar_tool.create_device(certificate_file=device_cert_file,
                           policy_name=my_policy,
                           thing_type=None)

Usage example 2: Register Signer¶

from pyawsutils.register_signer import register_signer

# Register signer with AWS. For custom provisioning only.
register_signer(signer_ca_key_path=signer_ca_key_file,
                signer_ca_cert_path=signer_ca_cert_file,
                signer_ca_ver_cert_path=signer_ca_ver_cert_file,
                aws_profile="default")

Usage example 3: Just-in-Time Registration (JITR)¶

from pyawsutils.aws_cloudformation import setup_aws_jitr_account
# Setup AWS account for JITR, using Cloudformation and uploading Lambda pack with JITR code
setup_aws_jitr_account(force=force_setup)

Usage example 4: Clean account¶

from pyawsutils.clean import AccountCleaner
clean_tool = AccountCleaner(profile_name)
clean_tool.cleanup()

Logging¶

This package uses the Python logging module for publishing log messages to library users. A basic configuration can be used (see example), but for best results a more thorough configuration is recommended in order to control the verbosity of output from dependencies in the stack which also use logging.

import logging
logging.getLogger(__name__).addHandler(logging.NullHandler())

Table of Contents

Previous topic

This Page

pyawsutils package¶

Multi-Account Registration¶

AWS CloudFormation¶

Lambda functions¶

Policy functions¶

Amazon root CA certificate retrieval¶

Signer registration¶

Account cleaning¶

pyawsutils¶

pyawsutils - Python AWS utilities¶

Overview¶

Usage example 1: Multi-Account Registration (MAR)¶

Usage example 2: Register Signer¶

Usage example 3: Just-in-Time Registration (JITR)¶

Usage example 4: Clean account¶

Logging¶