Skip to main content

Keys

Keys are cryptographic key pairs used to create signatures and enable authentication in decentralized identity ecosystems. This page explains how keys work in Procivis One and how to use them.

Overview​

Procivis One enables you to create asymmetric key pairs that can be used to:

  • Authenticate between parties
  • Generate Certificate Signing Requests (CSRs)
  • Create DIDs (Decentralized Identifiers)
  • Serve as direct identifiers for credential issuance (where supported)

Each key pair consists of a public key (visible through the API as publicKey) and a private key (used for signatures, never exported or visible).

Supported algorithms​

For the complete list of supported key algorithms and their configuration values, see:

Key storage​

Keys can be stored in different locations depending on your deployment and security requirements.

Internal storage​

An encrypted internal database solution suitable for evaluation and non-critical use cases. See the keyStorage reference for configuration details.

Azure Key Vault​

A cloud-based solution backed by software and hardware-security modules (HSM). Keys stored in HSM-backed solutions offer enhanced security but cannot be exported or transferred.

Learn more: Azure Key Vault documentation

Hardware-based keys are device-bound

Keys stored in hardware security modules are cryptographically tied to their storage device and cannot be backed up or transferred. Credentials signed with hardware-based keys are bound to that device.

Mobile device storage​

Software storage: Keys stored in the device's encrypted internal database can be backed up and transferred to another device.

Hardware storage: Mobile devices with supporting hardware can use chip-based storage for enhanced security:

Use SECURE_ELEMENT as the storageType when generating keys with hardware storage.

Hardware-based keys are device-bound

Keys stored in device hardware cannot be exported or transferred. Credentials signed with hardware-based keys are bound to that device.

Remote Secure Element (RSE)​

Available for Procivis One Wallet, RSE provides HSM-backed security with device portability. A secure link connects the mobile device to tamper-resistant hardware in a data center, where keys are stored. Users authenticate each key use with a PIN or biometrics.

Unlike other HSM solutions, RSE connections can be transferred to a new device, allowing you to change devices while retaining your keys.

Working with keys​

Create a key pair​

Key operations

Core API | Desk API

When creating a key, specify:

  1. Key algorithm: Reference a supported algorithm from your configuration (e.g., EDDSA, ES256, BBS_PLUS, ML_DSA)

  2. Key storage: Reference a configured storage instance from your deployment configuration

Storage configuration allows multiple instances of the same storage type. Always reference the specific configuration instance you want to use. For example, to use this storage configuration:

keyStorage:
  DATABASE:
    display: 'keyStorage.internal'
    type: 'INTERNAL'
    order: 0

Reference DATABASE when creating your key.

Use a key as an identifier​

Some credential formats support using keys directly as identifiers, without requiring a DID or certificate. To check if a credential format supports this:

  1. Retrieve the credential format configuration

  2. Check for these capabilities:

  • "issuanceIdentifierTypes": "KEY"
  • "verificationIdentifierTypes": "KEY"

To use a key as an identifier:

  1. Create a key

  2. Create an identifier referencing that key

Related: Create an identifier

Generate a Certificate Signing Request​

CSR operations

Core API | Desk API

CSRs can be generated using ECDSA or EDDSA keys for two main purposes:

Credential issuance: Some formats (like ISO mDOC) require a document signing certificate. Generate a CSR using the mDL profile, submit it to a Certificate Authority, then import the signed certificate as a certificate identifier.

Certificate Authority setup: When configuring CA infrastructure for Access Certificate issuance, generate a CSR with the CA profile and submit it for external signing. Alternatively, create a self-signed root CA directly through the identifiers API.

After receiving a signed certificate, import it using the POST /identifier endpoint.