Enable Secure Mode
When your application needs to handle sensitive information from a user, such as requesting the generation of a new private key, it's critical that this data is transmitted securely. DID Connect provides a secure mode that automatically encrypts such data between the user's wallet and your application server.
This mode is essential for claims like keyPair, which returns a newly generated secret key. It uses a hybrid encryption approach: the server and wallet first establish a secure channel by exchanging a symmetric AES key, which is itself encrypted using an asymmetric RSA key pair. All subsequent sensitive data is then protected using this shared AES key.
How It Works#
The secure data exchange process is handled transparently by the DID Connect library. Here is a simplified sequence of the events involved:
Implementation#
Implementing secure mode requires no extra configuration. It is automatically enabled when you request a claim that is designated as sensitive, such as keyPair or encryptionKey.
Step 1: Request a Sensitive Claim#
To initiate the secure workflow, simply request a sensitive claim. The library identifies this claim type and handles the encryption and decryption process automatically.
handlers.attach({
app: server,
action: 'get-new-key',
onConnect: () => {
// The keyPair claim is inherently sensitive and will trigger the encrypted workflow.
return [
{
keyPair: () => {
return {
mfa: true, // Optionally require MFA for this sensitive operation
description: 'Generate a new secure key for your profile.',
moniker: 'my-app-key',
targetType: {
role: 'application',
},
};
},
},
];
},
onAuth: ({ claims, didwallet, timestamp }) => {
console.log(`Authentication completed at ${timestamp} from wallet:`, didwallet);
const keyPair = claims.find((x) => x.type === 'keyPair');
if (keyPair) {
console.log('Successfully received new key pair.');
// The 'keyPair.secret' is automatically decrypted by the library.
// WARNING: Handle this secret key with extreme care.
console.log('Secret Key:', keyPair.secret);
}
return { successMessage: 'New key generated and secured.' };
},
// Standard callbacks...
});Step 2: Access the Decrypted Data#
As shown in the onAuth callback in the example above, the sensitive data arrives already decrypted. The DID Connect library uses the sharedKey it established during the handshake to decrypt the incoming response from the wallet before passing the claims to your onAuth function. You can access keyPair.secret as a plaintext value and use it immediately.
Warning: The
keyPair.secretvalue is a private key. Handle this data with extreme care. Do not log it in production or expose it unnecessarily.
Step 3: Understand the Wallet's Role#
For the secure mode to function, the user's wallet must initiate the session by providing two query parameters when fetching the authentication request. This process is handled automatically by compatible wallets like ABT Wallet when they scan a DID Connect QR code.
Parameter | Description |
|---|---|
| The wallet's public encryption key, base58 encoded. |
| The protocol version, which must be |
Next Steps#
Now that you understand how to handle sensitive claims securely, you can explore more advanced topics:
- Dive deeper into the available claims in the Claim Types Reference.
- Learn how you can use the result of one workflow as the input for another in our Chain Multiple Workflows guide.