Docs Using the wallet Protecting your keys

Protecting your keys

How to keep a key file safe, how an exported key differs from that file, and what to check before you approve a signature.

Protecting Your User Secrets

Understanding User Secret Key Files

A user secret is a key file you keep. It is a second factor for the cryptographic private key, in the same spirit as the extra confirmation a banking app asks for, and close to a passkey. The private key stays in the wallet’s hardened key module and is a different secret from this file. You decide where the file is stored. The wallet does not keep a copy. If you do not use a user secret, your account login and the service secret protect use of the key. See user secrets.

Key file characteristics:

  • A second factor, not the private key: the file lets the wallet use the private key; it is not the private key
  • You choose where it lives: a password manager, an encrypted vault, or a safe
  • Never stored on the server: only you possess the key file
  • Unique per key: use a different file for each key
  • Optional: your login and the service secret protect the key when you skip the file

When to use user secrets:

  • High-security keys for signing important credentials
  • Keys with significant authority or value
  • Multi-controller keys where each controller wants their own layer of protection
  • Compliance requirements for additional encryption layers

When you might skip user secrets:

  • Low-risk testing or development keys
  • Convenience is prioritized over maximum security
  • Service secret encryption is sufficient for your use case

Storing Your Key Files

Recommended storage methods for key files:

  1. Password manager with file storage (1Password, Bitwarden, KeePass)
    • Encrypted storage
    • Easy retrieval
    • Backup included
    • Can store key files securely
  2. Encrypted vault or key management system
    • Dedicated secure key storage
    • Access controls
    • Audit logging
  3. Physical safe with backup
    • USB drive in safe
    • Encrypted disk
    • Offline storage
    • Physical security

Do not store key files:

  • In unencrypted folders on your computer
  • In email or messaging apps
  • In cloud storage without encryption (Google Drive, Dropbox, etc.)
  • In publicly accessible locations
  • Without backup copies
  • In shared folders or network drives

Protecting Key Files in Use

When uploading/using key files:

  • Use private, secure location
  • Remove key files from temporary locations after upload
  • Ensure the key file comes from your secure storage
  • Don’t leave key files in Downloads folder
  • Don’t upload from publicly accessible locations

Exported keys

An exported key is a copy of the signing key, protected by a passphrase. It is a different file from a controller key file. The download name starts with exported-key-. A controller key file starts with key-secret-.

  • The passphrase is the only protection on the exported file. The wallet does not store it
  • Store the file and the passphrase in a password manager or encrypted vault
  • Anyone with both can import the key into a wallet
  • Download the file before the export request expires

See Exporting a Key and Importing a Key.

Key Security

Using Multi-Controller Keys

For high-value operations, use multi-controller keys:

When to require multiple controllers:

  • Issuing credentials containg claims that are aggreed on by a commitee
  • Issuing high-value credentials (certifications, licenses)
  • Credentials with legal implications
  • Operations affecting many users

Benefits:

  • No single person can act alone
  • Insider threat mitigation
  • Separation of duties
  • Audit trail of approvals

Setting up:

  1. Create key with multiple controllers
  2. Each controller can optionally configure their own user secret key file
  3. All must approve to use key (providing key files if configured)
  4. See “Key Management” section for details

Access for other people

Who can sign in, and which role they have, is set by an administrator. See Roles and permissions.

Operational Security

Secure Workflow Practices

Before issuing credentials:

  • Verify recipient identity
  • Confirm authorization to issue
  • Use correct credential template
  • Review all claims for accuracy
  • Select appropriate expiration date

When signing credentials:

  • Verify you’re using correct key
  • Confirm this is the intended operation
  • Ensure you have the correct user secret key file (if required)
  • Don’t approve operations you don’t recognize

After issuing:

  • Verify the credential appears correctly
  • Confirm it is published, if that was the intent
  • Record the issuance outside the wallet when your process requires it

Recognizing Security Threats

Suspicious activity:

  • Operations you don’t recognize in audit log
  • Credentials issued you didn’t authorize
  • Pending requests you didn’t expect
  • Failed login attempts
  • Operations at unusual times (middle of night)

System indicators:

  • Unexpected error messages
  • Slow performance suddenly
  • DIDs failing to resolve
  • Missing credentials or keys

If you see these, report immediately to your administrator.