gneiss-mqtt-aws

一套易于使用的 MQTT 客户端构建器，用于与 AWS IoT Core 一起工作。

无需烦恼的配置

• 通过 mtls 的 IoT Core
• 通过 WebSocket 与 sigv4 签名进行 IoT Core
• 通过自定义身份验证的 IoT Core

欢迎反馈。

许可证

此空间中的所有项目均采用 Apache 2.0 许可证。

lib.rs:

此 crate 提供了一个构建器 API，用于创建连接到 AWS IoT Core 的 MQTT 客户端，AWS IoT Core 是一个支持 MQTT5 和 MQTT311 的 AWS 管理的消息代理。此 crate 依赖于 gneiss-mqtt，其中包含 MQTT 客户端实现。

IoT Core 支持三种不同的安全建立 MQTT 连接方式

• 通过 mTLS 的 MQTT - 提供一个 X509 证书（已在 AWS IoT Core 中注册）及其相关的私钥
• 通过 WebSocket 的 MQTT - 使用 Sigv4 签名算法使用 AWS 凭据对 WebSocket 升级请求进行签名
• 具有自定义身份验证的 MQTT - 通过 MQTT 用户名和密码字段在连接包中传递数据字段来调用 AWS Lambda

此 crate 的构建器为每种连接方法都做了脏活累活，让您只需提供所需的最少数据。

用法

要使用此 crate，您首先需要将其和 gneiss-mqtt 添加到项目的 Cargo.toml 中，并启用 TLS 实现

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

(临时) 如果您的项目不包含 tokio，则还需要将其添加

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

未来的版本将支持其他异步运行时以及运行在后台线程中且不需要异步运行时的客户端。目前，需要 tokio。

示例：通过 AWS IoT Custom Authentication 连接到 AWS IoT Core（使用 tokio 运行时）

自定义认证是 AWS IoT Core 的一种特定方式，无需使用证书或 HTTP 请求签名即可进行认证。相反，调用 AWS Lambda 来决定是否允许连接。请参阅自定义认证文档，了解如何设置 AWS 资源（授权者、Lambda 等）以执行自定义认证的详细步骤。

一旦设置了必要的 AWS 资源，您可以轻松创建两种支持的自定义认证模式的客户端

• 未签名自定义认证 - 任何知道其 ARN 的人都可以调用授权者的 Lambda。这不适合生产环境，因为它无法防止外部滥用，可能会增加您的 AWS 账单。
• 签名自定义认证 - 只有当连接包包含基于 IoT Core 注册的公钥的加密签名（可控值）时，才会调用您的 Lambda 函数（并计费）。推荐用于生产环境。

您必须小心处理 authorizer、authorizer_signature 和 authorizer_token_key_name 的编码。因为自定义认证是通过 HTTP 支持的，所以这些值必须是 URI 安全的。如果需要，由您负责对其进行 URI 编码。通常，authorizer 和 authorizer_token_key_name 在您创建授权者资源时是固定的，因此可以轻松判断是否需要编码。 authorizer_signature 应始终进行 URI 编码。

TODO：如果需要，自动编码 authorizer_signature。

MQTT 客户端配置

上述示例跳过了所有客户端配置，以默认值为准。根据您的使用情况，可能有许多配置细节值得关注。这些选项由 gneiss-mqtt crate 中的结构控制，通过 AwsClientBuilder 上的 with_client_options 和 with_connect_options 方法。更详细的信息可以在 gneiss-mqtt 文档的相关部分中找到。

• Mqtt5ClientOptions
• ConnectOptions

其他注意事项

有关客户端使用细节和指导，请参阅 gneiss-mqtt 文档。

目标是使此 crate 尽可能不受底层实现细节（异步运行时、TLS/传输实现等）的影响，但到目前为止，它对 tokio、rustls 和一些相关的辅助库有硬依赖。这些将在 GA 之前通过功能标志进行限制，允许您根据确切的连接需求减少实现。在 Rust 的当前状态下，在尝试保持传输/运行时无关性和为用户期望的许多不同组合提供易于使用的接口之间存在着根本的紧张关系。