HTTP client for embedded devices

The reqwless crate implements an HTTP client that can be used in no_std environment, with any transport that implements the traits from the embedded-io crate. No alloc or std lib required!

It offers two sets of APIs:

• A low-level request API which allows you to construct HTTP requests and write them to a embedded-io transport.
• A higher level client API which uses the embedded-nal-async (+ optional embedded-tls / mbedtls-rs) crates to establish TCP + TLS connections.

example

let url = format!("http://localhost", addr.port());
let mut client = HttpClient::new(TokioTcp, StaticDns); // Types implementing embedded-nal-async
let mut rx_buf = [0; 4096];
let response = client
    .request(Method::POST, &url)
    .await
    .unwrap()
    .body(b"PING")
    .content_type(ContentType::TextPlain)
    .send(&mut rx_buf)
    .await
    .unwrap();

The client is still lacking many features, but can perform basic HTTP GET/PUT/POST/DELETE requests with payloads. However, not all content types and status codes are implemented, and are added on a need basis. For TLS, it uses either embedded-tls or mbedtls-rs (formerly known as esp-mbedtls) as the transport.

NOTE: TLS verification is not supported in no_std environments for embedded-tls.

In addition to common headers like .content_type() on requests, broader .headers() functions on both request and response objects access arbitrary header values.

If you are missing a feature or would like an improvement, please raise an issue or a PR.

TLS 1.2*, 1.3 and Supported Cipher Suites

reqwless uses embedded-tls or mbedtls-rs (formerly known as esp-mbedtls) to establish secure TLS connections for https://.. urls.

*TLS 1.2 is only supported with mbedtls-rs

⚠️ Note that both features cannot be used together and will cause a compilation error.

mbedtls-rs

mbedtls-rs supports TLS 1.2 and 1.3. It uses Espressif's Rust wrapper over mbedtls and allows for optimizations such as hardware acceleration.

Cargo.toml:

reqwless = { version = "0.14.0", default-features = false, features = ["mbedtls-rs", "log"] }
mbedtls-rs = { version = "0.1.0" }

Example

/// ... [initialization code. See esp-radio and mbedtls-rs examples]
let state = TcpClientState::<1, 4096, 4096>::new();
let mut tcp_client = TcpClient::new(stack, &state);
let dns_socket = DnsSocket::new(stack);

let _trng_source = TrngSource::new(peripherals.RNG, peripherals.ADC1);
let trng = Trng::try_new().unwrap();
let mbedtls_lib_instance = mbedtls_rs::Tls::new(&mut trng).unwrap();
// For debug messages:
// mbedtls_lib_instance.set_debug(1);

let tls_config = TlsConfig::new(
    reqwless::TlsVersion::Tls1_2,
    reqwless::Certificate::new(reqwless::X509::PEM(CERT)).unwrap(),
    None, // optionally, add client certificate for mTLS
    mbedtls_lib_instance.reference(),
);

let header_buf = [0; 1024];

let client = HttpClient::new_with_tls(&tcp_client, &dns_socket, tls_config);

let mut request = client
    .request(reqwless::request::Method::GET, "https://example.com")
    .await
    .unwrap()
    .content_type(reqwless::headers::ContentType::TextPlain)
    .headers(&[("Host", "example.com")]);
let response = request.send(&mut header_buf).await.unwrap();

embedded-tls

embedded-tls only supports TLS 1.3, so to establish a connection the server must have this ssl protocol enabled.

An addition to the tls version requirement, there is also a negotiation of supported algorithms during the establishing phase of the secure communication between the client and server. By default, the set of supported algorithms in embedded-tls is limited to algorithms that can run entirely on the stack. To test whether the server supports this limited set of algorithm, try and test the server using the following openssl command:

openssl s_client -tls1_3 -ciphersuites TLS_AES_128_GCM_SHA256 -sigalgs "ECDSA+SHA256:ECDSA+SHA384:ed25519" -connect hostname:443

If the server successfully replies to the client hello then the enabled tls version and algorithms on the server should be ok. If the command fails, then try and run without the limited set of signature algorithms

openssl s_client -tls1_3 -ciphersuites TLS_AES_128_GCM_SHA256 -connect hostname:443

If this works, then there are two options. Either enable the signature algorithms on the server by changing the private key from RSA to ECDSA or ed25519, or enable RSA keys on the client by specifying the alloc feature. This enables alloc on embedded-tls which in turn enables RSA signature algorithms.

Minimum supported Rust version (MSRV)

reqwless can compile on stable Rust 1.77 and up.