Skip to main content

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 {}