Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.
//! The account key hierarchy: the KEK encrypts the Account Key, which encrypts the Vault Encryption Key, the account
//! private key and the account signing private key. The KEK and SRP password hash are each HKDF-derived from the unlock
//! key using separate labels.
use hkdf::Hkdf;
use serde::{Deserialize, Serialize};
use sha2::Sha256;
use std::fmt;
use thiserror::Error;
use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
use super::aad;
use super::aes_gcm::{self, decrypt_text, encrypt_text, generate_key};
use super::rsa_oaep::generate_rsa_key_pair;
use super::signing::{self, generate_signing_key_pair};
use super::tokens::{ALGORITHM_AES256_GCM, ENCRYPTION_TYPE_ARGON2ID, ENCRYPTION_TYPE_ARGON2ID_HKDF};
use crate::common::encoding::{base64_decode, base64_encode, hex_encode_upper};
use crate::common::error::VaultResult;
fn account_key_encryption_algorithm() -> String {
ALGORITHM_AES256_GCM.to_string()
}
/// The encrypted halves of an account key hierarchy: what the server stores.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct AccountKeyBlobs {
pub encrypted_account_key: String,
#[serde(default = "account_key_encryption_algorithm")]
pub encrypted_account_key_algorithm: String,
pub encrypted_vek: String,
pub account_public_key: String,
pub encrypted_account_private_key: String,
pub signing_public_key: String,
pub encrypted_signing_private_key: String,
pub account_public_key_signature: String,
}
/// A newly created account key hierarchy: the encrypted blobs plus the plaintext halves the client keeps.
#[derive(Clone, Serialize, Deserialize, Zeroize, ZeroizeOnDrop)]
#[serde(rename_all = "camelCase")]
pub struct AccountKeyHierarchy {
pub account_key: String,
pub vault_encryption_key: String,
pub account_private_key: String,
pub signing_private_key: String,
#[zeroize(skip)]
pub account_keys: AccountKeyBlobs,
}
impl fmt::Debug for AccountKeyHierarchy {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("AccountKeyHierarchy").field("account_keys", &self.account_keys).finish_non_exhaustive()
}
}
/// HKDF `info` that binds the derived key to its use as the KEK; changing it breaks every stored Account Key.
const KEK_INFO: &[u8] = b"AliasVault KEK v1";
/// HKDF `info` that binds the derived key to its use as the SRP input; changing it breaks every verifier.
const SRP_INFO: &[u8] = b"AliasVault SRP v1";
/// Why an SRP password hash could not be derived.
#[derive(Error, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Error))]
#[cfg_attr(feature = "uniffi", uniffi(flat_error))]
pub enum SrpInputError {
/// The account uses an `EncryptionType` this build does not know (a newer client created it).
#[error("Unsupported encryption type: {0}")]
UnsupportedEncryptionType(String),
}
/// HKDF-SHA256 (no salt, 32 bytes) of an unlock key under one label.
fn hkdf_expand(unlock_key: &[u8], info: &[u8]) -> Zeroizing<Vec<u8>> {
let mut output = Zeroizing::new(vec![0u8; 32]);
Hkdf::<Sha256>::new(None, unlock_key).expand(info, &mut output).expect("32 bytes is a valid HKDF-SHA256 output length");
output
}
/// The KEK that encrypts the Account Key, derived from an unlock key with HKDF-SHA256 (no salt, 32 bytes).
pub fn derive_kek(unlock_key: &[u8]) -> Zeroizing<Vec<u8>> {
hkdf_expand(unlock_key, KEK_INFO)
}
/// The SRP `password_hash` (uppercase hex) an account's verifier is made from, for its `EncryptionType`.
pub fn derive_srp_password_hash(unlock_key: &[u8], encryption_type: &str) -> Result<Zeroizing<String>, SrpInputError> {
match encryption_type {
ENCRYPTION_TYPE_ARGON2ID => Ok(Zeroizing::new(hex_encode_upper(unlock_key))),
ENCRYPTION_TYPE_ARGON2ID_HKDF => Ok(Zeroizing::new(hex_encode_upper(&hkdf_expand(unlock_key, SRP_INFO)))),
other => Err(SrpInputError::UnsupportedEncryptionType(other.to_string())),
}
}
/// [`derive_kek`] over base64: the KEK as base64.
pub fn derive_kek_base64(unlock_key_base64: &str) -> VaultResult<Zeroizing<String>> {
let unlock_key = Zeroizing::new(base64_decode(unlock_key_base64)?);
Ok(Zeroizing::new(base64_encode(&derive_kek(&unlock_key))))
}
/// Encrypt the Account Key with the KEK derived from an unlock key.
pub fn encrypt_account_key(account_key_base64: &str, unlock_key_base64: &str) -> VaultResult<String> {
encrypt_key(account_key_base64, &derive_kek_base64(unlock_key_base64)?, aad::ACCOUNT_KEY)
}
/// Decrypt the Account Key with the KEK derived from an unlock key. Fails when the unlock key is not the one it was
/// encrypted for (wrong password).
pub fn decrypt_account_key(encrypted_account_key: &str, unlock_key_base64: &str) -> VaultResult<Zeroizing<String>> {
decrypt_key(encrypted_account_key, &derive_kek_base64(unlock_key_base64)?, aad::ACCOUNT_KEY)
}
/// Encrypt a base64 key with another base64 key, bound to `aad` (see [`aad`]). Returns base64 of `IV | ciphertext | tag`.
pub fn encrypt_key(key_base64: &str, with_key_base64: &str, aad: &[u8]) -> VaultResult<String> {
Ok(base64_encode(&aes_gcm::encrypt(&Zeroizing::new(base64_decode(key_base64)?), with_key_base64, aad)?))
}
/// Decrypt a key encrypted with [`encrypt_key`] bound to `aad`. Returns the key as base64.
pub fn decrypt_key(encrypted_key_base64: &str, with_key_base64: &str, aad: &[u8]) -> VaultResult<Zeroizing<String>> {
let raw = Zeroizing::new(aes_gcm::decrypt(&base64_decode(encrypted_key_base64)?, with_key_base64, aad)?);
Ok(Zeroizing::new(base64_encode(&raw[..])))
}
/// Decrypt the account private key (a JWK) with the Account Key.
pub fn open_account_private_key(encrypted_account_private_key: &str, account_key_base64: &str) -> VaultResult<Zeroizing<String>> {
decrypt_text(encrypted_account_private_key, account_key_base64, aad::ACCOUNT_PRIVATE_KEY).map(Zeroizing::new)
}
/// Decrypt the account signing private key (base64 seed) with the Account Key.
pub fn open_account_signing_private_key(encrypted_signing_private_key: &str, account_key_base64: &str) -> VaultResult<Zeroizing<String>> {
decrypt_key(encrypted_signing_private_key, account_key_base64, aad::ACCOUNT_SIGNING_PRIVATE_KEY)
}
/// The fingerprint of the account's own signing key, derived from the private key so that it never depends on the
/// public key the server reports for the account.
pub fn account_signing_key_fingerprint(encrypted_signing_private_key: &str, account_key_base64: &str) -> VaultResult<String> {
let private_key = open_account_signing_private_key(encrypted_signing_private_key, account_key_base64)?;
signing::fingerprint(&signing::signing_public_key_of(&private_key)?)
}
/// Why a key chain did not open.
#[derive(Error, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Error))]
#[cfg_attr(feature = "uniffi", uniffi(flat_error))]
pub enum KeyChainError {
/// The unlock key does not open the Account Key (wrong password).
#[error("The unlock key does not open the account key")]
UnlockKeyRejected,
/// The Account Key does not open the VEK: a stored Account Key that is not this chain's.
#[error("The account key does not open the vault encryption key")]
AccountKeyRejected,
/// The Account Key opened but the VEK does not open under it: a damaged chain, never a wrong password.
#[error("The key chain is unreadable: {0}")]
KeyChainUnreadable(String),
}
/// The keys an opened chain gives (base64, the private key as its JWK).
pub struct OpenedKeyChain {
pub vault_encryption_key: Zeroizing<String>,
/// The Account Key: what the caller stores for later unlocks.
pub account_key: Zeroizing<String>,
/// None when the account has no keypair or its private key does not open; grants then stay closed.
pub account_private_key: Option<Zeroizing<String>>,
}
/// Open a key chain with the unlock key (the password's Argon2id output): the KEK derived from it decrypts the Account
/// Key, which decrypts the VEK.
pub fn open_key_chain_with_unlock_key(unlock_key_base64: &str, encrypted_account_key: &str, encrypted_vek: &str, encrypted_account_private_key: Option<&str>) -> Result<OpenedKeyChain, KeyChainError> {
let account_key = decrypt_account_key(encrypted_account_key, unlock_key_base64).map_err(|_| KeyChainError::UnlockKeyRejected)?;
let vault_encryption_key = decrypt_key(encrypted_vek, &account_key, aad::PERSONAL_VEK).map_err(|e| KeyChainError::KeyChainUnreadable(e.to_string()))?;
let account_private_key = open_optional_account_private_key(encrypted_account_private_key, &account_key);
Ok(OpenedKeyChain { vault_encryption_key, account_key, account_private_key })
}
/// Open a key chain with the Account Key, as a device unlock method or an unlocked session holds it.
pub fn open_key_chain_with_account_key(account_key_base64: &str, encrypted_vek: &str, encrypted_account_private_key: Option<&str>) -> Result<OpenedKeyChain, KeyChainError> {
let vault_encryption_key = decrypt_key(encrypted_vek, account_key_base64, aad::PERSONAL_VEK).map_err(|_| KeyChainError::AccountKeyRejected)?;
let account_private_key = open_optional_account_private_key(encrypted_account_private_key, account_key_base64);
Ok(OpenedKeyChain { vault_encryption_key, account_key: Zeroizing::new(account_key_base64.to_string()), account_private_key })
}
/// The account private key when the chain carries one that opens.
fn open_optional_account_private_key(encrypted_account_private_key: Option<&str>, account_key_base64: &str) -> Option<Zeroizing<String>> {
encrypted_account_private_key.filter(|e| !e.is_empty()).and_then(|e| open_account_private_key(e, account_key_base64).ok())
}
/// Create a new Account Key, VEK, account keypair and signing keypair, with the Account Key encrypted under the KEK of
/// `unlock_key_base64`.
pub fn create_account_key_hierarchy(unlock_key_base64: &str) -> VaultResult<AccountKeyHierarchy> {
let key_pair = generate_rsa_key_pair()?;
let vault_encryption_key = generate_key();
let account_key = generate_key();
let signing_key_pair = generate_signing_key_pair();
let account_public_key_message = signing::account_public_key_message(&key_pair.public_key);
let account_keys = AccountKeyBlobs {
encrypted_account_key: encrypt_account_key(&account_key, unlock_key_base64)?,
encrypted_account_key_algorithm: account_key_encryption_algorithm(),
encrypted_vek: encrypt_key(&vault_encryption_key, &account_key, aad::PERSONAL_VEK)?,
account_public_key: key_pair.public_key.clone(),
encrypted_account_private_key: encrypt_text(&key_pair.private_key, &account_key, aad::ACCOUNT_PRIVATE_KEY)?,
signing_public_key: signing_key_pair.public_key.clone(),
encrypted_signing_private_key: encrypt_key(&signing_key_pair.private_key, &account_key, aad::ACCOUNT_SIGNING_PRIVATE_KEY)?,
account_public_key_signature: signing::sign(&signing_key_pair.private_key, &account_public_key_message)?,
};
Ok(AccountKeyHierarchy { account_key: account_key.to_string(), vault_encryption_key: vault_encryption_key.to_string(), account_private_key: key_pair.private_key.clone(), signing_private_key: signing_key_pair.private_key.clone(), account_keys })
}
/// The Account Key re-encrypted for a new password.
#[derive(Serialize, Zeroize, ZeroizeOnDrop)]
#[serde(rename_all = "camelCase")]
pub struct ReencryptedAccountKey {
pub account_key: String,
#[zeroize(skip)]
pub new_encrypted_account_key: String,
}
/// Re-encrypt the Account Key under the KEK of a new unlock key (password change).
pub fn reencrypt_account_key(encrypted_account_key: &str, old_unlock_key_base64: &str, new_unlock_key_base64: &str) -> Result<ReencryptedAccountKey, KeyChainError> {
let account_key = decrypt_account_key(encrypted_account_key, old_unlock_key_base64).map_err(|_| KeyChainError::UnlockKeyRejected)?;
let new_encrypted_account_key = encrypt_account_key(&account_key, new_unlock_key_base64).map_err(|e| KeyChainError::KeyChainUnreadable(e.to_string()))?;
Ok(ReencryptedAccountKey { account_key: account_key.to_string(), new_encrypted_account_key })
}