bitwarden_ipc/crypto_provider/noise/mod.rs
1//! # Noise Crypto Provider
2//!
3//! Implements IPC encryption using the [Noise Protocol Framework](http://noiseprotocol.org/)
4//! with the NN handshake pattern. Either side may lose state due to process reload, so
5//! re-handshakes are expected. Security is provided against passive attackers of both
6//! traffic and to some extent to subsequent key compromise, but active MITM attacks
7//! are not protected against.
8//!
9//! ## Protocol Flow
10//!
11//! ```text
12//! Initiator Responder
13//! | |
14//! |--- HandshakeStart ------------------>|
15//! |<-- HandshakeFinish ------------------|
16//! | |
17//! | [Both derive transport keys] |
18//! | |
19//! |--- TransportFrame (encrypted) ------>|
20//! |<-- TransportFrame (encrypted) -------|
21//! | ... |
22//! | |
23//! | [After REHANDSHAKE_INTERVAL |
24//! | initiator starts a new handshake] |
25//! | |
26//! |--- HandshakeStart ------------------>|
27//! |<-- HandshakeFinish ------------------|
28//! | ... |
29//! | |
30//! | [If responder has no session for an |
31//! | incoming TransportFrame, it replies |
32//! | with CryptoInvalidated so both |
33//! | sides reset and re-handshake] |
34//! | |
35//! |--- TransportFrame (no session) ----->|
36//! |<-- CryptoInvalidated ----------------|
37//! |--- HandshakeStart ------------------>|
38//! |<-- HandshakeFinish ------------------|
39//! | ... |
40//! ```
41//!
42//! ## Frame Types
43//!
44//! All frames are CBOR-encoded [`Frame`](crypto_provider::Frame) variants sent over
45//! the IPC channel:
46//! - **HandshakeStart** — initiates a Noise NN handshake
47//! - **HandshakeFinish** — completes the handshake
48//! - **TransportFrame** — encrypted payload
49//! - **CryptoInvalidated** — signals session loss so both sides reset
50//!
51//! ## Security Definitions
52//!
53//! Security Definition SD1:
54//! - Attacker Model:
55//! - Attacker has full passive read access to the entire IPC conversation
56//! - Security Goal:
57//! - Attacker should not be able to derive any information about the plaintext messages beyond
58//! length and timing.
59//!
60//! Security Definition SD2:
61//! - Attacker Model:
62//! - Attacker has full passive read access to the entire IPC conversation and access to the
63//! session state of one side at time X
64//! - Security Goal:
65//! - Attacker should only be able to decrypt messages that were received or sent within the
66//! re-handshake interval
67
68// Ref: http://noiseprotocol.org/noise.html#message-format
69const NOISE_MAX_MESSAGE_LEN: usize = 65535;
70
71pub mod crypto_provider;
72pub(super) mod handshake;
73mod transport_state;