libcoap_rs

Module crypto

Source
Expand description

Cryptography interfaces and types.

Currently, libcoap supports four different types of encrypted communications:

  • (D)TLS using pre-shared keys (PSK): The simplest method, uses a symmetric/pre-shared key to perform authentication (see RFC 4279).
  • (D)TLS using raw public keys (RPK): Uses asymmetric key pairs for authentication. The peer’s public key must be known in advance and must be validated by the library user.
  • (D)TLS using a public key infrastructure (PKI): Uses asymmetric key pairs signed by a certificate authority, which are authenticated by the TLS library using a set of pre-configured (or provided) root certificate authorities (the way most of the internet works).
  • OSCORE (unsupported by libcoap-rs, see issue #23): Uses Object Security for Constrained RESTful Environments (OSCORE, RFC 8613) to encrypt messages on the application layer.

§Configuration

Logically, libcoap provides two different structures for DTLS configuration: One for PSK configuration and another one for both PKI and RPK configurations. Each of these DTLS contexts may be provided to either a CoapClientSession on construction or be attached to a CoapContext for server-side use.

A client-side session can only be configured with either a PKI/RPK configuration or a PSK configuration, i.e., you must know in advance which type of encryption to use. The CoapContext can be configured with both a server-side PKI/RPK configuration and a PSK configuration, but only with one of each type, i.e., you can support both PSK and RPK/PKI, but not both RPK and PKI simultaneously, as the RPK/PKI configuration object can only be configured to enable either PKI or RPK.

For more information on how to configure the different types of encryption, see the module-level documentation for the PKI/RPK and PSK submodules.

You may also refer to the libcoap documentation on encryption for supplementary information.

§Compilation and TLS library support

Support for DTLS requires the dtls-rpk, dtls-pki, or dtls-psk features to be enabled, depending on the DTLS variants you wish to support.

libcoap may be built with different TLS libraries as backends, and support for the different variants of DTLS and certain features within those may differ between libraries. Assuming you have not called any unsafe functions that circumvent this check, enabling one of the three DTLS variant features while using a TLS library that does not support this feature will result in either a compilation error or a panic on when calling CoapContext::new, irrespective of whether you actually use DTLS.

Refer to the [libcoap_sys] documentation for more information on the build process specifics regarding DTLS libraries.

Modules§

pki_rpk
Types and traits related to (D)TLS with raw public keys and/or public key infrastructure support for CoAP.
psk
Types and traits related to support for (D)TLS with pre-shared keys for CoAP.

Enums§

ClientCryptoContext
Client-side context for cryptography.