The keyring provides the system to store secret keys in an encrypted
format, create and delete keys, display public keys and notes for the
user, and use these keys to peform public-key authentication on servers.
Keyring is serialized into `keyring.cbor` in the application directory.
It's a CBOR map with keys being key IDs (fingerprints), and the values
are key entries, the schema of which looks like this:
key-entry {
0 => uint, ; Algorithm tag, 1 byte
1 => text, ; Comment/note for the key
2 => bytes, ; Public key (certificate), 32 bytes
3 => bytes ; Encrypted and authenticated secret key (AEAD payload)
}
Key fingerprint is `BLAKE2b-256(tag || public_key)`, where `||` denotes
concatenation of byte strings.
Encrypted payload is a fixed binary structure (field sizes in bytes):
Version(1)
Salt(16)
Opslimit(4)
Memlimit(4)
Alg(1)
Ciphertext(32)
MAC(16)
Upon key generation, a new secret key is created, sourced from a secure
RNG. The wrap key is derived from the passphrase using Argon2 with
the specified iterations, memory cost, variant (3 iterations, 1 GB of
memory, Argon2id), and 16 bytes of randomly generated unique salt. This
wrap key is used with ChaCha20-Poly1305 to encrypt the secret key, with
all the prior fields as additional authenticatied data and all-zero
nonce (the uniqueness is already provided by the salt).
The key pairs are X25519, used specifically for key exchange. When the
server sends the ephemeral public key as a challenge, the client uses
`unlock_and_auth` function with the key corresponding to the right
certificate. After entering the correct passphrase, the secret key is
decrypted and used to derive a shared secret with the server's ephemeral
key. The client then responds with:
BLAKE2b-256("Einsof-Auth-DHCR" || shared_secret || challenge
|| certificate || username)
Where the first string is provided for domain separation, shared secret
proves possession of the secret key, and other parameters are hashed in
to bind this authentication attempt to the current session (via random
challenge), identity (via public key and username), and transcript.
Note on canonicalization: all fields but last are fixed-length,
concatenation here is unambiguous.
The server, in turn, performs the same opeations, except the shared
secret is derived from the server's ephemeral secret and the client's
public key. Naturally, username and public key must be correct. If the
response matches, the server authenticates the client. The client never
transmits its secret.
This scheme is essentially deriving a session secret and computing MAC
over the transcript with that secret to prove authenticity. It serves as
a simple identification protocol. Unlike digital signatures, it's
interactive, valid only in the context of a single authentication
attempt, and only between two participants involved. Signatures, in
contrast, are valid everywhere, for everyone, and they require
additional nonces and context. In fact, they're interactive
identification protocols turned non-interactive, so forcing them back
into this setting is unnecessary complexity.
The primitives are fixed: X25519 for key exchange, Argon2 for
password-based key derivation, ChaCha20-Poly1305 for encryption, BLAKE2b
for hashing. Provided by libsodium.
Simplicity is key. There's no flexibility, negotiation, or
compatibility, and it'll hopefully stay this way. Unless you're worried
about quantum computers appearing tomorrow and attacking a niche AO
implementation, in which case I'll add the ML-KEM variant just for you.