Crate oboron

Expand description

oboron is a string-in / string-out authenticated symmetric encryption layer for UTF-8 text: it encrypts a string under an AES-SIV or AES-GCM-SIV scheme and encodes the result to compact obtext (Crockford base32, base32, base64url, or hex). Every scheme is authenticated; the scheme is supplied by the caller (the obtext carries no marker), and keys are 128-character hex.

§Quick Start

use oboron::{DsivC32, ObtextCodec};
let key = oboron::generate_key(); // get key
let ob = DsivC32::new(&key)?;     // instantiate ObtextCodec (cipher+encoder)
let ot = ob.enc("secret data")?;  // get obtext (encoded ciphertext)

§Parameter Order Convention

All functions in this library follow a consistent parameter ordering convention:

data < format < key

data (plaintext/obtext) comes first - it’s what you’re operating on
format comes second (when present) - it’s configuration/options
key comes last (when present) - it’s the security credential

Examples:

// Operations: data, format
let ot = omb.enc("plaintext", "dsiv.b64")?;
omb.dec(&ot, "dsiv.b64")?;

// Constructors: format, key
oboron::Ob::new("dsiv.b64", &key)?;

// Convenience functions: data, format, key
let ot = oboron::enc("plaintext", "dsiv.b64", &key)?;
oboron::dec(&ot, "dsiv.b64", &key)?;

§Choosing the Right Type

Oboron provides several types optimized for different use cases:

§1. Fixed-Format Types (Fastest, Compile-Time)

Use format-specific types when you know the format at compile time:

let dsiv = DsivC32::new(&key)?;      // dsiv.c32 format (Crockford base32)
let dsiv_b64 = DsivB64::new(&key)?;  // dsiv.b64 format (base64url)

let ot = dsiv.enc("hello")?;
let pt2 = dsiv.dec(&ot)?;

Use case: Format is known at compile time
Performance: Fastest (zero overhead)
Flexibility: Format fixed, explicit in type name

§2. `Ob` - Runtime Format (Flexible)

Use Ob when you need to choose the format at runtime:

// Format chosen at runtime
let mut ob = Ob::new("dsiv.b64", &key)?;

let ot = ob.enc("hello")?;
let pt2 = ob.dec(&ot)?;

// Can change format if needed
ob.set_format("dsiv.hex")?;

Use case: Format determined at runtime (config, user input)
Performance: Near-zero overhead (inlines to static functions)
Flexibility: Runtime format selection, can be changed after construction

§3. `Omnib` - Multi-Format Operations

Use Omnib when working with different formats in a single context:

let omb = Omnib::new(&key)?;

// Encode to different formats
let ot_c32 = omb.enc("data", "dsiv.c32")?;
let ot_b64 = omb.enc("data", "dsiv.b64")?;
let ot_hex = omb.enc("data", "dsiv.hex")?;

// Decode with the matching format (the scheme is supplied, not detected)
let pt2 = omb.dec(&ot_b64, "dsiv.b64")?;

Use case: Working with multiple formats in one context
Performance: Small overhead (format parsing per operation)
Flexibility: Maximum - handles any format on a per-operation basis

§Quick Reference

Type	Format	Use Case	Performance
`DsivC32`, etc.	Compile-time	Known format	Fastest (zero-cost)
`Ob`	Runtime, mutable	Config-driven	Near-zero overhead
`Omnib`	Per-operation	Multiple formats	Small overhead

§Typical Production Usage: Fixed ObtextCodec

Best performance and type safety for multiple operations with the same format:

// Fixed format types (best performance for multiple operations with same format)
let dsiv = oboron::DsivC32::new(&key)?;  // "dsiv.c32" fixed-format ObtextCodec instance
let pgcmsiv = oboron::PgcmsivC32::new(&key)?;  // "pgcmsiv.c32" fixed-format ObtextCodec instance

let ot_dsiv = dsiv.enc("data1")?;
let ot_pgcmsiv = pgcmsiv.enc("data2")?;

// Decoding
let pt1 = dsiv.dec(&ot_dsiv)?;  // Decodes successfully
let pt2 = pgcmsiv.dec(&ot_pgcmsiv)?;
assert_eq!(pt1, "data1");
assert_eq!(pt2, "data2");

§Encryption Schemes

All four core schemes are authenticated:

Dgcmsiv: deterministic AES-GCM-SIV
Dsiv: deterministic AES-SIV (nonce-misuse resistant)
Pgcmsiv: probabilistic AES-GCM-SIV
Psiv: probabilistic AES-SIV

Unauthenticated (upcbc) and obfuscation (zdcbc) schemes are not part of oboron — they live in the separate obu crate.

Testing/Demo only schemes using no encryption (mock feature group):

Mock1: Identity
Mock2: Reverse plaintext

Each scheme supports four string encodings:

B64 - URL-safe base64 (RFC 4648 base64url standard)
B32 - Standard base32 (RFC 4648)
C32 - Crockford base32
Hex - Hexadecimal

§Security

oboron is a thin string/encoding layer over the obcrypt authenticated-encryption core; the cryptography, threat model, and usage limits are documented in obcrypt’s SECURITY.md and summarized in this crate’s SECURITY.md. Key points:

Not independently audited. Neither oboron nor obcrypt has had an external security audit. Evaluate accordingly for high-assurance use.
Deterministic schemes use a fixed nonce. dsiv / dgcmsiv encrypt under a constant (all-zero) nonce, sound only because AES-SIV / AES-GCM-SIV are nonce-misuse-resistant (RFC 5297, RFC 8452). The confidentiality cost is the deterministic-equality leak those schemes expose by design — equal plaintexts yield equal obtext.
The binding limit is data volume, not nonce reuse. Security degrades only as the total data encrypted under one key approaches the AES-GCM-SIV birthday bound — far out of reach for the short-string workloads oboron targets. The library is stateless, so honoring that bound is a deployment responsibility: under high-volume use, rotate the master key well before it.
Keys are 128-character lowercase hex. There is no base64 key encoding; generate keys with generate_key.

§The `ObtextCodec` Trait

All types (Ob, DsivC32, PsivB64, etc.) except Omnib implement the ObtextCodec trait,

fn process<O: ObtextCodec>(ob: &O, data: &str) -> Result<String, oboron::Error> {
    let ot = ob.enc(data)?;
    ob.dec(&ot)
}

let dsiv = DsivC32::new(&key)?;
let ob = Ob::new("dsiv.c32", &key)?;

process(&dsiv, "hello")?;
process(&ob, "hello")?;

The ObtextCodec trait is automatically imported via the prelude.

Modules§

prelude: Convenience prelude for common imports.

Structs§

DgcmsivB32: ObtextCodec implementation for dgcmsiv. b32 format.
DgcmsivB64: ObtextCodec implementation for dgcmsiv.b64 format.
DgcmsivC32: ObtextCodec implementation for dgcmsiv. c32 format.
DgcmsivHex: ObtextCodec implementation for dgcmsiv.hex format.
DsivB32: ObtextCodec implementation for dsiv.b32 format.
DsivB64: ObtextCodec implementation for dsiv.b64 format.
DsivC32: ObtextCodec implementation for dsiv.c32 format.
DsivHex: ObtextCodec implementation for dsiv.hex format.
Format: Format combines a scheme (encryption method) with an encoding (text representation).
Ob: A flexible ObtextCodec implementation with runtime format selection.
Omnib: An ObtextCodec that takes the format per operation.
PgcmsivB32: ObtextCodec implementation for pgcmsiv.b32 format.
PgcmsivB64: ObtextCodec implementation for pgcmsiv.b64 format.
PgcmsivC32: ObtextCodec implementation for pgcmsiv.c32 format.
PgcmsivHex: ObtextCodec implementation for pgcmsiv.hex format.
PsivB32: ObtextCodec implementation for psiv.b32 format.
PsivB64: ObtextCodec implementation for psiv.b64 format.
PsivC32: ObtextCodec implementation for psiv.c32 format.
PsivHex: ObtextCodec implementation for psiv.hex format.

Enums§

Encoding: Encoding identifier for text representation.
Error: All errors that can occur in oboron operations.
ObAny: Type-erased ObtextCodec encoder that can hold any scheme+encoding combination.
Scheme: Scheme identifier for oboron encoding schemes.

Constants§

Traits§

ObtextCodec: Core trait for ObtextCodec encryption+encoding/decoding+decryption implementations.

Functions§

dec: Decode+decrypt obtext with a specified format.
enc: Encrypt+encode plaintext with a specified format.
from_bytes: Create an encoder from a format string and raw bytes.
from_bytes_with_format: Create an encoder from a pre-parsed Format and raw bytes.
from_hex_key: Create an encoder from a format string and a 128-character hex key.
from_hex_key_with_format: Create an encoder from a pre-parsed Format and a 128-character hex key.
generate_key: Generate a cryptographically secure random 64-byte key and return it as a 128-character lowercase hex string.
generate_key_bytes: Generate a cryptographically secure random 64-byte key as raw bytes.
generate_key_hexDeprecated: Deprecated alias for generate_key.
new: Create an encoder from a format string and a 128-character hex key.
new_with_format: Create an encoder from a pre-parsed Format and a 128-character hex key.

Crate oboron

Crate oboron Copy item path

§Quick Start

§Parameter Order Convention

§Choosing the Right Type

§1. Fixed-Format Types (Fastest, Compile-Time)

§2. Ob - Runtime Format (Flexible)

§3. Omnib - Multi-Format Operations

§Quick Reference

§Typical Production Usage: Fixed ObtextCodec

§Encryption Schemes

§Security

§The ObtextCodec Trait

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Crate oboron

§2. `Ob` - Runtime Format (Flexible)

§3. `Omnib` - Multi-Format Operations

§The `ObtextCodec` Trait