Skip to main content

Encryption Architecture v3

Changes from v2 to v3​

  • Introduced asymmetric (ECDH-ES) wrapping layer between prfKey/passwordKey and mainKey. This enables mainKey to be easily rotated as the new key can be re-encrypted under the public key of each prfKey and passwordKey, instead of requiring each prfKey and passwordKey to be available to re-wrap the new mainKey.

  • privateKey now labeled in diagram as "ECDSA secp256r1" instead of "EC secp256r1".

Changes from v1 to v2​

  • Deleted outerSessionKey. innerSessionKey is renamed to sessionKey and is now stored in plaintext in session storage alongside the privateDataJwe which it encrypts.

  • Moved cache of WebAuthn RP ID and user handle from local storage to session storage.

These changes were made in order to support using the app in multiple tabs signed in to the same account, and to sign out of existing tabs if any tab signs out or signs in to a different account.

Encryption Architecture v3​

wwWallet uses the WebAuthn prf extension to derive encryption keys for the wallet contents, including the user's private proof signing key. This document explains the encryption architecture and its design rationale, as well as providing critique of the same.

Diagram: Wallet encryption architecture

The wallet uses the following keys and data types, as labeled in the above diagram:

  • EncryptedContainer: The user's wallet contents in encrypted form. This is stored both in the backend server database, and downloaded to the client's local storage when the user signs in to the wallet.

  • PrivateData: The cleartext contents of an EncryptedContainer. This contains both sensitive data, namely privateKey, and non-sensitive data, including the user's DID and public proof signing key. All of these contents are encrypted at rest on both the server side and the client side.

  • EphemeralEncapsulationInfo: An ephemeral ECDH public key and auxiliary parameters to use for unwrapping the mainKey used to encrypt the EncryptedContainer. This is shared between all prfKeys and passwordKeys in the EncryptedContainer.

  • StaticEncapsulationInfo: A wrapped copy of the mainKey along with a static ECDH key pair wrapPublicKey and wrapPrivateKey. This is unique per prfKey and passwordKey. The ECDH private key is in turn wrapped by the associated prfKey or passwordKey.

    When creating a new mainKey, a new ephPublicKey and ephPrivateKey pair is created and each StaticEncapsulationInfo is updated as follows. An ECDH exchange is made between ephPrivateKey and the wrapPublicKey of the StaticEncapsulationInfo. The resulting wrappingKey is used to wrap the new mainKey, and the resulting wrapping is stored in the StaticEncapsulationInfo. Finally, the ephPublicKey is stored in the EphemeralEncapsulationInfo of the EncryptedContainer and the ephPrivateKey is discarded.

    During sign-in, the user chooses a prfKey or passwordKey which is used to unwrap the wrapPrivateKey stored in the associated StaticEncapsulationInfo. The opposite ECDH exchange is made between wrapPrivateKey and the stored ephPublicKey to derive the wrappingKey used to unwrap the mainKey stored in the StaticEncapsulationInfo, and finally mainKey is used to decrypt the EncryptedContainer.

  • privateKey: The user's proof signing secp256r1 private key. This is the long-lived key that is used to prove the user's ownership of the wallet. This key is generated once, as part of creating the user's wallet when they first create a wwWallet account.

    The privateKey member of PrivateData is encrypted an additional time using the same encryption key.

    privateKey is only kept in volatile memory, and is never written to persistent storage in unencrypted form.

  • mainKey: The 256-bit AES-GCM encryption key of the EncryptedContainer. This is used to decrypt the contained PrivateData and is itself stored in encrypted (wrapped) form in the EncryptedContainer, asymmetrically encrypted using each of the user's prfKeys and, if applicable, passwordKey.

    This key is generated as part of creating the user's wallet when they first create a wwWallet account, but may be replaced at any time.

    mainKey is only kept in volatile memory, and is never written to persistent storage in unencrypted form.

  • prfKey: A 256-bit AES-GCM encryption key derived using the WebAuthn prf extension. This is used to wrap and unwrap an associated StaticEncapsulationInfo structure in order to decrypt the EncryptedContainer contents during sign-in.

    The user may have 0 or more instances of prfKey (or at least 1, when password authentication is disabled), each corresponding to a WebAuthn credential the user may use to sign in to the backend service. Each prfKey has its own unique associated StaticEncapsulationInfo.

    The prfSalt and HKDF parameters used to derive prfKey are randomly generated once, when the corresponding WebAuthn credential is registered.

    prfKey is only kept in volatile memory, and is never written to persistent storage.

  • passwordKey: A 256-bit AES-GCM encryption key derived from a password using PBKDF2. This is a legacy feature that is usually disabled. Like prfKey, this is used to wrap and unwrap an associated StaticEncapsulationInfo structure in order to decrypt the EncryptedContainer contents during sign-in. The passwordKey has its own unique associated StaticEncapsulationInfo.

    The PBKDF2 salt used to derive passwordKey is randomly generated once, when the account is created. Changing the password is not possible as of this writing.

    passwordKey is only kept in volatile memory, and is never written to persistent storage.

  • wrapPrivateKey and wrapPublicKey: The static ECDH keypair of a StaticEncapsulationInfo. These are used to perform an ECDH exchange with the ephPublicKey or ephPrivateKey, respectively, to derive the wrappingKey used to decrypt or encrypt the mainKey.

    Each wrapPrivateKey is only kept in volatile memory, and is never written to persistent storage in unencrypted form. Each wrapPublicKey is stored in cleartext in the StaticEncapsulationInfo.

  • ephPrivateKey and ephPublicKey: An ephemeral ECDH keypair for wrapping the mainKey. These are used to perform an ECDH exchange with a wrapPublicKey or wrapPrivateKey, respectively, to derive the wrappingKey used to decrypt or encrypt the mainKey.

    ephPublicKey is stored as an EphemeralEncapsulationInfo structure in the EncryptedContainer. ephPrivateKey is only kept in volatile memory, and is discarded after wrapping the mainKey.

  • sessionKey: A 256-bit AES-GCM encryption key used to decrypt the EncryptedContainer for the duration of a session.

    Upon successful sign-in, the EncryptedContainer is first decrypted using mainKey as described above. The PrivateData is then re-encrypted using a newly generated sessionKey, resulting in the ciphertext privateDataJwe which is stored in the client's session storage. The sessionKey is also stored in cleartext session storage alongside the privateDataJwe.

Design rationale​

The primary concerns during the development of this design was to keep all key material on the client side, and to minimize the exposure of long-lived secrets. Thus we keep the wallet contents encrypted at rest, and introduced the session keys by the following rationale.

Re-encrypting wallet contents to a session key​

This is a vestigial feature from the v1 and v2 architecture iterations where mainKey was a long-lived key that was not easily replaceable. The sessionKey was therefore used to minimize the exposure of the mainKey.

This v3 architecture revision allows for frequently rotating the mainKey, but we keep the sessionKey for now since rotation of mainKey is not yet implemented.

Selection of client-side storage areas​

We use the Web Crypto API for encryption, decryption and key management operations. The CryptoKey objects do not survive page reload or top-level navigation unless stored in some persistent storage. We use two client-side storage areas: local storage and session storage.

Local storage​

We store the EncryptedContainer in local storage in anticipation of the possibility to use the wallet in offline mode in the future. We also cache some other parameters:

  • The prfKey derivation parameters for each user that has logged in on the machine, and a display name for the user. These are used to eliminate the need for the user to authenticate twice to sign in to the wallet: once to retrieve the EncryptedContainer, including the PRF salts used to derive a prfKey, and once to evaluate the PRF with the retrieved salt. The cached salt allows both of these steps to be performed in a single WebAuthn authentication ceremony. The user may delete any entry of this cache while logged out.

  • The user's WebAuthn user handle, needed to detect if the user signs in to a different account in a different browser tab and log out of the older tab in that case.

Session storage​

We store the sessionKey and re-encrypted privateDataJwe in session storage so that they expire when the user closes the browser tab. We also cache some other parameters:

  • The WebAuthn RP ID for the wwWallet service, needed to derive prfKeys. This could be a configuration constant of the frontend app, but the backend already sends it during the initial authentication or signup, so we cache the value and eliminate the possibility of config mismatch.

  • The user's WebAuthn user handle, needed to detect if the user signs in to a different account in a different browser tab and log out of the older tab in that case.

Encrypting privateKey twice​

Since privateKey is more sensitive than other members of PrivateData, we encrypt it an additional time so that we can access the other members of PrivateData without exposing privateKey in cleartext unnecessarily.

Using prfKey and passwordKey to wrap en ECDH private key​

The deriveKey() function in WebCrypto does not support deriving an ECDH private key deterministically, for example from PRF output or from an PBKDF2 output key. Therefore we instead have to generate the ECDH key pair nondeterministically and store the wrapped private key.

Critique​

This design has some drawbacks, and some of the intended advantages are debatable. The following critique may inform a revised design. This is not exhaustive; we invite additional and ongoing review and critique of the design.

Cleartext session key​

The sessionKey is used for user convenience: once logged in, the session key can be used for the duration of the session to access encrypted data. However, this might not improve security much; with mainKey now easily replaceable it is not materially less secure to simply store the mainKey itself in cleartext in session storage.

Weak encryption at rest​

Although the EncryptedContainer itself is stored in encrypted form, we also store all encryption keys needed to decrypt it. This means that the encryption at rest is at best a "security by obscurity" measure or, more charitably, a dubious form of "defense in depth". It would thus be preferable to retrieve or derive the encryption keys from data not stored in cleartext on the client device.

The session keys could be eliminated in favour of simply re-deriving the prfKey or passwordKey whenever sensitive contents need to be accessed. This would require the user to perform an authentication ceremony (presenting a WebAuthn credential or entering a password) for each access. This may or may not be an acceptable user experience. The keys could be kept in application memory for a short time to avoid bursts of multiple authentication prompts during a single semantic user action. In fact the app already does this when adding or deleting WebAuthn credentials, which each need a corresponding prfKey.

Encrypting privateKey twice​

Likewise, encrypting privateKey twice may not materially improve security either. An adversary with read access to the other PrivateData members will likely also have read access to both of local storage and session storage, thus having access to the keys needed to decrypt privateKey anyway.

passwordKey is not entirely client-side​

When a passwordKey is used, the key material and algorithm parameters needed to derive passwordKey are exposed to the backend service. To make passwordKey entirely client-side, making it impossible for the backend service to access the contents of the EncryptedContainer, a different passphrase should be used to derive passwordKey than is used to sign in to the backend service. Alternatively, some password blinding method such as a PAKE protocol might be used to keep the backend server from learning the user's password.

Software keys, not hardware keys​

All cryptographic keys used by wwWallet are fundamentally software keys, held in browser memory. This is due to technical limitations, some of which may change in the future.

However, note the difference between encryption keys and signing keys. Encryption and decryption inherently involves exposing the cleartext anyway, so encryption keys do not need to be kept secret from parties accessing the cleartext.

The WebAuthn prf extension simply returns pseudo-random data which wwWallet uses to derive encryption keys. Thus the encryption keys are software keys held by the browser, but the WebAuthn authenticator holding the PRF key is needed in order to access the PRF outputs. This is sufficient hardware binding for encryption keys, assuming the browser is benevolent.

Ideally the user's privateKey should be a hardware-bound key, so that even if the mainKey or the PrivateData is exposed, an unauthorized party would still not be able to sign proofs on behalf of the legitimate user. This is not currently possible due to technical limitations. Although WebAuthn authentication keys may be hardware-bound, they do not support signing arbitrary data. Future extensions to the WebAuthn API might add the possibility to sign arbitrary data with a hardware-bound private key.