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.

Example

The following example demonstrates two Clients 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.

use aranya_fast_channels::{
    AfcState,
    AranyaState,
    Channel,
    ChannelId,
    Client,
    Directed,
    Error,
    Label,
    NodeId,
    crypto::Aes256Gcm,
    shm::{Flag, Mode, Path, ReadState, WriteState},
};
use aranya_crypto::{
    afc::{
        BidiChannel,
        BidiKeys,
        BidiSecrets,
        RawOpenKey,
        RawSealKey,
    },
    Csprng,
    EncryptionKey,
    Engine,
    Id,
    IdentityKey,
    Random,
    Rng,
    rust::HkdfSha256,
    default::{DefaultCipherSuite, DefaultEngine},
};

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 device1_node_id = NodeId::new(1);

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 device2_node_id = NodeId::new(2);

let (mut eng, _) = E::from_entropy(Rng);

let device1_id = IdentityKey::<CS>::new(&mut eng).id()?;
let device1_enc_sk = EncryptionKey::<CS>::new(&mut eng);

let device2_id = IdentityKey::<CS>::new(&mut eng).id()?;
let device2_enc_sk = EncryptionKey::<CS>::new(&mut eng);

// The label used for encryption and decryption.
//
// The value (12) should come from the label definition in
// the Aranya policy file.
const TOP_SECRET: Label = Label::new(12);

let ch1 = BidiChannel {
    parent_cmd_id: Id::random(&mut eng),
    our_sk: &device1_enc_sk,
    our_id: device1_id,
    their_pk: &device2_enc_sk.public()?,
    their_id: device2_id,
    label: TOP_SECRET.to_u32(),
};
let BidiSecrets { author, peer } =
    BidiSecrets::new(&mut eng, &ch1)?;

// Inform device1 about device2.
let (seal, open) = BidiKeys::from_author_secret(&ch1, author)?
    .into_raw_keys();
aranya_client_a.add(
    ChannelId::new(device2_node_id, TOP_SECRET),
    Directed::Bidirectional { seal, open },
);

let ch2 = BidiChannel {
    parent_cmd_id: ch1.parent_cmd_id,
    our_sk: &device2_enc_sk,
    our_id: device2_id,
    their_pk: &device1_enc_sk.public()?,
    their_id: device1_id,
    label: TOP_SECRET.to_u32(),
};

// Inform device2 about device1.
let (seal, open) = BidiKeys::from_peer_encap(&ch2, peer)?
    .into_raw_keys();
aranya_client_b.add(
    ChannelId::new(device1_node_id, TOP_SECRET),
    Directed::Bidirectional { seal, open },
);

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 = {
    let id = ChannelId::new(device2_node_id, TOP_SECRET);
    // 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];
    afc_client_a.seal(id, &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, seq, plaintext) = {
    let mut dst = vec![0u8; ciphertext.len() - Client::<ReadState<CS>>::OVERHEAD];
    let (label, seq) = afc_client_b.open(device1_node_id, &mut dst[..], &ciphertext[..])?;
    (label, 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_node_id` and we know it has the label `TOP_SECRET`.
// Both of those facts (`device1_node_id` and `TOP_SECRET`)
// 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, TOP_SECRET);
assert_eq!(seq, 0);
assert_eq!(plaintext, GOLDEN.as_bytes());