← Home ← Protocol Specification

Oboron CLI Specification

Spec version: v0 (initial)

Contents

• 1. Overview
• 2. Conventions
• 3. Binaries
• 4. Core Commands (REQUIRED)
  • 4.1 enc (alias: e)
  • 4.2 dec (alias: d)
  • 4.3 key / secret
• 5. Management Commands (OPTIONAL)
  • 5.1 init
  • 5.2 config
  • 5.3 profile
  • 5.4 completion
• 6. Key/Secret Resolution
• 7. Format Specification
• 8. Hardcoded Test Key
• 9. Test Vector Format
• 10. Exit Codes
• 11. Standard I/O Behavior

1. Overview

This document specifies the CLI interface for conforming Oboron implementations. Its purpose is to enable cross-implementation conformance testing via a shared CLI contract.

Conforming implementations provide two binaries:

• ob — The primary CLI for secure encryption. Handles a-tier schemes (aasv, aags, apsv, apgs) and the u-tier scheme (upbc). All conforming implementations MUST provide ob.
• obz — The obfuscation CLI for z-tier schemes (zrbcx, legacy). Implementations MAY choose not to support z-tier; the obz binary is OPTIONAL. If an implementation supports z-tier, the obz binary MUST conform to this specification.

The reference implementation source code is available at the GitHub repo ob-enc/oboron-rs.

For cryptographic details, format definitions, and key management, see the protocol specification.

2. Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Command Syntax Notation

• <REQUIRED> — a required argument or value
• [OPTIONAL] — an optional argument or value
• --flag — a long-form flag
• -f — a short-form flag
• --option <VALUE> — an option that takes a value

3. Binaries

ob

The ob binary is REQUIRED for all conforming implementations. It handles a-tier and u-tier encryption schemes.

obz

The obz binary is OPTIONAL. If provided, it MUST conform to this specification. It handles z-tier obfuscation schemes.

⚠️ Z-tier schemes are NOT cryptographically secure. obz is for obfuscation only and MUST NOT be used for sensitive data.

Comparison

4. Core Commands (REQUIRED)

The following commands MUST be implemented for a conforming CLI.

4.1 enc (alias: e)

Encrypt+encode a plaintext string.

ob enc [OPTIONS] [TEXT]

Flags

Behavioral Rules

• If [TEXT] is omitted, the implementation MUST read input from stdin.
• --key, --profile, and --keyless are mutually exclusive.
• --format MUST NOT be combined with individual scheme or encoding flags.
• At most one scheme flag MAY be specified.
• At most one encoding flag MAY be specified.
• Empty plaintext (empty string) MUST be rejected with a non-zero exit code.
• On success: print obtext to stdout followed by a single newline (\n), exit 0.
• On failure: print error to stderr, exit non-zero.

obz enc Variant

obz enc accepts the same flags with these differences:

• Uses --secret/-s instead of --key/-k. Note: since obz has no a-tier schemes, the -s short flag is repurposed for --secret in obz (it does not mean --aasv).
• Scheme flags are z-tier specific:

4.2 dec (alias: d)

Decode+decrypt an obtext string.

ob dec [OPTIONS] [TEXT]

Flags

Behavioral Rules

• If [TEXT] is omitted, the implementation MUST read input from stdin.
• --key, --profile, and --keyless are mutually exclusive.
• --format MUST NOT be combined with individual scheme or encoding flags.
• When no scheme flag is given, the implementation MUST auto-detect the scheme from the obtext payload (using the 2-byte scheme marker).
• Invalid obtext MUST result in a non-zero exit code.
• On success: print plaintext to stdout followed by a single newline (\n), exit 0.
• On failure: print error to stderr, exit non-zero.

4.3 key / secret (alias: k / s)

Output the encryption key (for ob) or obfuscation secret (for obz) for the active or specified profile.

ob key [OPTIONS]

obz secret [OPTIONS]

Flags

For obz, the command is secret (alias: s), and it outputs the 256-bit z-tier secret.

5. Management Commands (OPTIONAL)

The following commands are RECOMMENDED but not required for conformance.

5.1 init (alias: i)

Initialize configuration with a randomly-generated key profile.

ob init [NAME]

[NAME] defaults to default.

Behavioral Rules

• Creates ~/.ob/config.json and ~/.ob/profiles/<NAME>.json.
• config.json structure:

  {
    "profile": "<NAME>",
    "scheme": "aasv",
    "encoding": "c32"
  }

• Profile JSON structure:

  {
    "key": "<86-char base64 key>"
  }

• Existing profiles SHOULD be backed up before overwriting (to ~/.ob/bkp/).
• Profile files SHOULD be written with restrictive permissions (0o600 on Unix).

For obz:

• Config directory is ~/.obz/.
• The profile field is "secret" instead of "key".
• Default scheme is zrbcx.
• Profile JSON structure:

  {
    "secret": "<43-char base64 secret>"
  }

5.2 config (alias: c)

Manage configuration.

ob config [OPTIONS] [SUBCOMMAND]

Subcommands

config set

Accepts scheme flags, encoding flags, and --profile <NAME> to update the stored configuration.

5.3 profile (alias: p)

Manage key profiles.

ob profile <SUBCOMMAND>

Subcommands

Profile name validation: only alphanumeric characters, hyphens, and underscores are permitted.

5.4 completion

Generate shell completion scripts.

ob completion <SHELL>

6. Key/Secret Resolution

When resolving which key (or secret) to use, implementations MUST apply the following precedence order (highest to lowest):

If no key source is available, the implementation MUST exit with a non-zero exit code.

7. Format Specification

The --format flag accepts format strings of the form {scheme}.{encoding}.

Scheme Identifiers

• ob: aasv, aags, apsv, apgs, upbc
• obz: zrbcx, legacy

Encoding Identifiers

Implementations SHOULD support the named scheme flags (e.g. --aasv) as the primary interface; the --format flag provides a combined shorthand.

8. Hardcoded Test Key

For cross-implementation testing, both ob and obz support a hardcoded key via the -K/--keyless flag. Implementations MUST use these exact values to ensure test vector compatibility.

ob Master Key

Base64 (86 chars, URL-safe, no padding):

OBKEYz0C6l8134WWtcxCGDEAYEaOi0ZUVaQVF06m6Wap9I7sS6RG3fyLeFh4lTVvRadaGrdBlFTdn3qoqV291Q

Hex (128 chars):

381284633d02ea5f35df8596b5cc4218310060468e8b465455a415174ea6e966a9f48eec4ba446ddfc8b78587895356f45a75a1ab7419454dd9f7aa8a95dbdd5

obz Z-tier Secret

The z-tier secret is the first 32 bytes of the master key, encoded as base64url without padding.

Base64 (43 chars, URL-safe, no padding):

OBKEYz0C6l8134WWtcxCGDEAYEaOi0ZUVaQVF06m6WY

Bytes (hex):

38 12 84 63 3d 02 ea 5f
35 df 85 96 b5 cc 42 18
31 00 60 46 8e 8b 46 54
55 a4 15 17 4e a6 e9 66

9. Test Vector Format

Test vectors are stored as JSONL (JSON Lines) files. Each line is a JSON object with the following fields:

{
  "format": "aags.c32",
  "plaintext": "hello",
  "obtext": "..."
}

Optional fields: "description".

For legacy vectors, the first line MAY be a meta object carrying the scheme-specific secret:

{
  "type": "meta",
  "secret": "<43-char base64url secret>"
}

Test Strategy by Scheme Type

10. Exit Codes

The following error conditions MUST produce a non-zero exit code:

• Empty plaintext passed to enc
• Invalid or corrupt obtext passed to dec
• Missing key when no key source is available
• Conflicting flags (e.g. --key and --keyless together)

11. Standard I/O Behavior

• enc output: obtext string followed by a single newline (\n) on stdout.
• dec output: plaintext string followed by a single newline (\n) on stdout.
• Error messages: MUST be written to stderr.
• stdin: When [TEXT] is omitted, the implementation MUST read the full contents of stdin as input. A trailing newline from stdin SHOULD be stripped (to support echo "text" | ob enc patterns).