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#

• Application-Specific Accounts: When a user signs up, you can request a new key pair to create a dedicated account for them within your application. This new account's DID is distinct from the user's primary DID.
• Session or Device Keys: Generate temporary key pairs for specific sessions or devices, enhancing security by limiting the key's scope and lifetime.
• Identity Migration: Facilitate the process of migrating a user from an old account to a new one by specifying the migrateFrom property.

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:

Name	Type	Description
description	string	Required. A message displayed to the user explaining why a new key pair is needed.
moniker	string	Required. A human-readable name for the new account, which will be visible in the user's wallet. Must match the regex ^[a-zA-Z0-9][-a-zA-Z0-9_]{2,128}$.
declare	boolean	Optional. If true (the default), the new DID will be declared on the chain. Set to false to generate an off-chain key pair.
migrateFrom	string	Optional. A DID address to migrate from. The wallet can use this to link the new account to an old one.
targetType	object	Optional. An object specifying the cryptographic properties of the key pair to be generated.

The targetType Object#

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

Key	Type	Default	Description
role	string	account	The role of the DID, e.g., account, application, blocklet.
key	string	ed25519	The cryptographic key algorithm, e.g., ed25519, secp256k1.
hash	string	sha3	The hash algorithm used for generating the address, e.g., sha3, sha2, keccak.
encoding	string	base58	The encoding for the address, e.g., base58, base16.

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.

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.

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:

{
  "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.