Crate sframe 

Secure Frame (SFrame)

This library is an implementation of SFrame (RFC 9605).

Usage

frame is the main API. It encrypts and decrypts whole media frames with a key from key, writing and parsing the SFrame header on the way:

use sframe::{
    CipherSuite,
    frame::{MediaFrame, MonotonicCounter},
    key::{DecryptionKey, EncryptionKey},
};

const CIPHER_SUITE: CipherSuite = CipherSuite::AesGcm256Sha512;
let key_id = 42u64;

// both sides derive their key from key material shared out of band
let enc_key = EncryptionKey::derive_from(CIPHER_SUITE, key_id, "pw123")?;
let dec_key = DecryptionKey::derive_from(CIPHER_SUITE, key_id, "pw123")?;

let mut counter = MonotonicCounter::default();
let media_frame = MediaFrame::try_new(&mut counter, "Something secret")?;
let encrypted_frame = media_frame.encrypt(&enc_key)?;

assert_eq!(encrypted_frame.decrypt(&dec_key)?, media_frame);

frame::MediaFrame and frame::EncryptedFrame own their buffer. The frame module additionally offers:

• the view API, frame::MediaFrameView and frame::EncryptedFrameView, which read from a buffer you hold and write into one you supply through frame::FrameBuffer, so no copy is needed
• meta data, which stays unencrypted so a packetizer downstream can still read it, but is authenticated with the frame, so it cannot be tampered with

Beyond a single key:

• key::KeyStore provides a decryption key per Key ID, for a call with several senders
• frame::validation screens incoming frames before decryption, e.g. against replays
• ratchet ratchets a key forward instead of distributing a new one
• mls derives keys from an MLS group

Optional features

Using optional features sframe allows to configure different crypto libraries. Be aware that those features are mutually exlusive, if multiple are configured sframe issues a compiler error.

• ring (enabled by default) — Uses the ring library which allows compilation to Wasm32. AES-CTR mode ciphers are not supported.
• openssl — Uses the rust-openssl crate, which provides bindings to OpenSSL. Per default the OpenSSL library is locally compiled and then statically linked. The build process requires a C compiler, perl (and perl-core), and make. For further options see the openssl crate documentation. Compilation to Wasm32 is not yet supported.
• rust-crypto - Uses pure rust implementations of the RustCrypto project. Compilation to Wasm32 is supported.

If none of these features is enabled, only the generic crypto traits in crypto are exposed and a custom crypto backend has to be provided by implementing crypto::AeadEncrypt, crypto::AeadDecrypt and crypto::KeyDerivation, then parameterizing key::GenericEncryptionKey / key::GenericDecryptionKey with your types. See the custom-crypto-backend example for a walkthrough.

With a backend feature enabled, key::EncryptionKey and key::DecryptionKey are aliases of those pinned to it, so the type parameters never have to be spelled out.

Modules

crypto

Crypto backends

error

Errors

frame

Frame-based API

header

Header

key

Keys

mls

MLS

ratchet

Ratcheting

Enums

CipherSuite

Depicts which AEAD algorithm is used for encryption and which hashing function is used for the key expansion, see RFC 9605 4.4