Encryption Key Claim

The encryptionKey claim is a powerful feature that allows your application to request a secret encryption key from the user's wallet. This key is deterministically derived from the wallet's master secret and a salt you provide. It enables applications to encrypt user-specific data without ever handling the user's primary private key, enhancing security and privacy.

How It Works#

The process is straightforward and secure:

1. Application Initiates: Your application requests an encryptionKey claim, providing a unique salt string.
2. Wallet Derives Key: The user's wallet receives the request. It uses a secure key derivation function (specifically SHA3(Buffer.concat(keyPair.sk, salt), 3)) to combine its master secret with the provided salt.
3. User Approval: The wallet prompts the user to approve the request, explaining that the application wants to generate an encryption key.
4. Key Returned: Upon user approval, the derived key is sent back to your application as part of the DID Connect response.

This method ensures that even if two different applications request a key with the same salt, the derived keys will be different because they are tied to each user's unique master secret.

Parameters#

The encryptionKey claim object accepts the following parameters:

Parameter	Type	Required	Description
type	String	Yes	Must be set to 'encryptionKey'.
description	String	No	A message displayed to the user in the wallet to explain the purpose of the key. Defaults to 'Please provide encryptionKey to continue.'.
salt	String	Yes	A unique string provided by your application. This is a critical component in the key derivation process. Using a different salt will result in a different key.
delegation	String	No	An optional JWT token proving a delegation relationship, allowing an agent to request the key on behalf of another DID.
meta	Any	No	An object to hold any custom metadata you want to associate with the claim. Defaults to {}.

Requesting an Encryption Key#

Here is an example of how to request an encryptionKey claim within your application. You would typically define this within the claims object when initiating a DID Connect session.

const claims = {
  encryptionKey: {
    description: 'Generate a key to encrypt your application settings',
    salt: 'a-unique-and-persistent-salt-for-this-user-and-context',
  },
};

// This claims object would be passed to your WalletAuthenticator instance
const { authInfo } = await authenticator.sign({
  claims,
  // ... other context parameters
});

In the example above, the application requests a key, providing a descriptive message for the user and a unique salt.

Wallet Response#

After the user approves the request, your application's callback endpoint will receive the wallet's response. Once verified, the claims array in the response payload will contain the derived encryption key.

{
  "userDid": "z1...",
  "userPk": "...",
  "claims": [
    {
      "type": "encryptionKey",
      "salt": "a-unique-and-persistent-salt-for-this-user-and-context",
      "delegation": "",
      "key": "...derived_encryption_key..."
    }
  ],
  "challenge": "...",
  "timestamp": 1678886400
}

Your application can then extract the key from the response and use it for encryption and decryption tasks.

Use Cases#

This claim is ideal for scenarios where you need to protect user data stored by your application:

• Encrypting User Preferences: Securely store user settings or profile information in your database.
• Securing Application Data: Encrypt data specific to a user's session or activity within your application.
• End-to-End Encryption: Establish a shared secret for creating an encrypted communication channel.

By leveraging the encryptionKey claim, you can build more secure and privacy-preserving applications. To dive deeper into how claims are handled, proceed to the API Reference for WalletAuthenticator.