libcoap_rs/crypto/psk/
mod.rs

1// SPDX-License-Identifier: BSD-2-Clause
2/*
3 * Copyright © The libcoap-rs Contributors, all rights reserved.
4 * This file is part of the libcoap-rs project, see the README file for
5 * general information on this project and the NOTICE.md and LICENSE files
6 * for information regarding copyright ownership and terms of use.
7 *
8 * crypto/psk/mod.rs - Interfaces and types for PSK support in libcoap-rs.
9 */
10
11//! Types and traits related to support for (D)TLS with pre-shared keys for CoAP.
12//!
13//! PSK configuration differs between client-side and server-side.
14//!
15//! # Client Configuration
16//! Typically, you would follow these steps to configure a DTLS PSK client:
17//! 1. Create a [`PskKey`](psk::PskKey) that should be used as a default key when connecting to servers.
18//! 2. Create a [`ClientPskContextBuilder`](psk::ClientPskContextBuilder) using the default key,
19//!    (optionally) make some additional configuration changes in the builder.
20//!    Most notably, you might want to call [`ClientPskContextBuilder::key_provider`](psk::ClientPskContextBuilder::key_provider)
21//!    to set a key provider that may use server-provided identity hints to select a different key
22//!    than the default key (if your target server sends those hints).
23//! 3. Call [`ClientPskContextBuilder::build`](psk::ClientPskContextBuilder::build) to create a
24//!    [`ClientPskContext`](psk::ClientPskContext).
25//! 4. Provide the created context to [`CoapClientSession::connect_dtls`](crate::session::CoapClientSession::connect_dtls).
26//!
27//! ## Example
28//!
29//! ```no_run
30//! use libcoap_rs::CoapContext;
31//! use libcoap_rs::crypto::psk::{ClientPskContextBuilder, PskKey};
32//! use libcoap_rs::session::CoapClientSession;
33//!
34//! let example_key = PskKey::new(Some("dtls_test_id_client1"), "dtls_test_key__1");
35//! let psk_context = ClientPskContextBuilder::new(example_key.clone());
36//!
37//! let psk_context = psk_context.build();
38//!
39//! let mut context = CoapContext::new().unwrap();
40//! let session = CoapClientSession::connect_dtls(
41//!                 &mut context,
42//!                 "example.com:5684".parse().unwrap(),
43//!                 psk_context
44//!               ).unwrap();
45//!
46//! // The session might not be immediately established, but you can already create and send
47//! // requests as usual after this point.
48//! // To check for errors and/or disconnections, you might want to call and check the return value
49//! // of `session.state()` occasionally.
50//! // For error handling, you might also want to register an event handler with the CoAP context.
51//! // Remaining code omitted for brevity, see the crate-level docs for a full example of client
52//! // operation.
53//! ```
54//!
55//! # Server Configuration
56//! Typically, you would follow these steps to configure a DTLS PSK server:
57//! 1. Create a [`PskKey`](psk::PskKey) that should be used as a default key when connecting to clients.
58//! 2. Create a [`ServerPskContextBuilder`](psk::ServerPskContextBuilder) using the default key, (optionally) make some additional
59//!    configuration changes in the builder.
60//!    Most notably, you might want to call [`ServerPskContextBuilder::id_key_provider`](psk::ServerPskContextBuilder::id_key_provider) to choose
61//!    different pre-shared keys depending on the identity sent by clients, and
62//!    [`ServerPskContextBuilder::sni_key_provider`](psk::ServerPskContextBuilder::sni_key_provider) to send different identity hints for different
63//!    requested domains.
64//! 3. Call [`ServerPskContextBuilder::build`](psk::ServerPskContextBuilder::build) to create a [`ServerPskContext`](psk::ServerPskContext).
65//! 4. Provide the created context to [`CoapContext::set_psk_context`](crate::CoapContext::set_psk_context).
66//! 5. Add a DTLS endpoint using [`CoapContext::add_endpoint_dtls`](crate::CoapContext::add_endpoint_dtls).
67//!
68//! ## Example
69//!
70//! ```no_run
71//! use std::collections::HashMap;
72//! use libcoap_rs::CoapContext;
73//! use libcoap_rs::crypto::psk::{ClientPskContextBuilder, PskKey, ServerPskContextBuilder};
74//! use libcoap_rs::session::CoapClientSession;
75//!
76//!
77//! let example_key = PskKey::new(Some("dtls_test_id"), "dtls_test_key___");
78//!
79//! let mut client_keys = [
80//!     PskKey::new(Some("dtls_test_id_client1"), "dtls_test_key__1"),
81//!     PskKey::new(Some("dtls_test_id_client2"), "dtls_test_key__2"),
82//! ];
83//!
84//! let psk_context = ServerPskContextBuilder::new(example_key.clone())
85//!                     // Some types already implement ServerPskIdentityKeyProvider by default.
86//!                     // Namely, all types that implement AsRef<[PskKey]> do, such as [PskKey] and
87//!                     // Vec<PskKey>.
88//!                     .id_key_provider(client_keys);
89//!
90//! let psk_context = psk_context.build();
91//!
92//! let mut context = CoapContext::new().unwrap();
93//! context.set_psk_context(psk_context).expect("error while setting PSK context");
94//! context.add_endpoint_dtls("[::1]:5684".parse().unwrap()).expect("unable to create DTLS endpoint");
95//!
96//! // For error handling, you might want to register an event handler with the CoAP context.
97//! // Remaining code omitted for brevity, see the crate-level docs for a full example of server
98//! // operation.
99//!
100//! ```
101
102/// Data structures and builders for PSK client-side operation.
103mod client;
104/// Data structures for PSKs.
105mod key;
106/// Data structures and builders for PSK server-side operation.
107mod server;
108
109pub use client::*;
110pub use key::*;
111pub use server::*;
libcoap_rs/crypto/psk/mod.rs

libcoap_rs/crypto/psk/
mod.rs
