libcoap_rs/crypto/
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/mod.rs - CoAP cryptography provider interfaces and types.
9 */
10
11//! Cryptography interfaces and types.
12//!
13//! Currently, libcoap supports four different types of encrypted communications:
14//! - (D)TLS using pre-shared keys (PSK): The simplest method, uses a symmetric/pre-shared key to
15//!   perform authentication (see [RFC 4279](https://datatracker.ietf.org/doc/html/rfc4279)).
16//! - (D)TLS using raw public keys (RPK): Uses asymmetric key pairs for authentication. The peer's
17//!   public key must be known in advance and must be validated by the library user.
18//! - (D)TLS using a public key infrastructure (PKI): Uses asymmetric key pairs signed by a
19//!   certificate authority, which are authenticated by the TLS library using a set of
20//!   pre-configured (or provided) root certificate authorities (the way most of the internet works).
21//! - OSCORE (*unsupported by libcoap-rs, see
22//!   [issue #23](https://github.com/namib-project/libcoap-rs/issues/23)*): Uses Object Security for
23//!   Constrained RESTful Environments (OSCORE, [RFC 8613](https://datatracker.ietf.org/doc/html/rfc8613)) to encrypt messages on the application
24//!   layer.
25//!
26//! # Configuration
27//!
28//! Logically, `libcoap` provides two different structures for DTLS configuration: One for PSK
29//! configuration and another one for both PKI and RPK configurations.
30//! Each of these DTLS contexts may be provided to either a
31//! [`CoapClientSession`](crate::session::CoapClientSession) on construction or be attached to a
32//! [`CoapContext`](crate::CoapContext) for server-side use.
33//!
34//! A client-side session can only be configured with _either_ a PKI/RPK configuration _or_ a PSK
35//! configuration, i.e., you must know in advance which type of encryption to use.
36//! The [`CoapContext`](crate::CoapContext) can be configured with both a server-side PKI/RPK
37//! configuration _and_ a PSK configuration, but only with one of each type, i.e., you can support
38//! both PSK and RPK/PKI, but not both RPK and PKI simultaneously, as the RPK/PKI configuration
39//! object can only be configured to enable _either_ PKI _or_ RPK.
40//!
41//! For more information on how to configure the different types of encryption, see the module-level
42//! documentation for the [PKI/RPK](pki_rpk) and [PSK](psk) submodules.
43//!
44//! You may also refer to the [libcoap documentation on encryption](https://libcoap.net/doc/reference/develop/man_coap_encryption.html)
45//! for supplementary information.
46//!
47//! # Compilation and TLS library support
48//!
49//! Support for DTLS requires the `dtls-rpk`, `dtls-pki`, or `dtls-psk` features to be enabled,
50//! depending on the DTLS variants you wish to support.
51//!
52//! libcoap may be built with different TLS libraries as backends, and support for the different
53//! variants of DTLS and certain features within those may differ between libraries.
54//! Assuming you have not called any unsafe functions that circumvent this check, enabling one of
55//! the three DTLS variant features while using a TLS library that does not support this feature
56//! will result in either a compilation error or a panic on when calling [`CoapContext::new`](crate::CoapContext::new),
57//! irrespective of whether you actually use DTLS.
58//!
59//! Refer to the [libcoap_sys] documentation for more information on the build process specifics
60//! regarding DTLS libraries.
61
62#[cfg(any(feature = "dtls-rpk", feature = "dtls-pki"))]
63pub mod pki_rpk;
64#[cfg(feature = "dtls-psk")]
65pub mod psk;
66
67use std::fmt::Debug;
68
69/// Client-side context for cryptography.
70///
71/// Can be provided to a client-side session constructor for encrypted sessions (such as
72/// [`CoapClientSession::connect_dtls`](crate::session::CoapClientSession::connect_dtls)).
73///
74/// The available enum variants depend on the enabled DTLS features (`dtls-psk`, `dtls-pki`, and/or
75/// `dtls-rpk`).
76#[derive(Clone, Debug)]
77pub enum ClientCryptoContext<'a> {
78    /// Context for a client-side DTLS session with pre-shared keys.
79    #[cfg(feature = "dtls-psk")]
80    Psk(psk::ClientPskContext<'a>),
81    /// Context for a client-side DTLS session using a public key infrastructure for certificate
82    /// validation.
83    #[cfg(feature = "dtls-pki")]
84    Pki(pki_rpk::PkiRpkContext<'a, pki_rpk::Pki>),
85    /// Context for a client-side DTLS session using raw public keys.
86    #[cfg(feature = "dtls-rpk")]
87    Rpk(pki_rpk::PkiRpkContext<'a, pki_rpk::Rpk>),
88}
libcoap_rs/crypto/mod.rs

libcoap_rs/crypto/
mod.rs
