gneiss-mqtt-aws

A set of easy-to-use MQTT client builders for working with AWS IoT Core.

No-fuss configuration for:

• IoT Core via mtls
• IoT Core via websockets with sigv4 signing
• IoT Core via Custom Authentication

Frequently Asked Questions

See FAQ

Roadmap

See Gneiss MQTT Roadmap

License

All projects in this space are licensed under the Apache 2.0 License.

lib.rs:

This crate provides a builder API for creating MQTT clients that connect to AWS IoT Core, an AWS-managed message broker that supports both MQTT5 and MQTT311. This crate depends on gneiss-mqtt, which contains the MQTT client implementations.

IoT Core supports three different ways to securely establish and authenticate an MQTT connection:

• MQTT over mTLS - via an X509 certificate (registered with AWS IoT Core) and its associated private key
• MQTT over Websockets - sign the websocket upgrade request with AWS credentials using the Sigv4 signing algorithm
• MQTT with Custom Authentication - invoke an AWS Lambda with data fields passed via the MQTT username and password fields of the Connect packet

This crate's builder does all the dirty work for each of these connection methods, letting you just supply the required data.

Feature Flags

Gneiss-mqtt supports two different MQTT clients:

• tokio - An asynchronous client that executes on a Tokio async runtime. Intended for users comfortable with async programming in Rust.
• threaded - A callback-based client that executes on a background thread. Intended for users that do not wish to deal with the additional complexity (or dependencies) of async programming in Rust.

Client support is controlled by enabling one or more of these crate features:

• tokio-rustls: Enables the tokio client and establishing connections using the rustls TLS implementation.
• tokio-native-tls: Enables the tokio client and establishing connections using the native-tls TLS implementation.
• tokio-websockets: Enables the tokio client and transport over websockets.
• threaded-rustls: Enables the thread-based client and establishing connections using the rustls TLS implementation.
• threaded-native-tls: Enables the thread-based client and establishing connections using the native-tls TLS implementation.

AWS IoT Core requires TLS to connect and the crate will not build unless at least one TLS feature is enabled.

Usage

To use this crate, you'll first need to add it and gneiss-mqtt to your project's Cargo.toml, enabling a TLS implementation feature as well.

Enabling the tokio client:

[dependencies]
gneiss-mqtt = { version = "...", features = [ "tokio-rustls" ] }
gneiss-mqtt-aws = { version = "...", features = [ "tokio-rustls" ] }
tokio = { version = "1", features = ["full"] }

Enabling the thread-based client:

[dependencies]
gneiss-mqtt = { version = "...", features = [ "threaded-rustls" ] }
gneiss-mqtt-aws = { version = "...", features = [ "threaded-rustls" ] }

Standalone examples for each connection method can be found in the project repository examples folder.

Example: Connect to AWS IoT Core via AWS IoT Custom Authentication with the thread-based client

Custom authentication is an AWS IoT Core specific way to perform authentication without using certificates or http request signing. Instead, an AWS Lambda is invoked to decide whether or not a connection is allowed. The lambda function can access CONNECT packet fields (username and password) to determine whether the connection should be allowed and what permissions it should have. See the custom authentication documentation for step-by-step instructions in how to set up the AWS resources (authorizer, Lambda, etc...) to perform custom authentication.

Once the necessary AWS resources have been set up, you can easily create clients for each of the two supported custom authentication modes:

• Unsigned Custom Authentication - Anyone can invoke the authorizer's lambda if they know its ARN. This is not recommended for production since it is not protected from external abuse that may run up your AWS bill.
• Signed Custom Authentication - Your Lambda function will only be invoked (and billed) if the Connect packet includes the cryptographic signature (based on an IoT Core registered public key) of a controllable value. Recommended for production.

You must be careful with the encodings of authorizer, authorizer_signature, and authorizer_token_key_name. Because custom authentication is supported over HTTP, these values must be URI-safe. It is up to you to URI encode them if necessary. In general, authorizer and authorizer_token_key_name are fixed when you create the authorizer resource and so it is straightforward to determine if you need to encode them or not. authorizer_signature should always be URI encoded.

MQTT Client Configuration

The above examples skip all client configuration in favor of defaults. There are many configuration details that may be of interest depending on your use case. These options are controlled by structures in the gneiss-mqtt crate, via the with_client_options and with_connect_options methods on the AwsClientBuilder. Further details can be found in the relevant sections of the gneiss-mqtt docs:

• MqttClientOptions
• ConnectOptions

Frequently Asked Questions

See FAQ