Key Pair Claim

The Key Pair Claim is a powerful feature that allows your application to request the user's wallet to generate a new cryptographic key pair. This is particularly useful for creating new, application-specific accounts or identities that are securely managed by the user's wallet but dedicated to interacting with your service.

Instead of managing user credentials on your server, you can offload this responsibility to the user's DID Wallet, enhancing both security and user control.

Use Cases

How It Works

When you request a keyPair claim, the DID Wallet will prompt the user with the description you provide. If the user approves, the wallet generates a new key pair according to the parameters you've set (targetType). By default, the wallet also declares the new DID on the blockchain. The wallet then returns the new key pair (public key, secret key, and address) to your application through the secure DID Connect channel.

Parameters

The keyPair claim accepts the following parameters:

The targetType Object

You can customize the type of key pair generated with the targetType object:

Example: Requesting a New Account

Here is an example of how to request a new key pair for a user, which can be used as their account within your application.

Requesting a new key pair

const claims = {
  keyPair: {
    description: 'Create a new account for our awesome app',
    moniker: 'my-app-account',
    targetType: {
      role: 'account',
    },
  },
};

// In your handler
const { authInfo } = await authenticator.sign({
  claims,
  // ... other context properties
});

Example: Generating a Key Pair for a Blocklet

If you are building a Blocklet, you might need a key pair with a specific role. You can also choose not to declare it on-chain immediately and migrate from an existing DID.

Requesting a key pair for a blocklet

const claims = {
  keyPair: {
    description: 'Generate a key pair to manage your new Blocklet',
    moniker: 'my-blocklet-key',
    declare: false, // Generate the key pair but don't broadcast a declare tx
    migrateFrom: 'z3CtKiQt2QnLXaZfEfBYvJHTZoPXJggnHEYx4', // The DID to migrate from
    targetType: {
      role: 'blocklet',
      key: 'ed25519',
      hash: 'sha3',
    },
  },
};

// In your handler
const { authInfo } = await authenticator.sign({
  claims,
  // ... other context properties
});

Wallet Response

If the user approves the request, your application's onAuth callback will receive the newly generated key pair within the claims array. The response for a single keyPair claim will look like this:

Wallet Response Example

{
  "type": "keyPair",
  "sk": "...", // The secret key of the new key pair
  "pk": "...", // The public key of the new key pair
  "address": "...", // The DID address of the new key pair
  "moniker": "my-app-account",
  "meta": {}
}

Your application should securely handle the received secret key (sk), as it grants full control over the newly created DID.

Now that you understand how to request a new key pair, you might be interested in deriving keys for other purposes.