Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

9.5 KB
Raw Blame
//! Ed25519 account signing keys, which let a client check what another client published.

use ed25519_dalek::{Signature, Signer, SigningKey, VerifyingKey, PUBLIC_KEY_LENGTH, SECRET_KEY_LENGTH, SIGNATURE_LENGTH};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use std::fmt;
use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};

use crate::common::encoding::{base64_decode, base64_encode};
use crate::common::error::{VaultError, VaultResult};
use crate::common::rng::fill_random;
use crate::crypto::aad::normalize;

/// The label of a user's signature over their own account encryption public key (the RSA JWK).
pub const ACCOUNT_PUBLIC_KEY_LABEL: &str = "aliasvault/v1/sig/account-public-key";

/// The label of a grant: a manifest's VEK encrypted for one recipient key, signed by whoever handed it out.
pub const GRANT_LABEL: &str = "aliasvault/v1/sig/grant";

/// The label of a manifest's mail delivery public key, signed by whoever published it.
pub const DELIVERY_KEY_LABEL: &str = "aliasvault/v1/sig/delivery-key";

/// The label of the vault name an invitation carries, signed by the inviter.
pub const INVITATION_NAME_LABEL: &str = "aliasvault/v1/sig/invitation-name";

/// The label of moving an email alias to another manifest, signed by the user who moves it.
pub const EMAIL_CLAIM_TRANSFER_LABEL: &str = "aliasvault/v1/sig/email-claim-transfer";

/// The label of a Login with Mobile approval: the Account Key encrypted for the requesting client, signed by the approving user.
pub const MOBILE_LOGIN_APPROVAL_LABEL: &str = "aliasvault/v1/sig/mobile-login-approval";

/// The label of a key certification: one user vouching that a signing public key belongs to another user, after checking
/// its fingerprint against the account fingerprint that user gave them outside AliasVault.
pub const KEY_CERTIFICATION_LABEL: &str = "aliasvault/v1/sig/key-certification";

/// The label under which a signing public key is hashed into its fingerprint.
pub const FINGERPRINT_LABEL: &str = "aliasvault/v1/signing-key-fingerprint";

/// The decimal digits in a fingerprint, shown in groups of [`FINGERPRINT_GROUP_DIGITS`].
pub const FINGERPRINT_DIGITS: u32 = 20;

/// The digits per group of a fingerprint.
pub const FINGERPRINT_GROUP_DIGITS: usize = 4;

/// A new signing keypair, both halves base64: the 32-byte public key and the 32-byte private seed.
#[derive(Clone, Serialize, Deserialize, Zeroize, ZeroizeOnDrop)]
#[serde(rename_all = "camelCase")]
pub struct SigningKeyPair {
    pub public_key: String,
    pub private_key: String,
}

impl fmt::Debug for SigningKeyPair {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("SigningKeyPair").field("public_key", &self.public_key).field("private_key", &"<redacted>").finish()
    }
}

/// Generate a new Ed25519 signing keypair.
pub fn generate_signing_key_pair() -> SigningKeyPair {
    let mut seed = Zeroizing::new([0u8; SECRET_KEY_LENGTH]);
    fill_random(&mut seed[..]);
    let signing_key = SigningKey::from_bytes(&seed);
    SigningKeyPair { public_key: base64_encode(signing_key.verifying_key().as_bytes()), private_key: base64_encode(&seed[..]) }
}

/// The bytes a signature covers: the label and each field, each prefixed with its length as a big-endian u32.
pub fn signed_message(label: &str, fields: &[&[u8]]) -> Vec<u8> {
    let mut out = Vec::with_capacity(4 + label.len() + fields.iter().map(|f| 4 + f.len()).sum::<usize>());
    for part in std::iter::once(label.as_bytes()).chain(fields.iter().copied()) {
        out.extend_from_slice(&(part.len() as u32).to_be_bytes());
        out.extend_from_slice(part);
    }
    out
}

/// The signed message of an account's own encryption public key (JWK).
pub fn account_public_key_message(account_public_key: &str) -> Vec<u8> {
    signed_message(ACCOUNT_PUBLIC_KEY_LABEL, &[account_public_key.as_bytes()])
}

/// The signed message of a grant: version `key_version` of the manifest's VEK, encrypted for `recipient_public_key` (JWK,
/// as the server stores it) and handed out by `signer_user_id`.
pub fn grant_message(manifest_id: &str, key_version: i64, signer_user_id: &str, recipient_public_key: &str, algorithm: &str, encrypted_vek: &str) -> Vec<u8> {
    let manifest_id = normalize(manifest_id);
    let key_version = key_version.to_string();
    signed_message(GRANT_LABEL, &[manifest_id.as_bytes(), key_version.as_bytes(), signer_user_id.as_bytes(), recipient_public_key.as_bytes(), algorithm.as_bytes(), encrypted_vek.as_bytes()])
}

/// The signed message of the vault name an invitation carries, encrypted for `recipient_public_key`.
pub fn invitation_name_message(manifest_id: &str, signer_user_id: &str, recipient_public_key: &str, encrypted_name: &str) -> Vec<u8> {
    signed_message(INVITATION_NAME_LABEL, &[normalize(manifest_id).as_bytes(), signer_user_id.as_bytes(), recipient_public_key.as_bytes(), encrypted_name.as_bytes()])
}

/// The signed message of a delivery key publish, bound to the revision the write is based on so it cannot be replayed.
pub fn delivery_key_message(manifest_id: &str, public_key: &str, current_revision: i64) -> Vec<u8> {
    signed_message(DELIVERY_KEY_LABEL, &[normalize(manifest_id).as_bytes(), public_key.as_bytes(), current_revision.to_string().as_bytes()])
}

/// The signed message of moving `address` from `source_manifest_id` to `target_manifest_id`, bound to the claim version
/// the server reported so it cannot be replayed after the claim changed.
pub fn email_claim_transfer_message(address: &str, source_manifest_id: &str, target_manifest_id: &str, claim_version: i64) -> Vec<u8> {
    let claim_version = claim_version.to_string();
    signed_message(EMAIL_CLAIM_TRANSFER_LABEL, &[address.as_bytes(), normalize(source_manifest_id).as_bytes(), normalize(target_manifest_id).as_bytes(), claim_version.as_bytes()])
}

/// The signed message of approving Login with Mobile request `request_id` with `encrypted_account_key`.
pub fn mobile_login_approval_message(request_id: &str, algorithm: &str, encrypted_account_key: &str) -> Vec<u8> {
    signed_message(MOBILE_LOGIN_APPROVAL_LABEL, &[request_id.as_bytes(), algorithm.as_bytes(), encrypted_account_key.as_bytes()])
}

/// The signed message of a key certification: `certifier_user_id` vouches that `subject_signing_public_key` belongs to `subject_user_id`.
pub fn key_certification_message(certifier_user_id: &str, subject_user_id: &str, subject_signing_public_key: &str) -> Vec<u8> {
    signed_message(KEY_CERTIFICATION_LABEL, &[certifier_user_id.as_bytes(), subject_user_id.as_bytes(), subject_signing_public_key.as_bytes()])
}

/// Sign a message with a base64 private seed. Returns the base64 signature.
pub fn sign(private_key_base64: &str, message: &[u8]) -> VaultResult<String> {
    Ok(base64_encode(&signing_key(private_key_base64)?.sign(message).to_bytes()))
}

/// Whether a base64 signature over a message verifies under a base64 public key. Uses strict verification, which
/// refuses weak public keys and non-canonical signatures.
pub fn verify(public_key_base64: &str, message: &[u8], signature_base64: &str) -> bool {
    let (Ok(public_key), Ok(signature)) = (verifying_key(public_key_base64), base64_decode(signature_base64)) else { return false };
    let Ok(signature) = <[u8; SIGNATURE_LENGTH]>::try_from(signature.as_slice()) else { return false };
    public_key.verify_strict(message, &Signature::from_bytes(&signature)).is_ok()
}

/// The base64 public key of a base64 private seed.
pub fn signing_public_key_of(private_key_base64: &str) -> VaultResult<String> {
    Ok(base64_encode(signing_key(private_key_base64)?.verifying_key().as_bytes()))
}

/// The fingerprint of a base64 signing public key: [`FINGERPRINT_DIGITS`] decimal digits in groups of four (`1234-5678-...`),
/// taken from the SHA-256 of the key under [`FINGERPRINT_LABEL`]. Two users compare it outside AliasVault to check that
/// the server handed each of them the other's real key. This is the user's account fingerprint.
pub fn fingerprint(public_key_base64: &str) -> VaultResult<String> {
    let key = verifying_key(public_key_base64)?;
    let digest = Sha256::digest(signed_message(FINGERPRINT_LABEL, &[key.as_bytes()]));
    let mut leading = [0u8; 16];
    leading.copy_from_slice(&digest[..16]);
    let digits = format!("{:0width$}", u128::from_be_bytes(leading) % 10u128.pow(FINGERPRINT_DIGITS), width = FINGERPRINT_DIGITS as usize);
    Ok(digits.chars().collect::<Vec<_>>().chunks(FINGERPRINT_GROUP_DIGITS).map(|group| group.iter().collect::<String>()).collect::<Vec<_>>().join("-"))
}

/// Whether a fingerprint a user typed is the fingerprint of a signing public key. Only the digits count, so spaces and dashes may differ.
pub fn fingerprint_matches(public_key_base64: &str, code: &str) -> bool {
    let typed: String = code.chars().filter(char::is_ascii_digit).collect();
    fingerprint(public_key_base64).is_ok_and(|expected| expected.chars().filter(char::is_ascii_digit).collect::<String>() == typed)
}

fn signing_key(private_key_base64: &str) -> VaultResult<SigningKey> {
    let seed = Zeroizing::new(base64_decode(private_key_base64)?);
    let seed: &[u8; SECRET_KEY_LENGTH] = seed.as_slice().try_into().map_err(|_| VaultError::General(format!("Signing private key must be {} bytes", SECRET_KEY_LENGTH)))?;
    Ok(SigningKey::from_bytes(seed))
}

fn verifying_key(public_key_base64: &str) -> VaultResult<VerifyingKey> {
    let bytes = base64_decode(public_key_base64)?;
    let bytes: [u8; PUBLIC_KEY_LENGTH] = bytes.as_slice().try_into().map_err(|_| VaultError::General(format!("Signing public key must be {} bytes", PUBLIC_KEY_LENGTH)))?;
    VerifyingKey::from_bytes(&bytes).map_err(|e| VaultError::General(format!("Invalid signing public key: {}", e)))
}