Skip to main content

Keys

Learn how to work with keys.

Keys are used in decentralized identity ecosystems to create signatures and for authentication between parties. On this page you'll learn more about what they are, what kinds of keys are supported, and how to handle keys with Procivis One.

Keys in Procivis One​

The system enables you to create cryptographic key pairs using a number of different algorithms. These keys can then be used to create DIDs and Certificiate Signing Requests (CSRs), which are in turn used for authentication between parties.

The keys are asymmetric key pairs. Each key is comprised of one public key and one private key. These keys are inextricably linked together, cryptographically. The public key can be seen in the system — publicKey in the Core code base — while the private key, used to create signatures, cannot be exported and is not visible through the API.

Supported key algorithms​

EdDSA​

Configuration reference: EDDSA

Edwards-Curve Digital Signature Algorithm is a digital signature scheme that functions over elliptic curves. The EdDSA algorithm with edwards25519 curve is supported. See the W3C Data Integrity EdDSA Cryptosuites v1.0 for more information.

ES256​

Configuration reference: ES256

ES256 is the Elliptic Curve Digital Signature Algorithm with the P-256 curve and the SHA-256 cryptographic hash function. See the IETF proposed standards for JSON Web Algorithms for more information.

BBS+​

Configuration reference: BBS_PLUS

BBS+ is a digital signature scheme that supports several privacy-enhancing features, including selective disclosure, allowing holders to produce proofs which are subsets of the original credentials, thereby only sharing certain required claims and withholding all information related to other claims.

BBS+ uses the SHA-256 cryptographic hash function. For Procivis One, the Data Integrity BBS Cryptosuites v1.0 specification is implemented for W3C VCDM 2.0.

CRYSTALS-Dilithium​

Configuration reference: DILITHIUM

ML-DSA is a lattice-based digital signature algorithm designed to be resistant to attacks by quantum computers. See the NIST documentation for more information.

ML-DSA is an implementation of CRYSTALS-Dilithium, a digital signature scheme from the Cryptographic Suite for Algebraic Lattices (CRYSTALS), a Post-Quantum Cryptography suite. See the official page from the CRYSTALS team.

Supported key storage types​

Internal​

An encrypted internal database solution for key storage can be configured for the system. Intended for evaluation and non-critical use cases.

Azure Key Vault​

Azure Key Vault is a cloud-based solution for storing and accessing keys backed by software and hardware-security modules (HSM). See the Azure Key Vault docs for more information.

Hardware-based keys are bound to one device

Since hardware-based keys are inextricably linked to the device where they are stored, they are not exportable and cannot be backed up or transferred onto another device. Credentials signed by hardware-based keys are thus tied to one device.

Hardware storage​

Mobile devices with supporting hardware can take advantage of chip-based key storage for added security. A wallet initialized with either Secure Enclave for iOS or Keystore for Android can use SECURE_ELEMENT as its storageType when generating keys.

Hardware-based keys are bound to one device

Since hardware-based keys are inextricably linked to the chip where they are stored, they are not exportable and cannot be backed up or transferred onto another device. Credentials signed by hardware-based keys are thus tied to one device.

Remote Secure Element​

Mobile devices using the Procivis One Wallet can take advantage of "Remote Secure Element" (RSE), a hardware-security module (HSM)-backed implementation using Ubiqu. A secure link is established between the device and tamper-resistant hardware in a data center; keys are stored on the hardware and users must input a PIN code or biometrics with each key use.

Unlike other HSM-backed solutions, RSE connections can be transferred to a new device, making it possible to switch devices and keep your keys.

Working with keys​

Key operations

Core API | Desk API | SDK

To create a key:

  • Choose a key algorithm
  • Choose where to store it

In both cases, when passing your choice you must reference the configuration instance.

For key algorithms, the configuration reference must be from this list:

  • EDDSA
  • ES256
  • BBS_PLUS
  • DILITHIUM

For key storage, you must check your configuration for supported options. Key storage configuration allows for multiple instances of the same type of storage. Check the configuration for your options and always reference the configuration instance you want to use.

For example, if you want to use the following key storage:

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

you would reference DATABASE.

Working with CSRs​

Key operations

Core API | Desk API

The system enables you to create a CSR using an ES256 or EDDSA key.

Some credential formats require a Document Signing Certificate (DSC) to be used during issuance. This can be obtained by creating a Certificate Signing Request (CSR) and submitting that to a Certificate Authority (CA) for validation.