oboron 0.3.0

Encryption and encoding library for developer ergonomics: prefix entropy, compact outputs, high performance
Documentation

Oboron

Crates.io Documentation License: MIT MSRV

Oboron is a general-purpose encryption library focused on developer ergonomics:

  • String in, string out: Encryption and encoding are bundled into one seamless process
  • Standardized interface: Multiple encryption algorithms accessible through the same API
  • Unified key management: A single 512-bit key works across all schemes with internal extraction to algorithm-specific keys
  • Prefix-focused entropy: Maximizes entropy in initial characters for referenceable short prefixes (similar to Git commit hashes)

In essence, Oboron provides an accessible interface over established cryptographic primitives—implementing AES-CBC, AES-GCM-SIV, and AES-SIV— with careful attention to output characteristics. By reversing ciphertext in select schemes, entropy is concentrated in the output's prefix, enabling short, unique references.

Key Advantages:

  • Referenceable prefixes: High initial entropy enables Git-like short IDs
  • Simplified workflow: No manual encoding/decoding between encryption stages
  • Performance optimized for short-string use cases
  • Compact outputs

Contents

Quick Start

Add to your Cargo.toml:

[dependencies]
oboron = "1.0" # default features
# or with minimal features:
# oboron = { version = "1.0", features = ["ob32", "ob32p"] }

Generate your 512-bit key (86 base64 characters) using the keygen script (always included with the crate, not feature-gated):

cargo run --bin keygen

or in your code:

let key = oboron::generate_key();

then save the key as an environment variable.

Use Ob32 (a secure scheme, 256-bit encrypted with AES-SIV, encoded using Crockford's base32 variant) for enc/dec:

use oboron::{Ob32, Oboron};

let key = env::var("OBORON_KEY")?;  // get the key

let ob = Ob32::new(&key)?;          // create Oboron instance

let ot = ob.enc("Hello World")?;    // encrypt+encode
let pt2 = ob.dec(&ot)?;             // decode+decrypt

println!("obtext: {}", ot);  // e.g., "uf2glao2xd7fnbq5..."
assert_eq!(pt2, "Hello World");

Formats

Oboron encoding is a multi-stage process:

  1. Encryption: Plaintext UTF-8 string encrypted to ciphertext bytes
  2. Byte Reversal (select schemes only): Ciphertext bytes are reversed to maximize entropy in output prefixes
  3. Scheme byte: A byte identifying the encryption scheme is appended (enabling scheme auto-detection on decoding)
  4. Encoding: The binary payload is encoded to a string

The encryption stage is implemented using standard cryptographic algorithms, each variant termed an Oboron scheme. The encoding stage offers several supported string encodings. A combination of a scheme and encoding is referred to as an Oboron format. Given an encryption key, the format thus uniquely specifies the complete transformation from a plaintext string to an encoded "obtext" string. Formats are represented by compact identifiers: {scheme}:{encoding}, for example:

  • ob01:c32 - ob01 scheme, Crockford base32 encoding
  • ob21p:b32 - ob21p scheme, standard RFC 4648 base32 encoding
  • ob31:hex - ob31 scheme, hex encoding
  • ob32p:b64 - ob32p scheme (p=probabilistic), base64 encoding

A format thus defines the complete transformation, specifying not just the output encoding but also the encryption algorithm and payload byte arrangement.

API Note: The public interface uses enc/dec names for methods and functions. Thus the enc operation comprises the full process, including the encryption and encoding stages.

Encodings

  • base32crockford (default): Balanced compactness and readability, alphanumeric, lowercase; designed to avoid accidental obscenity
  • base32rfc: Balanced compactness and readability, alphanumeric, uppercase; standard base32 (RFC 4648 Section 6)
  • base64: Most compact, case-sensitive, includes - and \_ characters; standard URL-safe base64 (RFC 4648 Section 5)
  • hexadecimal: Slightly faster performance (~2-3%), longest output

FAQ: Why does Oboron use Crockford's base32?

Crockford's base32 alphabet minimizes the probability of accidental obscenity words. Whereas accidental obscenity is not an issue when working with full encrypted outputs (as any such words would be buried as substrings of a 28+ character long obtext), it does become a concern when using short prefixes. While the hexadecimal encoding is safe in this regard, the standard base32 is not.

Even though Crockford's base32 encoding is recommended, the standard base32 encoding (RFC 4648) is also fully supported (*:b32 formats), just like base64url (*:b64) and hex (*:hex).

Schemes

A scheme defines the encryption algorithm and its properties (deterministic vs. probabilistic, authenticated).

Scheme Tiers

Schemes are classified into tiers:

  • ob0x - insecure, non-authenticated
  • ob1x - insecure, authenticated
  • ob2x - secure, non-authenticated
  • ob3x - secure, authenticated

Note: The ob1x tier (insecure, authenticated) currently has no implementations. It is reserved for potential future additions, maintaining the pattern: even scheme tiers = non-authenticated; odd = authenticated.

Scheme Algorithm Deterministic? Authenticated? Notes
ob01 AES-CBC Yes No Legacy; uses constant IV. Prioritizes determinism and performance over security.
ob21p AES-CBC No No
ob31 AES-GCM-SIV Yes Yes
ob31p AES-GCM-SIV No Yes
ob32 AES-SIV Yes Yes
ob32p AES-SIV No Yes

Key Concepts:

  • Deterministic: Same input (key + plaintext) always produces same output. Useful for idempotent operations, lookup keys, caching, or hash-like references.
  • Probabilistic (p suffix): Incorporates a random nonce, producing different ciphertexts for identical plaintexts. Standard for most cryptographic use cases.
  • Authenticated: Ciphertext is tamper-proof. Any modification results in decryption failure.

Important Scheme Security Notes

All schemes use well-regarded cryptographic primitives. However, note the following:

  • ob01 and ob21p are not authenticated and vulnerable to tampering.
  • SECURITY WARNING: ob01 is cryptographically broken due to its use of a constant IV (by design, in order to achieve deterministic output). This scheme leaks equality and prefix structure and is vulnerable to chosen-plaintext attacks.
    Do not use ob01 for encrypting sensitive data or any application where confidentiality or integrity matters. Use ob01 only for maximum compactness and strong prefix entropy in non-security-critical contexts (e.g., development or obfuscation). For sensitive data, always use authenticated schemes (ob3x tier: ob31 or ob32).

We reiterate that the first digit in the scheme is a critically important one (see Scheme Tiers above):

  • ob0x and ob1x scheme tiers should be viewed as obfuscation, not encryption.
  • For encryption applications, always use ob2x or ob3x tier schemes

FAQ: Why include an insecure scheme?

Oboron is a general purpose library whose utility and application domain extend beyond encryption. For applications such as obfuscation or hashing alternative (see Application section below), ob0x schemes are sufficient, while outperforming ob2x and ob3x schemes by 2x to 4x. In our benchmarks, ob01 shows ~40% lower latency than SHA256 for short inputs on modern x86 CPUs.

FAQ: Why use numeric identifiers (e.g., ob01) instead of algorithm names (e.g., AES-CBC)?

Oboron's main target audience is developers who are not cryptography experts, to whom algorithm names are not likely to mean much. For them, Oboron hopes to provide value by making the algorithm's main properties obvious from the tier (e.g., ob3x) and optional suffix (p = probabilistic), while relegating actual algorithm names to the documentation. Besides, each algorithm is used in two different variants: deterministic and probabilistic, so to identify a scheme one would have to speak of "deterministic AES-CBC", as opposed to "ob01", or "probabilistic AES-CBC" as opposed to "ob21p", which is a mouthful.

Secure Defaults

Oboron presets (default features) only include secure schemes. In order to use ob0x or ob1x schemes, you need to enable them explicitly in your Cargo.toml.

The same holds for the keyless feature: while it is handy for development and quick obfuscation (using a hard-coded key), this feature is not enabled by default, and must be included explicitly in your Cargo.toml.

Algorithm

Oboron combines encryption and encoding in a single operation, requiring specific terminology:

  • enc: Combines encryption and encoding stages
  • dec: Combines decoding and decryption stages
  • obtext: The output of the enc operation (encryption + encoding), distinct from cryptographic ciphertext

The cryptographic ciphertext (bytes, not string) is an internal implementation detail, not exposed in the public API.

The high-level process flow is:

enc operation:
    [plaintext] (string) -> encryption -> [ciphertext] (bytes) -> encoding -> [obtext] (string)

dec operation:
    [obtext] (string) -> decoding -> [ciphertext] (bytes) -> decryption -> [plaintext] (string)

The above diagram is conceptual; actual implementation includes scheme-specific steps like scheme byte appending and optional ciphertext reversal. With this middle-step included, the diagram becomes:

enc operation:
    [plaintext] -> encryption -> [ciphertext] -> oboron pack -> [payload] -> encoding -> [obtext] 

dec operation:
    [obtext] -> decoding -> [payload] -> oboron unpack -> [ciphertext] -> decryption -> [plaintext]

Payload Structure

The payload construction is what gives the obtext its Oboron flavor. The two goals achieved with the payload structure are:

  1. Reversing the ciphertext for schemes in which this improves the prefix entropy
  2. Including a scheme marker which allows scheme autodetection in decoding

The first step gives a transformed ciphertext:

  • [ciphertext'] = [reverse(ciphertext)] for reversed schemes (ob01, ob21p),
  • [ciphertext'] = [ciphertext] for all other schemes (no change).

The second step is achieved by appending a single byte marker to the payload prior to encoding.

  • [payload] = [ciphertext'][marker]

This marker byte is the result of an XOR operation on a constant byte identifier for the scheme (e.g., oboron::constants::OB01_BYTE = 0x02), and the first byte of the transformed ciphertext (ciphertext'[0]).

  • marker = ciphertext'[0] XOR scheme-byte

The purpose of this XOR is entropy mix-in: by using the constant scheme byte directly, all ob01 obtexts would have a constant suffix.

FAQ: Why do some schemes reverse the ciphertext, while others don't?

The reversal step in ob01 and ob21p schemes moves the final AES block to the beginning of the output, ensuring maximal entropy in the encoded prefix. Both of these schemes use AES-CBC, a block-chaining algorithm: each 16-byte block's ciphertext becomes the IV for the next. Thus, while the first ciphertext block contains only the entropy from the first plaintext block, the final block accumulates entropy from the entire message.

Padding Design

Oboron's CBC schemes use a custom padding scheme optimized for UTF-8 strings:

  • Uses 0x01 byte for padding (Unicode control character, never valid in UTF-8)
  • No padding needed when plaintext ends at block boundary
  • 5% performance improvement over PKCS#7
  • Smaller output size compared to PKCS#7

Rationale: Oboron exclusively processes UTF-8 strings, not arbitrary binary data. The 0x01 padding byte can never appear in valid UTF-8 input, ensuring unambiguous decoding. Therefore, under the UTF-8 input constraint, this padding is functionally equivalent to PKCS#7 and does not weaken security. The UTF-8 input constraint is guaranteed by the Rust type system - all enc functions and methods accept a &str, therefore passing an input that is not valid UTF-8 would not be allowed by the Rust compiler. This UTF-8 guarantee is enforced at compile time, eliminating padding ambiguity errors at runtime.

Key Management

Key Partitioning Model

Oboron uses a single 512-bit master key that is partitioned, not cryptographically derived, into algorithm-specific subkeys.

This design is intentional and prioritizes low latency for short-string encryption. No hash-based KDF (e.g., HKDF) is used, as this would increase per-operation latency by several multiples and dominate runtime for the intended workloads.

Subkeys are fixed, non-adaptive slices of the master key. With the exception of ob32 / ob32p (AES-SIV schemes), which intentionally use the full 512-bit key, subkeys do not overlap.

This implies related-key structure by construction. Oboron does not claim formal related-key security. The design assumes:

  • The master key is generated uniformly at random
  • Keys are never attacker-controlled
  • Ciphertext oracles are not mixed across schemes

Under these assumptions, related-key attacks are not considered practical for Oboron’s threat model.

The master-key is partitioned into algorithm-specific keys in the following way:

  • ob01, ob21p: use the first 16 bytes (128 bits) for AES key
  • ob01: uses the second 16 bytes for IV
  • ob31, ob31p: use the last 32 bytes (256 bits) for AES-GCM-SIV key
  • ob32, ob32p: use the full 64 bytes (512 bits) for AES-SIV key

The master key never leaves your application. Algorithm-specific keys are extracted on-the-fly and never cached or stored.

FAQ: Why use a single key across all schemes?

Oboron uses key extraction to generate algorithm-specific keys from a single master key. This approach:

  • Simplifies deployment: Store one key instead of multiple
  • Reduces errors: No risk of mismatching keys to algorithms

Key Format

The default key input format is base64. This is consistent with Oboron's strings-first API design. As any production use will typically read the key from an environment variable, this allows the string format to be directly fed into the constructor.

The base64 format was chosen for its compactness, as an 86-character base64 key is easier to handle manually (in secrets or environment variables management UI) than a 128-character hex key.

While any 512-bit key is accepted by Oboron, the keys generated with oboron::generate_key() or cargo run --bin keygen do not include any dashes or underscores, in order to ensure the keys are double-click selectable, and to avoid any human visual parsing due to underscores.

Valid Base64 Keys

Important technical detail: Not every 86-character base64 string is a valid 512-bit key. Since 512 bits requires 85.3 bytes when base64-encoded, the final character is constrained by padding requirements. For correct encoding, the last character must be one of A, Q, g, or w. Always use oboron::generate_key() to create valid keys rather than attempting to construct them manually.

While base64 keys are used in the primary interface, Oboron also provides full support for working with keys in hexadecimal or raw bytes formats via *from_bytes* and *from_hex_key* method and function variants.

Properties

Referenceable Prefixes

If you've used Git, you're already familiar with prefix entropy: you can reference commits with just the first 7 characters of their SHA1 hash (like git show a1b2c3d). This works because cryptographic hashes distribute entropy evenly across all characters.

Oboron achieves similar prefix quality through careful byte arrangement. Consider these comparisons:

Short Reference Strength:

  • Git SHA1 (7 hex chars): 28 bits of entropy
  • Oboron (6 base32 chars): 30 bits of entropy
  • Oboron (7 base32 chars): 35 bits of entropy

Collision Resistance: For a 1-in-a-million chance of two items sharing the same prefix:

  • Git 7-char prefix (28 bits): After ~38 items
  • Oboron 6-char prefix (30 bits): After ~52 items
  • Oboron 7-char prefix (35 bits): After ~262 items

(These estimates assume uniform ciphertext distribution under a fixed key.)

Practical Implications: In a system with 1,000 unique items using 7-character Oboron prefixes:

  • Collision probability: ~0.007% (1 in 14,000)
  • In a system with 10,000 items: ~0.7% (1 in 140)

This enables Git-like workflows for moderate-scale systems: database IDs, URL slugs, or commit references that are both human-friendly and cryptographically robust for everyday use cases.

Deterministic Injectivity

Comparing the prefix collision resistance in the previous section, Oboron and standard hashing algorithms were compared against each other. But when we consider the full output, then they are not on the same plane: while SHA1 and SHA256 collision probabilities are astronomically small, they are never zero, and the birthday paradox risk can become a factor in large systems even with the full hash. Oboron, on the other hand, is a symmetric encryption library, and as such it is collision free (although applying this label to an encryption library is awkward): for a fixed key and within the block-cipher domain limits, Oboron is injective (one-to-one), i.e. two different inputs can never result in the same output.

Performance Comparison

Oboron is optimized for performance with short strings, often exceeding both SHA256 and JWT performance while providing reversible encryption.

Note: As a general-purpose encryption library, Oboron is not a replacement for either JWT or SHA256. We use those two for baseline comparison, as they are both standard and highly optimized libraries. However, as we show in the Applications section below, overlaps in applications with JWT and SHA256 are possible.

Scheme 8B Encode 8B Decode Security Use Case
ob01 132 ns 126 ns Insecure Maximum speed + compactness
ob32 334 ns 364 ns Secure + Auth Balanced performance + security
JWT 550 ns 846 ns Auth only* Signature without encryption
SHA256 191 ns N/A One-way Hashing only

* Note: JWT baseline (HMAC-SHA256) provides authentication without encryption, comparable to Oboron's unimplemented ob1x tier. Despite comparing against our stronger ob3x tier (secure + authenticated), Oboron maintains performance advantages while providing full confidentiality.

More detailed benchmark results are presented in a separate document:

Performance advantages:

  • ob01 encoding is 4.1x faster than JWT with 4.5x smaller output
  • All Oboron schemes outperform JWT for both encoding and decoding
  • ob01 shows lower latency than SHA256+hex for short strings while providing reversible (cryptographically insecure) encryption

Output Length Comparison

Method Small string output length
Oboron ob01: 28 characters
Oboron ob32: 34-47 characters
Oboron ob32p: 60-72 characters
SHA256: 64 characters
JWT: 150+ characters

A more complete output length comparison is given in the Appendix.

Scheme Selection Guidelines

  • ob01: Non-security-critical applications prioritizing speed and compactness
  • ob32: General-purpose secure encryption with deterministic output and compact size
  • ob32p: Maximum privacy protection with probabilistic output (larger size due to nonce)

Choose ob01 when:

  • Performance and compactness are primary requirements (~28 chars)
  • Security requirements are minimal (obfuscation contexts)

Choose ob32 when:

  • Cryptographic security with compact output is needed (~34-47 chars)
  • Deterministic behavior is beneficial (lookup keys, caching)

Choose ob32p when:

  • Cryptographic security with maximum privacy is required (~60-72 chars)
  • Hiding plaintext relationships is critical

Feature Flags

Oboron supports optional feature flags to reduce binary size by including only necessary encryption schemes. This is especially useful for WebAssembly builds where bundle size matters.

Default: All secure production-ready schemes are enabled; ob01 is not-it has to be enabled explicitly in your application.

For details on available features, scheme groups, and optimization guidance, see README_FEATURES.md.

Quick examples:

# Minimal: only ob32 (deterministic AES-SIV)
oboron = { version = "1.0", default-features = false, features = ["ob32"] }

# All authenticated schemes (ob3x tier)
oboron = { version = "1.0", default-features = false, features = ["authenticated-schemes"] }

# All SIV schemes for WebAssembly
oboron = { version = "1.0", default-features = false, features = ["all-siv-schemes"] }

Versioning

This crate follows semantic versioning. Version 1.0 signifies a stable, production-ready API with no anticipated breaking changes.

Applications

While Oboron serves as a general-purpose encryption library with its "string in, string out" API, its combination of properties—particularly prefix entropy and compactness—enables specialized applications:

  • Git-like short IDs - High-entropy prefixes for unique references
  • URL-friendly state tokens - Encrypt web application state into compact URLs
  • No-lookup captcha systems - Server issues encrypted challenge, verifies without database lookup
  • Database ID obfuscation - Hide sequential IDs while maintaining reversibility
  • Compact authentication tokens - Efficient alternative to JWT for simple use cases where JWT may be overkill
  • General-purpose symmetric encryption - Straightforward string-based API

Comparison with Alternatives

Use Case Traditional Solution Oboron Approach
Short unique IDs UUIDv4 (36 chars) ob01:c32 (28 chars, reversible)
URL parameters JWT (150+ chars) ob32:b64 (4.5x smaller, 4x faster)
Database ID masking Hashids (not secure) Proper encryption
Simple encryption Libsodium (complex) String in, string out API

API Simplification

Oboron simplifies symmetric encryption compared to lower-level cryptographic libraries:

Before (libsodium/ring - complex, byte-oriented):

// Manual key and nonce management
let key = generic_hash::Key::generate();
let nonce = randombytes::randombytes(24);
let ciphertext = secretbox::seal(plaintext, &nonce, &key)?;

// Manual encoding required
let encoded = base64::encode(ciphertext);

After (Oboron - simplified, string-oriented):

let ob = Ob32::new(&env::var("OBORON_KEY")?);
let ot = ob.enc("Hello World")?; // "uf2glao2xd7fnbq5z53cb63ukc"

Benefits:

  • No manual hex/base64 encoding/decoding
  • Keys as base64 strings (no byte array management)
  • Built-in nonce generation where applicable
  • Consistent error handling
  • Single dependency vs multiple cryptographic crates

When Oboron is appropriate:

  • General symmetric encryption requirements
  • Need for compact, referenceable outputs
  • Simplified key management (single 512-bit key)
  • String-to-string interface preferred

When lower-level libraries may be preferable:

  • Need for specific algorithms (ChaCha20-Poly1305, etc.)
  • Streaming encryption of large files
  • Asymmetric encryption cryptography requirements
  • Specialized protocols (Signal, Noise, etc.)

Pattern Implementation Examples

Database ID Obfuscation

Before (Hashids - insecure, encoding only):

let hashids = Hashids::new("salt", 6);
let obfuscated = hashids.encode(&[123]); // "k2d3e4"

After (Oboron - encrypted, reversible, secure):

let ob = Ob32::new(&env::var("OBORON_KEY")?);
let ot = ob.enc("user:123")?; // "uf2glao2xd7f"
// Can include namespace prefixes to prevent type confusion

Advantages:

  • Encodes arbitrary strings (vs integer-only encoding)
  • Actual encryption (not just encoding)
  • Can embed metadata (e.g., "user:", "order:" prefixes, or JSON)
  • Referenceable short prefixes
  • Tamper-proof with authenticated schemes

State Tokens

Before (JWT - large, complex):

// 150+ characters, requires JWT library
let token = encode(&Header::default(), &claims, &EncodingKey)?;
// "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

After (Oboron - compact, simple):

let ob = Ob31::new(&env::var("OBORON_KEY")?);
let state = serde_json::to_string(&claims)?;
let token = ob.enc(&state)?; // ~50 characters
// "ob31:b4g9lao2xd7fnbq5z53cb63ukc"

When to prefer Oboron over JWT:

  • Simple symmetric encryption requirements
  • Compact size important (URL parameters)
  • JWT standardization not required
  • Performance considerations

When JWT may be preferable:

  • Industry-standard tokens required
  • Public/private key signatures needed
  • Complex claims with registered names

ID Generation and Hash-like Applications

Oboron provides efficient alternatives to UUIDs and SHA256 for generating unique, referenceable identifiers.

The examples in this section use ob01 and keyless features, which are not included by default as cryptographically insecure. Enable the required features explicitly in your Cargo.toml.

Approach 1: Full Oboron Output (Reversible)
let ob = Ob01::new_keyless(); // Obfuscation context
let full_id = ob.enc(format!("user:{}", user_id))?;
// "uf2glao2xd7fnbq5z53cb63ukc" (28 base32 chars, reversible)
  • Pros: Reversible (decodes to "user:123"), full Oboron functionality
  • Cons: With hardcoded key: Anyone can decode; reveals structure
  • Best for: Internal systems where reversibility is useful and structure transparency acceptable.

Alternatively, keep the payload securely encrypted by having a shared secret (env::var("OBORON_KEY")).

Approach 2: Trimmed Prefix (Hash-like, Non-reversible)
let ob = Ob01::new_keyless();
// Domain separator for multiple blocks
let full = ob.enc(format!("myapp:user:{}", user_id))?;
let short_id = &full[0..20]; // "uf2glao2xd7fnbq5z53" (28 base32 chars)
  • Pros: Non-reversible even with hardcoded key, no key management, adjustable length
  • Best for: Public-facing identifiers requiring opacity and referenceable prefixes.

Oboron for Hash-like Identifier Generation

SHA256 is the ubiquitous go-to solution for hash identifiers. However, it is not optimized for short strings. Hashing a 6-digit ID or an 10-character parameter is a very common use-case, however reaching for SHA256 in this context may have drawbacks:

  • the output is much longer than the input (always 64 hex characters)
  • cutting the output down to a short prefix requires weighing odds of the birthday paradox problem
  • performance is not optimal (optimized for large files)

Performance considerations:

  • SHA256 + hex: ~190 ns, 64 hex characters (128-bit collision resistance)
  • Oboron ob01 (one block): ~130 ns, 28 base32/34 hex chars (37% faster)
  • Oboron ob01 (two blocks): ~147 ns, 53 base32/66 hex chars (27% faster, stronger than SHA256) (Times from benchmarks run on an Intel i5 laptop.)

Collision resistance comparison:

  • 6 base32 chars (30 bits): Exceeds 7 hex chars (28 bits) for short references
  • 20 base32 chars (100 bits): Comparable to SHA1 collision resistance
  • 28 base32 chars (136 bits): Slightly stronger than SHA256's 128 bits
  • 53 base32 chars (264 bits): Substantially stronger than SHA256 Note that the consideration of Oboron's 28- and 53-bit outputs in the context of collision resistance only makes sense in a global namespace; when using a fixed key, the collision problem for full Oboron outputs disappears altogether.

Oboron advantages:

  1. Better performance - 27-37% faster than SHA256 for short strings
  2. More compact encoding - Base32 provides 5 bits per char vs hex's 4 bits
  3. Referenceable prefixes - High entropy from initial characters
  4. Tunable security - Select prefix length for specific collision resistance requirements
  5. Deterministic guarantee - Different inputs always produce different outputs

When to choose which approach:

  • Oboron (28 chars): General-purpose quasi-hashing with deterministic non-collision guarantee, and improved performance over SHA256
  • Oboron (53 chars): Stronger-than-SHA256 collision resistance (in a scenario without a fixed key)
  • Shorter prefixes (6 chars): Git-like short references

Note: Oboron provides strong collision resistance for identifier generation but is not a comprehensive replacement for cryptographic hashing in all contexts (e.g., password hashing where slow hashes are desirable).

Rust API Overview

Oboron provides multiple API styles supporting different use cases. For most production applications, compile-time format selection (option 1 below) offers the best combination of performance, type safety, and clarity.

1. Compile-time Format Selection (Recommended for Production)

Use scheme-specific types when formats are known at compile time for optimal performance and type safety:

use oboron::{Ob31pBase64, Oboron};

let key = env::var("OBORON_KEY")?;
let ob31p = Ob31pBase64::new(&key)?;

let ot = ob31p.enc("hello")?;
let pt2 = ob31p.dec(&ot)?;
assert_eq!(pt2, "hello");

Available types include all combinations of scheme variants (e.g., Ob01, Ob21p, Ob31, Ob31p, Ob32, Ob32p) with encoding specifications (Base64, Hex, Base32Rfc, or Base32Crockford), and concatenates the two in struct names, for example:

  • Ob01Base32Rfc - encoder for ob01:b32 format
  • Ob21pHex - encoder for ob21p:hex format
  • Ob31Base64 - encoder for ob31:b64 format
  • Ob32Base32Crockford = Ob32 - encoder for ob32:c32 format.

All Base32Crockford-encoding (default) variants have short aliases with no explicit encoding (defaulting to c32): Ob01, Ob21p, etc.

Note that the ob01 scheme is not included by default as cryptographically insecure. In order to use the associated structs Ob01 = Ob01Base32Crockford, Ob01Base32Rfc, Ob01Base64, or Ob01Hex, you need to enable the ob01 feature in your Cargo.toml

2. Runtime Format Selection (Ob)

When format specification at runtime is required but format changes are unnecessary, use Ob:

use oboron::{Ob, Oboron};

let key = env::var("OBORON_KEY")?;
let ob = Ob::new("ob32:b64", &key)?;

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

Format is fixed at construction, providing intermediate flexibility between compile-time selection and full mutability.

3. Mutable Runtime Format (ObFlex)

Similar to Ob but with mutable format specification:

use oboron::{ObFlex, Oboron};

let mut ob = ObFlex::new("ob31:b64", &key)?;
let ot = ob.enc("hello")?; // ob31:b64 obtext

// Format modification
ob.set_format("ob32p:hex")?;
let ot_hex = ob.enc("world")?; // ob32p:hex obtext

4. Multiple Format Support (ObMulti)

ObMulti differs in format management and provides comprehensive autodec() functionality.

Multi-Format Workflow: Designed for simultaneous work with different formats, requiring format specification in each operation:

use oboron::{ObMulti, Oboron};

let obm = ObMulti::new(&key)?;

// Format specification per operation
let ot = obm.enc("test", "ob32p:b64");
let pt2 = obm.dec(&ot, "ob32p:b64");
let pt_other = obm.dec(&other, "ob01:c32");

Autodecode: While other interfaces perform scheme autodetection in dec() methods, only ObMulti provides full format autodetection including encoding (base32rfc, base32crockford, base64, or hex). Other structs decode only encodings matching their format.

// Autodecode when format is unknown
let pt2 = obm.autodec(&ot);

Note performance implications: autodetection uses trial-and-error across encodings, with worst-case performance ~3x slower than known-format dec operations. Meanwhile, scheme autodetection in other interfaces (e.g., Ob.dec(), ObFlex.dec(), Ob32Base64.dec()) has negligible overhead as the scheme is detected based on the scheme byte in the payload, and the logic follows a direct path with no retries.

Using Format Constants

For type safety and discoverability, use the provided format constants instead of string literals:

use oboron: :{Ob, ObMulti, Oboron, OB32_B64, OB32_HEX};

let key = oboron:: generate_key();

// With Ob (runtime format selection)
let ob = Ob::new(OB32_B64, &key)?;

// With ObMulti (multi-format operations)
let obm = ObMulti::new(&key)?;
let ot_b64 = obm.enc("data", OB32_B64)?;
let ot_hex = obm.enc("data", OB32_HEX)?;

Available constants:

  • OB01_C32, OB01_B32, OB01_B64, OB01_HEX
  • OB21P_C32, OB21P_B32, OB21P_B64, OB21P_HEX
  • OB31_C32, OB31_B32, OB31_B64, OB31_HEX
  • OB31P_C32, OB31P_B32, OB31P_B64, OB31P_HEX
  • OB32_C32, OB32_B32, OB32_B64, OB32_HEX
  • OB32P_C32, OB32P_B32, OB32P_B64, OB32P_HEX
  • Testing: OB70_*, OB71_*
  • Legacy: OB00_*

Advanced: Format Objects

Format structs provide a more fine-grained type safety than format string constants:

use oboron::{Ob, Format, Scheme, Encoding};

let format = Format::new(Scheme::Ob32, Encoding::Base64);
let ob = Ob::new_with_format(format, &key)?;

Typical Production Use

For compile-time known schemes and encodings, however, static types provide optimal performance, concise syntax, and strongest type guarantees:

use oboron::{Ob32Base64, Oboron};
let ob = Ob32Base64::new(&key)?;
let ot = ob.enc("secret")?;

The format is built into the struct, no format strings, constants, or Format structs are needed.

The Oboron Trait

All types except ObMulti implement the Oboron trait, providing a consistent interface:

  • enc(plaintext: &str) -> Result<String, Error> - Encode plaintext to obtext
  • dec(obtext: &str) -> Result<String, Error> - Decode with automatic scheme detection
  • dec_strict(obtext: &str) -> Result<String, Error> - Decode only matching configured scheme (no autodetection; error if not matching)
  • scheme() -> Scheme - Current scheme
  • encoding() -> Encoding - Current encoding
  • key() -> String - Base64 key access
  • key_hex() -> String - Hex key access (gated by hex-keys feature, not enabled by default)
  • key_bytes() -> &[u8; 64] - Raw key bytes access (gated by bytes-keys feature, not enabled by default)

Working with Keys

// main interface:
let ob = Ob31Base64::new(&env::var("OBORON_KEY")?);       // base64 key
// with "hex-keys" feature enabled:
let ob = Ob31Base64::from_hex_key(&env::var("HEX_KEY")?); // hex key
// with "bytes-keys" feature enabled:
let ob = Ob31Base64::from_bytes(&key_bytes)?;             // raw bytes key
// with "keyless" feature enabled:
let ob = Ob31Base64::new_keyless()?;              // insecure/testing only

Warning: new_keyless() uses the publicly available hardcoded key providing no security. Use only for testing or obfuscation contexts where encryption is not required. The keyless feature must be enabled to use the hardcoded key.

Common Issues

  • Key errors: Ensure keys are exactly 86 base64 characters characters properly encoded from 512 bits (see note about valid base64 keys)
  • Format strings: Must match exactly, e.g., "ob32:b64" not "ob32-b64"
  • Decoding errors: Use autodec() when format is unknown

Minimum Supported Rust Version (MSRV)

This crate requires Rust 1.74.0 or later.

Compatibility

Oboron implementations maintain full cross-language compatibility:

  • Identical encryption algorithms and key management
  • Consistent encoding formats and scheme specifications
  • Interoperable encoded values across Rust, Python, and Go (latter currently under development)

All implementations must pass the common test vectors

Getting Help

License

Licensed under the MIT license (LICENSE).

Appendix: Obtext Lengths

ob70 is a non-cryptographic scheme used for testing, whose ciphertext is equal to the plaintext bytes (identity transformation). It is included in the tables below as baseline.

(Note: the ob70 scheme is feature gated: use it by enabling the ob70 feature, or the ob7x testing feature group, or the non-crypto feature group.)

Base32 encoding (b32/c32)

Scheme Encoding 4B 8B 12B 16B 24B 32B 64B 128B
ob70 b32/c32 8 15 21 28 40 53 104 207
ob01 b32/c32 28 28 28 28 53 53 104 207
ob31 b32/c32 34 40 47 53 66 79 130 232
ob32 b32/c32 34 40 47 53 66 79 130 232
ob21p b32/c32 53 53 53 53 79 79 130 232
ob31p b32/c32 53 60 66 72 85 98 149 252
ob32p b32/c32 60 66 72 79 92 104 156 258

Base64 Encoding (b64)

Scheme Encoding 4B 8B 12B 16B 24B 32B 64B 128B
ob70 b64 7 12 18 23 34 44 87 172
ob01 b64 23 23 23 23 44 44 87 172
ob31 b64 28 34 39 44 55 66 108 194
ob32 b64 28 34 39 44 55 66 108 194
ob21p b64 44 44 44 44 66 66 108 215
ob31p b64 40 50 55 60 71 82 124 210
ob32p b64 46 55 60 66 76 87 130 215

Hex Encoding (hex)

Scheme Encoding 4B 8B 12B 16B 24B 32B 64B 128B
ob70 hex 10 18 26 34 50 66 130 258
ob01 hex 34 34 34 34 66 66 130 258
ob31 hex 42 50 58 66 82 98 162 290
ob32 hex 42 50 58 66 82 98 162 290
ob21p hex 66 66 66 66 98 98 162 290
ob31p hex 66 74 82 90 106 122 186 314
ob32p hex 74 82 90 98 114 130 194 322