This tutorial demonstrates how Mongoose Library can be used to communicate with the AWS IoT service. We create an MQTT client that:

  1. Connects to the AWS IoT MQTT server
  2. When connected, subscribes to the topic d/rx. Any message received on that topic, gets logged
  3. Publishes message hello to the d/tx every second

AWS IoT is an MQTT 3.1.1 service that uses two-way TLS for authentication - see SSL/TLS tutorial for TLS background. Two way TLS means that instead of using a traditional user/password to authenticate, AWS IoT uses TLS certificates. Before connecting, AWS IoT needs a "thing" to be registered, and for that "thing", a TLS certificate gets created. That certificate gets copied to a device and used as a "password" to authenticate with AWS IoT. Also, AWS IoT attaches a "policy" to every certificate which says which capability a "thing" has.

MQTT standard does not regulate access rights for clients. For example, any client can subscribe to a wildcard topic # and sniff all messages sent by any client. That is too dangerous for a production system. Therefore, commercial services like AWS IoT invent their ways to restrict access for clients. AWS IoT uses "policies", which is a JSON document that describes access rules - like, which topics a given client can send to, and which topics it can subscribe to. Once created, policies can be attached (referenced by) certificates.

To summarize, the following steps should be performed in order to connect to an AWS IoT service:

  • Create AWS IoT policy
  • Register AWS IoT thing and associated certificates
  • Download certificates
  • Configure MQTT client to use certificates for 2-way TLS

Create AWS IoT policy

  • Login to AWS IoT console

  • On the left bar, click on "Policies"

  • On the right pane, click on "Create"

  • Fill in fields in the following way and click "Create":

    • Name: Policy1
    • Action: iot:*
    • Resource ARN: *
    • Effect: allow
    Create AWS IoT Policy

Register AWS IoT Thing

  • On the left bar, click on "Manage" → "Things"
  • On the right pane, click on Create things → Create single thing → Next
  • Enter thing name, for example "thing1", click "Next"
  • Choose "Auto-generate new certificate", click "Next"
  • Chooae policy "Policy1", click "Create thing"

Download certificate files

In the dialog box that appears, download all three generated certificates: Create AWS IoT Policy

Configure MQTT client

  • Follow the Build Tools tutorial to setup your development environment.
  • Start a terminal in the project directory; clone the Mongoose Library repo, and go into the example directory:
    $ git clone
    $ cd mongoose/tutorials/mqtt/mqtt-client-aws-iot
  • Copy xxx-certificate.pem.crt as cert.pem to the example directory
  • Copy xxx-private.pem.key as key.pem to the example directory Now, these two files, cert.pem and key.pem, would serve the client certificate when our example authenticates with AWS IoT over 2-way TLS
  • Open main.c file and change the s_url variable to the actual URL of your AWS IoT service. To find it out, click on "Settings" link on the left bar and copy the "Endpoint" URL on the right pane
  • Build and run the example, check the "How to build" section of the TLS tutorial for specific information on building options for your OS

Testing MQTT Client

  • On the left pane, click on "Test" → "MQTT test client"
  • Subscribe to topic d/tx. You should see test messages appearing
  • Click on "Publish to a topic". Set topic name to d/rx, click "Publish"
  • Check example's log, see that the published message is received