During account creation, the client will construct a keyring that will facilitate the cryptography. Simply put, the account’s keyring will be encrypted in various ways that ultimately can only be decrypted by knowing the password of the account.
The procedure is based on https://eprint.iacr.org/2015/387.pdf
The first step prepares some cryptographical data for initial authentication. The user will enter their email address and password. The email will be sent to the server as registration data.
The client shall generate the master-key of 32 bytes with a CSPRNG.
The client shall generate a client-salt-input value of 16 bytes with a CSPRNG. This will be sent as registration data.
The salt shall be processed. This will facilitate hiding registered emails from snooping and also helps to prevent timing attacks. The salt is a secure cryptographic hash made of the client-salt-input padded to a constant length. This step is executed by the client for registration only. Later, the server will pad the client-salt-input with extra values deterministically to hide unregistered email addresses.
The processed salt and the password is derived into two keys using a KDF designed for use with passwords.
One of the keys is the authentication-key. Here this will be hashed and sent to the server as registration data.
The other key is the encryption-key. This will be used to encrypt the master-key before sending it as registration data.
The server will send out a confirmation email in which an URL with a register-token must be followed to continue. By this process the user proves access to the email address and their knowledge of the register process independently of each other. The correctness of the cryptographic primitives created in the first step is also checked.
The user will enter the email address once again, which will be sent to the server along with the register-token.
The server will respond with a processed-salt when the email is correct for the register-token.
The user will enter the password once again. Using the processed salt, the password derivation will take place.
The client shall submit the authentication-key, email and register-token to the server. The server will respond with the encrypted-master-key upon correct inputs.
The client will use the encryption-key to decrypt the master-key.
The client shall generate their asymmetric keys for the keyring. These are an Ed25519 and a Curve25519. The secret parts of these key-pairs shall be encrypted using the master-key.
The Ed25519 public key will be the trust-root of the account, so we sign the Curve25519 public key with it.
The client will send the authentication-key, email, register-token, encrypted secret keys and public keys of the asymmetric key-pairs and the signature of the Curve25519 to the server. The server will respond with a cryptographic challenge to ensure all constructs and the client operates in good faith and correctly.
The client will process the challenge:
Using the public Curve25519 key from the challenge, create a shared-secret using their own secret Curve25519 key. This will prove to the server that the client can decrypt and use their Curve25519 key-pair properly.
Decrypt the challenge payload using a HKDF derived key from the shared secret. This will prove to the server that the client is capable of key derivation and using a symmetric cipher.
Finally it will sign the decrypted challenge payload with their secret Ed25519 key. This will prove to the server that the client can decrypt and use their Ed25519 key-pair properly.
The challenge response must arrive in 90 seconds to the server for it to be accepted, where its signature will be validated.
The user will enter their email address and password.
The email address will be sent to the server.
The server will respond with a processed-salt. It will return fake salts for incorrect inputs, preventing the detection of actually registered email addresses.
Using the processed salt, the password derivation will take place.
The client shall generate two session-encryption-keys of 16 bytes each with a CSPRNG.
The client shall submit the authentication-key, email and one of the session-encryption-keys to the server. The server will respond with the encrypted-master-key, encrypted-ed2559-secret-key, encrypted-curve25519-secret-key, an encrypted-session-key and a server-public-key upon correct inputs. When the request fails the client is unable to tell if the email, the password or both were incorrect for the login attempt.
The client will use the encryption-key to decrypt the master-key.
The client will use the master-key to decrypt the ed2559-secret-key and curve2559-secret-key.
The client is now able to create their account’s keyring from the decrypted keys.
Using the account’s curve25519 secret key and the server-public-key, the encrypted-session-key will be decrypted by using a HKDF on the shared-secret.
The session-key shall be set as a cookie for authentication of the client session. NOTE: an additional “httpOnly” cookie is also set by the server response for security.
The secret keys of the keyring shall be encrypted using a HKDF key from the session-encryption-keys. The encrypted keys and the session-encryption-key that was not sent to the server will be stored in the local storage. The secret keys of the account will only ever be stored encrypted by the session’s unique keys generated by the client. By using remote session destruction an offline client may be prevented to recover the encrypted account keys, because the half of the session-encryption-keys that is stored by the server will become unavailable.
The user opens up a new browser tab or they logged in with “remember me” and start the browser.
The client will look for the cookies and keys to be present. If they are missing then no session-resume may happen.
The client shall ask the server for the missing session-encryption-key. The server will validate the client session and return the key if it is still alive.
Using the two session-encryption-keys the same HKDF can take place as at the end of login, which will allow the client to decrypt the master-key, ed2559-secret-key and curve2559-secret-key from local storage and re-create their keyring.
Account keyring summary¶
The master-key of the account is encrypted by the encryption-key derived from the user’s password. The master-key is used to secure all data that is exclusively used by the account: other account-private keys, workspace data, configs, administrative requests to a Nano, etc.
The private half of the Curve25519 keypair is encrypted by the master-key. This facilitates secure communication between two accounts using ECDH shared-secret generation for chat messages, sharing secret keys with each other, member requests to a Nano, etc.
The private half of the Ed25519 keypair is encrypted by the master-key. This facilitates identity checking and authenticity guarantees by digital signatures.
An account’s password is the the base of the initial key for decrypting an account’s keyring. Loosing the password may render the account permanently inaccessible. The keyring cryptography is designed to provide confidentiality for the user, even against the service providing server. Unlike for traditional systems, the support can’t help with restoring accounts that can’t recall their password.
Specifically, because loosing the password carries such grave danger, an account may reset their password without providing their current one from any active session they have. The password change is always protected by two factor authentication. A malicious person can’t lock the owner out of their account using a logged in session, without also gaining access to the owner’s emails for example. The Nano client also has the password reset feature to help an owner regain control over their account.
In the case when an account has no active sessions and the password is lost, the only way to regain access is by using a previously saved recovery-key. The recovery-key of the account is actually their unencrypted master-key. It is highly recommended for the user to save it, but the security risk in case of inappropriate storage must also be emphasized. Using the recovery-key, it is possible to gain access to all data stored for the account or transferred by their Nanos if the server colludes with the attacker. For many users, printing the key and not storing it digitally could be ideal. A malicious person that gains access to a recovery-key can’t hijack the owner’s account solely by that. They’d also need to know the account’s email address and gain access to the owner’s emails to pass two factor authentication.
In any case, the user is responsible for maintaining secure access to their account by either not forgetting their password, or keeping their recovery-key safe.
Account and session security notes¶
all keys and the password KDF input-salt are exclusively generated by the client, without input from the servers
the password and the encryption-key derived from it never leave the user’s machine and they are never stored by the client
no account-key is placed in permanent storage without encryption
the session-encryption-keys facilitate remote session destruction while keeping the account keys secure
the session authentication of the client is protected against XSS stealing, because of a second “httpOnly” cookie
the webapp is protected from XSS in general using a strict CSP
all encryption use authenticated encryption, meaning they are all tamper resistant
all encryption use a HKDF derived key of 64 bytes in AES-SIV (see AES-SIV for details)