Pyramidion Protocol Documentation

This directory describes the cryptographic protocols Pyramidion uses, in enough detail that a reader can evaluate them without reading the source — and check the source against them if they want to.

These documents are written for people who already know what PBKDF2, AES-CTR and HMAC are, and who want to know which constructions Pyramidion chose, which parameters it uses, and what an attacker holding a stolen device or a stolen backup file actually gets. They deliberately avoid marketing language. Where a design has a real limitation, the document says so.

Pyramidion is an offline password manager. There is no Pyramidion server, no account, and no key escrow. Every guarantee below rests on that: the only thing standing between an attacker with your encrypted vault and your data is your master password and the work factor applied to it.

Documents

Planned documents are listed so the shape of the set is visible; they do not exist yet.

Notation and conventions

These hold across every document in this directory.

• || means concatenation of byte strings.
• All lengths are in bytes unless a figure is explicitly written in bits.
• Multi-byte integers are big-endian.
• base64 means standard base64 (RFC 4648 §4) with padding.
• SHA-256(x) and SHA-512(x) return raw digest bytes, not hex text. Where the implementation happens to round-trip a digest through a hex string, the document notes it, because it changes nothing about the value but does matter to anyone reimplementing the protocol.
• HMAC-SHA-256(K, m) is the MAC of message m under key K.
• ⊕ is byte-wise XOR.
• A key id is an RFC 4122 version 4 UUID in its canonical lowercase 8-4-4-4-12 text form. When a key id is hashed, it is the UTF-8 bytes of that text, hyphens included, that are hashed — not the 16 raw UUID bytes.
• Vault means one encrypted store with one root key. A device may hold several; each has independent key material.

Names used for keys

Kx/Ky exist only to protect RK. They never touch vault contents. Ka/Kb/Kc are the keys that actually encrypt, authenticate and generate.

Versioning

Each document states the app version and source revision it was written against, and carries a change log at the bottom. A protocol change that would make existing vaults unreadable is called out explicitly, because for an offline app that is not a migration — it is data loss.

Reporting a problem

If you believe you have found a flaw in one of these protocols, or a place where the code does not do what the document says, please report it privately using the contact address published in the app's Terms of Service rather than opening a public issue.