embedded_mbedtls/lib.rs
1// Copyright Open Logistics Foundation
2//
3// Licensed under the Open Logistics Foundation License 1.3.
4// For details on the licensing terms, see the LICENSE file.
5// SPDX-License-Identifier: OLFL-1.3
6
7//! An [Mbed TLS](https://www.trustedfirmware.org/projects/mbed-tls/) Rust wrapper
8//! for constrained embedded devices.
9//!
10//! Currently, this project is developed with `no_std` CoAPs and LwM2M devices in mind, though usage
11//! is not limited to these use cases. Targeting CoAPs and LwM2M, it uses a static Mbed TLS configuration:
12//! - DTLS support
13//! - (D)TLS 1.2
14//! - Client-only
15//! - `TLS_PSK_WITH_AES_128_CCM_8` cipher suite support
16//! - CTR_DRBG pseudo-random number generator support
17//!
18//! In the future, a dynamic configuration using Rust features might be implemented, but there is
19//! currently no roadmap to do so.
20//!
21//! ## Platform abstraction
22//! - Networking with [`embedded_nal`](https://docs.rs/embedded-nal/latest/embedded_nal/)
23//! - Timing with [`embedded_timers`](https://docs.rs/embedded-timers/latest/embedded_timers/)
24//! - Random Number Generation with [`rand_core`](https://docs.rs/rand_core/latest/rand_core/)
25//!
26//! # Usage Example
27//! In addition to the following example code, also have a look at the example directory in the
28//! git repository. Due to the strong focus on `no_std` environments, the repository contains
29//! working examples for `no_std` hardware.
30//! ```
31//! # use core::net::{IpAddr, Ipv4Addr, SocketAddr};
32//! # use embedded_nal::UdpClientStack;
33//! # use embedded_timers::clock::Clock;
34//! # use rand_core::{CryptoRng, RngCore};
35//! use embedded_mbedtls::ssl::{SslConnection, SslContext, Preset};
36//! use nb::block;
37//!
38//! # fn _setup_ssl_stack<U: UdpClientStack, R: RngCore + CryptoRng>(
39//! # net_stack: U,
40//! # clock: &impl Clock,
41//! # rng: R,
42//! # ) {
43//! # let server_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 22);
44//! // Assuming the variables in use contain a valid hardware abstraction and the server address
45//! // Create the hardware context
46//! let mut ctx = SslContext::new_udp_client_side(net_stack, clock, rng, server_addr);
47//! // Create and configure the connection instance
48//! let mut connection = SslConnection::new_dtls_client(&mut ctx, Preset::Default).unwrap();
49//! connection
50//! .configure_psk(&[1, 2, 3, 4], "embedded-mbedtls".as_bytes())
51//! .unwrap();
52//!
53//! // Set up connection
54//! block!(connection.handshake()).unwrap();
55//!
56//! // Send data
57//! block!(connection.write("Hello, embedded-mbedtls".as_bytes())).unwrap();
58//!
59//! // Receive data
60//! let mut buf = [0u8; 1024];
61//! let len = block!(connection.read(&mut buf)).unwrap();
62//!
63//! // Close connection
64//! block!(connection.close_notify()).unwrap();
65//! # }
66//! ```
67//!
68//! # Features
69//! - `alloc`: enables use of heap allocated contexts, see the explanation in
70//! [`SslConnection`](ssl::SslConnection)
71//!
72//! # License
73//!
74//! Open Logistics License\
75//! Version 1.3, January 2023
76//!
77//! See the LICENSE file in the top-level directory.
78//!
79//! # Contact
80//!
81//! Fraunhofer IML Embedded Rust Group - <embedded-rust@iml.fraunhofer.de>
82
83#![cfg_attr(not(test), no_std)]
84
85#[cfg(feature = "alloc")]
86extern crate alloc;
87
88pub mod error;
89pub mod rng;
90pub mod ssl;
91mod timing;
92pub mod udp;