Glossary

Terms used throughout the OC Lock spec and docs, in alphabetic order.

AEAD

Authenticated Encryption with Associated Data. OC Lock uses AES-256-GCM with 12-byte IVs and 16-byte tags. The envelope id is bound into the ciphertext as AAD so any tamper of envelope metadata invalidates decryption.

Attestation id

The SHA-256 of a canonical OrangeCheck message, lowercase hex. Content-addressed: the same message always produces the same id.

Binding signature (binding_sig)

The BIP-322 signature over the binding statement, made by the Bitcoin address being bound. This is the load-bearing authenticity proof for every device record. Senders MUST verify binding_sig against the claimed address before encrypting — a forged record with an attacker's device_pk won't have a valid signature, and the web client rejects those records explicitly rather than silently using them.

Binding statement

The exact UTF-8 text a Bitcoin wallet signs via BIP-322 to bind an X25519 device pubkey to a Bitcoin address. See the specification §3.2 or the device keys walkthrough.

BIP-322

Bitcoin signed message format, generalized to all script types. Lets any wallet prove control of an address without revealing the private key. The wire format for OC Lock sender signatures and device binding signatures.

Chat inbox (chat pubkey)

The Schnorr/secp256k1 pubkey a Lock device subscribes to for incoming chat messages. Derived deterministically from device_sk via HKDF(device_sk, salt="oc-lock/v2/nostr-key", info="nostr-sk") — the same derivation already used to sign a device's own device record, so every registered Lock device automatically has a chat inbox with no extra onboarding.

Chat transport · gift-wrap

A Nostr kind:1059 event whose content is a base64url-encoded OC Lock envelope. Signed by an ephemeral Schnorr keypair the sender generates and discards per message. The recipient's stable chat pubkey appears as a p tag so the relay can deliver, but nothing ties the event back to the sender's real identity. Content tag: ct: oc-lock/chat/v1. Full rationale: /docs/chat.

Canonical form

The byte-exact JSON representation used to compute envelope ids and signatures. RFC 8785 JCS with one addition: recipients[] sorted by device_id.

Content key

32 random bytes. Encrypts the payload with AES-256-GCM. Wrapped per-recipient under a KEK derived from ECDH(eph_sk, device_pk).

Device key

A long-lived X25519 keypair generated per browser/device. Public half is published to Nostr; secret half lives in IndexedDB and never leaves.

Device record

A Nostr kind:30078 event announcing the binding of a device pubkey to a Bitcoin address. Identified by a d tag of the form oc-lock:device:<btc_address>.

ECDH

Elliptic Curve Diffie-Hellman. OC Lock uses X25519 per RFC 7748. Given two X25519 keypairs, produces a 32-byte shared secret that either party can derive.

Envelope

A sealed vault. A canonical JSON object containing from, recipients[], ciphertext, sig, and metadata. Self-contained — shareable through any transport.

Envelope id

SHA-256 of the canonical envelope bytes with sig.value emptied. Signed by the sender via BIP-322 and included as AAD during decryption.

Identity mode

The default sealing mode. Zero on-chain transactions; access is gated by possession of the recipient's device secret.

KEK

Key-encryption key. Derived per-recipient as HKDF(ECDH(eph_sk, device_pk), salt=nonce_ct, info="oc-lock/v2/kek:<device_id>"). Encrypts the content key.

Lock (verb)

To seal a message or file inside an OC Lock envelope.

Lock (noun) · .lock file

A single envelope serialized as canonical JSON. MIME type application/vnd.oc-lock+json. Extension .lock.

Nostr

Simple protocol for decentralized event relays. OC Lock uses Nostr as an addressable directory for device records — the relay does not need to be trusted because authenticity is proven by the embedded BIP-322 signature.

OrangeCheck

A sybil-resistance primitive — "proof of Bitcoin stake" via BIP-322. OC Lock is a sub-product of OrangeCheck; both rely on the same BIP-322 identity primitive and canonical-message discipline.

Payment mode

Opt-in sealing mode for commerce. A named relay holds the content key; releases it to a recipient upon observing a confirmed Bitcoin payment. Explicit trust anchor.

Recipient

A device a sender encrypts to. Identified by (address, device_id, device_pk). An envelope may have multiple recipients (multi-device, self-copy, group).

Relay

In OC Lock: a payment-mode custodian of wrapped content keys. In Nostr: a server that accepts and relays events.

Self-seal

A vault whose sender and recipient are the same address. Useful as a password manager or encrypted notebook.

Thread id

Deterministic identifier for a 1:1 chat conversation: sha256("oc-lock/chat/thread/v1|" + min(addrA, addrB) + "|" + max(addrA, addrB)). Both sides derive the same id without negotiation because the input is sorted.

Shared secret

The 32 bytes output by X25519(sk, pk). Used once per recipient as HKDF input material; never stored.

Vault (passphrase-encrypted secret)

A LockedDeviceVault — the at-rest wrapper for a device secret (or any 32-byte value) using PBKDF2-SHA256 at 600,000 iterations (OWASP 2023 baseline) plus AES-256-GCM. The alg identifier pbkdf2-sha256-aes256gcm/v1 versions the format; per-vault iteration counts are stored alongside the ciphertext so existing vaults remain readable after parameter bumps.

X25519

Montgomery-form elliptic curve used for ECDH. Distinct from the secp256k1 curve Bitcoin uses; chosen because it's faster, has smaller keys, and is constant-time by construction.