Crate gneiss_mqtt_aws

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 an MQTT connection:

• MQTT over mTLS - provide 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 in the Connect packet

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

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 as well:

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

(Temporary) If your project does not include tokio, you will need to add it too:

[dependencies]
tokio = { version = "1", features = ["full"] }

Future releases will support other async runtimes as well as a client that runs in a background thread and does not need an async runtime. For now, tokio is required.

Example: Connect to AWS IoT Core via mTLS (with tokio runtime)

You’ll need to create and register an X509 device certificate with IoT Core and associate an IAM permission policy that allows IoT Core connections. See X509 Certificates and AWS IoT Core for guidance on this process.

To create a client and connect:

use gneiss_mqtt_aws::AwsClientBuilder;
use tokio::runtime::Handle;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let endpoint = "<your AWS IoT Core endpoint>";
    let cert_path = "<path to your X509 certificate>";
    let key_path = "<path to the certificate's private key>";

    // In the common case, you will not need a root CA certificate
    let client =
        AwsClientBuilder::new_direct_with_mtls_from_fs(endpoint, cert_path, key_path, None)?
            .build_tokio(&Handle::current())?;

    // Once started, the client will recurrently maintain a connection to the endpoint until
    // stop() is invoked
    client.start(None)?;

    // <do stuff with the client>

    Ok(())
}

Example: Connect to AWS IoT Core via Websockets (with tokio runtime)

You’ll need to configure your runtime environment to source AWS credentials whose IAM policy allows IoT usage. This crate uses the AWS SDK for Rust to source the credentials necessary to sign the websocket upgrade request. Consult AWS documentation for more details.

To create a client and connect:

use gneiss_mqtt_aws::{AwsClientBuilder, WebsocketSigv4OptionsBuilder};
use tokio::runtime::Handle;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    use gneiss_mqtt_aws::WebsocketSigv4Options;let endpoint = "<your AWS IoT Core endpoint>";
    let signing_region = "<AWS region for endpoint>";

    // Creating a default credentials provider chain is an async operation
    let sigv4_options = WebsocketSigv4OptionsBuilder::new(signing_region).await.build();

    // In the common case, you will not need a root CA certificate
    let client =
        AwsClientBuilder::new_websockets_with_sigv4(endpoint, sigv4_options, None)?
            .build_tokio(&Handle::current())?;

    // Once started, the client will recurrently maintain a connection to the endpoint until
    // stop() is invoked
    client.start(None)?;

    // <do stuff with the client>

    Ok(())
}

Example: Connect to AWS IoT Core via AWS IoT Custom Authentication (with tokio runtime)

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. 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.

Unsigned Custom Authentication

For an unsigned custom authorizer (for testing/internal purposes only, not recommended for production):

use gneiss_mqtt_aws::{AwsClientBuilder, AwsCustomAuthOptionsBuilder};
use tokio::runtime::Handle;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let endpoint = "<your AWS IoT Core endpoint>";
    let authorizer_name = "<name of the authorizer you want to invoke>";
    let username = "<username value to pass to the authorizer>"; // only necessary if the authorizer's lambda uses it
    let password = "<password value to pass to the authorizer>".as_bytes(); // only necessary if the authorizer's lambda uses it

    let mut custom_auth_options_builder = AwsCustomAuthOptionsBuilder::new_unsigned(
        Some(authorizer_name)
    );

    custom_auth_options_builder.with_username(username);
    custom_auth_options_builder.with_password(password);

    // In the common case, you will not need a root CA certificate
    let client =
        AwsClientBuilder::new_direct_with_custom_auth(endpoint, custom_auth_options_builder.build(), None)?
            .build_tokio(&Handle::current())?;

    // Once started, the client will recurrently maintain a connection to the endpoint until
    // stop() is invoked
    client.start(None)?;

    // <do stuff with the client>

    Ok(())
}

Signed Custom Authentication

For a signed custom authorizer (recommended for production):

use gneiss_mqtt_aws::{AwsClientBuilder, AwsCustomAuthOptionsBuilder};
use tokio::runtime::Handle;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let endpoint = "<your AWS IoT Core endpoint>";
    let authorizer_name = "<name of the authorizer you want to invoke>";
    let authorizer_token_key_name = "<key name registered with the signing authorizer that indicates the name of the field whose value will contain the `authorizer_token_key_value`>";
    let authorizer_token_key_value = "<An arbitrary value.  The (Base64-encoded) signature of this value (using the private key of the public key associated with the authorizer) must be included as a separate field>";
    let authorizer_signature = "<URI-encoded Base64-encoded signature for `authorizer_token_key_value` signed by the private key of the public key associated with the authorizer>";
    let username = "<username value to pass to the authorizer>"; // only necessary if the authorizer's lambda uses it
    let password = "<password value to pass to the authorizer>".as_bytes(); // only necessary if the authorizer's lambda uses it

    let mut custom_auth_options_builder = AwsCustomAuthOptionsBuilder::new_signed(
        Some(authorizer_name),
        authorizer_signature,
        authorizer_token_key_name,
        authorizer_token_key_value
    );

    custom_auth_options_builder.with_username(username);
    custom_auth_options_builder.with_password(password);

    // In the common case, you will not need a root CA certificate
    let client =
        AwsClientBuilder::new_direct_with_custom_auth(endpoint, custom_auth_options_builder.build(), None)?
            .build_tokio(&Handle::current())?;

    // Once started, the client will recurrently maintain a connection to the endpoint until
    // stop() is invoked
    client.start(None)?;

    // <do stuff with the client>

    Ok(())
}

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.

TODO: automatically encode authorizer_signature if it needs it.

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:

• Mqtt5ClientOptions
• ConnectOptions

Additional Notes

See the gneiss-mqtt documentation for client usage details and guidance.

The intention is that this crate will eventually be as agnostic as possible of underlying implementation details (async runtimes, TLS/transport implementations, etc…) but at present it has hard dependencies on tokio, rustls, and some associated helper libraries. These will get feature-flag-gated before GA, allowing you to pare the implementation down to your exact connection needs. In Rust’s current state, there is a fundamental tension between trying to be transport/runtime agnostic and trying to provide an easy-to-use interface for getting successful clients set up for the many different combinations expected by users.

Structs

• AwsClientBuilder
  A builder object that allows for easy MQTT client construction for all supported connection methods to AWS IoT Core.
• AwsCustomAuthOptions
  A struct that holds all relevant details needed to perform custom authentication with AWS IoT Core. Use an appropriate new_*() function to create.
• AwsCustomAuthOptionsBuilder
  Builder type for AwsCustomAuthOptions
• WebsocketSigv4Options
  Struct holding all configuration relevant to connecting an MQTT client to AWS IoT Core over websockets using a Sigv4-signed websocket handshake for authentication
• WebsocketSigv4OptionsBuilder
  A builder type that configures all relevant AWS signing options for connecting over websockets using Sigv4 request signing.

Enums

• TlsImplementation
  This enumeration allows the user to override the default TLS implementation in the unfortunate case that they are forced to build the crate with multiple TLS implementations enabled.