Docs Using the wallet Keys

Key Management

A key is how the organization signs. This chapter explains how to create one, import a copy that was exported, decide who may use it, export a passphrase-protected copy, and delete it.

Understanding Cryptographic Keys

What are Keys?

A key is the organization’s digital signature. It is used to:

  • Prove identity when someone checks that a credential comes from you
  • Sign credentials so the signature cannot be forged
  • Let others verify that the signature matches the public key in the DID document

Public and Private Key

Every key has two halves:

  1. Private key: stays inside the hardened key module and is used to sign. It never leaves the wallet.
  2. Public key: is published in the DID document so others can check signatures

User Secrets

  • The private key stays in the wallet’s key module. The user secret is not that key, and it does not replace it.
  • The wallet does not store the file. You present it when you sign or approve.
  • It is optional. Without it, your account login and the service secret protect use of the key.

Controller Groups

Who may use a key is a list of controller groups. This is the same layout you see when you add a key and when you open Manage Key Access.

People in one group are alternatives. Any one of them can provide that group’s secret. The screen marks this with OR.

Every group is required. To sign or otherwise use the key, the wallet needs one secret from each group. The screen marks this with AND.

Example: a group named Office Holders with two people, and a group named Authorized Staff with three people. Signing needs one office holder and one staff member. Any person in a group can stand in for the others in that group.

A single group that contains only you is the usual starting point. Signing then needs only your secret.

You can name a group, for example Office Holders. A group without a name is shown as Controller Group 1, Controller Group 2, and so on.

On the key’s Controller tab, the wallet states the rule in one sentence. For the example above it reads: at least one controller of Office Holders and at least one controller of Authorized Staff need to provide their secret in order to operate this key.

Parts and splits

Each controller group is stored as one part of the key (one split of the secret). People in the same group hold the same part, so any one of them can supply it. More than one group means the key is split, and every part is required.

When you save a new layout, the wallet compares the groups you edited with the groups already on the key and applies the change. Adding colleagues to a group, and changing how the key is split across groups, are handled for you. You edit groups. The wallet decides the underlying update.

Creating a New Key

  1. Open Identities
  2. On an identity, click Add Key

The wizard is linked to that identity. The first step asks you to Generate a new key or Import one that was exported. The steps below are for Generate. Import is described in Importing a Key.

Step 1: Source

Choose Generate.

Step 2: Key name

Enter an optional name. Leave it empty and the wallet chooses an identifier.

Step 3: Key type

Choose the signature algorithm.

ES256 (ECDSA, elliptic curve)

  • Modern, fast, and widely supported
  • Smaller keys and signatures

Ed25519 (Edwards curve)

  • Alternative modern algorithm
  • Compatible with common JWT tooling

PS256 (RSA)

  • Older algorithm
  • Larger keys and signatures

Step 4: Purposes

Choose what the key is for. You can select more than one.

  • Authentication: proving identity, for example at login
  • Assertion Method: signing credentials (the usual choice for issuers)
  • Key Agreement: encrypting communication
  • Capability Delegation: delegating permissions
  • Capability Invocation: invoking operations

Step 5: Setup

Choose how many controller groups the new key should have.

Easy setup puts you alone in a single group. Signing needs only your secret. You can add people or groups later with Manage Key Access.

Complex setup lets you define the groups on the next step, Controllers.

Step 6: Controllers (complex setup only)

Build the groups:

  1. Each card is one controller group. Click the name to rename it.
  2. Add each person’s email with Add Controller. People in the same group are separated by OR.
  3. Add another required group with Add Controller Group. Groups are separated by AND.
  4. Every group needs at least one person. When you generate a key, you must be in at least one group.
  5. Each email can appear in only one group, and must belong to your company.

When the key is created, every listed person is asked to set up their own secret. Only the person who starts creation needs CREATE_KEY.

Step 7: Protection

Choose how your own access is protected.

Key file (recommended)

  1. Leave Generate key file for download on
  2. On the next step, download the file and store it immediately
  3. Upload the same file to confirm you saved it

Service secret only

  1. Turn Generate key file for download off
  2. No personal file is created
  3. Your account login protects use of the key, together with the service secret

After creation

The key is linked to the identity. It appears:

  • On that identity under Identities
  • In the identity’s DID document, as a verification method
  • In the key list when you sign a credential

If other people were added, they receive a pending request. Each of them sets up their own key file or service secret. They do not reuse yours.

Importing a Key

Import stores a key that was exported from a wallet onto an identity. You need the exported file and the passphrase that was set when it was exported. Starting an import needs CREATE_KEY, the same permission as generating a key.

  1. Open Identities
  2. On an identity, click Add Key
  3. Choose Import

Exported file

  1. Upload the exported key file. Its name starts with exported-key-
  2. Enter the Export passphrase. Only you provide this passphrase. It is not stored with the key

The wallet shows the file name, and the signature type and key type recorded in the file. You do not choose an algorithm. Those come from the file.

Key name

The identifier is filled from the file name. Change it if you want a different one, or clear it and the wallet assigns one.

Purposes, setup, and controllers

Choose purposes the same way as for a generated key. Assertion Method is the usual choice for issuing credentials.

Easy setup makes you the only controller.

Complex setup lets you define the groups. You can be a controller, and you do not have to be. Every group still needs at least one person. Each email can appear in only one group, and must belong to your company.

If you leave yourself out, you skip protection. Other people hold the key and set up their own secrets when they approve. You still supply the export passphrase.

If you include yourself, protection is the same as when you generate a key. Choose a key file or the service secret. Other people do not reuse your key file or the export passphrase.

Viewing a Key

On Identities, open the key menu and choose Details.

Meta shows the key id, type, purposes, and related metadata.

Controller shows each group’s name, the people in it, and whether each person uses a key file. It also states how many groups the key has and who must provide a secret.

Verification Method shows the public key material published for this key.

Changing Who Can Use a Key

Open the key menu and choose Manage Key Access.

You edit the same controller groups you would set up on a new key. The wallet compares your edit with the current groups and asks only the people who need to approve.

What you can change

  • Add a person to a group you belong to. From then on, any one person in that group can provide its secret. You no longer have exclusive control of that group.
  • Add a controller group when a second role must also approve. Signing then needs one secret from each group.
  • Remove a person from a group you belong to, or remove a group.
  • Rename a group you belong to. If the name is the only change, only you confirm it.

You can change the people and the name only in groups you belong to. You can still remove a group you are not in. You may remove yourself from every group, including when you are the only controller and you hand the group to someone else. A group still needs at least one person. Review warns you that you lose access when the request completes. Until then you can still use the key.

How to save a change

  1. Edit the groups
  2. Click Next and read Review
  3. Check Required approvals, and any warning about sharing a group, splitting the key across several groups, or removing yourself from the key
  4. Set a response deadline when other people must respond
  5. Click Submit request and provide your secret (upload your key file if this key uses one)

The change completes when everyone listed under required approvals has provided a secret. Until then it stays in pending requests.

Who has to approve

The review step lists this for the change you made:

  • People added to an existing group: one person who already belongs to that group, plus each new person. Other groups stay as they are.
  • Groups added, removed, or merged, or people moved between groups: every current controller, and every new person. Someone who is being removed must still approve.
  • Only your group’s name changed: only you. There is no response deadline for that confirmation.

New people create their own key file, or choose the service secret, when they approve.

Leaving a Key

Delete Personal Access removes only your access. It is available when at least one other person is already in your group, so that group can still provide its secret.

  1. Open the key menu
  2. Choose Delete Personal Access
  3. Type the key id to confirm

If you are the only person in your group, the action is hidden. Removing the last person in a group would make the key unusable. Add someone to your group and wait until that change is approved, or ask the other controllers to change the groups, before you leave.

The key stays on the identity until someone deletes it with Delete Key.

Exporting a Key

Export downloads a copy of the key, protected by a passphrase you choose. The key stays in this wallet and can still sign. The download is the key itself. It is a different file from a controller key file.

Starting an export needs EXPORT_KEY. Company administrators have it. You do not need to hold a part of the key. Controllers provide secrets until every required group has approved, the same rule as signing. They do not need EXPORT_KEY.

  1. On Identities, open the key menu and choose Export Key
  2. On Passphrase, enter a passphrase of at least 12 characters and confirm it
  3. Click Next and read Review. It states who must approve
  4. Set a response deadline when other people must respond
  5. Click Submit request. If you hold a part that uses a key file, upload that file

The passphrase is the only secret protecting the downloaded file. The wallet does not store it. If you are the only controller, the export finishes when you submit. If the key has more than one group, one person from each group provides a secret first.

The file is returned only to the person who started the export. On the finished request, click Download exported key. The file name starts with exported-key-. A controller key file starts with key-secret-. Download the file before the request expires. After that, the download is no longer available. Export again if you still need a copy.

Other controllers open the request from the bell. They see that the key stays in this wallet and that the file goes to the person who started the export. They upload their key file, or choose Approve Export when their part uses the service secret.

Deleting a Key

Delete Key removes the key from the identity and from the security module. Delete Personal Access, above, removes only your own access and leaves the key in place.

Starting a deletion needs DELETE_KEY. Company administrators have it. You do not need to hold a part of the key. Controllers provide secrets until every required group has approved, the same rule as signing and export. They do not need DELETE_KEY.

  1. On Identities, open the key menu and choose Delete Key
  2. Read the warning. The key is removed from the DID document. Credentials signed with it can no longer be verified, and the key can no longer sign or update their status
  3. Set a response deadline when other people must respond
  4. Click Delete key. If you hold a part that uses a key file, upload that file

If you are the only controller, the key is deleted when you submit, and you return to Identities. If the key has more than one group, one person from each group provides a secret first. When the last secret is in, the request page says the key was deleted.

Other controllers open the request from the bell. They see a warning that they are about to give permission for permanent deletion of the key, and that this cannot be undone. They upload their key file, or choose Approve Deletion when their part uses the service secret. The same warning is shown again when they provide the key file.

Using Keys to Sign Credentials

When you issue a credential:

  1. Select the signing identity
  2. Select the signing key
  3. Upload your key file if this key uses one
  4. Sign

If the key has more than one group, one person from each group provides a secret before the signature is complete. People in the same group are alternatives.

See Credential Management for the issuance steps.

Pending Requests

Creating or importing a key with other people, changing controller groups, exporting a key, deleting a key, and signing with more than one group all wait until the required people have provided their secrets.

Where to find them

Open the pending-requests menu in the header (the bell), or the requests on the dashboard. A request that still needs you is marked Action required. A request you have already answered is marked Waiting.

Approving

  1. Open the request
  2. Read which key it is, what the groups look like, and who started it
  3. Upload your key file if you use one, or confirm service-secret protection
  4. Submit

Only the person who starts key creation or import needs CREATE_KEY. Starting an export needs EXPORT_KEY. Starting a deletion needs DELETE_KEY. Everyone else approves with their secret.

Key Security Best Practices

Do

  • Prefer a key file for keys that sign important credentials
  • Store each key file in a password manager or encrypted vault, with a backup in a second safe place
  • Use several controller groups when two roles must both agree
  • Put more than one person in a group when any one of them should be able to stand in
  • Download the key file during setup and confirm it before you finish
  • Read a pending request before you approve
  • Name groups after the role they represent
  • Store an exported key and its passphrase together, and download the file before the request expires
  • Keep the exported file (exported-key-) apart from controller key files (key-secret-)

Don’t

  • Send a key file to anyone, including other controllers
  • Leave a key file in Downloads or in email
  • Reuse one key file for several keys
  • Approve a request you do not recognize
  • Remove the last person from a group that the key still needs
  • Share an exported key or its passphrase with anyone who should not be able to import that key
  • Delete a key while credentials signed with it should still verify