Crate oboron

Crate oboron 

Source
Expand description

This library provides encryption-based encoding to various text schemes using AES encryption with multiple scheme options.

§Quick Start

use oboron::{AasvC32, ObtextCodec};
let key = oboron::generate_key(); // get key
let ob = AasvC32::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", "aasv.b64")?;
omb.dec(&ot, "aasv.b64")?;

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

// Convenience functions: data, format, key
let ot = oboron::enc("plaintext", "aasv.b64", &key)?;
oboron::dec(&ot, "aasv.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 aasv = AasvC32::new(&key)?;      // aasv.c32 format (Crockford base32)
let aasv_b64 = AasvB64::new(&key)?;  // aasv.b64 format (base64url)

let ot = aasv.enc("hello")?;
let pt2 = aasv.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("aasv.b64", &key)?;

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

// Can change format if needed
ob.set_format("aasv.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_b32 = omb.enc("data", "aasv.c32")?;
let ot_b64 = omb.enc("data", "aasv.b64")?;
let ot_hex = omb.enc("data", "aasv.hex")?;

// Decode with automatic format detection
let pt2 = omb.autodec(&ot_b64)?;
  • Use case: Working with multiple formats or unknown formats
  • Performance: Small overhead (format parsing per operation)
  • Flexibility: Maximum - handles any format, autodetects on dec

§Quick Reference

TypeFormatUse CasePerformance
AasvC32, etc.Compile-timeKnown formatFastest (zero-cost)
ObRuntime, mutableConfig-drivenNear-zero overhead
OmnibPer-operationMultiple formatsSmall 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 aasv = oboron::AasvC32::new(&key)?;  // "aasv.c32" fixed-format ObtextCodec instance
let apgs = oboron::ApgsC32::new(&key)?;  // "apgs.c32" fixed-format ObtextCodec instance

let ot_aasv = aasv.enc("data1")?;
let ot_apgs = apgs.enc("data2")?;

// Decoding
let pt1 = aasv.dec(&ot_aasv)?;  // Decodes successfully
let pt2 = apgs.dec(&ot_apgs)?;
assert_eq!(pt1, "data1");
assert_eq!(pt2, "data2");

§Encryption Schemes

  • Authenticated:
    • Aags: deterministic AES-GCM-SIV
    • Aasv: deterministic AES-SIV (nonce-misuse resistant)
    • Apgs: probabilistic AES-GCM-SIV
    • Apsv: probabilistic AES-SIV
  • Un-authenticated:
    • Upbc: probabilistic AES-CBC
  • Insecure (obfuscation only):
    • Zrbcx: deterministic AES-CBC with constant IV

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

§The ObtextCodec Trait

All types (Ob, AasvC32, ApsvB64, 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 aasv = AasvC32::new(&key)?;
let ob = Ob::new("aasv.c32", &key)?;

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

The ObtextCodec trait is automatically imported via the prelude.

Modules§

prelude
Convenience prelude for common imports.

Structs§

AagsB32
ObtextCodec implementation for aags. b32 format.
AagsB64
ObtextCodec implementation for aags.b64 format.
AagsC32
ObtextCodec implementation for aags. c32 format.
AagsHex
ObtextCodec implementation for aags.hex format.
AasvB32
ObtextCodec implementation for aasv.b32 format.
AasvB64
ObtextCodec implementation for aasv.b64 format.
AasvC32
ObtextCodec implementation for aasv.c32 format.
AasvHex
ObtextCodec implementation for aasv.hex format.
ApgsB32
ObtextCodec implementation for apgs.b32 format.
ApgsB64
ObtextCodec implementation for apgs.b64 format.
ApgsC32
ObtextCodec implementation for apgs.c32 format.
ApgsHex
ObtextCodec implementation for apgs.hex format.
ApsvB32
ObtextCodec implementation for apsv.b32 format.
ApsvB64
ObtextCodec implementation for apsv.b64 format.
ApsvC32
ObtextCodec implementation for apsv.c32 format.
ApsvHex
ObtextCodec implementation for apsv.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 implementation that takes format on enc operation and autodetects on dec operation. Unlike all other implementations (Ob, ZrbcxC32, .. .) it does not have a format stored internally.
UpbcB32
ObtextCodec implementation for upbc.b32 format.
UpbcB64
ObtextCodec implementation for upbc.b64 format.
UpbcC32
ObtextCodec implementation for upbc.c32 format.
UpbcHex
ObtextCodec implementation for upbc.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§

AAGS_B32
AAGS_B64
AAGS_B32_STR
AAGS_B64_STR
AAGS_C32
AAGS_C32_STR
AAGS_HEX
AAGS_HEX_STR
AASV_B32
AASV_B64
AASV_B32_STR
AASV_B64_STR
AASV_C32
AASV_C32_STR
AASV_HEX
AASV_HEX_STR
APGS_B32
APGS_B64
APGS_B32_STR
APGS_B64_STR
APGS_C32
APGS_C32_STR
APGS_HEX
APGS_HEX_STR
APSV_B32
APSV_B64
APSV_B32_STR
APSV_B64_STR
APSV_C32
APSV_C32_STR
APSV_HEX
APSV_HEX_STR
UPBC_B32
UPBC_B64
UPBC_B32_STR
UPBC_B64_STR
UPBC_C32
UPBC_C32_STR
UPBC_HEX
UPBC_HEX_STR

Traits§

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

Functions§

generate_key
Generate a cryptographically secure random 64-byte key and return it as a base64 string.
generate_secret
Generate a random 32-byte secret and return it as a base64 string.
new
Create an encoder from a format string and base64 key.
new_with_format
Create an encoder from a pre-parsed Format and base64 key.