1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
//! # Secure Frame (`SFrame`)
//! This library is an implementation of [SFrame (RFC 9605)](https://www.rfc-editor.org/rfc/rfc9605.html).
//!
//! # 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:
//!
//! ```rust
//! use sframe::{
//! CipherSuite,
//! frame::{MediaFrame, MonotonicCounter},
//! key::{DecryptionKey, EncryptionKey},
//! };
//!
//! # fn main() -> sframe::error::Result<()> {
//! 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);
//! # Ok(())
//! # }
//! ```
//!
//! [`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](https://crates.io/crates/ring) library which allows compilation to Wasm32.
//! AES-CTR mode ciphers are not supported.
//! - **`openssl`** — Uses the [rust-openssl](https://crates.io/crates/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](https://docs.rs/openssl/0.10.55/openssl/).
//! Compilation to Wasm32 is not yet supported.
//! - **`rust-crypto`** - Uses pure rust implementations of the [RustCrypto](https://github.com/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.
pub
pub use CipherSuite;
/// Compiles the README's code examples as doctests, so they cannot rot.
;