kevy_noise/lib.rs
1//! The Noise IK handshake (`Noise_IK_25519_ChaChaPoly_BLAKE2s`) and the
2//! transport it establishes, without I/O.
3//!
4//! The initiator knows the responder's static public key in advance; the
5//! responder learns the initiator's static key from the first message and
6//! can decide there whether to accept it. One round trip, then each side
7//! holds a [`Transport`]. Messages travel length-prefixed ([`frame`],
8//! [`Frames`]) on whatever stream the caller owns.
9//!
10//! Ephemeral keys are passed in rather than drawn here, so the crate never
11//! touches an entropy source: every handshake needs a fresh one from the
12//! operating system.
13//!
14//! ```
15//! use kevy_noise::{Initiator, Keypair, Responder};
16//!
17//! let server = Keypair::from_secret([1; 32]);
18//! let client = Keypair::from_secret([2; 32]);
19//!
20//! let (m1, init) =
21//! Initiator::start(&client, &server.public(), Keypair::from_secret([3; 32]), b"kevy", b"")?;
22//! let (_, resp) = Responder::accept(&server, Keypair::from_secret([4; 32]), b"kevy", &m1)?;
23//! assert_eq!(resp.remote_static(), client.public());
24//! let (m2, mut server_t) = resp.finish(b"")?;
25//! let (_, mut client_t) = init.finish(&m2)?;
26//!
27//! let msg = client_t.seal(b"SET k v")?;
28//! assert_eq!(server_t.open(&msg)?, b"SET k v");
29//! # Ok::<(), kevy_noise::Error>(())
30//! ```
31
32#![forbid(unsafe_code)]
33#![warn(missing_docs)]
34
35mod handshake;
36mod symmetric;
37mod transport;
38
39#[cfg(test)]
40mod tests;
41
42pub use handshake::{Initiator, Keypair, Responder};
43pub use transport::{Frames, MAX_MESSAGE, Opener, Sealer, Transport, frame};
44
45// Send and Sync are part of the public contract: a change that loses
46// either fails to compile here rather than in a caller.
47const _: () = {
48 const fn send_sync<T: Send + Sync>() {}
49 send_sync::<Keypair>();
50 send_sync::<Initiator>();
51 send_sync::<Responder>();
52 send_sync::<Transport>();
53 send_sync::<Sealer>();
54 send_sync::<Opener>();
55 send_sync::<Frames>();
56 send_sync::<Error>();
57};
58
59/// Why a handshake or transport message was refused.
60///
61/// ```
62/// assert_eq!(kevy_noise::Error::Decrypt.to_string(), "message failed authentication");
63/// ```
64#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
65#[non_exhaustive]
66pub enum Error {
67 /// A message failed authentication: altered, replayed, out of order, or
68 /// from someone without the keys.
69 ///
70 /// ```
71 /// # use kevy_noise::{Error, Initiator, Keypair, Responder};
72 /// let (server, client) = (Keypair::from_secret([1; 32]), Keypair::from_secret([2; 32]));
73 /// let (m1, _) = Initiator::start(&client, &server.public(), Keypair::from_secret([3; 32]), b"a", b"").unwrap();
74 /// let wrong_prologue = Responder::accept(&server, Keypair::from_secret([4; 32]), b"b", &m1);
75 /// assert_eq!(wrong_prologue.err(), Some(Error::Decrypt));
76 /// ```
77 Decrypt,
78 /// A message was shorter than its fixed parts.
79 ///
80 /// ```
81 /// # use kevy_noise::{Error, Keypair, Responder};
82 /// let r = Responder::accept(&Keypair::from_secret([1; 32]), Keypair::from_secret([4; 32]), b"", &[1; 10]);
83 /// assert_eq!(r.err(), Some(Error::Truncated));
84 /// ```
85 Truncated,
86 /// A peer's public key was a point of small order.
87 ///
88 /// ```
89 /// # use kevy_noise::{Error, Keypair, Responder};
90 /// let zero_ephemeral = [0u8; 96];
91 /// let r = Responder::accept(&Keypair::from_secret([1; 32]), Keypair::from_secret([4; 32]), b"", &zero_ephemeral);
92 /// assert_eq!(r.err(), Some(Error::LowOrderPoint));
93 /// ```
94 LowOrderPoint,
95 /// A message is longer than [`MAX_MESSAGE`] allows.
96 ///
97 /// ```
98 /// let big = vec![0u8; kevy_noise::MAX_MESSAGE + 1];
99 /// assert_eq!(kevy_noise::frame(&big).err(), Some(kevy_noise::Error::TooLong));
100 /// ```
101 TooLong,
102 /// 2^64 - 1 messages have been sent or received on this key. A session
103 /// would have to run for centuries at line rate to see it.
104 ///
105 /// ```
106 /// assert_ne!(kevy_noise::Error::NonceExhausted, kevy_noise::Error::Decrypt);
107 /// ```
108 NonceExhausted,
109}
110
111impl core::fmt::Display for Error {
112 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
113 f.write_str(match self {
114 Error::Decrypt => "message failed authentication",
115 Error::Truncated => "message too short",
116 Error::LowOrderPoint => "peer key is a point of small order",
117 Error::TooLong => "message longer than a Noise message allows",
118 Error::NonceExhausted => "nonce space exhausted",
119 })
120 }
121}
122
123impl std::error::Error for Error {}