Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.
Add VaultKeyService.cs (#2159)
Leendert de Borst373a650a99e7
diff --git a/apps/server/AliasVault.Client/Services/StorageKeys.cs b/apps/server/AliasVault.Client/Services/StorageKeys.csindex 7d0c5d5fa..70c0f7ab2 100644--- a/apps/server/AliasVault.Client/Services/StorageKeys.cs+++ b/apps/server/AliasVault.Client/Services/StorageKeys.cs@@ -62,4 +62,49 @@ public static class StorageKeys/// Key for storing the return URL to redirect to after login or unlock./// </summary>public const string ReturnUrl = "returnUrl";++ /// <summary>+ /// Key for storing the Account Key encrypted with the password-derived KEK, as returned by the server.+ /// </summary>+ public const string EncryptedAccountKey = "encryptedAccountKey";++ /// <summary>+ /// Key for storing the vault encryption key (VEK) encrypted with the Account Key, as returned by the server.+ /// </summary>+ public const string EncryptedVek = "encryptedVek";++ /// <summary>+ /// Key for storing the account public key, used to seal shared vault grants to this account.+ /// </summary>+ public const string AccountPublicKey = "accountPublicKey";++ /// <summary>+ /// Key for storing the account private key encrypted with the Account Key.+ /// </summary>+ public const string EncryptedAccountPrivateKey = "encryptedAccountPrivateKey";++ /// <summary>+ /// Key for storing the Argon2 parameters the KEK is derived with, plus whether the account has a key chain.+ /// </summary>+ public const string EncryptionKeyDerivationParams = "encryptionKeyDerivationParams";++ /// <summary>+ /// Key for storing the plaintext session keys in development when the debug encryption key setting is on.+ /// </summary>+ public const string DebugSessionKeys = "debugSessionKeys";++ /// <summary>+ /// Keys holding key material derived from the account: the encrypted unlock chain, its derivation parameters and+ /// the local key check. Cleared on any logout, forced or user-initiated.+ /// </summary>+ public static readonly string[] VaultKeyStorageKeys =+ [+ EncryptedAccountKey,+ EncryptedVek,+ AccountPublicKey,+ EncryptedAccountPrivateKey,+ EncryptionKeyDerivationParams,+ EncryptionTestString,+ DebugSessionKeys,+ ];}diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Models/EncryptionKeyDerivationParams.cs b/apps/server/AliasVault.Client/Services/VaultSync/Models/EncryptionKeyDerivationParams.csindex 613ac5848..13c25c4bd 100644--- a/apps/server/AliasVault.Client/Services/VaultSync/Models/EncryptionKeyDerivationParams.cs+++ b/apps/server/AliasVault.Client/Services/VaultSync/Models/EncryptionKeyDerivationParams.cs@@ -8,9 +8,10 @@namespace AliasVault.Client.Services.VaultSync.Models;/// <summary>-/// The parameters the password-derived key (KEK) is derived with, cached for offline unlock.+/// The parameters the password-derived key (KEK) is derived with, cached locally./// </summary>/// <param name="Salt">The Argon2 salt.</param>/// <param name="EncryptionType">The key derivation type.</param>/// <param name="EncryptionSettings">The key derivation settings JSON.</param>-public sealed record EncryptionKeyDerivationParams(string Salt, string EncryptionType, string EncryptionSettings);+/// <param name="HasKeyChain">Whether the account is on the account-key model, so the derived key is only the KEK.</param>+public sealed record EncryptionKeyDerivationParams(string Salt, string EncryptionType, string EncryptionSettings, bool HasKeyChain = false);diff --git a/apps/server/AliasVault.Client/Services/VaultSync/VaultKeyService.cs b/apps/server/AliasVault.Client/Services/VaultSync/VaultKeyService.csnew file mode 100644index 000000000..339d05b9b--- /dev/null+++ b/apps/server/AliasVault.Client/Services/VaultSync/VaultKeyService.cs@@ -0,0 +1,357 @@+//-----------------------------------------------------------------------+// <copyright file="VaultKeyService.cs" company="aliasvault">+// Copyright (c) aliasvault. All rights reserved.+// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.+// </copyright>+//-----------------------------------------------------------------------++namespace AliasVault.Client.Services.VaultSync;++using System.Net.Http.Json;+using AliasVault.Client.Services.JsInterop;+using AliasVault.Client.Services.JsInterop.RustCore;+using AliasVault.Client.Services.VaultSync.Exceptions;+using AliasVault.Client.Services.VaultSync.Models;+using AliasVault.Shared.Models.Enums;+using AliasVault.Shared.Models.WebApi.V1.Auth;+using AliasVault.Shared.Models.WebApi.V2.Auth;+using Blazored.LocalStorage;+using Microsoft.JSInterop;++/// <summary>+/// Fetches, decrypts and caches the account-key unlock chain.+/// </summary>+/// <param name="httpClient">The HTTP client.</param>+/// <param name="localStorage">The local storage service.</param>+/// <param name="jsInteropService">JsInteropService instance.</param>+/// <param name="rustCoreService">RustCoreService instance.</param>+/// <param name="logger">ILogger instance.</param>+public sealed class VaultKeyService(HttpClient httpClient, ILocalStorageService localStorage, JsInteropService jsInteropService, RustCoreService rustCoreService, ILogger<VaultKeyService> logger)+{+ private static readonly string VaultKeyEndpoint = $"v2/VaultKey/{UnlockMethodTypes.ToToken(UnlockMethodType.Password)}";++ /// <summary>+ /// Fetch the current user's password vault key from the server.+ /// </summary>+ /// <returns>The vault key, or null when the account has no key chain (legacy account).</returns>+ public async Task<VaultKeyResponse?> FetchVaultKeyAsync()+ {+ var body = await httpClient.GetFromJsonAsync<VaultKeyGetResponse>(VaultKeyEndpoint);+ return body?.VaultKey;+ }++ /// <summary>+ /// Resolve the vault encryption key right after authentication: fetch the vault key from the server, decrypt the+ /// Account Key with the derived key (KEK), and with the AK decrypt the VEK and the account private key. All+ /// encrypted blobs are cached locally. For a legacy account (server explicitly reports no vault key) the derived+ /// key itself is the encryption key and any stale cached chain is cleared.+ /// </summary>+ /// <param name="derivedKeyBase64">The password-derived key.</param>+ /// <returns>The resolved keys.</returns>+ /// <exception cref="VaultKeyDecryptException">Thrown when the chain does not open with the derived key.</exception>+ public async Task<ResolvedVaultKey> ResolveEncryptionKeyAsync(string derivedKeyBase64)+ {+ var vaultKey = await FetchVaultKeyAsync();+ if (vaultKey is null)+ {+ await ClearCachedChainAsync();+ return new ResolvedVaultKey(derivedKeyBase64, null, true);+ }++ var resolved = await DecryptKeyChainAsync(vaultKey.EncryptedAccountKey, vaultKey.EncryptedVek, vaultKey.EncryptedAccountPrivateKey, derivedKeyBase64);+ await CacheVaultKeyBlobsAsync(vaultKey);+ return resolved;+ }++ /// <summary>+ /// Unlock with the master password: fetch the chain when online (its own derivation parameters decide the KEK),+ /// fall back to the cached chain and parameters when the server cannot be reached.+ /// </summary>+ /// <param name="username">The username, needed to look up the salt of a legacy account.</param>+ /// <param name="password">The master password.</param>+ /// <returns>The resolved keys. A legacy result still has to be validated by the caller.</returns>+ /// <exception cref="VaultKeyDecryptException">Thrown when the password is wrong.</exception>+ /// <exception cref="VaultKeyUnavailableException">Thrown when offline and the chain this account unlocks with is not cached.</exception>+ public async Task<ResolvedVaultKey> UnlockWithPasswordAsync(string username, string password)+ {+ VaultKeyResponse? vaultKey = null;+ var online = false;+ Exception? fetchError = null;+ try+ {+ vaultKey = await FetchVaultKeyAsync();+ online = true;+ }+ catch (Exception ex) when (ex is HttpRequestException { StatusCode: null } or TaskCanceledException)+ {+ // No response at all (network down, DNS, timeout): attempt an offline unlock. A server error response propagates.+ logger.LogWarning(ex, "Vault key could not be fetched, attempting offline unlock.");+ fetchError = ex;+ }++ if (vaultKey is not null)+ {+ var kek = await DeriveKeyAsync(password, vaultKey.Salt, vaultKey.EncryptionSettings);+ var resolved = await DecryptKeyChainAsync(vaultKey.EncryptedAccountKey, vaultKey.EncryptedVek, vaultKey.EncryptedAccountPrivateKey, kek);+ await CacheVaultKeyBlobsAsync(vaultKey);+ return resolved;+ }++ if (online)+ {+ // Legacy account: the derived key is the encryption key and the salt comes from the login handshake.+ var initiate = await httpClient.PostAsJsonAsync("v2/Auth/login", new LoginInitiateRequest(username));+ initiate.EnsureSuccessStatusCode();+ var loginResponse = await initiate.Content.ReadFromJsonAsync<LoginInitiateResponse>() ?? throw new InvalidOperationException("Empty login initiate response.");+ await StoreDerivationParamsAsync(new EncryptionKeyDerivationParams(loginResponse.Salt, loginResponse.EncryptionType, loginResponse.EncryptionSettings));+ await ClearCachedChainAsync();+ return new ResolvedVaultKey(await DeriveKeyAsync(password, loginResponse.Salt, loginResponse.EncryptionSettings), null, true);+ }++ // Offline: derive from the cached parameters and open the cached chain.+ var parameters = await GetDerivationParamsAsync() ?? throw new VaultKeyUnavailableException(fetchError);+ var offlineKek = await DeriveKeyAsync(password, parameters.Salt, parameters.EncryptionSettings);+ var cached = await ResolveFromLocalCacheAsync(offlineKek);+ if (cached is not null)+ {+ return cached;+ }++ return new ResolvedVaultKey(offlineKek, null, true);+ }++ /// <summary>+ /// Resolve the key to use for WebAuthn or mobile QR unlock.+ /// </summary>+ /// <param name="storedKeyBase64">The key restored from the auxiliary unlock method.</param>+ /// <returns>The resolved keys and whether the stored key was upgraded to the VEK.</returns>+ public async Task<(ResolvedVaultKey Key, bool Upgraded)> ResolveStoredUnlockKeyAsync(string storedKeyBase64)+ {+ try+ {+ var resolved = await ResolveFromLocalCacheAsync(storedKeyBase64);+ if (resolved is null)+ {+ // Legacy account: no chain to upgrade the stored key with, so it is the encryption key itself.+ return (new ResolvedVaultKey(storedKeyBase64, null, true), false);+ }++ return (resolved, resolved.VaultEncryptionKey != storedKeyBase64);+ }+ catch (VaultKeyDecryptException)+ {+ // The stored key is not the KEK, so it is the VEK itself; the private key cannot be recovered from it.+ return (new ResolvedVaultKey(storedKeyBase64, null, false), false);+ }+ }++ /// <summary>+ /// Whether the given derived key opens the cached chain.+ /// </summary>+ /// <param name="derivedKeyBase64">The password-derived key to test.</param>+ /// <returns>True or false when a chain is cached, null when there is none to test against.</returns>+ public async Task<bool?> TryOpenCachedChainAsync(string derivedKeyBase64)+ {+ var encryptedAccountKey = await localStorage.GetItemAsStringAsync(StorageKeys.EncryptedAccountKey);+ if (string.IsNullOrEmpty(encryptedAccountKey))+ {+ return null;+ }++ try+ {+ await DecryptKeyOrThrowAsync(encryptedAccountKey, derivedKeyBase64);+ return true;+ }+ catch (VaultKeyDecryptException)+ {+ return false;+ }+ }++ /// <summary>+ /// Refresh the local chain cache from the server without needing the KEK.+ /// </summary>+ /// <returns>Task.</returns>+ public async Task CacheEncryptedVekFromServerAsync()+ {+ var vaultKey = await FetchVaultKeyAsync();+ if (vaultKey is not null)+ {+ await CacheVaultKeyBlobsAsync(vaultKey);+ }+ else+ {+ await ClearCachedChainAsync();+ }+ }++ /// <summary>+ /// The cached account public key, or null when the account has no keypair yet.+ /// </summary>+ /// <returns>The public key as a JWK JSON string.</returns>+ public async Task<string?> GetAccountPublicKeyAsync()+ {+ return await localStorage.GetItemAsStringAsync(StorageKeys.AccountPublicKey);+ }++ /// <summary>+ /// Persist the KEK derivation parameters.+ /// </summary>+ /// <param name="parameters">The parameters.</param>+ /// <returns>Task.</returns>+ public async Task StoreDerivationParamsAsync(EncryptionKeyDerivationParams parameters)+ {+ await localStorage.SetItemAsync(StorageKeys.EncryptionKeyDerivationParams, parameters);+ }++ /// <summary>+ /// The cached KEK derivation parameters, or null when none are cached.+ /// </summary>+ /// <returns>The parameters.</returns>+ public async Task<EncryptionKeyDerivationParams?> GetDerivationParamsAsync()+ {+ try+ {+ return await localStorage.GetItemAsync<EncryptionKeyDerivationParams>(StorageKeys.EncryptionKeyDerivationParams);+ }+ catch (Exception ex)+ {+ logger.LogWarning(ex, "Cached key derivation parameters are unreadable, ignoring them.");+ return null;+ }+ }++ /// <summary>+ /// Persist a server vault-key response's encrypted blobs and derivation parameters.+ /// </summary>+ /// <param name="vaultKey">The server's vault key response.</param>+ /// <returns>Task.</returns>+ public async Task CacheVaultKeyBlobsAsync(VaultKeyResponse vaultKey)+ {+ await localStorage.SetItemAsStringAsync(StorageKeys.EncryptedAccountKey, vaultKey.EncryptedAccountKey);+ if (!string.IsNullOrEmpty(vaultKey.EncryptedVek))+ {+ await localStorage.SetItemAsStringAsync(StorageKeys.EncryptedVek, vaultKey.EncryptedVek);+ }+ else+ {+ await localStorage.RemoveItemAsync(StorageKeys.EncryptedVek);+ }++ if (!string.IsNullOrEmpty(vaultKey.AccountPublicKey) && !string.IsNullOrEmpty(vaultKey.EncryptedAccountPrivateKey))+ {+ await localStorage.SetItemAsStringAsync(StorageKeys.AccountPublicKey, vaultKey.AccountPublicKey);+ await localStorage.SetItemAsStringAsync(StorageKeys.EncryptedAccountPrivateKey, vaultKey.EncryptedAccountPrivateKey);+ }+ else+ {+ await localStorage.RemoveItemsAsync([StorageKeys.AccountPublicKey, StorageKeys.EncryptedAccountPrivateKey]);+ }++ await StoreDerivationParamsAsync(new EncryptionKeyDerivationParams(vaultKey.Salt, vaultKey.EncryptionType, vaultKey.EncryptionSettings, true));+ }++ /// <summary>+ /// Remove the cached chain (the account has no chain, or the user logged out).+ /// </summary>+ /// <returns>Task.</returns>+ public async Task ClearCachedChainAsync()+ {+ await localStorage.RemoveItemsAsync([StorageKeys.EncryptedAccountKey, StorageKeys.EncryptedVek, StorageKeys.AccountPublicKey, StorageKeys.EncryptedAccountPrivateKey]);++ // Keep the flag in step with the chain, otherwise an offline unlock refuses to fall back to the legacy path.+ var parameters = await GetDerivationParamsAsync();+ if (parameters is { HasKeyChain: true })+ {+ await StoreDerivationParamsAsync(parameters with { HasKeyChain = false });+ }+ }++ /// <summary>+ /// Derive the KEK from a password.+ /// </summary>+ /// <param name="password">The password.</param>+ /// <param name="salt">The Argon2 salt.</param>+ /// <param name="encryptionSettings">The Argon2 settings JSON.</param>+ /// <returns>The derived key as base64.</returns>+ private async Task<string> DeriveKeyAsync(string password, string salt, string encryptionSettings)+ {+ return Convert.ToBase64String(await rustCoreService.Argon2DeriveKeyAsync(password, salt, encryptionSettings));+ }++ /// <summary>+ /// Decrypt the locally cached chain with the given KEK.+ /// </summary>+ /// <param name="derivedKeyBase64">The password-derived key.</param>+ /// <returns>The resolved keys, or null when no chain is cached.</returns>+ private async Task<ResolvedVaultKey?> ResolveFromLocalCacheAsync(string derivedKeyBase64)+ {+ var encryptedAccountKey = await localStorage.GetItemAsStringAsync(StorageKeys.EncryptedAccountKey);+ if (string.IsNullOrEmpty(encryptedAccountKey))+ {+ return null;+ }++ var encryptedVek = await localStorage.GetItemAsStringAsync(StorageKeys.EncryptedVek);+ var encryptedAccountPrivateKey = await localStorage.GetItemAsStringAsync(StorageKeys.EncryptedAccountPrivateKey);+ return await DecryptKeyChainAsync(encryptedAccountKey, encryptedVek, encryptedAccountPrivateKey, derivedKeyBase64);+ }++ /// <summary>+ /// Walk the chain: AK first, then the VEK (or the AK itself for a transitional account where AK equals VEK), then the account private key.+ /// </summary>+ /// <param name="encryptedAccountKey">The AK encrypted with the KEK.</param>+ /// <param name="encryptedVek">The VEK encrypted with the AK, or null for a transitional account.</param>+ /// <param name="encryptedAccountPrivateKey">The account private key encrypted with the AK, or null when the account has no keypair.</param>+ /// <param name="derivedKeyBase64">The password-derived KEK.</param>+ /// <returns>The resolved keys.</returns>+ private async Task<ResolvedVaultKey> DecryptKeyChainAsync(string encryptedAccountKey, string? encryptedVek, string? encryptedAccountPrivateKey, string derivedKeyBase64)+ {+ var accountKey = await DecryptKeyOrThrowAsync(encryptedAccountKey, derivedKeyBase64);+ var vek = string.IsNullOrEmpty(encryptedVek) ? accountKey : await DecryptKeyOrThrowAsync(encryptedVek, accountKey);+ return new ResolvedVaultKey(vek, await DecryptPrivateKeyAsync(encryptedAccountPrivateKey, accountKey), false);+ }++ /// <summary>+ /// Decrypt the account private key with the AK. A stale or corrupt blob must not fail the unlock; grant decryption then degrades until the next sync.+ /// </summary>+ /// <param name="encryptedAccountPrivateKey">The encrypted private key, or null.</param>+ /// <param name="accountKeyBase64">The Account Key.</param>+ /// <returns>The private key as a JWK JSON string, or null.</returns>+ private async Task<string?> DecryptPrivateKeyAsync(string? encryptedAccountPrivateKey, string accountKeyBase64)+ {+ if (string.IsNullOrEmpty(encryptedAccountPrivateKey))+ {+ return null;+ }++ try+ {+ return await jsInteropService.SymmetricDecrypt(encryptedAccountPrivateKey, accountKeyBase64);+ }+ catch (JSException ex)+ {+ logger.LogWarning(ex, "The account private key could not be decrypted; shared vault grants stay closed until the next sync.");+ return null;+ }+ }++ /// <summary>+ /// Decrypt a wrapped key, mapping an AES-GCM authentication failure onto <see cref="VaultKeyDecryptException"/>.+ /// </summary>+ /// <param name="encryptedKey">The wrapped key as base64(IV | ciphertext | tag).</param>+ /// <param name="decryptingKeyBase64">The key that wraps it.</param>+ /// <returns>The unwrapped key as base64.</returns>+ private async Task<string> DecryptKeyOrThrowAsync(string encryptedKey, string decryptingKeyBase64)+ {+ try+ {+ return Convert.ToBase64String(await jsInteropService.SymmetricDecryptBase64ToBytes(encryptedKey, decryptingKeyBase64));+ }+ catch (JSException ex)+ {+ throw new VaultKeyDecryptException(ex);+ }+ }+}