Crate aloha

source ·
Expand description

This library implements draft-ietf-ohai-ohttp-06.

Quick start

use aloha::{bhttp, id, Config, Error};
use rand::thread_rng;

// Some of the crypto functions require a RNG.
let mut rng = thread_rng();

// [server] Generates a server side config with selected algorithms.
let srv_conf = Config::builder()
   .with_id(1)
   .gen_keypair(id::KemId::X25519HKDFSHA256, &mut rng)
   .push_alg(id::KdfId::HKDFSHA256, id::AeadId::AESGCM128)
   .build()?;

// [server] From the server side config, get a client side one and
// deliver in to the client side after serializaion.
let mut cli_conf_bytes = Vec::new();
srv_conf.get_client().compose(&mut cli_conf_bytes)?;

// ... distribute the cli_conf_bytes to the client

// [client] Parse the client config from raw bytes.
let cli_conf = Config::parse(&mut cli_conf_bytes.as_slice())?;

// [client] Build a bhttp request
let mut req = Vec::new();
bhttp::Builder::new(&mut req, bhttp::Framing::KnownLenReq)
   .push_ctrl(b"GET", b"https", b"example.com", b"/ping")?
   .push_headers(&[("host".as_bytes(), "example.com".as_bytes())])?;

// [client] Encrypt the request data and send it to the server.
let (enc_req, cli_ctx) = cli_conf.encrypt_req(0, &req, &mut rng)?;

// [server] Use the server side config to decrypt the request.
let (dec_req, srv_ctx) = srv_conf.decrypt_req(&enc_req)?;
assert_eq!(req, dec_req.as_ref());

// [server] Parse the bhttp msg.
let parser = bhttp::Parser::new(&dec_req);
let req_ctrl = parser.next_req()?;
let ctrl = req_ctrl.get()?;
assert_eq!(b"GET", ctrl.method);
assert_eq!(b"https", ctrl.scheme);
assert_eq!(b"example.com", ctrl.authority);
assert_eq!(b"/ping", ctrl.path);
let _headers = req_ctrl.next()?;

// [server] Use the context to encrypt a (bhttp) response.
let res = b"pong";
let enc_res = srv_ctx.encrypt_res(&res[..], &mut rng)?;
// [client] Use the context to decrypt the response.
let dec_res = cli_ctx.decrypt_res(&enc_res)?;
assert_eq!(&res[..], &dec_res);

Modules

  • bhttp
    A RFC 9292 implementation that has chained parser and builder to avoid heap allocation.
  • id
    Reexport of several HPKE algorithm IDs that supported by this library.

Structs

  • Config
    Config contains necessary parameters to establish a conversation between a client and a server.
  • ConfigBuilder
    A builder to build config.
  • Ctx
    A context used in either client side or server side to carry necessary information for handling the response later.
  • Header
    Message header is a low level data representation which contains various identifiers.

Enums

  • Error
    Errors used in this library.

Constants

Traits

  • InPlaceMut
    Trait to support in place operations over a mutable buffer. The method is an associated function because it can benefit from the internal macros, same reason for the unused header parameter in response decryption.