Skip to content

Commit

Permalink
doc: aws_iot: Update setup instructions
Browse files Browse the repository at this point in the history 
Changes the aws_iot setup and configuration
instructions to use the AWS CLI instead of the
AWS Console. This should make the instructions
more stable and facilitate automations.

Signed-off-by: Fabian Nawratil <[email protected]>
Signed-off-by: divya pillai <[email protected]>
Co-authored-by: divya pillai <[email protected]>
  • Loading branch information
@fnawratil @divipillai @nordicjm
2 people authored and nordicjm committed Sep 8, 2023
1 parent 0204f74 commit ecbd150
Show file tree
Hide file tree
Showing 5 changed files with 242 additions and 65 deletions.
292 changes: 230 additions & 62 deletions doc/nrf/libraries/networking/aws_iot.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,39 +13,196 @@ The library supports the following technologies:
* TLS secured MQTT transmission protocol
* Firmware-Over-The-Air (FOTA)

To connect to AWS IoT, complete the following steps:
.. _aws_setup_and_configuration:

1. :ref:`setup_aws_and_permissions`
#. :ref:`creating_a_thing_in_AWS_IoT`
#. :ref:`flash_certi_device`
#. :ref:`Configuring the application <configuring>`
Setup and configuration
***********************

See `AWS IoT Developer Guide`_ for general information about the Amazon Web Services IoT service.
To connect a device to AWS IOT Core, complete the following steps:

.. _setup_aws_and_permissions:
1. :ref:`aws_setup_and_permissions`
#. :ref:`generating_and_provisioning_certificates`
#. :ref:`creating_a_policy`
#. :ref:`creating_a_thing`
#. :ref:`Configuring the library <configuring_the_library>`

Set up your AWS account and permissions
***************************************
.. rst-class:: numbered-step

To connect to AWS IoT, you need to set up an AWS account with the appropriate permissions.
Complete the steps documented in `Set up your AWS account`_.
.. _aws_setup_and_permissions:

.. _creating_a_thing_in_AWS_IoT:
Setting up AWS and configuring permissions
==========================================

Create a Thing in AWS IoT
*************************
The initial AWS account setup required for using AWS IoT Core is described in `Set up your AWS account`_.

Before you can use this library, you must create a *Thing* for your client in AWS IoT.
The *Thing* must be connected to a security policy.
For testing, you can use a permissive policy, but make sure to update the policy to be more restrictive before you go into production.
See `AWS IoT Developer Guide: Basic Policy Variables`_ and `AWS IoT Developer Guide: Security Best Practices`_ for more information about policies.
For development purposes, the AWS managed policies ``AWSIoTConfigAccess`` and ``AWSIoTDataAccess`` provide sufficient permissions to manage AWS IoT.
If you want to use AWS FOTA, the ``AmazonS3FullAccess`` policy can be used to obtain access to AWS S3.

To create a Thing for your device:
.. note::
These policies provide a large number of permissions to the user.
But for development purposes, you must operate on the least-privilege principle whenever possible.

To complete the steps described in this document, make sure that the following prerequisites are met:

* Install `AWS Command Line Interface`_ on your system and login as a user with appropriate permissions.
* To use the ``nrfcredstore`` tool, the dependencies in the :file:`nrf/scripts/requirements-extra.txt` file must be installed.

.. rst-class:: numbered-step

.. _generating_and_provisioning_certificates:

Generating and provisioning certificates
========================================

*Things* in AWS IoT are typically authenticated using device certificates.
There are multiple ways to generate and register these certificates:

* The device key pair and certificate are generated by AWS and downloaded onto the device.
* The device generates the key pair and a Certificate Signing Request (CSR).
This request is uploaded to AWS to obtain a device certificate and is used to generate a self-signed device certificate.

.. tabs::

.. tab:: nRF91: Keys generated on device

.. note::
Generating a key pair on device requires an nRF91 Series device.
If you are using an nRF9160 DK, modem version v1.3.x or later is required.

.. important::
Program the :ref:`at_client_sample` sample to your device before following this guide.

Complete the following steps to generate a key pair and CSR on the modem, which is then used to obtain a device certificate signed by AWS:

1. Obtain a list of installed keys using the following command:

.. code-block:: console
nrfcredstore <serial port> list
where ``<serial port>`` is the serial port of your device.

#. Select a security tag that is not yet in use.
This security tag must match the value set in the :kconfig:option:`CONFIG_AWS_IOT_SEC_TAG` Kconfig option.

#. Generate a key pair and obtain a CSR using the following command:

.. code-block:: console
nrfcredstore <serial port> generate <sec tag> device_cert.csr.der
|serial_port_sec_tag|

#. Convert the CSR from DER format to PEM format using the following command:

.. code-block:: console
openssl req -inform DER -in device_cert.csr.der -outform PEM -out device_cert.csr.pem
#. Obtain a signed certificate using the following command:

.. code-block:: console
aws iot create-certificate-from-csr --certificate-signing-request device_cert.csr.pem --certificate-pem-outfile device_cert.pem --set-as-active --no-cli-pager --query certificateArn
#. Take note of the certificate ARN, as it will be required later.
#. Provision the certificate using the following command:

.. code-block:: console
nrfcredstore <serial port> write <sec tag> CLIENT_CERT device_cert.pem
|serial_port_sec_tag|

#. Download the `Amazon Root CA 1`_ PEM file.
#. Provision the certificate using the following command:

.. code-block:: console
nrfcredstore <serial port> write <sec tag> ROOT_CA_CERT AmazonRootCA1.pem
|serial_port_sec_tag|

.. tab:: nRF91: Keys generated by AWS

.. warning::
This option is not recommended for production scenarios, since the private key leaves the device.

.. important::
Program the :ref:`at_client_sample` sample to your device before following this guide.

To obtain a key pair and certificate generated by AWS, and to provision them to the modem, complete the following steps:

1. Generate the key pair and certificate using the following command:

.. code-block:: console
aws iot create-keys-and-certificate --set-as-active --certificate-pem-outfile device_cert.pem --public-key-outfile pub_key.pem --private-key-outfile priv_key.pem --no-cli-pager --query certificateArn
1. Log in to the `AWS IoT console`_.
#. Go to :guilabel:`Security` > :guilabel:`Policies` and select :guilabel:`Create policy`.
#. Enter a name and define your policy.
For testing purposes, you can use the following policy (click on :guilabel:`JSON`, copy, and paste it):
#. Take note of the certificate ARN, as it will be required later.
#. Obtain a list of installed keys using the following command:

.. code-block:: console
nrfcredstore <serial port> list
where ``<serial port>`` corresponds to the serial port of your device.

#. Select a security tag that is not yet in use.
This security tag must match the value set in :kconfig:option:`CONFIG_AWS_IOT_SEC_TAG` Kconfig option.

#. Provision the client certificate using the following command:

.. code-block:: console
nrfcredstore <serial port> write <sec tag> CLIENT_CERT device_cert.pem
|serial_port_sec_tag|

#. Provision the client key using the following command:

.. code-block:: console
nrfcredstore <serial port> write <sec tag> CLIENT_KEY priv_key.pem
|serial_port_sec_tag|

#. Download the `Amazon Root CA 1`_ PEM file.
#. Provision the certificate using the following command:

.. code-block:: console
nrfcredstore <serial port> write <sec tag> ROOT_CA_CERT AmazonRootCA1.pem
|serial_port_sec_tag|

.. tab:: nRF70: Keys generated by AWS

To obtain a key pair and certificate generated by AWS, complete the following steps:

1. Generate the key pair and certificate using the following command:

.. code-block:: console
aws iot create-keys-and-certificate --set-as-active --certificate-pem-outfile client-cert.pem --public-key-outfile public-key.pem --private-key-outfile private-key.pem --no-cli-pager --query certificateArn
#. Take note of the certificate ARN, as it will be required later.
#. Download the `Amazon Root CA 1`_ PEM file as :file:`ca-cert.pem`.
#. Provision the certificates and private key at runtime to the Mbed TLS stack.
This is achieved by placing the PEM files into a :file:`certs/` subdirectory and ensuring the :kconfig:option:`CONFIG_AWS_IOT_PROVISION_CERTIFICATES` Kconfig option is enabled.
For more information, refer to the :ref:`aws_iot` sample as well as the :kconfig:option:`CONFIG_AWS_IOT_CERTIFICATES_FILE` Kconfig option.

.. rst-class:: numbered-step

.. _creating_a_policy:

Creating a policy
=================

AWS IoT Core policies determine which permissions a *Thing* has and are required to connect to the AWS IoT data plane.
To create a policy, complete these steps:

1. Create a file :file:`policy.json` with the following content:

.. code-block:: javascript
Expand All @@ -61,63 +218,72 @@ To create a Thing for your device:
}
.. note::
The policy example is only intended for development environments.
All devices in your production fleet must have credentials with privileges that authorize only intended actions on specific resources.
The specific permission policies can vary depending on the use case and should meet business and security requirements.
This policy example is only intended for development environments.
Make sure to update this to a more restrictive policy before you go into production.
For more information, refer to the example policies listed in `AWS IoT Core policy examples`_ and `Security best practices in AWS IoT Core`_.

#. Click :guilabel:`Create`.
#. Go to :guilabel:`Manage` > :guilabel:`All devices`> :guilabel:`Things` and select :guilabel:`Create things`.
#. Click :guilabel:`Create Thing`.
#. Enter a name.
The default name used by the library is ``my-thing``.
#. Create the policy using the following command:

.. note::
.. code-block:: console
aws iot create-policy --policy-name my-policy --policy-document file://policy.json
#. Attach the policy to the previously registered certificate using the following command:

.. code-block:: console
aws iot attach-policy --target <certificate arn> --policy-name my-policy
where ``<certificate arn>`` is the ARN of the previously generated device certificate.

If you are working with an application, that automatically sets the client ID to the IMEI of the device at run-time, you must locate the IMEI of the device and use that as the *Thing name*.
If you choose a different name, make sure to :ref:`configure a custom client ID <configuring>` before building.
.. rst-class:: numbered-step

#. Accept the defaults and continue to the next step.
#. Select :guilabel:`Auto-generate a new certificate` to generate new certificates.
#. Select the policy that you created in a previous step.
#. Click on :guilabel:`Create Thing`.
#. Download the following certificates and keys for later use:
.. _creating_a_thing:

* Thing certificate (:file:`*-certificate.pem.crt`)
* The private key (:file:`*.private.pem.key`)
* The root CA (choose the Amazon Root CA 1, :file:`AmazonRootCA1.pem`)
#. Click :guilabel:`Done`.
Creating a Thing
================

The certificates that you created or added for your Thing in AWS IoT must be stored on your device so that it can successfully connect to AWS IoT.
Create a *Thing* in AWS IoT core by completing the following steps:

.. _flash_certi_device:
1. Create a *Thing* using the following command:

Provisioning of the certificates
********************************
.. code-block:: console
.. include:: /includes/cert-flashing.txt
aws iot create-thing --thing-name <thing name>
For nRF70 Series devices, the TLS credentials need to be provisioned to the Mbed TLS stack at runtime before establishing a connection to AWS IoT.
This can be done by enabling the :kconfig:option:`CONFIG_AWS_IOT_PROVISION_CERTIFICATES` option and placing the credentials in the path specified by the :Kconfig:option:`CONFIG_AWS_IOT_CERTIFICATES_FILE` option.
where ``<thing name>`` is the desired name for the *Thing*, for example, ``my-thing``.

.. _configuring:
#. Attach the certificate to the *Thing* using the following command:

Configuration
*************
.. code-block:: console
aws iot attach-thing-principal --principal <certificate arn> --thing-name <thing name>
where ``<certificate arn>`` is the ARN of the previously generated device certificate and ``<thing name>`` is the previously chosen name of the *Thing*.

.. rst-class:: numbered-step

.. _configuring_the_library:

Configuring the library
=======================

Complete the following steps to set the required library options:

1. In the `AWS IoT console`_, navigate to :guilabel:`IoT core` > :guilabel:`Settings`.
#. Find the ``Device data endpoint`` address and set :kconfig:option:`CONFIG_AWS_IOT_BROKER_HOST_NAME` to this address string.
The address can also be provided at runtime by setting the :kconfig:option:`CONFIG_AWS_IOT_BROKER_HOST_NAME_APP` option.
See :ref:`lib_set_aws_hostname` for more details.
#. Set the option :kconfig:option:`CONFIG_AWS_IOT_CLIENT_ID_STATIC` to the name of the *Thing* created earlier in the process.
This is not needed if the application sets the client ID at run time.
If you still want to set a custom client ID, make sure that the :kconfig:option:`CONFIG_AWS_IOT_CLIENT_ID_APP` is disabled and set the :kconfig:option:`CONFIG_AWS_IOT_CLIENT_ID_STATIC` option to your desired client ID.
#. Set the security tag configuration :kconfig:option:`CONFIG_AWS_IOT_SEC_TAG` to the security tag, chosen while you :ref:`provisioned the certificates to the modem <flash_certi_device>`.
1. Obtain the AWS IoT broker endpoint using the following command:

.. code-block:: console
aws iot describe-endpoint --endpoint-type iot:Data-ATS
#. Set the :kconfig:option:`CONFIG_AWS_IOT_BROKER_HOST_NAME` Kconfig option to the obtained endpoint value.
For information on how to set this value at runtime, refer to :ref:`lib_set_aws_hostname`.
#. Set the :kconfig:option:`CONFIG_AWS_IOT_CLIENT_ID_STATIC` Kconfig option to the name of the *Thing* created earlier.
For information on how to set this value at runtime, refer to :ref:`lib_set_client_id`.
#. Set the :kconfig:option:`CONFIG_AWS_IOT_SEC_TAG` to the security tag for which the key and certificate were provisioned earlier.

Optional library options
========================
------------------------

To subscribe to the various `AWS IoT Device Shadow Topics`_ , set the following options:

Expand Down Expand Up @@ -253,6 +419,8 @@ The following code example shows how to publish to non-AWS specific topics:
return err;
}
.. _lib_set_client_id:

Setting client ID at run-time
=============================

Expand Down
1 change: 1 addition & 0 deletions doc/nrf/links.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -821,6 +821,7 @@
.. _`AWS account`: https://aws.amazon.com/iot/
.. _`Setting up an AWS account`: https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/
.. _`Set up your AWS account`: https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html
.. _`AWS Command Line Interface`: https://aws.amazon.com/cli/
.. _`AWS IoT Core policy examples`: https://docs.aws.amazon.com/iot/latest/developerguide/example-iot-policies.html
.. _`Security best practices in AWS IoT Core`: https://docs.aws.amazon.com/iot/latest/developerguide/security-best-practices.html
.. _`AWS IoT Core Server Authentication`: https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html
Expand Down
2 changes: 2 additions & 0 deletions doc/nrf/shortcuts.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -196,3 +196,5 @@
.. |Supported OS| replace:: The operating system versions that support the |NCS| tools are listed in the :ref:`supported_OS` section.

.. |no_changes_yet_note| replace:: No changes since the latest |NCS| release.

.. |serial_port_sec_tag| replace:: where ``<serial port>`` is the serial port of your device and ``<sec tag>`` is the previously chosen unused security tag.
11 changes: 8 additions & 3 deletions samples/net/aws_iot/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ The Amazon Web Services Internet-of-Things (AWS IoT) sample demonstrates how to
This sample showcases the use of the :ref:`lib_aws_iot` library, which includes support for FOTA using the :ref:`lib_aws_fota` library.

Before this sample can be used, an AWS IoT server instance needs to be setup in order for the device to connect to it.
Refer to :ref:`aws_iot_sample_server_setup` to complete the nessecary steps.
Refer to :ref:`aws_iot_sample_server_setup` to complete the necessary steps.

Requirements
************
Expand Down Expand Up @@ -80,8 +80,9 @@ Configuration
Setup
=====

To run this sample and connect to AWS IoT, complete the steps described in the :ref:`lib_aws_iot` documentation.
This documentation retrieves the AWS IoT broker *hostname*, *security tag*, and *client ID*.
To run this sample and connect to AWS IoT, complete the steps described in the :ref:`aws_setup_and_configuration` section of the AWS IoT library documentation.
This is to obtain the AWS IoT broker *hostname* and the *client ID* of the device and provision a device certificate to a *security tag*.

The corresponding options that must be set for each of these values are:

* :kconfig:option:`CONFIG_AWS_IOT_BROKER_HOST_NAME`
Expand All @@ -91,6 +92,10 @@ The corresponding options that must be set for each of these values are:
Set these options in the project configuration file located at :file:`samples/nrf9160/aws_iot/prj.conf`.
For documentation related to FOTA DFU, see :ref:`lib_aws_fota`.

.. note::
For nRF70 Series devices, certificates must be provisioned at runtime.
This is achieved by pasting the PEM content into the respective files in the :file:`certs/` subdirectory and ensuring the :kconfig:option:`CONFIG_AWS_IOT_PROVISION_CERTIFICATES` Kconfig option is enabled.

Configuration options
=====================

Expand Down
1 change: 1 addition & 0 deletions scripts/requirements-extra.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@ pygit2<=1.10
editdistance>=0.5.0
PyGithub
zcbor>=0.5.1
nrfcredstore>=1.0.0,<2

0 comments on commit ecbd150

Please sign in to comment.