Secure Frame (SFrame)

This library is an implementation of Sframe (RFC 9605) and provides and end-to-end encryption mechanism for media frames that is suited for WebRTC conferences. It was forked from the original goto-opensource/secure-frame-rs and is continued here.

Supported crypto libraries

Currently two crypto libraries are supported:

• ring
  • is enabled per default with the feature ring
  • supports compilation to Wasm32
  • Aes-CTR mode ciphers are not supported
• openssl
  • is enabled with the feature openssl
    • To build e.g. use cargo build --features openssl --no-default-features
  • uses rust 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
  • is enabled with the feature rust-crypto
    • to build e.g. use cargo build --features rust-crypto --no-default-features
  • pure rust implementation of the necessary crypto primitives (AES-GCM, SHA-512, HKDF, AES-CTR)
  • Compilation to Wasm32 is supported

Both cannot be enabled at the same time, thus on conflict sframe issues a compiler error.

Usage

Depending on your use case, this library offers two distinct APIs.

Sender / Receiver API

This API provides an easy to use interface to the Sframe implementation. The Sender / Receiver:

• model the sframe encryption/decryption block in the data path, see RFC 9605 4.1
• derive and store the necessary Sframe key(s)
• keep an internal, dynamic buffer to encrypt/ decrypt a single frame at one time
• provide ratchet support as of RFC 9605 5.1
• optional frame validation before decryption
• For example you can use them like this:

let key_id = 123;
let key_material = "pw123";
let skipped_payload = 1; // payload bytes which are skipped for encryption
let media_frame = b"SOME DATA";

let mut sender = Sender::new(key_id);
sender.set_encryption_key(key_material).unwrap();
let encrypted_frame = sender
  .encrypt(media_frame, skipped_payload)
  .unwrap();

let mut receiver = Receiver::default();
receiver
    .set_encryption_key(key_id, key_material)
    .unwrap();
let decrypted_frame = receiver.decrypt(encrypted_frame, skipped_payload).unwrap();

assert_eq!(media_frame, decrypted_frame);

For more options see the encrypt_decrypt example.

Frame-based API

This API provides low-level access to encryption and decryption at the frame level, offering granular control. It allows the use of arbitrary buffers, enabling the creation of views to avoid unnecessary copies:

• MediaFrameView for unencrypted data
• EncryptedFrameView for encrypted data

For encryption and decryption, a buffer must be provided implementing the FrameBuffer trait to allocate the necessary memory. For convenience, this trait has already been implemented for Vec<u8>. For example:

let key_id = 42u64;
let enc_key = EncryptionKey::derive_from(CipherSuiteVariant::AesGcm256Sha512, key_id, "pw123").unwrap();
let dec_key = DecryptionKey::derive_from(CipherSuiteVariant::AesGcm256Sha512, key_id, "pw123").unwrap();

let frame_count = 1u8;
let payload = "Something secret";

let mut encrypt_buffer = Vec::new();
let mut decrypt_buffer = Vec::new();
let media_frame = MediaFrameView::new(frame_count, payload);

let encrypted_frame = media_frame.encrypt_into(&enc_key, &mut encrypt_buffer).unwrap();

let decrypted_media_frame = encrypted_frame
  .decrypt_into(&mut dec_key, &mut decrypt_buffer)
  .unwrap();

assert_eq!(decrypted_media_frame, media_frame);

There is also a variant which allocates the necessary memory and owns the buffers:

• MediaFrame for unencrypted data
• EncryptedFrame for encrypted data

To see how the API is used with another buffer type, you can check out the bip_frame_buffer example.

Benchmarks

The criterion benchmarks located at ./benches currently test

• encryption/decryption with all available cipher suites and different frame size
• key derivation with all available cipher suites
• header (de)serialization

They are tracked continously with a Bencher Perf Page:

Contribution

Any help in form of descriptive and friendly issues or comprehensive pull requests are welcome!

The Changelog of this library is generated from its commit log, there any commit message must conform with https://www.conventionalcommits.org/en/v1.0.0/. For simplicity you could make your commits with convco.

License