aranya_fast_channels/

lib.rs

//! The core library for Aranya Fast Channels (AFC).
//!
//! # Overview
//!
//! AFC provides a high-throughput, low latency encryption engine
//! protected by Aranya's policy rules. Data encrypted with (or
//! decrypted by) the engine is sent out of band (not though
//! Aranya itself), making it suitable for encrypting network
//! streams and other high-throughput data.
//!
//! AFC can be configured to use custom cryptography and random
//! number generation.
//!
//! # Usage
//!
//! AFC uses the client-daemon model, with AFC being the
//! "client" and Aranya being the "daemon." However, this is
//! merely a logical distinction; for instance, it's possible for
//! both to be in the same process, just running as different
//! threads (or tasks).
//!
//! All AFC operations are handled by the [`Client`], which
//! communicates with the daemon over [`AfcState`] and
//! [`AranyaState`]. By default, AFC provides a state
//! implementation backed by shared memory.
//!
//! # Notes
//!
//! AFC encrypts/seals each message with a deterministic nonce derived from a
//! base nonce and sequence number. Sequence numbers should not be re-used in a given channel
//! but it is possible to do so by passing a "new" [`AfcState::SealCtx`] to the seal methods
//! on [`Client`].
//!
//! # Example
//!
//! The following example demonstrates two [`Client`]s encrypting
//! data for each other. In practice, the two clients are almost
//! always on different machines. The example also uses shared
//! memory for the state, but in practice anything supported by
//! Aranya can be used.
//!
//! ```
//! # fn main() -> Result<(), Box<dyn core::error::Error>> {
//! # #[cfg(all(feature = "posix", not(feature = "trng")))]
//! # {
//! use aranya_crypto::{
//!     Csprng, EncryptionKey, Engine, IdentityKey, Random, Rng,
//!     afc::{RawOpenKey, RawSealKey, UniChannel, UniOpenKey, UniSealKey, UniSecrets},
//!     dangerous::spideroak_crypto::rust::HkdfSha256,
//!     default::{DefaultCipherSuite, DefaultEngine},
//!     id::IdExt as _,
//!     policy::{CmdId, LabelId},
//! };
//! use aranya_fast_channels::{
//!     AfcState, AranyaState, Channel, Client, Directed, Error, LocalChannelId,
//!     crypto::Aes256Gcm,
//!     shm::{Flag, Mode, Path, ReadState, WriteState},
//! };
//!
//! type E = DefaultEngine;
//! type CS = DefaultCipherSuite;
//!
//! // The maximum number of channels supported by the shared
//! // memory.
//! //
//! // You can use any value, this is just an example.
//! const MAX_CHANS: usize = 42;
//!
//! let aranya_client_a: WriteState<CS, Rng> = {
//!     let path = Path::from_bytes(b"/afc_doc_client_a\x00")
//!         .map_err(|err| Error::SharedMem(err.into()))?;
//!     # aranya_fast_channels::shm::unlink(path);
//!     WriteState::open(path, Flag::Create, Mode::ReadWrite, MAX_CHANS, Rng)
//!         .map_err(Error::SharedMem)?
//! };
//!
//! let aranya_client_b: WriteState<CS, Rng> = {
//!     let path = Path::from_bytes(b"/afc_doc_client_b\x00")
//!         .map_err(|err| Error::SharedMem(err.into()))?;
//!     # aranya_fast_channels::shm::unlink(path);
//!     WriteState::open(path, Flag::Create, Mode::ReadWrite, MAX_CHANS, Rng)
//!         .map_err(Error::SharedMem)?
//! };
//!
//! let (eng, _) = E::from_entropy(Rng);
//!
//! let device1_id = IdentityKey::<CS>::new(&eng).id()?;
//! let device1_enc_sk = EncryptionKey::<CS>::new(&eng);
//!
//! let device2_id = IdentityKey::<CS>::new(&eng).id()?;
//! let device2_enc_sk = EncryptionKey::<CS>::new(&eng);
//!
//! // The label ID used for encryption and decryption.
//! let label_id = LabelId::random(Rng);
//!
//! let ch1 = UniChannel {
//!     parent_cmd_id: CmdId::random(&eng),
//!     our_sk: &device1_enc_sk,
//!     seal_id: device1_id,
//!     their_pk: &device2_enc_sk.public()?,
//!     open_id: device2_id,
//!     label_id,
//! };
//! let UniSecrets { author, peer } = UniSecrets::new(&eng, &ch1)?;
//!
//! // Inform device1 about device2.
//! let seal = UniSealKey::from_author_secret(&ch1, author)?.into_raw_key();
//! let client_a_channel_id =
//!     aranya_client_a.add(Directed::SealOnly { seal }, label_id, device2_id)?;
//!
//! let ch2 = UniChannel {
//!     parent_cmd_id: ch1.parent_cmd_id,
//!     our_sk: &device2_enc_sk,
//!     open_id: device2_id,
//!     their_pk: &device1_enc_sk.public()?,
//!     seal_id: device1_id,
//!     label_id,
//! };
//!
//! // Inform device2 about device1.
//! let open = UniOpenKey::from_peer_encap(&ch2, peer)?.into_raw_key();
//! let client_b_channel_id =
//!     aranya_client_b.add(Directed::OpenOnly { open }, label_id, device1_id)?;
//!
//! let mut afc_client_a = {
//!     let path = Path::from_bytes(b"/afc_doc_client_a\x00")
//!         .map_err(|err| Error::SharedMem(err.into()))?;
//!     let state = ReadState::open(path, Flag::OpenOnly, Mode::ReadWrite, MAX_CHANS)
//!         .map_err(Error::SharedMem)?;
//!     Client::<ReadState<CS>>::new(state)
//! };
//! let mut afc_client_b = {
//!     let path = Path::from_bytes(b"/afc_doc_client_b\x00")
//!         .map_err(|err| Error::SharedMem(err.into()))?;
//!     let state = ReadState::open(path, Flag::OpenOnly, Mode::ReadWrite, MAX_CHANS)
//!         .map_err(Error::SharedMem)?;
//!     Client::<ReadState<CS>>::new(state)
//! };
//!
//! const GOLDEN: &str = "hello from APS!";
//!
//! // Have device1 encrypt data for device2.
//! let ciphertext = {
//!     // Encryption has a little overhead, so make sure the
//!     // ouput buffer is large enough.
//!     let mut dst = vec![0u8; GOLDEN.len() + Client::<ReadState<CS>>::OVERHEAD];
//!
//!     // Create the ctx to pass in.
//!     let mut ctx = afc_client_a.setup_seal_ctx(client_a_channel_id)?;
//!     afc_client_a.seal(&mut ctx, &mut dst[..], GOLDEN.as_bytes())?;
//!     dst
//! };
//!
//! // Here is where you'd send ciphertext over the network, or
//! // whatever makes sense for your application.
//!
//! // Have device2 decrypt the data from device1.
//! let (label_from_open, seq, plaintext) = {
//!     let mut dst = vec![0u8; ciphertext.len() - Client::<ReadState<CS>>::OVERHEAD];
//!     // Create the ctx to pass in.
//!     let mut ctx = afc_client_b.setup_open_ctx(client_b_channel_id)?;
//!     let (label_id, seq) = afc_client_b.open(&mut ctx, &mut dst[..], &ciphertext[..])?;
//!     (label_id, seq, dst)
//! };
//!
//! // At this point we can now make a decision on what to do
//! // with plaintext based on the label. We know it came from
//! // `device1` and we know it has the label `label_id`.
//! // Both of those facts (`device1` and `label_id`)
//! // have been cryptographically verified, so we can make
//! // decisions based on them. For example, we could forward the
//! // plaintext data on to another system that ingests "top
//! // secret" data.
//! assert_eq!(label_from_open, label_id);
//! assert_eq!(seq, 0);
//! assert_eq!(plaintext, GOLDEN.as_bytes());
//!
//! # }
//! # Ok(())
//! # }
//! ```

#![allow(unstable_name_collisions)]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(feature = "allocator_api", feature(allocator_api))]
#![cfg_attr(
    feature = "core_intrinsics",
    allow(internal_features),
    feature(core_intrinsics)
)]
#![cfg_attr(feature = "try_find", feature(try_find))]
#![cfg_attr(not(any(feature = "std", test)), no_std)]
#![warn(
    clippy::alloc_instead_of_core,
    clippy::implicit_saturating_sub,
    clippy::undocumented_unsafe_blocks,
    clippy::expect_used,
    clippy::indexing_slicing,
    clippy::missing_panics_doc,
    clippy::string_slice,
    clippy::unimplemented,
    missing_docs
)]
#![cfg_attr(not(any(feature = "std", test)), deny(clippy::std_instead_of_core))]
#![expect(
    clippy::arithmetic_side_effects,
    reason = "https://github.com/aranya-project/aranya-core/issues/253"
)]

#[cfg(feature = "alloc")]
extern crate alloc;

#[macro_use]
mod features;

mod buf;
mod client;
pub mod crypto;
pub mod errno;
mod error;
mod header;
pub mod memory;
mod mutex;
pub mod rust;
pub mod shm;
mod state;
pub mod testing;
mod util;

pub use buf::*;
pub use client::*;
pub use error::*;
pub use header::*;
pub use state::*;
#[cfg(feature = "unsafe_debug")]
pub use util::init_debug_logging;