Oboron

String in, string out symmetric encryption

Protocol Specification version 1.0

Oboron is an authenticated symmetric encryption protocol designed around developer ergonomics. enc takes a plaintext string and returns a printable obtext string; dec reverses it. Encoding is part of the protocol, not your problem: no byte buffers, no separate base64 step, no nonce management — and the key is a hex string, read straight from an environment variable into the constructor.

The cryptography is deliberately curated, not comprehensive: four schemes — deterministic or probabilistic, each built on a misuse-resistant AEAD (AES-SIV or AES-GCM-SIV). Oboron does not compete with general-purpose libraries such as libsodium; it complements them, standardizing a task they leave as an exercise, with a scheme family (deterministic, misuse-resistant, avalanche) they deliberately don't offer.

Features

• One operation each way — enc returns printable obtext, dec returns the plaintext; encryption and encoding are one step, and you never handle raw bytes
• Env-var-ready keys — a single 512-bit master key as 128 hex characters works across all schemes; pass it to the constructor as-is — the library handles per-scheme key setup
• Curated schemes — exactly four: deterministic or probabilistic × AES-SIV or AES-GCM-SIV, all authenticated and misuse-resistant, named by property + algorithm (e.g., dsiv = deterministic + AES-SIV) so the choice is legible without deep expertise
• Avalanche output, front-loaded entropy — any plaintext change reshuffles the whole obtext, and high initial entropy enables Git-like referenceable short prefixes
• Cross-language interoperability — all implementations produce identical outputs for the same inputs, enforced by shared test vectors and a conformance suite

Quick Start

Install:

cargo add oboron

pip install oboron

go get oboron.org/go/oboron

git clone https://gitlab.com/oboron/oboron-rs
cd oboron-rs
cargo build --release -p oboron-ffi
export OBORON_FFI_LIB=$PWD/target/release/liboboron_ffi.so

Generate your 128-character hex key (512 bits):

cargo install oboron
keygen

let key = oboron::generate_key();

python -m oboron.keygen

key = oboron.generate_key()

go run oboron.org/go/cmd/keygen

key := oboron.GenerateKey()

perl -MOboron -E 'say Oboron::generate_key()'

my $key = Oboron::generate_key();

Save the key as an environment variable, then use e.g., DsivC32 — the dsiv.c32 format: a deterministic scheme using AES-256-SIV, encoded using Crockford's base32 variant — for enc/dec:

use oboron::DsivC32;

let key = env::var("OBORON_KEY")?;
let ob = DsivC32::new(&key)?;

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

println!("obtext: {}", ot);
// "obtext: cbv74r1m7a7cf8n6gzdy..."

assert_eq!(pt2, "hello, world");

import os
from oboron import DsivC32

key = os.getenv("OBORON_KEY")
ob = DsivC32(key)

ot = ob.enc("hello, world")
pt2 = ob.dec(ot)

print(f"obtext: {ot}")
# "obtext: cbv74r1m7a7cf8n6gzdy..."

assert pt2 == "hello, world"

import (
    "fmt"
    "os"

    "oboron.org/go/oboron"
)

key := os.Getenv("OBORON_KEY")
ob, _ := oboron.NewDsivC32(key)

ot, _ := ob.Enc("hello, world")
pt2, _ := ob.Dec(ot)

fmt.Printf("obtext: %s\n", ot)
// "obtext: cbv74r1m7a7cf8n6gzdy..."

// pt2 == "hello, world"

use Oboron qw(enc dec);

my $key = $ENV{OBORON_KEY};

my $ot  = enc('hello, world', 'dsiv.c32', $key);
my $pt2 = dec($ot, 'dsiv.c32', $key);

print "obtext: $ot\n";
# "obtext: cbv74r1m7a7cf8n6gzdy..."

# $pt2 eq 'hello, world'

All implementations produce identical obtext for the same key and plaintext, and use the same enc/dec API.

Applications

Oboron's combination of properties — particularly prefix entropy, compactness, and deterministic injectivity — enables specialized use cases beyond general-purpose encryption:

• 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
• Mandate tokens — via obsigil, a JWT-like token format built directly on Oboron's schemes

Comparison with Alternatives

Implementations

• Rust — reference implementation (GitLab: oboron/oboron-rs)
  • Core library: oboron crate
  • CLI: oboron-cli crate (ob binary)
• Python (GitLab: oboron/oboron-rs/oboron-py)
  • Python bindings for core library: PyPI: oboron
  • CLI: PyPI: oboron-cli
• Go (oboron.org/go module)
  • Library: oboron.org/go/oboron
  • CLI: go install oboron.org/go/cmd/ob@latest (also obcrypt, obu)
• Perl
  • Library: Oboron module — an FFI::Platypus binding over the oboron-ffi C ABI, so all cryptography is the shared Rust core (CPAN release pending)

Byte Layer (obcrypt)

obcrypt is the bytes-in/bytes-out cryptographic core beneath the string layer: the same four authenticated schemes operating on raw byte slices, with no encoding and no UTF-8 validation. For binary applications it is available as a standalone library: obcrypt (Rust, source: oboron/obcrypt-rs), obcrypt (PyPI), and oboron.org/go/obcrypt (Go).

Unauthenticated Layer (obu)

obu is Oboron's unauthenticated layer — two performance-oriented schemes over a single 256-bit secret: upcbc (confidentiality without authentication) and zdcbc (deterministic obfuscation). Neither provides integrity protection, and the layer shares no code with the authenticated core.

No integrity protection. Neither obu scheme is authenticated: upcbc gives confidentiality but is vulnerable to ciphertext tampering, and zdcbc is obfuscation only — not cryptographically secure. Do not use obu where authentication or tamper-resistance is required; use the authenticated core schemes for that.

Its formats and algorithms are defined in the obu Specification.

Specifications

The 1.0 specifications are final. Each is available in HTML and PDF.

Conformance

Oboron is specified once and verified everywhere: every implementation checks itself against the same language-agnostic test vectors, driven through a shared command-line contract.

Test Vectors

The canonical test vectors live in oboron/oboron-test-vectors — plain JSONL files with a stable schema, consumed directly by every implementation. They pin the exact obtext each scheme must produce and the inputs every implementation must reject, giving all implementations one shared ground truth.

Conformance Testing Suite

The standard suite is oboron-cli-conformance (source: oboron/oboron-tools-rs). It runs the test vectors end-to-end against an implementation's command-line binaries and reports pass/fail; implementers in any language point it at their own binaries to validate conformance.

What makes this work across languages is the CLI Specification, which defines a standardized ob command-line interface — in effect a language-neutral API. Any implementation that conforms to that contract can be driven by the same reference suite, confirming it produces identical output.

License

The Oboron specifications and the documentation on this website are licensed under CC BY 4.0; the reference implementations are dual-licensed under the MIT or Apache 2.0 licenses, at your option.