aerogramme/doc/src/crypt-key.md

Cryptography & key management

Keys that are used:

• master secret key (for indexes)
• curve25519 public/private key pair (for incoming mail)

Keys that are stored in K2V under PK keys:

• public: the public curve25519 key (plain text)
• salt: the 32-byte salt S used to calculate digests that index keys below
• if a password is used, password:<truncated(128bit) argon2 digest of password using salt S>:
  • a 32-byte salt Skey
  • followed a secret box
  • that is encrypted with a strong argon2 digest of the password (using the salt Skey) and a user secret (see below)
  • that contains the master secret key and the curve25519 private key

User secret: an additionnal secret that is added to the password when deriving the encryption key for the secret box. This additionnal secret should not be stored in K2V/S3, so that just knowing a user's password isn't enough to be able to decrypt their mailbox (supposing the attacker has a dump of their K2V/S3 bucket). This user secret should typically be stored in the LDAP database or just in the configuration file when using the static login provider.

Operations:

• Initialize(user_secret, password):

  • if "salt" or "public" already exist, BAIL
  • generate salt S (32 random bytes)
  • generate public, private (curve25519 keypair)
  • generate master (secretbox secret key)
  • calculate digest = argon2_S(password)
  • generate salt Skey (32 random bytes)
  • calculate key = argon2_Skey(user_secret + password)
  • serialize box_contents = (private, master)
  • seal box blob = seal_key(box_contents)
  • write S at "salt"
  • write concat(Skey, blob) at "password:{hex(digest[..16])}"
  • write public at "public"

• InitializeWithoutPassword(private, master):

  • if "salt" or "public" already exist, BAIL
  • generate salt S (32 random bytes)
  • write S at "salt"
  • calculate public the public key associated with private
  • write public at "public"

• Open(user_secret, password):

  • load S = read("salt")
  • calculate digest = argon2_S(password)
  • load `blob = read("password:{hex(digest[..16])}")
  • set Skey = blob[..32]
  • calculate key = argon2_Skey(user_secret + password)
  • open secret box box_contents = open_key(blob[32..])
  • retrieve master and private from box_contents
  • retrieve public = read("public")

• OpenWithoutPassword(private, master):

  • load public = read("public")
  • check that public is the correct public key associated with private

• AddPassword(user_secret, existing_password, new_password):

  • load S = read("salt")

  • calculate digest = argon2_S(existing_password)

  • load `blob = read("existing_password:{hex(digest[..16])}")

  • set Skey = blob[..32]

  • calculate key = argon2_Skey(user_secret + existing_password)

  • open secret box box_contents = open_key(blob[32..])

  • retrieve master and private from box_contents

  • calculate digest_new = argon2_S(new_password)

  • generate salt Skeynew (32 random bytes)

  • calculate key_new = argon2_Skeynew(user_secret + new_password)

  • serialize box_contents_new = (private, master)

  • seal box blob_new = seal_key_new(box_contents_new)

  • write concat(Skeynew, blob_new) at "new_password:{hex(digest_new[..16])}"

• RemovePassword(password):

  • load S = read("salt")
  • calculate digest = argon2_S(existing_password)
  • check that "password:{hex(digest[..16])}" exists
  • check that other passwords exist ?? (or not)
  • delete "password:{hex(digest[..16])}"