Advanced usage#

In this section, more complex uses of the session helper are described. All examples and walkthroughs will be categorized and be referable from the menu to the right.

Protecting credentials#

One main tenet for devices or users outside of our control is to reduce the attack surface if or when the device is compromised. These uses cover different scenarios.

PKCS#11 on Canonical Ubuntu walkthrough#

This walkthrough demonstrated how to use the session helper with SoftHSM. It covers how to use a private key stored within a PKCS#11 environment.

Prerequisites#

  • AWS IoT Role Alias configured with thing, certificate, and AWS IoT policy

  • A registered X.509 certificate and corresponding private key

  • An Ubuntu desktop or server environment with sudo access - the walkthrough uses Ubuntu 22.04.1 LTS

  • Python with the awsiot-credentialhelper installed

Steps#

  1. Login to the Ubuntu system (host system) and start a command line interface.

  2. Create a directory and copy the certificate and private key there

    $ mkdir $HOME/hsm_test
$ cd $HOME/hsm_test
$ cp /path/to/certificate thing-cert.pem
$ cp /path/to/private-key thing-key.pem

  3. Install dependencies, SoftHSM2, initialize and record slot number

    $ sudo apt update && sudo apt install -y softhsm2 pcregrep opensc gnutls-bin
$ mkdir -p $HOME/lib/softhsm/tokens
$ cd $HOME/lib/softhsm/
$ echo "directories.tokendir = $PWD/tokens" > softhsm2.conf
$ export SOFTHSM2_CONF=$HOME/lib/softhsm/softhsm2.conf
$ cd $HOME/hsm_test
$ echo $(softhsm2-util --init-token --free \
  --so-pin 1234 --pin 1234 --label hsm_thing|pcregrep -o1 \
  '.* to slot (.*)') > slot.txt

  4. Verify the private key is in PKCS#8 format. This the first major challenge in getting keys into the right format. SoftHSM2 will alert if the key is not in the correct format.

    $ # Covert PCKS#1 (--BEGIN RSA PRIVATE KEY--) to PKCS#8 (--BEGIN PRIVATE KEY--)
$ mv thing-key.pem thing-key-pkcs1.pem
$ openssl pkcs8 -in thing-key-pkcs1.pem -topk8 -nocrypt -out thing-key.pem

  5. Import the private key into newly initialized slot and verify content.

    $ softhsm2-util --import thing-key.pem --slot $(cat slot.txt) --label hsm_thing_key \
--id 0000 --pin 1234
The key pair has been imported.
$ p11-tool --list-tokens
 Token 0:
     URL: pkcs11:model=p11-kit-trust;manufacturer=PKCS%2311%20Kit;serial=1;token=System%20Trust
     Label: System Trust
     Type: Trust module
     Flags: uPIN uninitialized
     Manufacturer: PKCS#11 Kit
     Model: p11-kit-trust
     Serial: 1
     Module: p11-kit-trust.so


 Token 1:
     URL: pkcs11:model=SoftHSM%20v2;manufacturer=SoftHSM%20project;serial=050524a5fd9dec1d;token=hsm_thing
     Label: hsm_thing
     Type: Generic token
     Flags: RNG, Requires login
     Manufacturer: SoftHSM project
     Model: SoftHSM v2
     Serial: 050524a5fd9dec1d
     Module: /usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so

  6. Create a Python file with the follow code (pkcs11.py), replacing the endpoint, role_alias, and thing_name values. The pkcs11 entry uses values for the imported key.

    from awsiot_credentialhelper.boto3_session import (
    Boto3SessionProvider,
)
from awsiot_credentialhelper.boto3_session import (
    Pkcs11Config,
)
# from awscrt.io import LogLevel

boto3_session = Boto3SessionProvider(
    endpoint="YOUR_ENDPOINT.credentials.iot.REGION.amazonaws.com",
    role_alias="YOUR_ROLE_ALIAS",
    certificate="thing-cert.pem",
    thing_name="YOUR_THING_NAME",
    pkcs11=Pkcs11Config(
        pkcs11_lib="/usr/lib/softhsm/libsofthsm2.so",
        user_pin="1234",
        token_label="hsm_thing",
        private_key_label="hsm_thing_key",
    ),
    # awscrt_log_level=LogLevel.Trace,
).get_session()
print(boto3_session.client("sts").get_caller_identity())

  7. Test the code by running and verifying a response.

    $ python3 pkcs11.py
{'UserId': 'AROA...F3D:4686...0a0d', 'Account': '1234567890', 'Arn': 'arn:aws:sts::1234567890:assumed-role/test_iot_role_alias/4686...0a0d', 'ResponseMetadata': {'RequestId': 'd6598737-9b63-4dd2-a0d3-cdf3a719bb39', 'HTTPStatusCode': 200, 'HTTPHeaders': {'x-amzn-requestid': 'd6598737-9b63-4dd2-a0d3-cdf3a719bb39', 'content-type': 'text/xml', 'content-length': '554', 'date': 'Fri, 24 Feb 2023 23:36:50 GMT'}, 'RetryAttempts': 0}}

That confirms that the session helper used the SoftHSM2 to perform the cryptographic operations. This walkthrough doesn’t cover the nuances of PKCS#11–there are many! However, if you uncomment the from awscrt.io and awscrt_log_level lines, this will provide details on what the awscrt runtime is doing.