Cosmian provides readily available, easy to use software components, based on next-generation cryptography to secure data and applications in all environments, from the cloud to the edge.

This is the technical documentation

This site provides the technical documentation of the components. It provides information for technical users, architects to developers.

The documentation is divided by security use cases and then by products.

Security use cases

1. Architecture security of data and applications with a mapping of threats to solutions and a review of common architecture uses cases.

2. Use modern encryption schemes such as:

   • Advanced encryption schemes on client-side encryption (or application level encryption) and server-side encryption:

     • Cosmian Covercrypt: Protect data with the latest post-quantum encryption, access control, and traceable keys.

     • Cosmian KMS: Central point of security for managing encryption keys and enabling server-side encryption.

   • Alternative encryption schemes

     • Cosmian FPE: Selectively encrypt data while preserving the data format with format-preserving encryption.

     • Anonymizing clear-text data with Cosmian Anonymization

3. Compute over encrypted data with Cosmian's Verifiable Confidential Computing solutions:

   • Solutions based on Confidential Virtual Machine:

     • Cosmian VM: quickly secure data in any running application in the cloud.

     • Cosmian AI: Benefit of Cosmian VM and leverage advanced AI models with built-in privacy and security features.

   • Solutions based on Intel SGX enclave:

     • Cosmian Enclave (formerly MSE): protects algorithms and data in the cloud and on 3rd party premises with maximum security.

4. Searching encrypted data with Cosmian Findex and Findex server: run encrypted queries on an encrypted index.

Cosmian products

1. Cosmian KMS: A modern, open-source, highly-scalable key management system that is KMIP 1.x/2.x compliant.
2. Cosmian VM Secure data in any running application in the cloud.
3. Cosmian AI: Leverage advanced AI models with built-in privacy and security features.
4. Cosmian Enclave: Protect algorithms and data in the cloud and on third-party premises with maximum security.
5. Cosmian Findex Server: Run encrypted queries on an encrypted index with server-side capabilities.
6. Cosmian CLI: Command-line interface for managing and interacting with Cosmian's suite of tools.

If you want to see our technology in action and "play" with it, please visit our Interactive Tutorial

For pricing, check the website

For pricing information, general information on Cosmian and its products, please visit our website

All our code is open-sourced on GitHub

All our code is available on GitHub

Chat with us

To chat with our technical team, please join our Discord server

Legal

End User License Agreements

• EULA (AWS)

• EULA (Azure)

• EULA (GCP)

Terms and Conditions

• For Packs

The first step in understanding how to secure data and applications in a zero-trust environment is to look at potential attackers and their threat model. We assume the application code is safe and that we do not need to protect against the software developer.

Protection against all attackers

Client-side encryption is the only ubiquitous solution that protects against all attackers because data is encrypted by the data owner under its own key before it reaches any of these attackers. Enabling client-side encryption without loss of functionality usually requires a modification to the application and the use of a few Cosmian products: Cosmian Covercrypt, Cosmian KMS, and possibly Cosmian VM and Cosmian Findex.

See the last use case on this page for details.

Protection against a reduced list of attackers

When the threat model is limited to a reduced list of attackers, other solutions may be used. The following table summarizes the solutions that Cosmian provides to protect against each attacker.

Use case: move to the cloud

When moving an application for its own users to the cloud, the main threat is the cloud provider itself. It is assumed that the system administrators and the application administrators are trusted.

In that particular case the use of TLS connections to applications running in Cosmian VMs with a simple at-rest encryption scheme is sufficient to protect the data and the application from the cloud provider. The Cosmian VM integrity is remotely verifiable by the user, preventing the infrastructure administrator from tampering with the VM hardware or software.

Use case: protect code at client's premises (or client's cloud)

When the application code is to be deployed at a client premises (or cloud), and needs to remain secret (such as an AI model), the main threat is the client's system administrator.

Cosmian Enclave is the solution that lets the code provider encrypt its code under its own key, deliver it encrypted to the client's system administrator. The encrypted code is then loaded in an enclave with encrypted memory, and before securely provisioning the code encryption key to the enclave, the code provider can then verify that the code is correctly deployed inside the enclave. Check this section for more details.

Use case: a 3rd party SaaS platform running in the cloud

From a user's perspective this is the use case where its data is exposed to all potential attackers: client side encryption will be the answer to protecting its data.

Enabling client-side encryption

From the SaaS provider perspective, this means making a client-side encryption API available to its users. If the application offers a web interface, the web application will need to be modified to encrypt the data before sending it to the servers. Encryption will require the ability to connect to a KMS from the web application. Performing encryption client-side will require

• either Cosmian javascript (or Dart, or Java, etc.) encryption libraries running client-side with calls to the Cosmian KMS server to fetch keys
• or direct encryption/decryption calls to the Cosmian KMS which can perform encryption on the fly in a scalable manner.

An example: Google Workspace

Google Workspace is a good example of a SaaS application that offers client-side encryption out of the box. Google made an API available that allows connecting compatible Key Management Systems such as Cosmian KMS to encrypting data in the browser.

Thanks to Cosmian VM, the user does not even have to install its KMS on premise. The KMS can be deployed in a Cosmian VM on GCP, which will protect it from Google and its browser can connect to it over a TLS connection.

Likewise, other services, such as document summarization using a language model, can be deployed in a Cosmian VM and made available to the user through a web interface. The user's data will be encrypted by the TLS connection to the AI service and will only be available to service in encrypted memory which is protected from Google.

Cosmian VM and Cosmian KMS are now offered as IaaS services on the marketplaces of all major hyperscalers Azure, AWS and GCP.

• Cosmian VM and KMS on AWS Marketplace
• Cosmian VM and KMS on Azure Marketplace
• Cosmian VM and KMS on GCP Marketplace

SaaS platform: distributing keys between clients

When using client-side encryption in a SaaS platform setting, some users may need to be able to decrypt data from another user that was encrypted with a key that they do not have. This is the case, for example, when a user shares a document with another user. The document is encrypted with the key of the user that created it.

The Cosmian KMS offers a key sharing mechanism that allows users to share keys with other users. The key sharing mechanism is based on a standard Public Key Infrastructure (PKI) available in the KMS which offers the ability to wrap a decryption key under the public key of another user. The receiving user can then unwrap the key using its own private key.

The users can safely use the Cosmian KMS PKI deployed in the cloud because the KMS does not have access to the private keys of the users.

Say Client 1 wants to provide Client 2 with a decryption key sk_a to decrypt data previously encrypted with Covercrypt with Client 1's public key pk_1.

This decryption key is sensitive and should be wrapped under Client 2's public key to be transferred from Client 1's KMS to Client 2's KMS. Since their KMS cannot communicate, the clients are using the Public Key Infrastructure (PKI) built in Cosmian KMS to exchange keys.

The typical flow for the distribution of a decryption key is illustrated in the following diagram.

Say Client 1 wants to provide Client 2 with a decryption key sk_a to decrypt data previously encrypted under Client 1's key.

1. Client 2 (the recipient) generates a key pair sk_2/pk_2 and publishes its public key pk_2 wrapped in a certificate to the SaaS PKI.
2. Client 1 recovers Client 2's certificate containing pk_2.
3. Client 1 wraps (i.e., encrypts) the decryption key sk_a under the public key pk_2 and publishes the wrapped key in the SaaS PKI.
4. Client 2 recovers the wrapped key sk_a from the SaaS PKI and unwraps it (i.e. decrypts it) using its private key sk_2.

Covercrypt is a post-quantum public key encryption scheme that allows encrypting data for a set of attributes in order to provide fine-grained partitioning.

Covercrypt is being developed in partnership with the ENS cryptographic Lab , has been published at the ESORICS 2023 conference and is being standardized at ETSI. Covercrypt is coded in Rust and the source is available on GitHub.

Unique Decryption Keys with Access Policies

Consider the following 2 policy axes, Department and Country which data are partitioned by the following attributes:

1. Department, Finance, Marketing, Human Res. and Sales
2. Country, France, UK, Spain and Germany

Each pair (Department, Country) constitutes one of the $4^2=16$ data partitions.

When defining the Policy for these partitions, Covercrypt offers the ability to selectively choose which partition is protected by post-quantum cryptography.

With Covercrypt, the encryption key is public. Encrypting systems (A browser, a mobile phone, a Spark process, data engineering applications, ETLs, etc...) do not have to be secured and can directly hold the key, relaxing constraints on the infrastructure. The public key can encrypt for any partition defined by the policy.

Decryption keys can decrypt a subset of the partitions defined by the policy.

Key 1 can decrypt all the France data with the following access policy:

Country::France

Key 2 can decrypt all the Sales data with the following access policy:

Department::Sales

Key 3 can decrypt the Marketing and Sales data from Spain and Germany with the following access policy:

(Department::Marketing || Department::Sales) && (Country::Spain || Country::Germany )

User keys are truly unique: even though two users have the same access policy, their key fingerprints will be different. This makes it much easier for forensic cyber teams to trace a key leak.

Policy axes can be hierarchical. Suppose three levels on a Confidentiality axis: Medium, Secret, and Top Secret. This hierarchical axis will let users with a Top Secret attribute in their key access policy decrypt Medium, Secret, and Top Secret data – whereas users with a Medium attribute will only be able to decrypt Medium data.

Finally, attributes can be rotated providing forward secrecy on selected partitions only.

The libraries are available in multiple languages to facilitate encryption close to the data source and decryption close to the decryption target, including mobile devices and browsers.

This section describes the Application Level Encryption API, the Encrypted Search API is on this page.

Supported Languages

The application-level encryption scheme is called Covercrypt. It is open-source and written in Rust. For the cryptographic documentation and implementation details, please check its GitHub repository.

Unless low-level programming in Rust, implementers should use Covercrypt through the various cloudproof_xxx user libraries:

• cloudproof_java: the Cloudproof Java Library,
• cloudproof_js: the Cloudproof Javascript Library,
• cloudproof_python: the Cloudproof Python Library,
• cloudproof_flutter: the Cloudproof Flutter Library.
• cloudproof_spark: the Cloudproof Spark Library.

All these libraries are open-source and available on GitHub

The user libraries all contain extensive tests, and it is highly recommended to start by hacking those tests.

Installing the Libraries

It is possible to create keys using the libraries; however, it is more likely that you will want to store them in a KMS. Please go to the KMS documentation to fetch and run a local KMS.

npm install cloudproof_js

<dependency>
  <groupId>com.cosmian</groupId>
  <artifactId>cloudproof_java</artifactId>
  <version>8.0.1</version>
  <type>jar</type>
</dependency>

python3 scripts/get_native_libraries.py

byte[] ciphertext = CoverCrypt.encrypt(...);

pip install cloudproof_py

from cloudproof_py.cover_crypt import Policy, PolicyAxis, Attribute, CoverCrypt

# needed if you use Cosmian KMS
from cloudproof_py.kms import KmsClient

flutter pub add cloudproof

#include "cloudproof.h"

g++ main.cpp -o main -I include/ -L lib/ -lcloudproof
LD_LIBRARY_PATH=lib ./main

g++ main.cpp -o main -I include/ -L lib/ -lcloudproof
DYLD_FALLBACK_LIBRARY_PATH=lib ./main

cl main.cpp  /I "include" /link "lib/libcloudproof.dll.a" /OUT:main.exe
main.exe

Creating a Policy

A policy defines the space of rights that are used for encryption. It is composed by a set of axes that contain attributes.

For example, the following two axes are divided into four attributes and define a policy:

1. Department: Finance, Marketing, Human Res., Sales
2. Country: France, UK, Spain, Germany

A combination of axis attributes is associated to a partition. For example Department::Finance && Country France points to a valid partition under the above policy.

An access policy is defined by a set of partitions. It can be written as a boolean expression of axis attributes:

(Department::Marketing || Department::Sales) && Country::France

In the following demo, we will create a policy that combines two axes, a security level, and a department. A user will be able to decrypt data only if it possesses a key with a sufficient security level and the correct department.

Policy Axes

Security Level Axis:

The first policy axis is the Security Level. It is hierarchical and is composed of 3 levels: Protected, Confidential, and Top Secret. Since this axis is hierarchical, when a user is granted access to a given level, it is granted access to all lower levels. The attributes must be provided in ascending order.

Department Security Axis:

The second policy axis is the Department axis. It is composed of 3 values: HR, MKG, and FIN. This axis is not hierarchical: granting access to an attribute of this axis to a user does not give access to any other attribute.

Hybridization

Covercrypt offers the possibility to hybridize the classic asymmetric scheme with the winner of the NIST post-quantum algorithm selection process: Kyber. Hybridization can be applied with granularity since it is specified at the attribute level. A partition corresponding to a combination of attributes with at least one hybridized attribute is hybridized. Any data encrypted for a hybridized partition will result in a hybridized ciphertext.

Rotations

Rotations allow to refresh the value of a given partition. The maximum number of creations of partition values is set in the policy.

Generating the Master Keys

The master authority possesses the master key pair:

• a master secret key which is used to generate user keys;
• and a public key which is used for encryption. Since it cannot decrypt, the public key can be freely distributed to encrypting systems.

Encrypting Data

Data is encrypted using the Public Key and an encryption policy that determines the target partitions of the ciphertext.

Anyone who has access to the Public Key can encrypt data, however, only users possessing user keys with the right access policy can decrypt the ciphertext.

A Covercrypt ciphertext is the concatenation of an encrypted header and an encrypted content.

• The encrypted content is a plaintext symmetrically encrypted using an ephemeral secret key (i.e. a random key generated on the fly).
• The header is the encapsulation of the ephemeral key for a given encryption policy, concatenated with some optional metadata. The metadata, if present, is symmetrically encrypted using the same ephemeral key.

Header and encrypted content can be generated separately using the various APIs. Check the inline documentation of the various languages and the test suites for details.

The code below shows the encryption of 3 messages with 3 different encryption policies targeting 3 different partitions.

Generating User Decryption Keys

User Decryption Keys are generated from the Master Private Key using access policies.

Let us create 2 users with different access policies to illustrate their effect.

Decrypting Ciphertexts

The confidential marketing user can successfully decrypt a protected marketing message:

.. however, it can neither decrypt a marketing message with higher security:

... nor decrypt a message from another department even with lower security:

As expected, the top-secret marketing financial user can successfully decrypt all messages

Rekeying keys

At any time the Master Authority can generate new keys for any access policy.

When that happens future encryption of data for a given access policy cannot be decrypted with keys that have not been "refreshed".

It is best to perform rekeying using the KMS to automatically refresh each user key if it is active in the KMS (the key has not been revoked).

rekeying all keys having access to "Department::MKG"

This operation will rekey all keys with access to Department::MKG. It is also possible to rekey all keys with a precise access policy like Department::MKG && Security Level::Protected.

You successfully rekeyed the master keys and all active user keys with access to marketing data.

Pruning keys

After a rekey operation, the affected keys will store both the old and the newly generated subkeys to be able to decrypt old and new ciphertexts. If you only need access to the new ciphertexts, you can save space by pruning these keys.

By performing the pruning operation using a KMS, the active user keys will be automatically synced with the master keys.

WARNING: This operation will permanently remove access to old ciphertexts for the pruned access policy.

pruning all keys having access to "Department::MKG"

The master and user keys will only keep the latest subkeys associated to the access policy Department::MKG.

Pruned keys will only be able to decrypt ciphertexts generated after the last rekey operation for the corresponding access policy.

Policy editing

The Policy in use by a KMS can be modified on the fly through various operations:

• Rename attributes: purely visual modification of the Policy.

• Add new attributes to an existing Policy dimension. ONLY supported by unordered dimension.

• Disable attributes: soft removal of an attribute, prevents the encryption of new messages for this attribute while keeping the ability to decrypt existing ciphertexts.

• Remove attributes: will permanently remove the ability to use this attribute in both encryptions and decryptions. ONLY supported by unordered dimension.

The masters keys and users keys will automatically be updated accordingly by the KMS.

Rename attributes

Specify the existing attribute Dimension::Name and the desired name for the attribute NewName. The resulting attribute will be Dimension::NewName.

rename attribute "MKG" to "Marketing"

The rename operation is purely visual and will not impact the existing user keys and ciphertexts.

From now on, be sure to use the new attribute name when encrypting data or issuing new user keys. New messages can still be decrypted by marketing user keys created before the renaming and vice versa.

Add attributes

Add a new attribute to an unordered dimension, specify the attribute to create with Dimension::Name and whether to use hybridized keys.

add new attribute "Department::R&D"

Create a non-hybridized attribute R&D in the existing dimension Department.

The newly added attribute can be used to encrypt and generate keys as seen previously.

Disable attributes

Remove the ability to encrypt new message for an existing attribute using the KMS. Existing messages associated to the disabled attribute will remain readable.

disable attribute "Department::R&D"

Prevent the generation of new R&D messages while keeping access to existing ones.

Encryption of new R&D messages is no longer possible.

Remove attributes

Completely removes an attribute from the policy and from all associated keys in the KMS.

WARNING: Encryption and decryption for this attribute will no longer be possible after this operation. We strongly recommend to make a local copy of the master secret key beforehand, otherwise messages whose encryption policy does not contain any other attributes belonging to the dimension of the deleted attribute will be lost.

remove "Department::R&D"

All user keys in the KMS associated with this attribute will automatically loose the ability to decrypt for this attribute.

Ciphertexts for which the only Department access was R&D are now unreadable by all KMS keys.

The Whole Code

The code used in this documentation as well as more examples can be found for each library:

Format Preserving Encryption

Format Preserving Encryption (FPE) is a cryptographic technique standardized in NIST SP 800-38G specification that allows the encryption of data while preserving its original format or structure. Unlike traditional encryption methods that transform data into ciphertext with a different format, FPE ensures that the encrypted output maintains the same format as the original input, such as preserving the length, character set, and other specific formatting requirements.

The purpose of Format Preserving Encryption is to provide confidentiality for sensitive data while minimizing the impact on applications or systems that rely on the original data format. This technique finds applications in scenarios where data format constraints are critical, such as databases, legacy systems, or data interchange processes.

FPE-FF1, the underlying cryptographic primitive, is a normalized algorithm that uses symmetric encryption, but it's not as fast or secure as standardized symmetric (or public key) encryption methods like AES or ChaCha. It should only be used where the format of the ciphertext container is constrained (e.g., a fixed database schema that cannot be changed).

Features

Cosmian FPE implementation supports the encryption of strings, floats and big integers.

In order to keep the format of the input plaintext, the alphabet used for plaintext must be specified.

There are multiple pre-defined alphabets available:

• alpha-> abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
• alpha_lower-> abcdefghijklmnopqrstuvwxyz
• alpha_upper-> ABCDEFGHIJKLMNOPQRSTUVWXYZ
• numeric-> 0123456789
• hexa_decimal-> 0123456789abcdef
• alpha_numeric-> 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
• chinese
• latin1sup
• latin1sup_alphanum

These alphabets can easily be extended with any character.

Implementations and quick start

The FPE techniques are open-source and written in Rust. For the cryptographic documentation and implementation details, please check its GitHub repository.

Unless low-level programming in Rust, implementers should use those techniques through the various Cloudproof user libraries:

• cloudproof_js: the Cloudproof Javascript Library,
• cloudproof_python: the Cloudproof Python Library,

All these libraries are open-source and available on GitHub

The user libraries all contain extensive tests, and it is highly recommended to start by hacking those tests.

Setup

npm install cloudproof_js

pip install cloudproof_py

from cloudproof_py.cover_crypt import Policy, PolicyAxis, Attribute, CoverCrypt

# needed if you use Cosmian KMS
from cloudproof_py.kms import KmsClient

Encrypting integers

The most common example when using FPE is the encryption of credit card numbers. Here the alphabet numeric is used (characters of this alphabet being 0123456789) as follows:

Here are various examples for integers encryption:

Encrypting chinese plaintexts

Using the chinese alphabet can be done as follows:

Encrypting using a custom alphabet

Data Anonymization

Data anonymization is the process of transforming data in such a way that it can no longer be used to identify individuals without the use of additional information. This is often done to protect the privacy of individuals whose data is being collected or processed.

Anonymization techniques can include removing identifying information such as names and addresses, replacing identifying information with pseudonyms, and aggregating data so that individual data points cannot be distinguished. It's important to note that while anonymization can reduce the risk of re-identification, it is not foolproof and must be used in conjunction with other security measures to fully protect personal data.

Features

Cosmian anonymization provides multiple methods:

• Hashing: transforms data into a fixed-length representation that is difficult to reverse and provides a high level of anonymity.

• Noise Addition: adds random noise to data in order to preserve privacy. Support various types of noise distributions to float, integer, and date.

• Word Masking: hides sensitive words in a text.

• Word Pattern Masking: replaces a sensitive pattern in text with specific characters or strings. Supports Regex.

• Word Tokenization: removes sensitive words from text by replacing them with tokens.

• Number Aggregation: rounds numbers to a desired power of ten. This method is used to reduce the granularity of data and prevent re-identification of individuals.

• Date Aggregation: rounds dates based on the specified time unit. This helps to preserve the general time frame of the original data while removing specific details that could potentially identify individuals.

• Number Scaling: scales numerical data by a specified factor. This can be useful for anonymizing data while preserving its relative proportions.

• Format preserving encryption: encrypts data preserving its format.

Implementations and quick start

The data anonymization techniques are open-source and written in Rust. For the cryptographic documentation and implementation details, please check its GitHub repository.

Unless low-level programming in Rust, implementers should use those techniques through the various Cloudproof user libraries:

• cloudproof_java: the Cloudproof Java Library,
• cloudproof_js: the Cloudproof Javascript Library,
• cloudproof_python: the Cloudproof Python Library,
• cloudproof_flutter: the Cloudproof Flutter Library.

All these libraries are open-source and available on GitHub

The user libraries all contain extensive tests, and it is highly recommended to start by hacking those tests.

Setup

npm install cloudproof_js

pip install cloudproof_py

from cloudproof_py.anonymization import (
    DateAggregator,
    Hasher,
    NoiseGenerator,
    NumberAggregator,
    NumberScaler,
    WordMasker,
    WordPatternMasker,
    WordTokenizer,
)

Hashing

The goal of hashing techniques for data anonymization is to transform sensitive or personally identifiable information (PII) into a fixed-length string of characters, called a hash value, while preserving the privacy and confidentiality of the original data. Hashing is a one-way process, meaning that it is computationally infeasible to reverse-engineer the original data from the hash value.

The supported hashing algorithms are SHA2, SHA3 and Argon2:

• SHA-2: SHA-2 consists of multiple hash functions, including SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, and SHA-512/256. These functions use the Merkle-Damgård construction and operate on a block size of 512 bits. They employ different combinations of logical functions, such as bitwise logical operations, modular addition, and logical rotation.
• SHA-3: SHA-3 is a cryptographic hash function primarily designed for data integrity, digital signatures, and message authentication codes. It takes an input of any length and produces a fixed-length hash value.
• Argon2: Argon2 is a password hashing function that is specifically designed for secure password storage. It aims to protect against password cracking attacks, such as brute-force and dictionary attacks, by incorporating memory-hardness and resistance to parallel computation.

Noise addition

The goal of the Noise Addition technique for data anonymization is to introduce random noise or perturbation to sensitive data to preserve privacy while still allowing for meaningful analysis or processing. Noise addition helps protect the confidentiality of individual records by obscuring specific details while preserving the statistical properties and patterns of the dataset.

Three noise distributions are supported:

• Laplace: The Laplace distribution, also known as the double-exponential distribution, is characterized by its peakiness around the mean and its exponential decay in the tails. It is often used to model data with heavy-tailed or skewed distributions.
• Gaussian (Normal): The Gaussian distribution, also known as the normal distribution, is a symmetric bell-shaped distribution. It is one of the most widely used distributions in statistics and probability theory, often employed to model data that is normally distributed or approximately so.
• Uniform: The uniform distribution is a probability distribution where all values within a specified range are equally likely. It forms a rectangle-shaped distribution with a constant probability density function (PDF) over the range.

The noiser object needs to be instantiated with a specified distribution and then call the method apply.

Either mean and standard deviation can be specified:

Or minimum or maximum bounds can be specified:

Noise can be added with correlated information and apply_correlated function as follows:

Word Masking

The purpose of the Word Masking technique in data anonymization is to protect sensitive information by replacing specific words or terms with more generic or generalized placeholders. This technique is commonly applied to text data, such as documents, emails, or chat logs, where preserving privacy is crucial while maintaining the overall meaning and context of the text.

Word Pattern Masking

Word Pattern Masking technique is similar to Word Masking but using a Regular Expression (RegEx).

Word Tokenization

Word tokenization involves splitting a given text or document into its constituent words, and then replace specific sensitive words.

Number Aggregation

The purpose of the Number Aggregation technique in data anonymization is to group or summarize numerical data to protect individual privacy while preserving the overall statistical properties and trends of the dataset. This technique is commonly applied to datasets containing sensitive numerical information, such as income, age, or medical measurements.

Date Aggregation

The purpose of the Date Aggregation technique is similar to the Number Aggregation technique.

Number Scaling

Data Scaling, also known as feature scaling or normalization, is a preprocessing technique used to standardize or transform numerical data to a common scale. The purpose of Data Scaling is not specifically related to data anonymization but rather to ensure that features or variables have similar ranges or distributions, which can benefit various data analysis and machine learning tasks. It aims to address issues that may arise when variables have different scales or units, which can impact the performance and accuracy of algorithms.

Format Preserving Encryption

Format Preserving Encryption (FPE) aims to encrypt plaintext while retaining its format (alphabet). FPE-FF1 is a normalized algorithm that uses symmetric encryption, but it's not as fast or secure as standardized symmetric (or public key) encryption methods like AES or ChaCha. It should only be used where the format of the ciphertext container is constrained (e.g., a fixed database schema that cannot be changed).

FPE can be applied to string, specifying an alphabet. Characters of the plaintext that belong to the alphabet are encrypted while the others are left unchanged at their original location in the ciphertext.

FPE can be applied to int or float, specifying radix and digits parameters:

Anonymization application flow

To facilitate the usage of these anonymization techniques, we offer advanced tools that simplify the process of anonymizing datasets.

Python package

Utilizing the cosmian-anonymization Python package, anonymize a dataframe based on a specified configuration stored in a JSON file. This file defines the techniques to be applied to each column along with specific parameters. The JSON configuration file adheres to a specific format and can be generated through the provided user interface (UI).

pip install cosmian-anonymization

UI generating configuration

This user interface (UI) is crafted for constructing JSON configuration files, subsequently parsed by the Python cosmian-anonymization package. Choose the appropriate technique and parameters for each column in a given data sample, and easily download the configured JSON file.

The UI is available on GitHub, and can be run locally.

Verifiable Confidential Computing

Cosmian Enclave and Cosmian VM are solutions to compute over data

• that keeps data encrypted at all times, even when in use
• and that can be remotely verified at any time, i.e., that a correct non-tampered application is currently running in encrypted memory.

In other words, these solutions ensure that you know what processes your data, and that the data is always encrypted.

Both of these solutions

• have low performance overhead compared to processing in clear text,
• do not require modifications to existing software,
• provide real-time remote verifiability of the hardware environment and the running software
• can run either on the cloud or on-premise.
• are remotely administered and verified using simple CLI tools provided by Cosmian
• do not require external key management while in use

Security Models and Use Cases

The two solutions protect applications and data against malicious infrastructure providers (cloud administrators, third-party premises administrators, etc...) that can have physical access to the machine.

• Cosmian Enclave is a solution that provides additional protection against the system administrator of the machine, i.e. someone with operating system level access. Cosmian Enclave is a sealed secured environment best-suited for scenarios where the provider of the application code - or its parameters such as a neural network - wants to protect its intellectual property from the system administrator. This is typically the case of collaborative confidential computing scenarios where the code provider wants to deploy its code (or its parameters) on a system administered by a third party, such as the data provider.
• Cosmian VM provides additional flexibility and performance and is appropriate for scenarios where the running code does not have to be protected against the system administrator. This is typically the migration of an on-premise application to the cloud, or the security upgrade of an on-premise application to allow it to process data with increased confidentiality.

Note: it is possible to "seal" a Cosmian VM by shutting down all operating system level access to the VM (such as the SSH daemon)

Cosmian Enclave

Please check the dedicated documentation at Cosmian Enclave

Cosmian VM

Please check the dedicated documentation at Cosmian VM

Summary Comparison of Cosmian Enclave and Cosmian VM

Search encrypted data

Building an index is required to search an encrypted database without having to decrypt it entirely. However, this index can also contain sensitive data and thus need to be encrypted before it can be outsourced to a Zero-Trust such as a public cloud.

Cosmian Findex is a Searchable Encryption scheme that allows building and securely retrieving information from an encrypted index.

A detailed functional description of Findex is available in its functional documentation.

Implementations

The Findex library provides a Rust implementation of the Findex algorithm. This implementation is storage-technology agnostic. This means that in order for Findex to use a given storage (e.g. a database), all it needs is a Rust implementation of the Findex DB interface on top of this storage.

Two implementations of Findex are available:

• using Cloudproof Rust library which exposes binding for other languages
• using Findex server that provides a HTTP server offering REST API.

The current documentation focuses on the Cloudproof Rust library.

The Cloudproof Rust library provides:

• implementations of the Findex DB interface for some popular databases;
• a wrapper that allows easily instantiating Findex using a selected DB interface;
• bindings to other languages (FFI/WASM/Python).

The other Cloudproof libraries build easy-to-use abstractions on top of these bindings to allow users to use the Findex API and to implement a custom Findex DB interface from languages such as JavaScript, Python or Java. See the section on DB interface implementation to know more about how to code, select and instantiate Findex with a given DB interface.

All those libraries are open-source and contain extensive tests. It is highly recommended to start by hacking some of those tests.

Using Findex using the REST DB interface

The REST DB interface relies on a DB server implementing the Findex REST API.

Setup

npm install cloudproof_js

<dependency>
  <groupId>com.cosmian</groupId>
  <artifactId>cloudproof_java</artifactId>
  <version>7.0.0</version>
  <type>jar</type>
</dependency>

pip install cloudproof_py

flutter pub add cloudproof

Instantiating Findex

Findex relies on the user to provide it with:

• the private key;
• the public label.

These are used to encrypt the index before it is sent to the DB for storage. See the security documentation to know more about the cryptographic algorithms used.

The REST DB interface requires an additional parameter: the server URL. A different server can be used for the two Findex tables. If only one URL is provided, it is used for both tables.

import { Findex, } from "cloudproof_js"

const key = randomBytes(16)
const label = 'hello, world!'
const url = 'http://localhost:8080'

const findex = new Findex(key, label)

// Instantiating an interface is performed in a dedicated step in JS since
// it is an asynchronous one.
await findex.instantiateRestInterface(serverUrl)

// Dependencies:
//
// import java.security.SecureRandom;
// import com.cosmian.jna.findex.Findex;

byte[] key = new byte[16];
SecureRandom rng = new SecureRandom();
rng.nextBytes(key);

String label = "hello, world!";

String url = "http://localhost:8080";

Findex findex = new Findex(key, label, url);

from cloudproof_findex import (Findex, Key)

key = Key.random()
label = 'hello, world!'
url = 'http://localhost:8080'

findex = Findex.new_with_rest_interface(key, label, url)

const dbPath = "./build/sqlite2.db";
await initDb(dbPath);
final key = base64Decode("6hb1TznoNQFvCWisGWajkA==");
SqliteFindex.init(dbPath, key, "Some Label");

Adding and deleting associations to and from the index

Adding associations to the index

Populating the index is done using the add API. It takes as argument a list of associations that map values to sets of keywords. Each value passed as input can then be retrieved by searching for any associated keyword.

This API returns the keywords that have been added to the index (meaning that no value where associated to these before).

The following snippet indexes the data 1337 under the keywords "John" and "Doe".

await findex.add([
  {
    indexedValue: Location.fromNumber(1337),
    keywords: ["John", "Doe"],
  }
])

HashMap<IndexedValue, Set<Keyword>> indexedValuesAndWords =
    new HashMap<>();

indexedValuesAndWords.put(
    new Location(1337).toIndexedValue(),
    new HashSet<>(Arrays.asList(new Keyword("John"),
                                new Keyword("Doe")))
);

KeywordSet res = findex.add(indexedValuesAndWords);

res = findex.add({ Location.from_int(1337): ['John', 'Doe'] })

It is also possible to index keywords under other keywords. Indexing keywords under other keywords can be seen as building a graph where nodes represent keywords and contain the data associated to them and a directed vertex from a node "A" to a node "B" represents "B" being indexed under "A".

In the following example the ID "0xA43C" represents John Doe. It is indexed under both "John" and "Doe" such that a search for either "John" or "Dow" would find the results indexed under this ID.

await findex.add([
  {
    indexedValue: Keyword.fromString("0xA43C"),
    keywords: ["John", "Doe"],
  }
])

HashMap<IndexedValue, Set<Keyword>> indexedValuesAndWords =
    new HashMap<>();

indexedValuesAndWords.put(
    new Keyword("0xA43C").toIndexedValue(),
    new HashSet<>(Arrays.asList(new Keyword("John"), new Keyword("Doe")))
);

KeywordSet res = findex.add(indexedValuesAndWords);

res = findex.add({ Keyword.from_string('0xA43C'): ['John', 'Doe'] })

Deleting associations from the index

Similarly to the add operation, the delete operation takes associations as argument. Instead of removing these associations from the index, it adds their negation. No association added before its negation was indexed can be found during a search.

The consequence is that the index size increases during this operation. The compact operation collapses negated associations, which allows deflating the index size.

Searching the index

The input of the search API is a set of keywords to search for, and an optional interrupt function.

It searches the index for all values indexed under the given keywords. If new keywords are found, the interrupt is called with all found values (both data and keywords). If it returns true, the search process is interrupted and the function returns with the data found so far, otherwise the index is searched for the keywords found in the previous search operation.

The result of the search is a map of the searched keywords to a set containing the data directly associated to them, the data associated to a keyword that is associated to them etc.

In the following example, the index is searched for "Mar". When provided, the interrupt stops the search after more than 10 results have been found.

// Search without interruption.
const results = await findex.search(["Mar"])

// Search with interruption.
let searchCounter = 0
const filteredResults = await findex.search(
    ["Mar"],
    async (results: IntermediateSearchResults) => {
        searchCounter += results.total()
        return 10 <= searchCounter
    }
)

// Search without interruption.
SearchResults results = findex.search(new String[] {"Mar"});

// Search with interruption.
SearchResults filteredResults = findex.search(new String[] {"Mar"},
                                              new Interrupt() {
     int counter = 0;

    @Override
    public boolean interrupt(Map<Keyword, Set<IndexedValue>> results)
    throws CloudproofException {
        for (Set<IndexedValue> values: results.values()) {
            counter += values.size();
        }
        return (10 <= counter);
    }
});

# Search without interruption.
results = instance.search(['Mar'])

counter = 0
def interrupt(res: ProgressResults, counter: int) -> bool:
    for _, values in res.items():
        counter += len(values)
    return 10 <= counter

# Search with interruption.
filtered_results = instance.search(['Mar'],
                                   lambda res: interrupt(res, counter))

Compacting the Index

The compact operation allows to:

• collapse negated associations;
• increase the index density;
• remove obsolete data;
• remove keywords not associated to any value (which can happen if all of them where negated values or obsolete data);
• reset any knowledge gained by an attacker watching index requests. This gives a lower bound on the frequency of the compact operation allowing to maintain the safety of index (see the Findex security documentation).

The compact operation takes as argument:

• The new key and a new label used to encrypt the index. At least one of them needs to be different from the old key and old label.
• The compacting rate, which is a float between 0 and 1 and determines how many compact operations (1/compacting_rate) would allow to compact the index entirely.
• An optional filter that it is called on all the data found during the compact operation and allows to filter out data that does not need to be indexed back (only the data that is returned from the filter is present in the compacted version of the index).

In the following example, the index is entirely compacted in one operation using the old key and a new label, and the data Location(1337) is removed from the index.

Set<Location> filteredLocations = new HashSet<Location>(Arrays.asList(new Location(1337)));

findex.compact(key, "new label", 1, new FilterLocations() {
    @Override
    public List<Location> filter(List<Location> locations)
    throws CloudproofException {
        return locations.stream()
                        .filter((Location l) -> filteredLocations.contains(l))
                        .collect(Collectors.toList());
        }
});

filtered_locations = { Location.from_int(1337) }

def filter(dataset: Set[Location]):
    res = set()
    for data in dataset:
        if data not in filtered_locations:
            res.add(data)
    return res

instance.compact(key, "new label", 1, filter)

Using Findex with other DB interfaces

The following figure describes the relationship between the user code, Cloudproof Rust, Findex and the DB interface.

+-----------------------------------------------------------------+
| +-----------------------------------------+                     |
| |  +-------+   +------+         +-----+   | //                  |
| |  | Redis |   | HTTP |   ...   | FFI |   | // DB interfaces    |
| |  +-------+   +------+         +-----+   | //                  |
| +-----------------------------------------+                     |
| |             Findex instance             |                     |
| +-----------------------------------------+                     |
|              ^                ^                                 |
|              |                |                                 |
|      +---------------+      Findex                              |
|      | Configuration |       API                                |
|      +---------------+        |                                 |
|              |                v                                 |
|           ------------------------                              |
|          /           |            \                             |
|     +-----+      +------+     +--------+     //                 |
|     | FFI |      | WASM |     | Python |     // User interface  |
|     +-----+      +------+     +--------+     //                 |
|                                                                 |
+-----------------------------------------------------------------+
|                         Cloudproof Rust                         |
+-----------------------------------------------------------------+
                                 ^
                                 |
                                 v
+-----------------------------------------------------------------+
|           Cloudproof Js/Python/Java/Flutter (optional)          |
+-----------------------------------------------------------------+
                                 ^
                                 |
                                 v
+-----------------------------------------------------------------+
|                            User Code                            |
+-----------------------------------------------------------------+

The user code calls Cloudproof Rust (directly or using a binding from one of the other Cloudproof libraries) to instantiate a Findex. It provides the configuration with the required information (which depends on the targeted DB interface). Cloudproof Rust instantiates the selected DB interface and a Findex object on top of it, which can then be used by the client code through the Findex API.

Available Rust implementations of the Findex DB interface

The following Findex DB interfaces are implemented in Cloudproof Rust:

• REST: interface relying on a server implementing the Findex REST API. It is called by passing the URL of the server to the configuration. It can be identical for the Entry Table and the Chain Table.
• SQLite: called passing a path for the Entry Table and Chain Table. The path can be identical since a dedicated SQL table (entry_table resp. chain_table) is created in the SQLite DB at the given path.
• Redis: called passing a Redis URL for the Entry Table and the Chain table in the configuration. The URL can be identical since the tokens are prefixed with an identifier allowing to determine which DB they belong to.
• Custom: each language that exports the Findex API offers the possibility to provide an custom DB interface implementation. It is called by passing the implementation of the Findex DB interface for the Entry Table and for the Chain Table. The following section describes in details how to implement this interface in different languages.

Implementing the Findex DB interface

The DB interface needs to be implemented for:

• the Entry Table;
• the Chain Table.

To understand why two tables are used, see the functional documentation. What is important to know here is that these two tables are simple key/value stores, and that the Entry Table keys and the Chain Table keys are collision free. This means that a single key/value store can be used for both of them, as long as the Entry Table keys can be retrieved for the compact operation.

The following section describes the requirement of each function from the Findex DB interface and the following table describes which function from the Findex DB interface (the columns) needs to be implemented in order to use a function from the Findex API (the rows).

          +-----------+-----------+-----------+-----------+---------------+
          | `fetch`   | `upsert`  | `insert`  | `delete`  | `dump_tokens` |
+---------+-----------+-----------+-----------+-----------+---------------+
| search  |  ET + CT  |           |           |           |               |
+---------+-----------+-----------+-----------+-----------+---------------+
| add     |  ET + CT  |     ET    |    CT     |           |               |
+---------+-----------+-----------+-----------+-----------+---------------+
| delete  |  ET + CT  |     ET    |    CT     |           |               |
+---------+-----------+-----------+-----------+-----------+---------------+
| compact |  ET + CT  |           |  ET + CT  |  ET + CT  |       ET      |
+---------+-----------+-----------+-----------+-----------+---------------+

Fetch

The fetch function takes as argument a list of keys. It returns the list of key/value pairs of each key for which a value was found. The keys that didn't match any value should not be returned.

It is needs to be implemented for the both tables, for each Findex operation.

const fetch= async (
  uids: Uint8Array[],
  table: Map<string, Uint8Array>,
): Promise<Index[]> => {
  const results = []
  for (const k of uids) {
    const v = table.get(k.toString())
    if (v !== undefined) {
      results.push(new Index(k, v))
    }
  }
  return results
}

def fetch(uids, table):
    res = {}
    for k in uids:
        if k in table:
            res[k] = table[k]
    return res

Upsert

This is the most difficult function to implement since it is in charge of ensuring the concurrence safety of the index.

It takes as argument a list of old key/value pairs and a list of new key/value pairs. For each new key, it performs the following operation atomically:

If the current value stored under this key equals the old value given for this key, replace the current value with the new value. Otherwise, if the current value is not defined, return an error. Otherwise stack the current key/value pair for return.

The returned value is therefore the map of current key/value pairs for which the corresponding old key/value pair was different. If no conflict happened nothing should be returned.

It needs to be implemented for the add and delete Findex operations for the Entry Table only.

const upsert = async (
  oldValues: UidsAndValues,
  newValues: UidsAndValues,
  table: Map<string, Uint8Array>,
): Promise<UidsAndValues> => {
  const rejected = [] as UidsAndValues

  // Add old values in a map to efficiently search for matching UIDs.
  const mapOfOldValues = new Map()
  for (const { uid, value } of oldValues) {
    mapOfOldValues.set(uid.toString(), value)
  }

  for (const { uid, value: newValue } of newValues) {
    const currentValue = table.get(uid.toString())

    if (currentValue?.toString() === mapOfOldValues.get(uid.toString())?.toString()) {
      table.set(uid.toString(), newValue)
    } else if (currentValue === undefined) {
      throw new Error(
        "Rust shouldn't send us an oldValue if the table never contained a value… (except if there is a compact between)",
      )
    } else {
      rejected.push({ uid, value: currentValue })
    }
  }
  return rejected
}

def upsert(old_values: dict, new_values: dict, table: dict):
    res = {}
    for uid, new_value in new_values.items():
        current_value = entry_table.get(uid)
        old_value = old_values.get(uid)
        if old_value == current_value:
            entry_table[uid] = new_value
        elif not current_value:
            raise ValueError('current value for uid ' + uid
                + ' needs to be defined as long as the old value is defined')
        else:
            res[uid] = current_value
    return res

Insert

It takes as input a list of key/value pairs. It stores each pair and returns. An error should be returned if there already was a value for any given key.

It needs to be implemented for the add, delete and compact Findex operations for the Chain Table and for the compact operation only for the Entry Table.

const insert = async (
  links: UidsAndValues,
  table: Map<string, Uint8Array>,
): Promise<void> => {
  for (const { uid: newUid, value: newValue } of links) {
    table.set(newUid.toString(), newValue)
  }
}

def insert(items: dict, table):
    for uid, value in items.items():
        if uid in table:
            raise ValueError('collision on insert for UID: ' + uid)
        table[uid] = value

Delete

It takes as argument a list of keys. It removes all values stored for those keys from the DB.

It needs to be implemented for both tables for the compact Findex operation only.

def delete(uids, table):
    for uid in uids:
        table.pop(uid)

Dump tokens

It returns all keys stored in the Entry Table.

def dump_entry_tokens(table: dict):
    return table.keys()

Instantiating Findex with a custom DB interface

Given that the required functions have been implemented, Findex can then be instantiated with a custom DB interface.

await loadWasm()

const entryTable: Map<string, Uint8Array> = new Map()
const chainTable: Map<string, Uint8Array> = new Map()

const entryInterface = new DbInterface()
entryInterface.fetch = async (uids: Uint8Array[]) => {
    await fetch(uids, entryTable)
}
entryInterface.upsert = async (oldEntries: UidsAndValues,
                               newEntries: UidsAndValues) => {
    await upsert(oldEntries, newEntries, entryTable)
}

const chainInterface = new DbInterface()
chainInterface.fetch = async (uids: Uint8Array[]) => {
    await fetch(uids, chainTable)
}
chainInterface.insert = async (links: UidsAndValues) => {
    await insert(links, chainTable)
}

const findex = new Findex(key, label)
findex.instantiateCustomInterface(entryInterface, chainInterface)

Findex findex = new Findex(key,
                           label,
                           new SqliteEntryTable("/tmp/sqlite.db"),
                           new SqliteChainTable("/tmp/sqlite.db"));

entry_interface = PythonCallbacks.new()
entry_interface.set_fetch(lambda uids: fetch(uids, entry_table))
entry_interface.set_insert(lambda entries: insert(entries, entry_table))
entry_interface.set_delete(lambda entries: delete(entries, entry_table))
entry_interface.set_dump_tokens(lambda : dump_tokens(entry_table))
entry_interface.set_upsert(
    lambda old_entries, new_entries: upsert(old_entries, new_entries, entry_table))

chain_interface = PythonCallbacks.new()
chain_interface.set_fetch(lambda uids: fetch(uids, chain_table))
chain_interface.set_insert(lambda links: insert(links, chain_table))
chain_interface.set_delete(lambda links: delete(links, chain_table))

findex = Findex.new_with_custom_interface(key,
                                          label,
                                          entry_interface,
                                          chain_interface)

Eviden KMS

Note: Cosmian has become part of Eviden. The Cosmian KMS is now the Eviden KMS.

The Eviden KMS is a high-performance, source available, FIPS 140-3 compliant server application written in Rust with unique capabilities.

High-scale, secure encryption, anywhere

• High-performance: Delivers encryption and decryption services at up to millions of operations per second, with master keys held in a secure HSM-backed environment.
• Flexible pricing: Per-CPU pricing with no hidden costs, all connectors are included; deploying any number of servers.
• Runs securely in public clouds: or zero-trust environments using Eviden VMs available on Azure, GCP, and AWS marketplaces. See our deployment guide.

Standards' compliance

• FIPS 140-3 mode
• KMIP support (versions 1.0-1.4, 2.0-2.1) in both binary and JSON formats - see KMIP documentation.
• HSM support for Trustway Proteccio & Crypt2Pay, Utimaco general purpose, Nitrokey HSM 2, Smartcard HSMs, etc. with KMS keys wrapped by the HSM.
• Developed in Rust, a memory safe language, with the source code available on GitHub.
• 100% developed in the European Union.

Modern technology

• Source Available server application written in Rust
• Full-featured Web UI with client command line and graphical interface
• Advanced authentication mechanisms
• High-availability mode with simple horizontal scaling
• Multi-language client support: Python, JavaScript, Dart, Rust, C/C++, and Java (see the cloudproof libraries on Cosmian GitHub)
• Advanced logging with OpenTelemetry

Integrations

• Cloud integrations:
  • Azure BYOK
  • GCP CSEK and Google CMEK
  • AWS BYOK and AWS Fargate
  • ...
• Workplace security:
  • Google Workspace Client Side Encryption (CSE)
  • Microsoft 365 Double Key Encryption (DKE)
• Transparent data encryption:
  • Oracle Database TDE
  • MongoDB
  • Mysql Enterprise
  • Microsoft SQL Server External (EKM)
  • PostgreSQL
    • and more
• Disk encryption:
  • Veracrypt
  • LUKS
  • Cryhod
• Storage encryption:
  • VMware
  • Veeam Backup & Replication
  • Synology DSM
• Big Data:
  • Snowflake
  • Databricks, Spark,.. UDFs
• Other integrations:
  • FortiGate / FortiOS
  • S/MIME email encryption
  • OpenSSH
• HSM integrations:
  • Trustway Proteccio and Crypt2Pay
  • Utimaco
  • Nitrokey HSM 2 / SmartCard HSMs

Three-in-one: Key lifecycle management + Encryption oracle + Public key infrastructure

The Eviden KMS combines the functions of a Key Management System, an Encryption Oracle, and a Public Key Infrastructure:

• Key Management System: Manages the full key lifecycle, including on-the-fly generation and revocation, including for connected HSMs.
• Encryption Oracle: Provides high-availability, high-scalability encryption and decryption operations at millions of operations per second with HSM-backed security.
• PKI: Manages root and intermediate certificates, signs and verifies certificates, and uses public keys for encryption/decryption. Certificates can be exported in various formats (including PKCS#12) for applications like S/MIME encrypted emails.

The Eviden KMS supports all standard NIST cryptographic algorithms as well as advanced post-quantum cryptography algorithms like Covercrypt. See the complete supported algorithms list.

Deployment options

The Eviden KMS is available as:

• Linux packages: Debian or RPM
• Windows installer: Windows
• macOS installer: macOS
• Docker: Standard image and FIPS image

User Interface

The Eviden KMS includes an intuitive graphical user interface (GUI) with support for client certificate and OIDC token authentication.

The UI can be fully customized to match your organization's branding.

Client CLI

The KMS CLI provides a powerful command-line interface for managing the server, handling keys, and performing encryption/decryption operations. It features integrated help and is available for multiple operating systems.

The KMS CLI is packaged as:

• Debian or RPM package
• Pre-built binaries for Linux, Windows, and macOS

Quick start

To quick-start a Eviden KMS server on http://localhost:9998 that stores its data inside the container, run the following command:

docker run -p 9998:9998 --name kms ghcr.io/cosmian/kms:latest

# Minimal default configuration
[http]
port = 9998
hostname = "0.0.0.0"

To run a KMS where the database will survive restarts, run:

docker run  -p 9998:9998 --name kms --volume cosmian-kms:/cosmian-kms  ghcr.io/cosmian/kms:latest

# Same default configuration; persistence is handled by Docker volume
[http]
port = 9998
hostname = "0.0.0.0"

Please note that if you want to use the KMIP wire protocol, you need to configure TLS and the socket server using the server configuration file first.

If you do not have Docker available, install a Eviden KMS server as described in installation guide:

Using the Web UI

Open your web browser and navigate to http://localhost:9998/ui to access the GUI.

Using the CLI

Get the KMS CLI from Cosmian packages. You can then easily manage the server:

1. Create a 256-bit symmetric key

   ckms sym keys create --number-of-bits 256 --algorithm aes --tag my-file-key
   
   The symmetric key was successfully generated.
         Unique identifier: 87e9e2a8-4538-4701-aa8c-e3af94e44a9e
   

2. Encrypt the image.png file with AES GCM using the key

   ckms sym encrypt --tag my-file-key --output-file image.enc image.png
   The encrypted file is available at "image.enc"
   

3. Decrypt the image.enc file using the key

   ckms sym decrypt --tag my-file-key --output-file image2.png image.enc
   The decrypted file is available at "image2.png"
   

Encrypting and Decrypting at Scale

The Eviden KMS is architected specifically to deliver high-performance cryptography at scale for enterprise applications.

Scalability Design

The KMS scales efficiently through:

• Vertical scaling: Adding CPUs on the same machine
• Horizontal scaling: Deploying across multiple machines with load balancing
• High availability: Support for high-availability configuration

Performance Considerations

Cryptographic operations themselves are rarely the bottleneck. The key factors affecting overall performance are:

1. Network latency: Minimizing the distance between the KMS and client applications
2. CPU resources: Allocating sufficient processing power for concurrent operations
3. Database performance: Using optimized database configurations

Deployment Architecture

The optimal architecture places KMS instances as close as possible to the applications they serve. Thanks to Eviden KMS's:

• Stateless design
• Per-CPU pricing model
• Containerized an OS packaged deployment option

This makes it practical to deploy KMS instances in multiple locations, including:

• Private data centers
• Edge locations
• Public cloud environments:

Security Considerations

Placing KMS instances closer to applications can introduce security challenges by potentially exposing key material in less trusted environments.

HSM Integration

To maintain strong security while preserving performance, Eviden KMS can be backed by Hardware Security Modules (HSMs):

• HSM integration details are explained in the HSM support section
• HSM master keys wrap all application keys handled by the KMS
• This protects keys at rest while only exposing the cleartext application keys in memory cache; the cache expiration delay is configurable
• Supported HSMs include Trustway Proteccio and Utimaco

For additional security details, see the FIPS 140-3 compliance and zeroization documentation.

Additional Protection in Public Clouds

For deployments in public clouds, consider using the Eviden VM to run the KMS. The Eviden VM provides memory and disk encryption and verifiability of the KMS's integrity.

Pre-packaged KMS in Eviden VMs is available on the Azure, GCP, and AWS marketplaces.

Integration Examples

For practical examples of integrating the KMS for high-volume operations, see:

• Client-side and application-level encryption
• Google Workspace Client-Side Encryption
• Microsoft Double Key Encryption

The Eviden KMS is particularly suited for application-level and client-side encryption scenarios, which may require high-performance encryption and decryption.

The KMS offers two mechanisms for encrypting and decrypting data:

• by calling the Encrypt and Decrypt operations on the KMS KMIP API and benefiting from its parallelization, concurrency, and optimized batching capabilities.
• by using the cosmian CLI client to encrypt and decrypt data locally, including large files.

Calling the KMS API

The KMS provides a high-performance encryption and decryption API for encrypting and decrypting data at scale.

Parallelization, concurrency, and batching

Due to its stateless user session model, the Eviden KMS is designed to use modern multi-core processors and can parallelize encryption and decryption operations across multiple cores. Parallelization can be achieved by scaling vertically (increasing the number of cores on a single machine) or horizontally (increasing the number of machines in a cluster).

The Eviden KMS can also handle multiple concurrent encryption and decryption requests on a single core using (async) concurrency primitives. The asynchronous model optimizes the use of CPU resources by allowing the CPU to perform other tasks while waiting for I/O operations to complete.

Finally, batching can further optimize the performance of encryption and decryption operations. Batching allows multiple encryption or decryption operations to be performed in a single request, reducing the overhead of making multiple requests to the KMS.

Efficient batching

The KMIP way

Batching in KMIP is achieved by sending multiple Operations in a single KMIP RequestMessage operation. The protocol is highly flexible and allows various operations to be batched together.

The Eviden KMS supports batching using the KMIP protocol.

Optimized batching

However, the overhead of the KMIP protocol can be significant, especially for small data sizes. Each Operation in a KMIP message carries significant metadata, which can be prohibitively expensive for small data sizes.

When batching encryption or decryption requests, the metadata is likely identical for each request, and the overhead of unnecessarily sending the metadata multiple times can be significant.

To address this issue, the Eviden KMS provides an optimized batching API that allows multiple encryption or decryption requests to be batched together in a single request, without the overhead of the KMIP protocol. The optimized batching API is designed to be lightweight and efficient, allowing multiple encryption or decryption requests to be batched together with minimal overhead.

The method is to use a single Encrypt or Decrypt operation with multiple data items encoded in the data field of the request.

Encoding scheme

The encoding scheme is called BulkData and encodes an array of items, each item being an array of bytes. It works as follows.

• The encoded data starts with the 2-byte fixed sequence 0x87 0x87
• followed by the unsigned leb128 encoded number of items in the array
• followed, for each item, by
  • the unsigned leb128 encoded byte length of the item
  • the item itself

BulkData = 0x87 0x87 <number of items> <item 1 length> <item 1> ... <item n length> <item n>

number of items = leb128 encoded number of items
item 1 length = leb128 encoded length of item 1

When the server receives an Encrypt or Decrypt operation and detects the header 0x87 0x87, it attempts to decode the data as a BulkData array. If the decoding is unsuccessful, the server returns to the standard KMIP protocol (i.e., single item encryption or decryption).

If the decoding is successful, the server processes each item in the array as a separate encryption or decryption request and re-encodes the results.

When processing symmetric encryption results, the server will first, for each encrypted item, concatenate the IV, the ciphertext, and the MAC, and then encode the result as a single item in the BulkData array.

For AES-GCM encryption, the concatenation is as follows:

• the IV (12 bytes)
• the ciphertext (same size as the plaintext)
• the MAC (16 bytes)

Performance heuristics

The Eviden KMS uses heuristics to determine the optimal batch size for encryption and decryption requests. The heuristics consider the size of the data, the number of cores available, and the expected latency of the KMS.

Typically, for 64-byte data items, the optimal batch size is around 100,000. With these kinds of batch sizes, each CPU core should be sent an average of five batches to maximize concurrency.

Hence, to encrypt 5 million messages on 10 core machines, 50 requests of 100,000 items each should be sent in parallel. On a standard server CPU, the total processing time should be around 8 seconds, excluding network latency.

Using the KMS CLI client

The KMS CLI client can be used to encrypt and decrypt data locally, including large files.

Encryption can be performed in two modes:

• server side: the file data is sent server-side and encrypted there. This mode is well suited for small or medium files, and where a direct encryption scheme is required.
• client side: the file data is encrypted locally using a hybrid encryption scheme with key wrapping. This mode is well-suited for any type of file, including large ones, requiring high performance.

Server-side encryption and decryption

The file content is sent to the server when using server-side encryption or decryption. To use This method uses the encrypt or decrypt command of the KMS CLI client WITHOUT specifying a --key-encryption-algorithm option.

Say, the KMS holds a 256-bit AES key with the ID 43d28ec7-7438-4d2c-a1a0-00379fa4fe5d, and you want to encrypt a file image.png with AES 256-bit GCM encryption:

ckms sym encrypt \
--data-encryption-algorithm aes-gcm \
--key-id 43d28ec7-7438-4d2c-a1a0-00379fa4fe5d \
--output-file image.enc \
image.png

To decrypt the file, use the decrypt command:

ckms sym decrypt \
--data-encryption-algorithm aes-gcm \
--key-id 43d28ec7-7438-4d2c-a1a0-00379fa4fe5d \
--output-file decrypted-image.png \
image.enc

Available ciphers

The following ciphers are available for server-side encryption and decryption:

When in doubt, use AES GCM with a 256-bit key. AES GCM is NIST-certified (as NIST SP 800–38D) and well suited for arbitrary data encryption with a length of up to 2^39–256 bits ~ 64 GB.

Please note that for AES XTS, that.

• The key size must be doubled to achieve the same security level: 256 bits for AES 128 and 512 bits for AES 256.
• There is no authentication

Format of the encrypted file

The encrypted file is the concatenation of the IV (or Tweak for XTS), the ciphertext, and the MAC (None for XTS).

IV || Ciphertext || MAC

With these symmetric block ciphers, the size of the ciphertext is equal to the size of the plaintext.

The table below shows the size of the IV (tweak for XTS) and the MAC in bytes.

Client-side encryption and decryption

When using client-side encryption or decryption, the file content is encrypted locally using a hybrid encryption scheme with key wrapping:

• A random data encryption key (DEK) is generated. The key size is 256 bits for all schemes except for AES, which is 512 bits to provide 256 bits of classic security, and 128 bits post-quantum security.
• The DEK is used to encrypt the file content using the specified locally --data-encryption-algorithm for the data encryption mechanism (DEM).
• The DEK is server-side encrypted (i.e., wrapped) using the specified --key-encryption-algorithm for the key encryption mechanism (KEM) and the KMS key encryption key (KEK) identified by --key-id.

To use this method, use the encrypt or decrypt command and specify BOTH the --key-encryption-algorithm and --data-encryption-algorithm.

Say, the KMS holds a 256-bit AES KEK (key encryption key) with the ID 43d28ec7-7438-4d2c-a1a0-00379fa4fe5d and you want to client-side encrypt a file image.png with AES-GCM encryption, the ephemeral KEK key is wrapped with RFC5649 (a.k.a. NIST key wrap):

ckms sym encrypt \
--data-encryption-algorithm aes-gcm \
--key-encryption-algorithm rfc5649 \
--key-id 43d28ec7-7438-4d2c-a1a0-00379fa4fe5d \
--output-file image.enc \
image.png

To decrypt the file, use the decrypt command:

ckms sym decrypt \
--data-encryption-algorithm aes-gcm \
--key-encryption-algorithm rfc5649 \
--key-id 43d28ec7-7438-4d2c-a1a0-00379fa4fe5d \
--output-file decrypted-image.png \
image.enc

Available ciphers

The following ciphers are available for client-side encryption and decryption:

• Data Encryption

• Key Wrapping (Encryption)

When in doubt, use the AES GCM data encryption scheme with the AES GCM key encryption scheme (or RFC5649) with a 256-bit key. These are the most widely used schemes, and they are NIST-certified.

Format of the encrypted file

The encrypted file is the concatenation of

• the length of the key wrapping (a.k.a. encapsulation) in unsigned LEB 128 format
• the key encapsulation
• the data encryption mechanism (DEM) IV (or tweak for XTS)
• the ciphertext (same size as the plaintext)
• the data encryption mechanism (DEM) MAC

encapsulation length || encapsulation || DEM IV || Ciphertext || DEM MAC

The key encapsulation is the concatenation of

• the key encryption mechanism (KEM) IV (or tweak for XTS, none for RFC5649)
• the encrypted DEK (same length as the DEK, +8 bytes for RFC5649)
• the key encryption mechanism (KEM) MAC (none for XTS and RFC5649)

KEM IV || Encrypted DEK || KEM MAC

Using AES GCM as a KEM and a DEM, the details will be as follows:

• 1 unsigned LEB 128 byte holding the length of the encapsulation (60)
• 60 bytes of encapsulation decomposed in :
  • 12 byte KEM IV
  • 32 bytes encrypted DEK
  • 16 byte KEM MAC
• 12 bytes of DEM IV
• x bytes of ciphertext (same size as plaintext)
• 16 bytes of DEM MAC

Public Key Infrastructure (PKI)

The Eviden KMS is a full-featured X.509 certificate authority capable of issuing, storing, validating, and revoking certificates for both classical and post-quantum algorithms.

Supported standards

Not supported

The following specifications are not currently implemented:

• Merkle Tree Certificates (IETF draft) — transparency-based certificate format.
• Composite Certificates (draft-ietf-lamps-pq-composite-sigs / draft-ietf-lamps-pq-composite-kem) — hybrid classical+PQC keys in a single certificate.
• OCSP responder — the KMS does not act as an OCSP responder.
• CRL generation — the KMS does not generate CRLs; it can include crlDistributionPoints pointing to an external CRL.

Certificate export formats

Certificates and their associated private keys can be exported in:

• PEM (.pem) — Base64-encoded, human-readable.
• DER (.der) — Binary ASN.1 encoding.
• PKCS#12 (.p12 / .pfx) — Bundled certificate + private key, password-protected.

Post-quantum algorithms

Algorithm identifiers (OIDs)

ML-DSA — signing (RFC 9881, FIPS 204)

SLH-DSA — signing (RFC 9909, FIPS 205)

ML-KEM — key encapsulation (RFC 9935, FIPS 203)

Key usage requirements

ML-DSA and SLH-DSA (signing algorithms)

Per RFC 9881 §5 and RFC 9909 §6:

• The keyUsage extension MUST be present and MUST be critical.
• It MUST include digitalSignature.
• For CA certificates: keyCertSign and cRLSign are added.

X509v3 Key Usage: critical
    Digital Signature

ML-KEM (key encapsulation algorithm)

Per RFC 9935 §5:

• The keyUsage extension MUST be present and MUST be critical.
• It MUST contain keyEncipherment and MUST NOT contain any other bit.

X509v3 Key Usage: critical
    Key Encipherment

Generating certificates with the CLI

Self-signed ML-DSA-44 certificate

ckms certificates certify \
  --generate-key-pair \
  --algorithm ml-dsa-44 \
  --subject-name "CN=My ML-DSA CA,O=Acme,C=FR" \
  --days 365

The server will:

1. Generate an ML-DSA-44 key pair.
2. Issue a self-signed X.509 v3 certificate.
3. Automatically add a critical keyUsage extension with digitalSignature (per RFC 9881).
4. Return the certificate identifier.

CA-issued ML-KEM-512 certificate (RFC 9935)

First create an ML-DSA-44 CA:

# Step 1: create the CA certificate (self-signed ML-DSA-44)
CA_CERT_ID=$(ckms certificates certify \
  --generate-key-pair \
  --algorithm ml-dsa-44 \
  --subject-name "CN=PQC Root CA,O=Acme,C=FR" \
  --days 3650 \
  | grep "Certificate ID" | awk '{print $NF}')

# Retrieve the CA private key ID from the certificate attributes
CA_SK_ID=$(ckms certificates export \
  --certificate-id "$CA_CERT_ID" \
  --output-format json-ttlv \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(next(l['LinkedObjectIdentifier'] for l in d.get('Link',[]) if l['LinkType']=='PrivateKeyLink'))")

Then issue an ML-KEM-512 leaf certificate signed by the CA:

# Step 2: create an ML-KEM-512 leaf certificate signed by the CA
ckms certificates certify \
  --generate-key-pair \
  --algorithm ml-kem-512 \
  --subject-name "CN=ML-KEM-512 Leaf,O=Acme,C=FR" \
  --issuer-private-key-id "$CA_SK_ID" \
  --issuer-certificate-id "$CA_CERT_ID" \
  --days 365

The server will:

1. Generate an ML-KEM-512 key pair.
2. Issue an X.509 certificate signed by the ML-DSA-44 CA.
3. Automatically add a critical keyUsage extension with keyEncipherment only (per RFC 9935).

SLH-DSA-SHA2-128s self-signed certificate

ckms certificates certify \
  --generate-key-pair \
  --algorithm slh-dsa-sha2-128s \
  --subject-name "CN=SLH-DSA Test,O=Acme,C=FR" \
  --days 365

RSA or EC self-signed certificate

# RSA 4096
ckms certificates certify \
  --generate-key-pair \
  --algorithm rsa4096 \
  --subject-name "CN=RSA CA,O=Acme,C=FR" \
  --days 365

# NIST P-256
ckms certificates certify \
  --generate-key-pair \
  --algorithm nist-p256 \
  --subject-name "CN=EC CA,O=Acme,C=FR" \
  --days 365

Verifying certificates with OpenSSL 3.5+

OpenSSL 3.5+ supports all NIST PQC algorithms. Use the following commands to inspect and verify PQC certificates:

# Inspect the certificate
openssl x509 -text -noout -in ml-dsa-cert.pem

# Verify a leaf certificate against a CA certificate
openssl verify -CAfile ca-cert.pem leaf-cert.pem

Using the Web UI

The Eviden KMS Web UI exposes certificate generation through the Certificate Issuance and Renewal page at /ui/certificates/certs/certify.

• Select "4. Generate New Keypair".
• Choose an algorithm from the Key Algorithm dropdown (e.g. ML-DSA-44 (PQC), ML-KEM-512 (KEM), RSA-4096, NIST-P256).
• Enter a subject name.
• Optionally provide issuer key and certificate IDs for CA-signed certificates.

Cross-algorithm PKI

RFC 9881 and RFC 9935 explicitly support cross-algorithm PKI: the CA signing key does not need to match the subject key algorithm.

Examples of supported combinations:

Certificate lifecycle

All standard KMIP certificate lifecycle operations work with certificates:

Revocation handling

CRL distribution points

To include a CRL distribution point in a certificate, add a crlDistributionPoints entry in the extension config file passed via --certificate-extensions:

[ v3_ext ]
crlDistributionPoints=URI:http://ca.example.com/crl.pem

Authority Information Access (AIA)

The AIA extension (authorityInfoAccess, OID 1.3.6.1.5.5.7.1.1) can be added via the extension config file to point to an OCSP responder or CA issuer:

[ v3_ext ]
authorityInfoAccess=OCSP;URI:http://ocsp.example.com/,caIssuers;URI:http://ca.example.com/ca.crt

No Revocation Available (id-ce-noRevAvail, RFC 9608)

For self-signed certificates (no issuer key provided) that do not carry a CRL distribution point, the KMS automatically adds the id-ce-noRevAvail extension (OID 2.5.29.56, RFC 9608 §2). This signals to relying parties that no revocation information is available for this certificate, and that they should not reject it for lack of a CRL or OCSP response.

This behavior applies to all algorithms (RSA, EC, ML-DSA, SLH-DSA, …), not only PQC.

When validating a chain, the KMS skips CRL fetching for any certificate that carries this extension.

Anonymization

Cosmian KMS exposes a set of data anonymization methods through a dedicated REST endpoint. These methods are stateless, require no cryptographic key, and are available under /tokenize/{method} on any KMS instance built with the non-fips feature.

All endpoints accept a JSON body and return a JSON object with a single result field. Errors come back as HTTP 422 with { "code": 422, "message": "..." }.

The ckms tokenize CLI command wraps each of these endpoints if you prefer working from the command line.

Endpoints

Hash

POST /tokenize/hash

Produces an irreversible, base64-encoded hash of a string. Three algorithms are available: SHA2 (SHA-256), SHA3 (SHA3-256), and Argon2. A salt can be passed as a base64-encoded byte string; for Argon2 it is required.

{
  "data": "test sha2",
  "method": "SHA2"
}

Response:

{ "result": "Px0txVYqBePXWF5K4xFn0Pa2mhnYA/jfsLtpIF70vJ8=" }

Use Argon2 when the input has low entropy (passwords, short identifiers) and you need resistance to brute-force lookup. Use SHA2 or SHA3 for high-entropy values or when throughput matters.

Noise

POST /tokenize/noise

Adds random noise to a numeric or date value. Three distributions are supported: Gaussian, Laplace, and Uniform. You can parameterize the distribution either by mean and standard deviation, or by lower and upper bounds.

The data_type field controls what kind of input to expect: float, integer, or date. Dates must be in RFC 3339 format (2023-04-07T12:34:56Z); the timezone is preserved in the output.

{
  "data": 42000.0,
  "data_type": "float",
  "method": "Laplace",
  "mean": 0.0,
  "std_dev": 500.0
}

{
  "data": "2023-04-07T12:34:56+02:00",
  "data_type": "date",
  "method": "Uniform",
  "min_bound": -3600.0,
  "max_bound": 3600.0
}

Laplace noise is the standard choice for differential privacy budgets. Uniform noise is appropriate when you need a hard bound on the perturbation. Gaussian is a reasonable default for datasets where outliers are acceptable.

Word Mask

POST /tokenize/word-mask

Replaces every occurrence of a listed word with XXXX, case-insensitively, matching only on word boundaries.

{
  "data": "Confidential: contains -secret- documents",
  "words": ["confidential", "secret"]
}

{ "result": "XXXX: contains -XXXX- documents" }

Non-word characters surrounding a target word (dashes, punctuation, spaces) are preserved.

Word Tokenize

POST /tokenize/word-tokenize

Replaces listed words with random 16-byte hex tokens. All occurrences of the same word receive the same token within a single request, so joins across a single document remain consistent. Across separate requests, the tokens are different.

{
  "data": "confidential meeting with confidential sources",
  "words": ["confidential"]
}

The output might be:

{ "result": "3A9F1C8B2E7D4A60 meeting with 3A9F1C8B2E7D4A60 sources" }

Word Pattern Mask

POST /tokenize/word-pattern-mask

Replaces all substrings matching a regular expression with a fixed replacement string. The pattern is limited to 1024 characters.

{
  "data": "Call me at +33 6 12 34 56 78 or +1-555-123-4567",
  "pattern": "\\+[\\d\\s\\-]+",
  "replace": "[PHONE]"
}

{ "result": "Call me at [PHONE] or [PHONE]" }

Aggregate Number

POST /tokenize/aggregate-number

Rounds a number to the nearest power of ten. power_of_ten: 2 rounds to the nearest hundred; power_of_ten: -1 keeps one decimal place.

{
  "data": 1234567,
  "data_type": "integer",
  "power_of_ten": 3
}

{ "result": "1235000" }

data_type is either float or integer.

Aggregate Date

POST /tokenize/aggregate-date

Truncates a date to the specified precision. The time_unit field accepts Second, Minute, Hour, Day, Month, or Year. The timezone offset is preserved.

{
  "data": "2023-04-07T12:34:56+02:00",
  "time_unit": "Month"
}

{ "result": "2023-04-01T00:00:00+02:00" }

Scale Number

POST /tokenize/scale-number

Applies a z-score normalization followed by a linear transformation. Given the mean and standard deviation of the original distribution, each value is standardized to zero mean and unit variance, then multiplied by scale and shifted by translate.

{
  "data": 75.0,
  "data_type": "float",
  "mean": 50.0,
  "std_deviation": 15.0,
  "scale": 10.0,
  "translate": 100.0
}

{ "result": 116.6666666666667 }

data_type is either float or integer. For integers the result is rounded to the nearest integer.

Relation to Format-Preserving Encryption

The methods above are one-way or statistically approximate transformations. They do not require a key and cannot be reversed to recover the original value.

For reversible, key-based field-level encryption that preserves the format of the original value (digit strings stay digit strings, alphanumeric stays alphanumeric), see Format-Preserving Encryption (FPE FF1). FPE is accessed through the KMIP Encrypt and Decrypt operations, not through the /tokenize endpoint.

HSM Support

The Eviden KMS can be configured to use HSMs to store and manage keys and create KMS keys wrapped by the HSM keys. This provides the best of both worlds: the security of an HSM at rest and the scalability of a KMS at runtime.

Eviden KMS natively integrates with the Proteccio, the Utimaco general purpose, the Smartcard HSM, and any HSM that has a standard PKCS#11 interface such as SoftHSMv2.

Integration Workflow

Main use case and benefits

Aside from providing a single interface to manage both KMS and HSM keys, the main use case for HSM support is to host keys in the KMS that are wrapped by keys stored in the HSM.

This combination provides the best of both worlds:

• the scalability and performance of the KMS at runtime to answer a large number of requests concurrently,
• and the hardware security of the HSM at rest, which may be a compliance requirement in some industries.

Typical use cases include:

• securing workplace applications such as MS 365 or Google Workspace, where concurrent requests from potentially a large number of users need to be processed quickly,
• securing big data applications such as Hadoop/Spark, Snowflake, Databricks, where a large number of encryption and decryption requests need to be processed on the fly for each request.

At Rest

KMS keys are stored in the KMS database in a wrapped form, and the wrapping key is stored in the HSM. This provides an additional layer of security for the keys stored in the KMS, since the keys stored in the HSM are protected by the HSM's hardware security mechanisms, and benefit from the HSM certifications.

At Runtime

Encryption and decryption requests from applications are processed by the KMS, which first unwraps the keys stored in the KMS database using the keys stored in the HSM. Contrary to the HSM, the KMS is a highly scalable and performant system that can handle a large number of requests concurrently.

In addition to managing its keys, Eviden KMS can act as a proxy to an HSM, storing and managing keys within the HSM.

HSM keys

HSM keys are prefixed keys. They are created with a unique identifier that is prefixed by the hsm keyword and the slot number in the form:

hsm::<slot_number>::<key_identifier>

For instance, the key hsm::1::mykey is stored in the HSM slot 1 with the identifier mykey. Technically, the identifier is stored in the LABEL field of the key object in the HSM.

!!! warning Labels must be unique within a slot The PKCS#11 standard does not enforce label uniqueness: multiple key objects can share the same LABEL in the same slot. Eviden KMS however uses the label as the sole key identifier within a slot, so it requires labels to be unique per slot per key type. If two objects of the same type share a label in the same slot, Eviden KMS will return an error when that label is referenced. Always verify that no existing object already uses a label before creating a new key with pkcs11-tool --list-objects.

!!! info CKA_ID is automatically set by Eviden KMS Eviden KMS sets both CKA_LABEL and CKA_ID (to the same bytes as the label) on every key it creates in the HSM. This conforms to PKCS#11 v2.40 and prevents spurious warnings from tools such as pkcs11-tool --list-objects. Keys provisioned externally (via pkcs11-tool or the HSM vendor software) should also have CKA_ID set to match the label bytes if they are intended to be used with Eviden KMS.

Non-prefixed keys are considered KMS keys and are stored in the KMS database.

HSM admin

The KMS server maintains a list of HSM admin users that are allowed to create and destroy objects directly in the HSM. This is configured with the hsm_admin key in kms.toml:

# One or more KMS usernames with HSM admin privileges
hsm_admin = ["alice@example.com", "bob@example.com"]

# Wildcard: any authenticated user becomes an HSM admin
hsm_admin = ["*"]

From the command line, pass one --hsm-admin flag per username (or a single comma-separated value):

# Two explicit admins
cosmian_kms --hsm-admin alice@example.com --hsm-admin bob@example.com ...

# Or via environment variable
KMS_HSM_ADMIN=alice@example.com,bob@example.com cosmian_kms ...

!!! note Authorization of HSM keys is still managed by the KMS Although key material is stored in the HSM, the KMS continues to enforce the standard ownership and access-rights model for all other operations (Encrypt, Decrypt, Get, etc.). An HSM admin can therefore grant these operations to ordinary users, who can then use the HSM key without themselves being HSM admins. See HSM keys and authorization for details.

HSM key authorization model

HSM keys follow a stricter permission model than regular KMS keys. The key principles are:

• HSM admins are the only users who can create and destroy HSM keys.
• All HSM admins share ownership of all HSM keys (any admin can grant, revoke, or destroy any HSM key).
• Non-admin users can only use HSM keys they have been explicitly granted operations on.
• The Get permission does not act as a wildcard for HSM keys — each operation must be granted individually.
• Locate only returns HSM keys the user is authorized to see (all keys for admins, granted keys for non-admins).
• The server KEK (Key Encryption Key) is a shared wrapping resource accessible to all users for wrapping/unwrapping, but direct cryptographic operations on the KEK itself require explicit grants.

Operations by role

Grantable operations on HSM keys

!!! warning Get is not a wildcard for HSM keys Unlike regular KMS keys, granting Get on an HSM key does not implicitly grant all other operations. Each operation (Encrypt, Decrypt, Sign, etc.) must be granted individually.

Creating a KMS key wrapped by an HSM key

KMS Keys can be created wrapped by an HSM key, either manually or automatically.

Manually using the CLI

To create a KMS key wrapped by an HSM key, the --wrapping-key-id argument must be used to specify the unique identifier of the HSM key.

The user creating the key must be the HSM admin (see above) or have been granted the Encrypt operation on the HSM key.

!!! note Server-level key_encryption_key is accessible to all users When the server is configured with a key_encryption_key (see Automatically using the server configuration), that KEK is a shared server resource and can be used as a wrapping key by any authenticated user, not just the HSM admin. This allows non-admin users to create their own KMS keys wrapped by the server KEK.

For instance, the following command creates a 256-bit AES key wrapped by the HSM RSA (public) key hsm::4::my_rsa_key_pk:

> ckms sym keys create --algorithm aes --number-of-bits 256 --sensitive \
  --wrapping-key-id hsm::4::my_rsa_key_pk my_sym_key
The symmetric key was successfully generated.
      Unique identifier: my_sym_key

The symmetric key is now stored in the database encrypted (wrapped) by the HSM key. The encryption happened in the HSM.

Manually using the Web UI

In the web UI, fill in the Wrapping Key ID field with the unique identifier of the HSM key.

Automatically using the server configuration

The KMS server can automatically wrap all KMS keys with a specific HSM key. This is done by setting the key_encryption_key property in the TOML server configuration file or using the corresponding command line switch.

When key_encryption_key is configured, all newly created and imported keys will be automatically wrapped by the specified Key Encryption Key (KEK), typically an HSM key. Keys are stored wrapped in the KMS database, ensuring no clear-text key material is persisted.

The server provides selective automatic unwrapping through the default_unwrap_type configuration parameter. This controls which KMIP object types are automatically unwrapped when retrieved via Get or Export operations:

• Valid values: ["PrivateKey", "PublicKey", "SymmetricKey", "SecretData"]
• Default: [] (no automatic unwrapping)
• When a key_encryption_key is set, it's common to configure default_unwrap_type = ["SymmetricKey", "SecretData"]

Example configuration:

# Force all keys to be wrapped by an HSM key
key_encryption_key = "hsm::4::master_kek"

# Automatically unwrap symmetric keys and secret data when retrieved
default_unwrap_type = ["SymmetricKey", "SecretData"]

When an object matching the configured types is retrieved, it is automatically unwrapped and cached in the server's memory cache (see The Unwrapped Objects Cache). This enables transparent encryption/decryption operations without storing clear-text keys in the database while minimizing HSM calls through expiring caching.

Using the wrapped KMS key

The symmetric key created above can now be used to encrypt and decrypt data, and the KMS will transparently unwrap the key using the HSM key.

This unwrapping will happen once, and the unwrapped symmetric key will be cached in memory for later operations; no clear-text symmetric key will be stored in the KMS database.

Small data: encrypting server-side

For example, to encrypt a message with the key my_sym_key server-side, the following command can be used:

> ckms sym encrypt --key-id my_sym_key /tmp/secret.txt
The encrypted file is available at "/tmp/secret.enc"

To decrypt a message with the key my_sym_key, the following command can be used:

> ckms sym decrypt --key-id my_sym_key --output-file /tmp/secret.recovered.txt /tmp/secret.enc
The decrypted file is available at "/tmp/secret.recovered.txt"

Large data: encrypting client side with key wrapping

To encrypt a large file with the key my_sym_key client side, the following command can be used:

>ckms sym encrypt --key-id my_sym_key_2 --data-encryption-algorithm aes-gcm \
--key-encryption-algorithm rfc5649 /tmp/large.bin
The encrypted file is available at "/tmp/large.enc"

In this case, an ephemeral symmetric key (the Data Encryption Key, DEK) is generated and used to encrypt the data. The DEK is then encrypted/wrapped with RFC4659 (a.k.a NIST AES Key Wrap) with the key my_sym_key, called the Key Encryption Key, KEK. The wrapping of the DEK by the KEK is stored at the beginning of the encrypted file. At rest, in the KMS database, my_sym_key is stored encrypted/wrapped with the HSM key hsm::4::my_rsa_key_pk.

To decrypt a large file with the KEK my_sym_key client side, the following command can be used:

> ckms sym decrypt --key-id my_sym_key_2 --data-encryption-algorithm aes-gcm \
  --key-encryption-algorithm rfc5649 --output-file /tmp/large.recovered.bin /tmp/large.enc
The decrypted file is available at "/tmp/large.recovered.bin"

Unwrapping a KMS-wrapped key from a file

If a KMS key was exported in wrapped KMIP JSON TTLV format (for example, via ckms sym keys export without --unwrap), it can later be unwrapped using ckms sym keys unwrap.

When the unwrapping key is an HSM key (identified by the hsm:: prefix), the KMS performs the unwrap server-side using its crypto oracle: the wrapped file is imported to the KMS with key_wrap_type=NotWrapped, the server decrypts it using the HSM key, and the result is exported back to the output file. This is transparent to the caller and works even when the HSM key is marked sensitive (non-extractable).

# Export a wrapped DEK to disk
ckms sym keys export --key-id my_sym_key /tmp/my_sym_key_wrapped.json

# Unwrap it using the HSM KEK — the KMS handles the decryption server-side
ckms sym keys unwrap --unwrap-key-id hsm::4::master_kek \
  /tmp/my_sym_key_wrapped.json /tmp/my_sym_key_unwrapped.json

The Unwrapped Objects Cache

The unwrapped cache is a memory cache, and it is not persistent. The unwrapped cache is used to store unwrapped objects that are fetched from the database.

When a wrapped object is fetched from the database, it is unwrapped and stored in the unwrapped cache. Further calls to the same object will use the unwrapped object from the cache until the cache expires.

The time in minutes after an unused object is evicted from the cache is configurable using the unwrapped_cache_max_age setting. The default is 15 minutes.

When HSM keys wrap objects, a long expiration time reduces the number of calls made to the HSM to unwrap the object. However, increasing the cache time will increase the memory the KMS server uses and expose the key in clear text in the memory for a longer time.

HSM KMIP operations

Some KMIP operations can be performed directly via the KMS server API on the HSM keys.

Create

Create a new key in the HSM. The key unique must be provided on the request and must follow the hsm::<slot_number>::<key_identifier> format described above. Only HSM admin users can create keys directly in the HSM (see HSM admin above).

RSA and AES keys are supported.

When creating an RSA key, the key_identifier will be that of the private key. The corresponding public key will be automatically created and stored in the HSM with the same key_identifier but with the _pk suffix, for example, the public key of the hsm::1::mykey private key will be created with a unique identifier hsm::1::mykey_pk.

Create an RSA 4096-bit key on the HSM slot 4, with the KMS CLI:

❯ ckms rsa keys create --size_in_bits 4096 hsm::4::my_rsa_key
The RSA key pair has been created.
      Public key unique identifier: hsm::4::my_rsa_key_pk
      Private key unique identifier: hsm::4::my_rsa_key

Create an AES 256-bit key on HSM slot 4, with the KMS CLI:

❯ ckms sym keys create --algorithm aes --number-of-bits 256 hsm::4::my_aes_key
The symmetric key was successfully generated.
   Unique identifier: hsm::4::my_aes_key

HSM keys are always created with CKA_SENSITIVE=true (private/symmetric key material cannot be exported). Pass --sensitive false explicitly only if you intentionally need an extractable key.

Note: HSM keys do not support object tagging in this release.

Using pkcs11-tool directly

Keys can also be provisioned directly in the HSM with pkcs11-tool (part of OpenSC), bypassing the Eviden KMS entirely. This is useful for pre-provisioning a master KEK before the KMS server starts, or for HSM models where the Eviden PKCS#11 integration does not yet support key generation.

The LABEL set with --label becomes the <key_identifier> part of the Eviden KMS unique identifier hsm::<slot_number>::<label>.

Step 1 — List available slots

pkcs11-tool --module /tw/oemDist/libnethsmpkcs11.so --list-slots

Step 2 — Create an AES key

--key-type AES:<bytes> — size in bytes (16 = 128-bit, 24 = 192-bit, 32 = 256-bit).

# AES-128 key on slot 1, label "master_kek"
pkcs11-tool --module /tw/oemDist/libnethsmpkcs11.so \
  --slot 1 \
  --key-type AES:16 \
  --keygen \
  --label master_kek

# AES-256 key on slot 1, label "data_kek"
pkcs11-tool --module /tw/oemDist/libnethsmpkcs11.so \
  --slot 1 \
  --key-type AES:32 \
  --keygen \
  --label data_kek

If the slot requires a PIN, add --login --pin <PIN> (or --login alone to be prompted interactively):

pkcs11-tool --module /tw/oemDist/libnethsmpkcs11.so \
  --slot 1 \
  --login --pin 1234 \
  --key-type AES:32 \
  --keygen \
  --label data_kek

Step 3 — Create an RSA key pair

# RSA-4096 key pair on slot 4, label "my_rsa_key"
pkcs11-tool --module /tw/oemDist/libnethsmpkcs11.so \
  --slot 4 \
  --login --pin 1234 \
  --key-type RSA:4096 \
  --keypairgen \
  --label my_rsa_key

The private key label becomes hsm::4::my_rsa_key in Eviden KMS. For RSA key pairs, Eviden KMS appends _pk to the label to build the public key identifier: hsm::4::my_rsa_key_pk.

Step 4 — Verify the objects are visible

Always check for existing objects with the same label before creating a new key — Eviden KMS requires labels to be unique within a slot and key type:

pkcs11-tool --module /tw/oemDist/libnethsmpkcs11.so \
  --slot 1 \
  --list-objects

The AES key created above will then be addressable in Eviden KMS as hsm::1::master_kek and can immediately be used as a KEK:

# kms.toml
key_encryption_key = "hsm::1::master_kek"

Destroy

Unlike KMS keys, HSM keys must not be revoked before being destroyed. The Destroy operation will remove the key from the HSM.

Only HSM admin users can destroy keys in the HSM. The Destroy operation cannot be delegated to non-admin users.

To destroy the key hsm::4::my_rsa_key, the following command can be used:

❯ ckms rsa keys destroy --key-id hsm::4::my_rsa_key
Successfully destroyed the key.
      Unique identifier: hsm::4::mykey

To destroy the corresponding public key hsm::4::my_rsa_key_pk, the following command can be used:

❯ ckms rsa keys destroy --key-id hsm::4::my_rsa_key_pk
Successfully destroyed the object.
   Unique identifier: hsm::4::my_rsa_key_pk

Get - Export

The Get and Export operations are used to retrieve the key material from the HSM. Only HSM admin users, or a user granted the Get operation by an HSM admin, can retrieve keys from the HSM.

Private or symmetric keys marked as sensitive cannot be retrieved from the HSM. The public key of a key pair can always be retrieved.

To export the public key hsm::4::my_rsa_key_pk in PKCS#8 PEM format, the following command can be used:

❯ ckms rsa keys export --key-id hsm::4::my_rsa_key_pk --key-format pkcs8-pem /tmp/pubkey.pem
The key hsm::4::my_rsa_key_pk of type PublicKey was exported to "/tmp/pubkey.pem"
   Unique identifier: hsm::4::my_rsa_key_pk

To export the private key hsm::4::mykey in PKCS#8 PEM format, the following command can be used:

❯ ckms rsa keys export --key-id hsm::4::my_rsa_key --key-format pkcs8-pem /tmp/privkey.pem
The key hsm::4::my_rsa_key of type PrivateKey was exported to "/tmp/privkey.pem"
   Unique identifier: hsm::4::my_rsa_key

To export the symmetric key hsm::4::my_aes_key in raw format (i.e., raw bytes), the following command can be used:

❯ ckms sym keys export --key-id hsm::4::my_aes_key --key-format raw /tmp/symkey.raw
The key hsm::4::my_aes_key of type SymmetricKey was exported to "/tmp/symkey.raw"
   Unique identifier: hsm::4::my_aes_key

Encrypt

Symmetric keys and public keys can be used to encrypt data. Only HSM admin users, or a user granted the Encrypt operation by an HSM admin, can encrypt data with keys stored in the HSM.

For symmetric keys, only AES GCM is supported. CKM_RSA_PKCS_OAEP and the now-deprecated, but still widely used, CKM_RSA_PKCS (v1.5) are supported for RSA keys. The hashing algorithm is fixed to SHA256.

When using RSA, the maximum message size in bytes is:

• PKCS#1 v1.5: (key size in bits / 8) - 11
• OAEP: (key size in bits / 8) - 66

To encrypt a message with the public key hsm::4::my_rsa_key_pk and the CKM RSA PKCS OAEP algorithm, the following command can be used:

❯ ckms rsa encrypt --key-id hsm::4::my_rsa_key_pk --encryption-algorithm ckm-rsa-pkcs-oaep \
/tmp/secret.txt
The encrypted file is available at "/tmp/secret.enc"

To encrypt a message using AES GCM with the symmetric key hsm::4::my_aes_key, the following command can be used:

❯ ckms sym encrypt --key-id hsm::4::my_aes_key --data-encryption-algorithm aes-gcm /tmp/secret.txt
The encrypted file is available at "/tmp/secret.enc"

Decrypt

Symmetric keys and private keys can be used to decrypt data. Only HSM admin users, or a user granted the Decrypt operation by an HSM admin, can decrypt data with keys stored in the HSM.

For symmetric keys, only AES GCM is supported. CKM_RSA_PKCS_OAEP and the now-deprecated, but still widely used, CKM_RSA_PKCS (v1.5) are supported for RSA keys. The hashing algorithm is fixed to SHA256.

To decrypt a message with the private key key hsm::4::hsm::4::my_rsa_key and the CKM RSA PKCS OAEP algorithm, the following command can be used:

❯ ckms rsa decrypt --key-id hsm::4::my_rsa_key --encryption-algorithm ckm-rsa-pkcs-oaep \
  --output-file /tmp/secret.recovered.txt /tmp/secret.enc
The decrypted file is available at "/tmp/secret.plain"

To decrypt a message using AES GCM with the symmetric key hsm::4::my_aes_key, the following command can be used:

> ckms sym decrypt --key-id hsm::4::my_aes_key --data-encryption-algorithm aes-gcm \
  --output-file /tmp/secret.recovered.txt /tmp/secret.enc
The decrypted file is available at "/tmp/secret.recovered.txt"

Multi-HSM Support

Eviden KMS can connect to multiple Hardware Security Modules simultaneously. Each HSM instance is independently initialised via PKCS#11 and exposed to the rest of the server through a unique routing prefix derived from its model name.

Routing prefix scheme

Every KMS object stored inside an HSM has a UID of the form:

hsm::<model>::<slot_id>::<key_id>

The model name embedded in the prefix allows the server to route any KMIP operation to the correct HSM without additional configuration.

When the same model appears more than once, the second instance gets the suffix _1, the third _2, and so on (e.g. hsm::softhsm2, hsm::softhsm2_1, hsm::softhsm2_2).

Configuration

Option A — flat single-HSM CLI flags (backward compatible)

The existing --hsm-model, --hsm-admin, --hsm-slot, and --hsm-password flags continue to work exactly as before. They configure one HSM instance whose prefix is "hsm::<model>".

Option B — TOML [[hsm_instances]] array (multi-HSM)

Add one [[hsm_instances]] section per HSM in kms.toml. When this section is present it takes precedence over the flat CLI flags.

# First HSM — prefix "hsm::softhsm2"
[[hsm_instances]]
hsm_model    = "softhsm2"
hsm_admin    = ["tech@example.com"]
hsm_slot     = [0]
hsm_password = ["changeme"]

# Second HSM — prefix "hsm::utimaco"
[[hsm_instances]]
hsm_model    = "utimaco"
hsm_admin    = ["tech@example.com"]
hsm_slot     = [0, 1]
hsm_password = ["slot0pass", "slot1pass"]

# Third HSM — same model as first, disambiguated as "hsm::softhsm2_1"
[[hsm_instances]]
hsm_model    = "softhsm2"
hsm_admin    = ["tech@example.com"]
hsm_slot     = [2]
hsm_password = ["anotherpass"]

Checking HSM status at runtime

The GET /hsm/status endpoint returns a JSON array of all configured HSM instances. Authentication is required (pass the usual credentials):

curl http://localhost:9998/hsm/status

Example response:

[
  {
    "prefix": "hsm::softhsm2",
    "model": "softhsm2",
    "slots": [
      { "slot_id": 0, "accessible": true }
    ]
  },
  {
    "prefix": "hsm::utimaco",
    "model": "utimaco",
    "slots": [
      { "slot_id": 0, "accessible": true },
      { "slot_id": 1, "accessible": false }
    ]
  }
]

The same information is available in the HSM Status page of the Web UI (Objects → HSM Status).

Supported platforms

HSM support is available on:

• Linux x86_64 — all models (softhsm2, utimaco, proteccio, crypt2pay, smartcardhsm, other)
• macOS (arm64 / x86_64) — softhsm2 and smartcardhsm only

See also

• SoftHSM2 setup
• Utimaco setup
• Proteccio setup
• HSM operations

The Smartcard HSM integration is supported on Linux (x86_64). It has been tested with the following devices: BULL PKCS11 C2P 5.0.7 (Release) Unix64

HSM files installation

Copy the Crypt2pay PKCS#11 library to /lib

Copy libpkcs11c2p.so to /lib. Make sure it is readable by the user running the KMS.

Create the c2p directory

Create a c2p directory in, say, /etc/c2p (hereafter called [C2P_DIR])

In this directory copy the following files:

• c2padmin <- The Crypt2pay admin tool
• c2p.xml <- The Crypt2pay configuration file
• ca.der <- The CA certificate
• installca <- The Crypt2pay CA installation tool
• p11tool <- The PKCS#11 tool used to test the connection
• The two files with extensions .kdk and .ksk <- The client key files

Install the CA certificate

This certificate is the one that signed the HSM certificate and will be used to authenticate the HSM. In the [C2P_DIR], run the installca tool:

./installca -i ./ca.der ssl

This will create an ssl directory in the [C2P_DIR] and copy the CA certificate there. To check that the CA certificate is installed correctly, run:

./installca -l ./ssl/

Edit the c2p.xml file and insert the full path to the CA certificate ssl directory in C2Pconfig/sslDefinition/Authorities:

<C2Pconfig>
  ...
  <sslDefinition>
   <Authorities>[C2P_DIR]/ssl</Authorities>
  </sslDefinition>
  ...
</C2Pconfig>

replace [C2P_DIR] with the actual path.

Set logging and Verify the c2p.xml file

In the c2p.xml file, set the logging to

<C2Pconfig>
  <TraceLevel>debug functions parameters pkcs hsm</TraceLevel>
  <TraceFile>+logs\c2p.trc</TraceFile>
  ...
</C2Pconfig>

Check the Crypt2pay manual to make sure that other elements of the c2p.xml are correct, in particular,

• the name of the . ksk file in C2Pconfig/KSKfile
• the name of the . kdk file in C2Pconfig/C2pSlot/C2PBox/KDKfile
• the IP address of the HSM in C2Pconfig/C2pSlot/C2PBox/IP

.. and recover the configured Slot ID(s) in C2Pconfig/C2pSlot[Id]"

IMPORTANT NOTE: The configuration above authenticates the HSM only. To configure mutual authentication with mTLS, additional configuration is required. Check the Crypt2pay manual for details.

Set the C2P_CONF environment variable to [C2P_DIR]/c2p.xml

export C2P_CONF=[C2P_DIR]/c2p.xml

replace [C2P_DIR] with the actual path.

Test the configuration

Run the p11tool tool to create a new 256-bit AES key:

./p11tool -genkey -keyalg aes -keysize 256 -shared /lib/libpkcs11c2p.so -slot 1 -verbose

The creation should be successful and print the key alias and ID:

use slot #1
Alias 'mykey' selected
Secret key #1000004 created

The logs are available in [C2P_DIR]/logs/c2p.trc.

KMS Configuration

When using the TOML configuration file, enable HSM support by setting these parameters:

hsm_model = "crypt2pay"
hsm_admin = "<HSM_ADMIN_USERNAME>" # defaults to "admin"
hsm_slot = [0, 0, ] # example [0,4] for slots 0 and 4
hsm_password = ["<password>", "<password>", ] # example ["648219", "648219"] for slots 0 and 4

NOTE: hsm_slot and hsm_password must always be arrays, even if only one slot is used.

The order of the passwords must match the order of the slots in the hsm_slot array.

If you want to login with an empty (null) password, use an empty string.

If you do not want to login, use the special password value <NO_LOGIN>

Configuration via command-line

HSM support can also be enabled with command-line arguments:

--hsm-model "crypt2pay" \
--hsm-admin "<HSM_ADMIN_USERNAME>"  \
--hsm-slot <number_of_1st_slot> --hsm-password <password_of_1st_slot> \
--hsm-slot <number_of_2and_slot> --hsm-password <password_of_2and_slot>

The hsm-model parameter is the HSM model. Use crypt2pay.

The hsm-admin parameter is the username of the HSM administrator. The HSM administrator is the only user who can create objects on the HSM via the KMIP Create operation and delegate other operations to other users.

The hsm-slot and hsm-password parameters are the slot number and user password (PIN) of the HSM slots used by the KMS. These options can be repeated to configure multiple slots.

NOTE: To list available slots and keys run from the [C2P_DIR] directory:

./p11tool -list -shared /lib/libpkcs11c2p.so -verbose

Eviden KMS natively integrates with the Trustway Proteccio HSM.

Proteccio library setup

This solution works on Linux (x86_64) and has been validated against the Proteccio nethsm library version 3.17.

The KMS expects:

• the Proteccio nethsm library to be installed in /lib/libnethsm.so
• and the Proteccio configuration files in /etc/proteccio.

/etc/proteccio configuration files

The Proteccio client library reads its configuration from /etc/proteccio. The directory must contain the following files:

The proteccio.rc / proteccio.ini file contains two sections:

[PROTECCIO]
IPaddr=<HSM_IP_ADDRESS>   ; IP address of the Proteccio appliance
SSL=1                     ; Enable TLS (1) or plain TCP (0)
SrvCert=proteccio.crt     ; Server certificate filename (relative to /etc/proteccio)
SEC_CHANNEL=1             ; Enable encrypted secure channel (1) or not (0)
SecChlSrvKey=secchannel_hsm.pem  ; HSM secure-channel public key filename

[CLIENT]
Mode=0                    ; 0 = synchronous
LoggingLevel=7            ; Verbosity (0–7, 7 = most verbose)
LogFile=proteccio_log_file.log   ; Path to the library log file
ClntKey=proteccio_client.key     ; Client TLS private key filename
ClntCert=proteccio_client.crt    ; Client TLS certificate filename
SecChlClntPrivKey=secchl_clt_privkey.pem  ; Client secure-channel private key
SecChlClntPubKey=secchl_clt_pubkey.pem    ; Client secure-channel public key

NOTE: All filenames in the configuration file are relative to /etc/proteccio unless an absolute path is given.

A secondary status log (HSM_Status.log) is written to /etc/proteccio by the nethsmstatus monitoring daemon and records HSM availability events. It is not read by the KMS.

Please run the nethsmstatus tool to check the status of the HSM before proceeding with the rest of the installation.

KMS configuration

At least one slot and its corresponding password must be configured. Any slot and any number of slots may be used.

When using the TOML configuration file, the HSM support is enabled by configuring these 4 parameters:

hsm_model = "proteccio"
hsm_admin = "<HSM_ADMIN_USERNAME>" # defaults to "admin"
hsm_slot = [0, 0, ] # example [1,4] for slots 1 and 4
hsm_password = ["<password>", "<password>", ] # example ["pass1", "pass4"] for slots 1 and 4

NOTE: hsm_slot and hsm_password must always be arrays, even if only one slot is used.

The order of the passwords must match the order of the slots in the hsm_slot array.

If you want to login with an empty (null) password, use an empty string.

If you do not want to login, use the special password value <NO_LOGIN>

When the KMS is started from the command line, the HSM support can be enabled by using the following arguments:

--hsm-model "proteccio" \
--hsm-admin "<HSM_ADMIN_USERNAME>"  \
--hsm-slot <number_of_1st_slot> --hsm-password <password_of_1st_slot> \
--hsm-slot <number_of_2and_slot> --hsm-password <password_of_2and_slot>

The hsm-model parameter is the HSM model to be used; use proteccio

The hsm-admin parameter is the username of the HSM administrator. The HSM administrator is the only user that can create objects on the HSM via the KMIP Create operation the delegate other operations to other users. (see below)

The hsm-slot and hsm-password parameters are the slot number and password of the HSM slots to be used by the KMS. These arguments can be repeated multiple times to specify multiple slots.

This solution works on Linux (x86_64) and has been validated against the Utimaco client library version 6.0.

Utimaco library setup

This solution works on Linux (x64_86) and has been validated against the Utimaco libcs_pkcs11_R3.so library version 6.0.

The KMS expects:

• the Utimaco cs_pkcs11_R3 library to be installed in /lib/libcs_pkcs11_R3.so
• the Utimaco configuration file cs_pkcs11_R3.cfg to be in /etc/utimaco and
• and the environment variable CS_PKCS11_R3_CF to point to it, i.e.,

export CS_PKCS11_R3_CFG=/etc/utimaco/cs_pkcs11_R3.cfg

Please make sure the cs_pkcs11_R3.cfg is set with the correct parameter, and validate your installation with the p11tool2 utility, by running, for instance,

./p11tool2 Slot=0 GetSlotInfo

KMS configuration

At least one slot and its corresponding password must be configured. Any slot and any number of slots may be used.

When using the TOML configuration file, the HSM support is enabled by configuring these 4 parameters:

hsm_model = "utimaco"
hsm_admin = "<HSM_ADMIN_USERNAME>" # defaults to "admin"
hsm_slot = [0, 0, ] # example [0,4] for slots 0 and 4
hsm_password = ["<password>", "<password>", ] # example ["pass0", "pass4"] for slots 0 and 4

NOTE: hsm_slot and hsm_password must always be arrays, even if only one slot is used.

The order of the passwords must match the order of the slots in the hsm_slot array.

If you want to login with an empty (null) password, use an empty string.

If you do not want to login, use the special password value <NO_LOGIN>

When the KMS is started from the command line, the HSM support can be enabled by using the following arguments:

--hsm-model "utimaco" \
--hsm-admin "<HSM_ADMIN_USERNAME>"  \
--hsm-slot <number_of_1st_slot> --hsm-password <password_of_1st_slot> \
--hsm-slot <number_of_2and_slot> --hsm-password <password_of_2and_slot>

The hsm-model parameter is the HSM model; use utimaco.

The hsm-admin parameter is the username of the HSM administrator. The HSM administrator is the only user who can create objects on the HSM via the KMIP Create operation and delegate other operations to other users. (see below)

The hsm-slot and hsm-password parameters are the slot number and user password of the HSM slots used by the KMS. These arguments can be repeated multiple times to specify various slots.

Using the simulator

Utimaco provides a simulator that can be used instead of a physical HSM to test your installation. The simulator is a 32-bit Linux i386 library (it also exists as a Windows binary).

Follow these general steps to install the simulator on a Debian-based (e.g., Ubuntu) Linux amd64/x86_64.

1. Enable 32-bit support

   sudo dpkg --add-architecture i386
   

   Then

   sudo apt-get update
   sudo apt-get install libc6:i386 libncurses5:i386 libstdc++6:i386
   

2. Start the simulator

   In <eval-bundle-6.0.0>\Software\Windows\Simulator\sim5_windows\bin, run

   .\bl_sim5.exe -h -o -d ..\devices\
   

3. Make sure the Device in cs_pkcs11_R3.cfg points to the simulator.

4. Initialize a slot and create the Security Officer and User pins.

   Due to a bug (?) in the simulator, the Security Officer PIN must be set then changed before the User PIN can be set, and then changed as well.

   # Set the SO PIN to 11223344
   ./p11tool2 Slot=0 login=ADMIN,./key/ADMIN_SIM.key  InitToken=11223344
   # Change the SO PIN to 12345678
   ./p11tool2 Slot=0 LoginSO=11223344 SetPin=11223344,12345678
   

   Failing to change the SO PIN before setting the User PIN will result in the following error: Error 0x000001B8 ( CKR_PIN_TOO_WEAK)

   # Set the User PIN to 11223344
   ./p11tool2 Slot=0 LoginSO=12345678 InitPin=11223344
   # Change the User PIN to 12345678
   ./p11tool2 Slot=0 LoginUser=11223344 SetPin=11223344,12345678
   

   Now, both the SO and User PINs have been set to 12345678.

   To list objects on Slot 0, use:

   ./p11tool2 Slot=0 LoginUser=12345678 ListObjects
   

The Smartcard HSM integration is supported on Linux (x86_64). It has been tested with the following devices:

• SC HSM 4k (Smartcard and USB variants)
• Nitrokey HSM 2

Smartcard HSM library setup

To use a Smartcard HSM with the KMS, the sc-hsm-embedded PKCS#11 library must be installed. The integration has been validated with version 2.12.

The KMS expects the library to be installed at /usr/local/lib/libsc-hsm-pkcs11.so.

To build and install the library, follow the instructions in the sc-hsm-embedded GitHub repository.

Smartcard HSM initialisation

⚠️ Warning:

• Initialization is destructive. It will erase all existing keys and objects on the HSM.
• Losing the Security Officer (SO) PIN will prevent future resets of the HSM. This can make the device permanently unusable. Keep it secure.

NOTE: The default PINs shown below are recommended by the manufacturer for development purposes. Always change them in production.

Before use, the HSM must be initialized. There are two ways to accomplish this:

Graphical Initialization (SmartCard-HSM Key Manager)

1. Download and install Smart Card Shell.
2. Launch Smart Card Shell and insert the HSM.
3. From the File menu (or with CTRL+M), open the SmartCard-HSM Key Manager.
4. Right-click on the HSM entry and select Initialize Device.
5. Follow the on-screen guide.

Using sc-hsm-tool

1. Install the OpenSC for your distribution.

2. Initialize the card with a Security Officer and a User PIN.

   sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219 --label "SC HSM test"
   

   Additional initialisation options are documented in the sc-hsm-tool man page.

KMS configuration

At least one slot and its corresponding PIN must be configured. Multiple slots can be used simultaneously, with each represented by a separate slot.

Configuration via config file

When using the TOML configuration file, enable HSM support by setting these parameters:

hsm_model = "smartcardhsm"
hsm_admin = "<HSM_ADMIN_USERNAME>" # defaults to "admin"
hsm_slot = [0, 0, ] # example [0,4] for slots 0 and 4
hsm_password = ["<password>", "<password>", ] # example ["648219", "648219"] for slots 0 and 4

NOTE: hsm_slot and hsm_password must always be arrays, even if only one slot is used.

The order of the passwords must match the order of the slots in the hsm_slot array.

If you want to login with an empty (null) password, use an empty string.

If you do not want to login, use the special password value <NO_LOGIN>

Configuration via command-line

HSM support can also be enabled with command-line arguments:

--hsm-model "smartcardhsm" \
--hsm-admin "<HSM_ADMIN_USERNAME>"  \
--hsm-slot <number_of_1st_slot> --hsm-password <password_of_1st_slot> \
--hsm-slot <number_of_2and_slot> --hsm-password <password_of_2and_slot>

The hsm-model parameter is the HSM model. Use smartcardhsm.

The hsm-admin parameter is the username of the HSM administrator. The HSM administrator is the only user who can create objects on the HSM via the KMIP Create operation and delegate other operations to other users.

The hsm-slot and hsm-password parameters are the slot number and user password (PIN) of the HSM slots used by the KMS. These options can be repeated to configure multiple slots.

NOTE: To list available slots, run:

pkcs11-tool --module /usr/local/lib/libsc-hsm-pkcs11.so --list-slots

The SoftHSMv2 integration is supported on Linux (x86_64).

SoftHSMv2 library setup

To use SoftHSMv2 with the KMS, the library must first be installed.

The KMS expects the library to be installed at /usr/lib/softhsm/libsofthsm2.so.

Install the library using your distributions package manager, or build it by following the instructions in the SoftHSMv2 GitHub repository.

SoftHSMv2 initialisation

Before use, SoftHSMv2 requires initialization:

softhsm2-util --init-token --slot 0 --so-pin 000000 --pin 000000 --label "SoftHSM"

NOTE: The slot number will be reassigned randomly. Use the new slot number in your KMS configuration.

KMS configuration

At least one slot and its corresponding PIN must be configured. Multiple slots can be used at the same time.

Configuration via config file

When using the TOML configuration file, enable HSM support by setting these parameters:

hsm_model = "softhsm2"
hsm_admin = "<HSM_ADMIN_USERNAME>" # defaults to "admin"
hsm_slot = [0, 0, ] # example [0,4] for slots 0 and 4
hsm_password = ["<password>", "<password>", ] # example ["000000", "444444"] for slots 0 and 4

NOTE: hsm_slot and hsm_password must always be arrays, even if only one slot is used.

The order of the passwords must match the order of the slots in the hsm_slot array.

If you want to login with an empty (null) password, use an empty string.

If you do not want to login, use the special password value <NO_LOGIN>

Configuration via command-line

HSM support can also be enabled with command-line arguments:

--hsm-model "softhsm2" \
--hsm-admin "<HSM_ADMIN_USERNAME>"  \
--hsm-slot <number_of_1st_slot> --hsm-password <password_of_1st_slot> \
--hsm-slot <number_of_2and_slot> --hsm-password <password_of_2and_slot>

The hsm-model parameter is the HSM model. Use softhsm2.

The hsm-admin parameter is the username of the HSM administrator. The HSM administrator is the only user who can create objects on the HSM via the KMIP Create operation and delegate other operations to other users.

The hsm-slot and hsm-password parameters are the slot number and user password (PIN) of the HSM slots used by the KMS. These options can be repeated to configure multiple slots.

NOTE: To list available slots, run:

softhsm2-util --show-slots

Integration of other HSMs is supported on Linux (x86_64).

Even if your HSM is not explicitly listed in this documentation, there is a great chance that it will work, in particular its PKCS#11 driver API is compatible with that of SofHsmV2.

Library setup

The KMS expects the HSM linux PKCS#11 library to be installed at /lib/libkmshsm.so. Rename your HSM library to libkmshsm.so if necessary.

HSM initialization

Before using the HSM with the KMS, follow your documentation to initialize a slot and a user pin/password for that slot.

KMS configuration

At least one slot and its corresponding PIN must be configured. Multiple slots can be used at the same time.

Configuration via config file

When using the TOML configuration file, enable HSM support by setting these parameters:

hsm_model = "other"
hsm_admin = "<HSM_ADMIN_USERNAME>" # defaults to "admin"
hsm_slot = [0, 0, ] # example [0,4] for slots 0 and 4
hsm_password = ["<password>", "<password>", ] # example ["000000", "444444"] for slots 0 and 4

NOTE: hsm_slot and hsm_password must always be arrays, even if only one slot is used.

The order of the passwords must match the order of the slots in the hsm_slot array.

If you want to login with an empty (null) password, use an empty string.

If you do not want to login, use the special password value <NO_LOGIN>

Configuration via command-line

HSM support can also be enabled with command-line arguments:

--hsm-model "other" \
--hsm-admin "<HSM_ADMIN_USERNAME>"  \
--hsm-slot <number_of_1st_slot> --hsm-password <password_of_1st_slot> \
--hsm-slot <number_of_2and_slot> --hsm-password <password_of_2and_slot>

The hsm-model parameter is the HSM model. Use other.

The hsm-admin parameter is the username of the HSM administrator. The HSM administrator is the only user who can create objects on the HSM via the KMIP Create operation and delegate other operations to other users.

The hsm-slot and hsm-password parameters are the slot number and user password (PIN) of the HSM slots used by the KMS. These options can be repeated to configure multiple slots.

API

The Eviden KMS server implements the JSON TTLV profile of the KMIP 1.x and 2.x specifications. In addition, the server exposes a few additional endpoints for authorization operations.

Calling the KMIP API

This API is documented in the KMIP section of this manual.

Calling the authorization API

This API is documented in the authorization section of this manual.

Authentication

The Eviden server supports various authorization mechanisms: see the authentication section of this manual for details. When authenticating using JWT, an HTTP Authorization header must be passed with the JWT token as a bearer token.

For example: Authorization: Bearer <JWT_TOKEN>

REST Native Crypto API

In addition to the KMIP protocol, the server exposes a lightweight JOSE-compatible REST API under /v1/crypto for encrypt, decrypt, sign, verify, and MAC operations. See the REST Native Crypto API page for full documentation.

OpenAPI specification and interactive documentation

The KMS server exposes its full API as an OpenAPI 3.1 specification and serves an interactive Swagger UI browser directly from the server binary.

Using the Swagger UI

Navigate to <server_url>/swagger in a browser. The page serves Swagger UI assets directly from the KMS server binary (no external CDN dependency) and applies a strict Content-Security-Policy header with frame-ancestors 'none' for clickjacking protection.

https://<your-kms-host>:9998/swagger

The UI displays all documented operations grouped by tag:

• KMIP — TTLV-over-HTTP (POST /kmip/2_1, POST /kmip/1_4)
• REST Crypto API — key lifecycle, encrypt/decrypt/sign/verify/MAC under /v1/crypto
• Server — health, version, server-info
• Access control — grant, revoke, list, and check permissions
• HSM — HSM status
• Download — CLI download endpoint

Downloading the spec

curl -O https://<your-kms-host>:9998/openapi.yaml

The downloaded YAML can be imported into any OpenAPI-compatible tooling (Postman, Insomnia, code generators, etc.).

REST Native Crypto API (/v1/crypto)

The Eviden KMS exposes a lightweight REST Native Crypto API under the /v1/crypto path. This API follows the JOSE (JSON Object Signing and Encryption) conventions from RFC 7516 (JWE), RFC 7515 (JWS), and RFC 7518 (JWA).

Key material never leaves the KMS. Only ciphertext, signatures, and MACs travel over the network.

Table of Contents

• Authentication
• Endpoints
  • POST /v1/crypto/keys
  • DELETE /v1/crypto/keys/{kid}
  • POST /v1/crypto/keys/unwrap
  • POST /v1/crypto/encrypt
  • POST /v1/crypto/decrypt
  • POST /v1/crypto/sign
  • POST /v1/crypto/verify
  • POST /v1/crypto/mac
• Key tag management
  • POST /v1/crypto/keys/{kid}/tags
  • DELETE /v1/crypto/keys/{kid}/tags
  • GET /v1/crypto/keys/{kid}/tags
• Error responses
• Known limitations
• Algorithm support matrix

Authentication

The /v1/crypto endpoints share the same authentication as the rest of the KMS API. Pass a JWT bearer token, a TLS client certificate, or an API token, depending on your server configuration. See Authentication.

Endpoints

POST /v1/crypto/keys

Generate or import a cryptographic key (or key pair) in the KMS. The request follows JWK conventions — specify kty (key type) and alg (algorithm) at minimum.

• Generate: omit key material fields to create a new random key.
• Import: include key material (k for symmetric, d for asymmetric) to import an existing key.

Request body

{
  "kty": "oct",
  "alg": "A256GCM"
}

Response body

{
  "kid": "<key-uuid>",
  "kid_public": "<public-key-uuid>"  // only for generated asymmetric key pairs
}

Note: Imported asymmetric keys return kid_public: null because only the private key is stored. The KMS derives the public key internally when needed for verification or encryption.

Examples

Symmetric key generation (AES-256-GCM):

{ "kty": "oct", "alg": "A256GCM" }

Symmetric key import (HMAC-SHA256):

{ "kty": "oct", "alg": "HS256", "k": "<base64url-encoded-32-byte-key>" }

RSA key pair generation (PS256):

{ "kty": "RSA", "alg": "PS256" }

EC key import (P-256):

{ "kty": "EC", "crv": "P-256", "alg": "ES256", "d": "<base64url-encoded-scalar>" }

RSA key import:

{
  "kty": "RSA", "alg": "RS256",
  "n": "<modulus>", "e": "AQAB", "d": "<private-exponent>",
  "p": "<prime1>", "q": "<prime2>",
  "dp": "<exponent1>", "dq": "<exponent2>", "qi": "<coefficient>"
}

DELETE /v1/crypto/keys/{kid}

Destroy (permanently delete) a key from the KMS. The key is first revoked (deactivated) then removed from the database, including any linked public/private key in the pair.

Path parameters

Response

• 204 No Content on success (empty body).

POST /v1/crypto/keys/unwrap

Unwrap (decrypt) a JWE encrypted_key using an RSA private key and import the resulting symmetric CEK into the KMS as a managed key. The raw key material is never returned to the caller — only a kid identifier is provided.

This endpoint is designed for the JWE decryption use case where the same CEK is reused across multiple messages: unwrap once, then decrypt subsequent ciphertexts using POST /v1/crypto/decrypt with alg=dir.

Supported alg values: RSA-OAEP, RSA-OAEP-256. Supported enc values: A128GCM, A192GCM, A256GCM.

Flow — Unwrap CEK then decrypt

sequenceDiagram
    participant Client
    participant KMS
    Note over Client,KMS: Prerequisite: RSA key pair exists in KMS
    Client->>KMS: POST /v1/crypto/keys/unwrap<br/>{protected: {alg,enc,kid}, encrypted_key}
    Note over KMS: RSA-OAEP decrypt → CEK<br/>Import CEK as Active symmetric key
    KMS-->>Client: {"kid":"<cek-uuid>","kty":"oct","alg":"A256GCM","key_ops":[...]}
    Client->>KMS: POST /v1/crypto/decrypt<br/>{protected: {alg:"dir",enc,kid:"<cek-uuid>"},<br/>iv, ciphertext, tag}
    Note over KMS: AES-GCM decrypt with persisted CEK
    KMS-->>Client: {"kid":"<cek-uuid>","data":"..."}

Request body

{
  "protected":     "<base64url JWE Protected Header>",
  "encrypted_key": "<base64url wrapped CEK>"
}

The protected header must decode to a JSON object containing:

Response body

{
  "kid":     "<cek-uuid>",
  "kty":     "oct",
  "alg":     "A256GCM",
  "key_ops": ["encrypt", "decrypt"]
}

Error conditions

Example (curl)

# Assume $PROTECTED and $ENCRYPTED_KEY come from a JWE token
# The protected header contains {"alg":"RSA-OAEP-256","enc":"A256GCM","kid":"<priv-uuid>"}

# 1. Unwrap the CEK
UNWRAP_RESP=$(curl -s -X POST https://kms.example.com/v1/crypto/keys/unwrap \
  -H 'Content-Type: application/json' \
  -d "{\"protected\":\"$PROTECTED\",\"encrypted_key\":\"$ENCRYPTED_KEY\"}")
CEK_KID=$(echo "$UNWRAP_RESP" | jq -r '.kid')

# 2. Decrypt subsequent ciphertexts using the persisted CEK
# Build a protected header for direct decryption:
DIR_HEADER=$(printf '{"alg":"dir","enc":"A256GCM","kid":"%s"}' "$CEK_KID" \
  | base64 | tr '+/' '-_' | tr -d '=')
curl -s -X POST https://kms.example.com/v1/crypto/decrypt \
  -H 'Content-Type: application/json' \
  -d "{\"protected\":\"$DIR_HEADER\",\"iv\":\"$IV\",\"ciphertext\":\"$CT\",\"tag\":\"$TAG\"}" \
  | jq -r '.data | @base64d'

# 3. Clean up
curl -s -X DELETE https://kms.example.com/v1/crypto/keys/$CEK_KID

POST /v1/crypto/encrypt

Encrypt plaintext using either:

• Direct encryption (alg=dir): uses a symmetric key directly as the content encryption key (CEK).
• RSA-OAEP key wrapping (alg=RSA-OAEP or alg=RSA-OAEP-256): generates an ephemeral CEK, wraps it with the RSA public key, and encrypts data with AES-GCM.

Supported alg values: dir, RSA-OAEP, RSA-OAEP-256. Supported enc values: A128GCM, A192GCM, A256GCM.

Flow — Direct (dir)

sequenceDiagram
    participant Client
    participant KMS
    Client->>KMS: POST /v1/crypto/keys {"kty":"oct","alg":"A256GCM"}
    KMS-->>Client: {"kid":"<uuid>"}
    Client->>KMS: POST /v1/crypto/encrypt {"kid":"<uuid>","alg":"dir","enc":"A256GCM","data":"..."}
    Note over KMS: AES-GCM encrypt with symmetric key
    KMS-->>Client: {"protected":"...","encrypted_key":"","iv":"...","ciphertext":"...","tag":"..."}
    Client->>KMS: POST /v1/crypto/decrypt {"protected":"...","iv":"...","ciphertext":"...","tag":"..."}
    Note over KMS: AES-GCM decrypt with symmetric key
    KMS-->>Client: {"kid":"<uuid>","data":"..."}
    Client->>KMS: DELETE /v1/crypto/keys/<uuid>
    KMS-->>Client: 204 No Content

Flow — RSA-OAEP

sequenceDiagram
    participant Client
    participant KMS
    Client->>KMS: POST /v1/crypto/keys {"kty":"RSA","bits":2048}
    KMS-->>Client: {"kid":"<priv-uuid>","kid_public":"<pub-uuid>"}
    Client->>KMS: POST /v1/crypto/encrypt {"kid":"<pub-uuid>","alg":"RSA-OAEP-256","enc":"A256GCM","data":"..."}
    Note over KMS: Generate ephemeral CEK<br/>Wrap CEK with RSA-OAEP-256<br/>AES-GCM encrypt data<br/>Wipe CEK from memory
    KMS-->>Client: {"protected":"...","encrypted_key":"<wrapped-CEK>","iv":"...","ciphertext":"...","tag":"..."}
    Client->>KMS: POST /v1/crypto/decrypt {"protected":"...","encrypted_key":"<wrapped-CEK>","iv":"...","ciphertext":"...","tag":"..."}
    Note over KMS: RSA-OAEP unwrap → CEK<br/>AES-GCM decrypt<br/>(implicit rejection on OAEP failure)
    KMS-->>Client: {"kid":"<priv-uuid>","data":"..."}
    Client->>KMS: DELETE /v1/crypto/keys/<priv-uuid>
    KMS-->>Client: 204 No Content (cascades to public key)

Request body

{
  "kid": "<key-uuid>",
  "alg": "RSA-OAEP",
  "enc": "A256GCM",
  "data": "<base64url-encoded plaintext>",
  "aad": "<base64url-encoded AAD>"   // optional
}

Response body (Flattened JWE)

{
  "protected":     "<base64url JWE Protected Header>",
  "encrypted_key": "<base64url wrapped CEK>",
  "iv":            "<base64url IV>",
  "ciphertext":    "<base64url ciphertext>",
  "tag":           "<base64url GCM authentication tag>",
  "aad":           "<base64url AAD>"   // omitted when not supplied
}

For alg=dir, the encrypted_key field is an empty string. For RSA-OAEP, it contains the RSA-OAEP-wrapped CEK.

Example — Direct encryption (curl)

# 1. Create a 256-bit AES key
KID=$(curl -s -X POST https://kms.example.com/v1/crypto/keys \
  -H 'Content-Type: application/json' \
  -d '{"kty":"oct","alg":"A256GCM"}' | jq -r '.kid')

# 2. Encrypt
DATA_B64=$(printf 'Hello KMS!' | base64 | tr '+/' '-_' | tr -d '=')
JWE=$(curl -s -X POST https://kms.example.com/v1/crypto/encrypt \
  -H 'Content-Type: application/json' \
  -d "{\"kid\":\"$KID\",\"alg\":\"dir\",\"enc\":\"A256GCM\",\"data\":\"$DATA_B64\"}")

# 3. Decrypt
curl -s -X POST https://kms.example.com/v1/crypto/decrypt \
  -H 'Content-Type: application/json' \
  -d "$JWE" | jq -r '.data | @base64d'

# 4. Clean up
curl -s -X DELETE https://kms.example.com/v1/crypto/keys/$KID

Example — RSA-OAEP (curl)

# 1. Create an RSA-2048 key pair
KEYS=$(curl -s -X POST https://kms.example.com/v1/crypto/keys \
  -H 'Content-Type: application/json' \
  -d '{"kty":"RSA","bits":2048}')
KID=$(echo "$KEYS" | jq -r '.kid')
KID_PUB=$(echo "$KEYS" | jq -r '.kid_public')

# 2. Encrypt with RSA-OAEP-256 using the public key
DATA_B64=$(printf 'Secret message' | base64 | tr '+/' '-_' | tr -d '=')
JWE=$(curl -s -X POST https://kms.example.com/v1/crypto/encrypt \
  -H 'Content-Type: application/json' \
  -d "{\"kid\":\"$KID_PUB\",\"alg\":\"RSA-OAEP-256\",\"enc\":\"A256GCM\",\"data\":\"$DATA_B64\"}")

# 3. Decrypt (kid in protected header resolves to private key automatically)
curl -s -X POST https://kms.example.com/v1/crypto/decrypt \
  -H 'Content-Type: application/json' \
  -d "$JWE" | jq -r '.data | @base64d'

# 4. Clean up (cascades to the linked public key)
curl -s -X DELETE https://kms.example.com/v1/crypto/keys/$KID

POST /v1/crypto/decrypt

Decrypt a Flattened JWE token.

Supports both alg=dir (direct AES-GCM) and alg=RSA-OAEP/RSA-OAEP-256 (RSA-OAEP key unwrapping + AES-GCM content decryption).

The kid in the JWE protected header identifies the decryption key. For RSA-OAEP, this can be either the private key or the public key UUID (the server resolves to the private key automatically).

The decrypt endpoint has no standalone flow diagram — it is the second half of the encrypt/decrypt flows shown in the encrypt section above.

Request body

{
  "protected":     "<base64url JWE Protected Header>",
  "encrypted_key": "<base64url wrapped CEK>",
  "iv":            "<base64url IV>",
  "ciphertext":    "<base64url ciphertext>",
  "tag":           "<base64url GCM authentication tag>",
  "aad":           "<base64url AAD>"  // optional; must match the value used during encryption
}

Response body

{
  "kid":  "<key-uuid>",
  "data": "<base64url plaintext>"
}

Security: implicit rejection

For RSA-OAEP decryption, the server implements implicit rejection as recommended by RFC 7516 §11.5. If the RSA-OAEP unwrap fails (indicating a tampered or invalid encrypted_key), the server substitutes a random CEK and proceeds with AES-GCM decryption — which will fail with the same generic "Decryption failed" error. This prevents padding oracle attacks.

Example (curl)

# JWE is the JSON response from POST /v1/crypto/encrypt
PLAINTEXT=$(curl -s -X POST https://kms.example.com/v1/crypto/decrypt \
  -H 'Content-Type: application/json' \
  -d "$JWE" | jq -r '.data | @base64d')
echo "$PLAINTEXT"

POST /v1/crypto/sign

Sign data using an asymmetric private key. Returns a detached JWS (payload not included in the response).

Supported algorithms: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512; EdDSA and MLDSA44 (non-FIPS builds only).

Flow — Sign and verify

sequenceDiagram
    participant Client
    participant KMS
    Client->>KMS: POST /v1/crypto/keys {"kty":"RSA","alg":"PS256"}
    KMS-->>Client: {"kid":"<priv-uuid>","kid_public":"<pub-uuid>"}
    Client->>KMS: POST /v1/crypto/sign {"kid":"<priv-uuid>","alg":"PS256","data":"<b64>"}
    Note over KMS: RSA-PSS sign with private key
    KMS-->>Client: {"protected":"<b64-header>","signature":"<b64>"}
    Client->>KMS: POST /v1/crypto/verify {"protected":"<b64-header>","data":"<b64>","signature":"<b64>"}
    Note over KMS: Decode protected header → kid<br/>Fetch public key<br/>RSA-PSS verify
    KMS-->>Client: {"kid":"<pub-uuid>","valid":true}
    Client->>KMS: DELETE /v1/crypto/keys/<priv-uuid>
    KMS-->>Client: 204 No Content (cascades to public key)

Request body

{
  "kid":  "<private-key-uuid>",
  "alg":  "RS256",
  "data": "<base64url payload>"
}

Response body

{
  "protected": "<base64url JWS Protected Header>",
  "signature": "<base64url signature>"
}

Example (curl)

# 1. Create an RSA-2048 key pair
KEYS=$(curl -s -X POST https://kms.example.com/v1/crypto/keys \
  -H 'Content-Type: application/json' \
  -d '{"kty":"RSA","alg":"RS256"}')
KID=$(echo "$KEYS" | jq -r '.kid')

# 2. Sign
DATA_B64=$(printf 'data to sign' | base64 | tr '+/' '-_' | tr -d '=')
SIGN_RESP=$(curl -s -X POST https://kms.example.com/v1/crypto/sign \
  -H 'Content-Type: application/json' \
  -d "{\"kid\":\"$KID\",\"alg\":\"RS256\",\"data\":\"$DATA_B64\"}")

# 3. Verify
curl -s -X POST https://kms.example.com/v1/crypto/verify \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --argjson s "$SIGN_RESP" --arg d "$DATA_B64" \
       '{protected:$s.protected,data:$d,signature:$s.signature}')"

# 4. Clean up
curl -s -X DELETE https://kms.example.com/v1/crypto/keys/$KID

POST /v1/crypto/verify

Verify a detached JWS signature. The KMS looks up the public key from the protected header.

Required: the JWS protected header decoded from protected must contain a kid field set to the KMS public key UUID. Requests without kid are rejected with 400. This field is set automatically by POST /v1/crypto/sign.

The verify endpoint is the second half of the sign/verify flow shown in the sign section above.

Request body

{
  "protected": "<base64url JWS Protected Header (contains kid + alg)>",
  "data":      "<base64url payload>",
  "signature": "<base64url signature>"
}

Response body

{
  "kid":   "<public-key-uuid>",
  "valid": true   // false when the signature does not match
}

POST /v1/crypto/mac

Compute or verify a MAC (Message Authentication Code).

• Compute: omit the mac field → the KMS returns the computed MAC value.
• Verify: include the mac field → the KMS returns valid: true/false.

Supported algorithms: HS256, HS384, HS512.

Flow — MAC compute and verify

sequenceDiagram
    participant Client
    participant KMS
    Client->>KMS: POST /v1/crypto/keys {"kty":"oct","alg":"HS256"}
    KMS-->>Client: {"kid":"<uuid>"}
    Client->>KMS: POST /v1/crypto/mac {"kid":"<uuid>","alg":"HS256","data":"<b64>"}
    Note over KMS: HMAC-SHA256 compute
    KMS-->>Client: {"kid":"<uuid>","mac":"<b64>"}
    Client->>KMS: POST /v1/crypto/mac {"kid":"<uuid>","alg":"HS256","data":"<b64>","mac":"<b64>"}
    Note over KMS: HMAC-SHA256 verify
    KMS-->>Client: {"kid":"<uuid>","valid":true}
    Client->>KMS: DELETE /v1/crypto/keys/<uuid>
    KMS-->>Client: 204 No Content

Request body

{
  "kid":  "<key-uuid>",
  "alg":  "HS256",
  "data": "<base64url data>",
  "mac":  "<base64url MAC to verify>"  // omit to compute
}

Response body — compute

{
  "kid": "<key-uuid>",
  "mac": "<base64url MAC>"
}

Response body — verify

{
  "kid":   "<key-uuid>",
  "valid": true   // false when the MAC does not match
}

RFC 7515 §A.1 known-answer vector

The MAC value below is pinned by an integration test (test_rfc7515_a1_hs256_known_answer). It reproduces the exact HS256 result from RFC 7515 §Appendix A.1.

Example (curl)

# 1. Create an HMAC-SHA256 key
KID=$(curl -s -X POST https://kms.example.com/v1/crypto/keys \
  -H 'Content-Type: application/json' \
  -d '{"kty":"oct","alg":"HS256"}' | jq -r '.kid')

# 2. Compute MAC
DATA_B64=$(printf 'message' | base64 | tr '+/' '-_' | tr -d '=')
MAC_RESP=$(curl -s -X POST https://kms.example.com/v1/crypto/mac \
  -H 'Content-Type: application/json' \
  -d "{\"kid\":\"$KID\",\"alg\":\"HS256\",\"data\":\"$DATA_B64\"}")
MAC_VALUE=$(echo "$MAC_RESP" | jq -r '.mac')

# 3. Verify MAC
curl -s -X POST https://kms.example.com/v1/crypto/mac \
  -H 'Content-Type: application/json' \
  -d "{\"kid\":\"$KID\",\"alg\":\"HS256\",\"data\":\"$DATA_B64\",\"mac\":\"$MAC_VALUE\"}"

# 4. Clean up
curl -s -X DELETE https://kms.example.com/v1/crypto/keys/$KID

Key tag management

User-defined string tags can be attached to any key stored in the KMS. Tags enable key discovery (for example the JWKS endpoint returns only keys tagged "jwks") and custom key grouping.

Rules:

• Tags are arbitrary, non-empty strings.
• Tags starting with _ are system tags (_kk, _sk, _pk, _cert, …) and cannot be created or deleted through these endpoints.
• All write operations are idempotent: adding an existing tag or removing a missing tag has no effect.

POST /v1/crypto/keys/{kid}/tags

Add one or more user tags to a key. Existing tags are preserved.

Request body

{ "tags": ["jwks", "prod"] }

Response body

{ "kid": "<key-uuid>", "tags": ["jwks", "prod"] }

The tags array reflects the complete current set of user tags after the operation (sorted, system tags excluded).

Status codes

curl example

curl -s -X POST "https://kms.example.com/v1/crypto/keys/${KID}/tags" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["jwks", "prod"]}'

DELETE /v1/crypto/keys/{kid}/tags

Remove one or more user tags from a key. Tags not present on the key are silently ignored.

Request body

{ "tags": ["prod"] }

Response body

{ "kid": "<key-uuid>", "tags": ["jwks"] }

The tags array reflects the remaining user tags after removal.

Status codes

curl example

curl -s -X DELETE "https://kms.example.com/v1/crypto/keys/${KID}/tags" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["prod"]}'

GET /v1/crypto/keys/{kid}/tags

List the current user tags on a key. No body required.

Response body

{ "kid": "<key-uuid>", "tags": ["jwks"] }

System tags are never included.

Status codes

curl example

curl -s "https://kms.example.com/v1/crypto/keys/${KID}/tags" \
  -H "Authorization: Bearer ${TOKEN}"

Error responses

All endpoints return a JSON body { "error": "<type>", "description": "<detail>" } with an appropriate HTTP status code:

Known limitations

The following JOSE features are not yet implemented in this API.

Full RFC 7515 §A.2/A.3/A.4 known-answer tests are deferred until kid-less verification is supported (current tests do round-trips with freshly generated keys).

Algorithm support matrix

Key management algorithms (alg)

Content encryption algorithms (enc)

Signature algorithms

MAC algorithms

JWE Decryption — Unwrap without Key Exposure

This use case describes how to decrypt JWE (JSON Web Encryption) tokens using the Cosmian KMS without ever exposing the symmetric content encryption key (CEK) to the calling application.

Problem Statement

You receive JWE tokens with the structure: Kpub(Ksym) . Ksym(value)

• Ksym(value): the payload value is encrypted with a symmetric AES key Ksym (the CEK)
• Kpub(Ksym): the CEK is wrapped (encrypted) with an RSA public key Kpub
• The kid (Key ID) of the RSA key pair is known

Security constraint: the calling application must never have access to Ksym.

Solution: One-Shot JWE Decrypt (No Key Persistence)

If the full JWE is available at each decryption call (including the encrypted_key field), the REST crypto endpoint performs all operations server-side in a single request. Ksym is used ephemerally in memory and immediately zeroized.

No additional development required.

Flow

sequenceDiagram
    participant App as Application
    participant KMS as KMS Server
    participant HSM as HSM (optional)

    App->>KMS: POST /v1/crypto/decrypt<br/>{protected, encrypted_key=Kpub(Ksym),<br/>iv, ciphertext=Ksym(value), tag}
    alt Kpriv in HSM
        KMS->>HSM: C_Decrypt(handle_kpriv, Kpub(Ksym))
        HSM-->>KMS: Ksym (stays in server RAM only)
    else Kpriv in database
        KMS->>KMS: RSA-OAEP decrypt(Kpriv, Kpub(Ksym)) → Ksym
    end
    KMS->>KMS: AES-GCM decrypt(Ksym, iv, ciphertext, tag) → value
    KMS->>KMS: Zeroize(Ksym)
    KMS-->>App: {"kid":"<kid>", "data":"<base64url(value)>"}

Request

curl -s -X POST https://kms.example.com/v1/crypto/decrypt \
  -H 'Content-Type: application/json' \
  -d '{
    "protected": "<base64url JWE header: {\"alg\":\"RSA-OAEP-256\",\"enc\":\"A256GCM\",\"kid\":\"<kid>\"}>",
    "encrypted_key": "<base64url of Kpub(Ksym)>",
    "iv": "<base64url of 12-byte IV>",
    "ciphertext": "<base64url of Ksym(value)>",
    "tag": "<base64url of 16-byte GCM tag>"
  }'

Response

{ "kid": "<kid>", "data": "<base64url of decrypted value>" }

The application receives value — never Ksym.

Server Configuration (TOML)

Minimal configuration with HSM holding the RSA private key:

[[hsm_instances]]
hsm_model    = "softhsm2"     # or: utimaco, proteccio, crypt2pay, smartcardhsm
hsm_admin    = ["admin"]
hsm_slot     = [0]
hsm_password = ["changeme"]

[http]
port = 9998
hostname = "0.0.0.0"

[db]
database_type = "sqlite"
sqlite_path   = "data/kms-objects"

If Kpriv is stored in the HSM with UID hsm::softhsm2::0::my_rsa_key, set the kid in the JWE protected header to this UID. The KMS automatically routes the RSA-OAEP decrypt to the HSM via the crypto oracle.

Re-encryption

After decryption, re-encrypt value with a new key in the same call flow:

curl -s -X POST https://kms.example.com/v1/crypto/encrypt \
  -H 'Content-Type: application/json' \
  -d '{
    "kid": "<kid_new_key>",
    "alg": "RSA-OAEP-256",
    "enc": "A256GCM",
    "data": "<base64url of value>"
  }'

Advanced: Persisting Ksym in the KMS (Key Unwrap Endpoint)

If the application receives subsequent ciphertexts Ksym(value) without the Kpub(Ksym) wrapper (i.e., the same CEK is reused across multiple messages), then Ksym must be persisted for later reuse. The POST /v1/crypto/keys/unwrap endpoint unwraps the CEK using RSA-OAEP and imports it as a managed symmetric key — without ever exposing the raw key material to the calling application.

Flow

sequenceDiagram
    participant App as Application
    participant KMS as KMS Server
    participant HSM as HSM (optional)

    Note over App,KMS: Step 1 — Unwrap and persist Ksym (once)
    App->>KMS: POST /v1/crypto/keys/unwrap<br/>{protected: {alg:"RSA-OAEP-256",<br/>enc:"A256GCM", kid:"<kpriv_uid>"},<br/>encrypted_key: Kpub(Ksym)}
    alt Kpriv in HSM
        KMS->>HSM: C_Decrypt(handle_kpriv, Kpub(Ksym))
        HSM-->>KMS: Ksym
    else Kpriv in database
        KMS->>KMS: RSA-OAEP decrypt(Kpriv, Kpub(Ksym)) → Ksym
    end
    KMS->>KMS: Import Ksym as Active symmetric key
    KMS-->>App: {"kid":"<ksym_uid>", "kty":"oct",<br/>"alg":"A256GCM", "key_ops":["encrypt","decrypt"]}

    Note over App,KMS: Step 2 — Decrypt with persisted Ksym (subsequent calls)
    App->>KMS: POST /v1/crypto/decrypt<br/>{protected: {alg:"dir", enc:"A256GCM",<br/>kid:"<ksym_uid>"},<br/>iv, ciphertext, tag}
    KMS->>KMS: AES-GCM decrypt(Ksym, iv, ciphertext, tag) → value
    KMS-->>App: {"kid":"<ksym_uid>", "data":"<base64url(value)>"}

Step 1: Unwrap the CEK

curl -s -X POST https://kms.example.com/v1/crypto/keys/unwrap \
  -H 'Content-Type: application/json' \
  -d '{
    "protected": "<base64url of {\"alg\":\"RSA-OAEP-256\",\"enc\":\"A256GCM\",\"kid\":\"<kpriv_uid>\"}>",
    "encrypted_key": "<base64url of Kpub(Ksym)>"
  }'

Response

{
  "kid": "<ksym_uid>",
  "kty": "oct",
  "alg": "A256GCM",
  "key_ops": ["encrypt", "decrypt"]
}

The symmetric key is now stored in the KMS. The application receives only the kid identifier — never the raw key bytes.

Step 2: Decrypt with the Persisted Key

curl -s -X POST https://kms.example.com/v1/crypto/decrypt \
  -H 'Content-Type: application/json' \
  -d '{
    "protected": "<base64url of {\"alg\":\"dir\",\"enc\":\"A256GCM\",\"kid\":\"<ksym_uid>\"}>",
    "iv": "<base64url of 12-byte IV>",
    "ciphertext": "<base64url of Ksym(value)>",
    "tag": "<base64url of 16-byte GCM tag>"
  }'

Response

{ "kid": "<ksym_uid>", "data": "<base64url of decrypted value>" }

Supported Algorithms

Error Conditions

Advanced: Persisting Ksym in the HSM (Requires Development)

If the application requires that Ksym never leaves the HSM boundary (even transiently in KMS server memory), the PKCS#11 C_UnwrapKey operation can be used to import the key directly into the HSM hardware.

Target Flow (After Development)

sequenceDiagram
    participant App as Application
    participant KMS as KMS Server
    participant HSM as HSM

    Note over App,HSM: Step 1 — Unwrap and persist Ksym (once)
    App->>KMS: KMIP Import {wrapped_key=Kpub(Ksym),<br/>wrapping_key="hsm::softhsm2::0::kpriv",<br/>store_in_hsm=true}
    KMS->>HSM: C_UnwrapKey(CKM_RSA_PKCS_OAEP, handle_kpriv, Kpub(Ksym))
    HSM->>HSM: Decrypt + store AES key<br/>CKA_SENSITIVE=TRUE, CKA_EXTRACTABLE=FALSE
    HSM-->>KMS: handle_ksym (opaque)
    KMS-->>App: {"UniqueIdentifier": "hsm::softhsm2::0::ksym_123"}

    Note over App,HSM: Step 2 — Decrypt with persisted Ksym (subsequent calls)
    App->>KMS: POST /v1/crypto/decrypt<br/>{protected: {alg:"dir", enc:"A256GCM",<br/>kid:"hsm::softhsm2::0::ksym_123"},<br/>iv, ciphertext, tag}
    KMS->>HSM: C_Decrypt(handle_ksym, iv||ciphertext||tag)
    HSM-->>KMS: value
    KMS-->>App: {"kid":"hsm::softhsm2::0::ksym_123", "data":"<base64url(value)>"}

What Needs to be Developed

Summary

JWKS endpoint

The KMS exposes a standard RFC 7517 JWKS endpoint at:

GET /.well-known/jwks.json

By default, every public key pair created through the REST API is automatically tagged jwks and immediately advertised in the JWKS document. No extra step is needed for the common case.

To exclude a specific public key from the JWKS remove its jwks tag via the tag management endpoint.

How it works

sequenceDiagram
    participant Client
    participant KMS

    Client->>KMS: POST /v1/crypto/keys  {kty, alg}
    KMS-->>Client: {kid, kid_public}

    Note over Client,KMS: kid_public is auto-tagged "jwks" — no extra step

    Client->>KMS: GET /.well-known/jwks.json
    KMS-->>Client: {keys: [{kid, kty, alg, use, n, e, ...}]}

Quickstart

# EC P-256 key for JWS (ES256)
curl -s -X POST "https://kms.example.com/v1/crypto/keys" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"kty":"EC","alg":"ES256"}'

The response contains the KMS identifier for both the private key (kid) and the public key (kid_public):

{
  "kid": "<private-key-uuid>",
  "kid_public": "<public-key-uuid>",
  "kty": "EC",
  "alg": "ES256",
  "crv": "P-256",
  "key_ops": ["sign", "verify"]
}

Verify the key is advertised

curl -s "https://kms.example.com/.well-known/jwks.json" | jq .

Expected output (abbreviated):

{
  "keys": [
    {
      "kty": "EC",
      "use": "sig",
      "alg": "ES256",
      "kid": "<public-key-uuid>",
      "crv": "P-256",
      "x": "...",
      "y": "..."
    }
  ]
}

Opt a key out of JWKS

Remove the jwks tag from the public key to stop advertising it. The key material is not deleted.

curl -s -X DELETE "https://kms.example.com/v1/crypto/keys/${KID_PUBLIC}/tags" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["jwks"]}'

The response confirms the updated tag set (the jwks tag is absent):

{ "kid": "<public-key-uuid>", "tags": [] }

If you later want to re-advertise a key that was previously opted out, add thejwks tag back via https://kms.example.com/v1/crypto/keys/${KID_PUBLIC}/tags

Key rotation

During rotation, both the retiring key and the new key are present in the JWKS document for a brief overlap period, allowing relying parties to verify tokens signed by either key.

# 1. Create the new key pair — automatically tagged "jwks".
NEW_KID_PUBLIC=$(curl -s -X POST "https://kms.example.com/v1/crypto/keys" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"kty":"EC","alg":"ES256"}' | jq -r .kid_public)

# 2. (overlap window) Both old and new keys appear in JWKS.

# 3. Opt the old key out of JWKS once all outstanding tokens have expired.
curl -s -X DELETE "https://kms.example.com/v1/crypto/keys/${OLD_KID_PUBLIC}/tags" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["jwks"]}'

Keys created outside the REST API

Keys created directly through the KMIP protocol (e.g. via ckms or a KMIP client library) are not auto-tagged. To include such a key in the JWKS document, explicitly add the jwks tag:

curl -s -X POST "https://kms.example.com/v1/crypto/keys/${KID_PUBLIC}/tags" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["jwks"]}'

Disable auto-tagging globally

By default the KMS tags every REST-created key pair for JWKS inclusion. If you prefer a fully manual opt-in model, disable auto-tagging in the server configuration:

When auto-tagging is disabled, newly created key pairs do not receive the jwks tag. To publish a key you must tag it explicitly:

curl -s -X POST "https://kms.example.com/v1/crypto/keys/${KID_PUBLIC}/tags" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["jwks"]}'

Existing keys are not affected when you change this setting.

See also

• JOSE API — full endpoint reference
• JWE Decryption — using the KMS as a JWE decryption oracle

Eviden KMS on AWS ECS

Deploy Eviden KMS on AWS ECS (Fargate) using either a production-ready setup with an Application Load Balancer (ALB) or a fast, fully managed Express Mode deployment.

Overview

This repository documents two supported ways to run Eviden KMS on AWS ECS.

Prerequisites

• AWS account with access to:
  • ECS
  • EC2 (Security Groups)
  • Elastic Load Balancing
• A VPC with at least two subnets
• Docker image: ghcr.io/cosmian/kms:latest
• KMS CLI installed https://docs.cosmian.com/kms_clients/installation/

Standard Deployment (Fargate + ALB)

1. Architecture

Traffic flows from the client to the ALB on the public HTTP port, which then routes requests to the private Fargate container on the application port.

flowchart LR
    client["Client Station<br/>(KMS CLI)"]
    subgraph aws["AWS Cloud"]
        alb["ALB<br/>(Public Subnet)<br/>Listener Port 80"]
        subgraph ecs["ECS Fargate (Private/Public)"]
            container["Container<br/>Port 9998"]
        end
        sg_alb["Security Group<br/>(SG-ALB)"]
        sg_ecs["Security Group<br/>(SG-ECS)"]
    end
    client -- "HTTP :80" --> alb
    alb --> container
    sg_alb -. controls .-> alb
    sg_ecs -. controls .-> container

2. Deployment Steps

Networking

• ALB runs in public subnets
• ECS tasks can run in public or private subnets
• NAT Gateway is required if tasks run in private subnets

Security Groups

ALB Security Group

• Inbound: 80/TCP (and 443/TCP if HTTPS is enabled)
• Outbound: all traffic

ECS Task Security Group

• Inbound: 9998/TCP
• Source: ALB security group only
• Outbound: as required (database, external services)

Application Load Balancer

• Type: Internet-facing ALB
• Listener: HTTP on port 80

Target Group

• Target type: IP
• Protocol and port: HTTP / 9998

Health Check

• Path: /ui
• Success codes: 200
• Interval: 30 seconds
• Timeout: 10 seconds

ECS Task Definition

• Image: ghcr.io/cosmian/kms:latest
• Container port: 9998
• Environment variables:
  • KMS configuration
  • Database connection (if persistence is enabled)

ECS Service

• Attach the target group to container port 9998
• Health check grace period: minimum 60–120 seconds

3. Client Setup (KMS CLI)

install KMS CLI

Run: ckms configure

KMS URL example:
http(s)://<ALB-DNS-NAME>

4. Validation & Testing

Connectivity Test Verify that the ALB is correctly routing traffic to a healthy container.

curl http(s)://<YOUR-ALB-DNS-NAME>/ui
# Expected response: 200 OK with a JSON payload containing the version.

Create a symmetric key:

ckms sym keys create --tag test --algorithm aes --number-of-bits 256
# Expected response:
The symmetric key was successfully generated.
      Unique identifier: xxxxxxx_xxxxxxx

  Tags:
    - test

5. Troubleshooting

503 Service Unavailable usually means:

• No running ECS tasks
• No healthy targets in the target group
• Health checks failing

Actions:

• Check ECS Service events
• Verify target group target health
• Increase health check grace period

Unhealthy targets:

• Ensure port 9998 is exposed
• Ensure ECS SG allows traffic from ALB SG
• Confirm /ui endpoint is reachable

6. Production Recommendations

• Enable HTTPS using ACM certificates
• Redirect HTTP to HTTPS
• Use an external database (e.g. RDS PostgreSQL) for persistence
• Configure Route53 DNS pointing to the ALB

Express Mode Deployment

Express Mode Architecture

flowchart LR
    client["Client (CLI)"]
    alb["Express ALB"]
    task["Fargate Task (KMS:9998)"]
    container["Container"]
    client -->|HTTPS| alb
    alb -->|HTTP| task
    task --> container

Express Mode Deployment Steps

AWS Console → ECS → Express Mode

• Image: ghcr.io/cosmian/kms:latest
• Service name: kms-express
• Container port: 9998
• Desired tasks: 1
• healthcheck path : /ui

Wait until service status is Active.

Express Mode Client Setup

install KMS CLI

Run:

ckms configure

KMS URL example:
https://ex-xxxxxxxx.ecs.<region>.on.aws

Express Mode Validation

Connectivity test:

curl https://ex-xxxxxxxx.ecs.<region>.on.aws/ui
# Expected response: 200 OK with a JSON payload containing the version.

Create a symmetric key:

ckms sym keys create --tag test-express --algorithm aes --number-of-bits 256
# Expected response:
The symmetric key was successfully generated.
      Unique identifier: xxxxxxx_xxxxxxx

  Tags:
    - test-express

Production Notes

• Express Mode is suitable for development, demos, and PoCs
• HTTPS is included by default
• Storage is ephemeral
• Use an external database for persistence
• Deleting the service removes all associated resources

License

Refer to Eviden documentation for licensing and support details.

Integration to AWS External Key Service (XKS)

Background

AWS XKS (External Key Store) is a feature of AWS Key Management Service (AWS KMS) that allows you to use cryptographic keys stored in an external key management system with AWS KMS. It enables you to maintain control over your keys while leveraging AWS services that integrate with AWS KMS.

Source: AWS KMS XKS Proxy API Specification - Background

Architecture

The Eviden KMS integrates to AWS XKS and proposes a novel architecture (dubbed xksv2) that solves the traditional XKS performance issues without compromising on security.

The Eviden XKSv2 architecture is composed of the following components:

Eviden Confidential KMS

This is the Confidential Key Management System, deployed as IaaS, in the customer AWS tenant. It is responsible for managing the Key Encryption Keys (KEKs) wrapping the XKS keys in AWS KMS and for answering encryption and decryption requests from the AWS KMS.

To protect the KEKs, the Eviden KMS runs inside an Eviden VM on top of confidential computing machines. Eviden VM provides strong security and verifiability guarantees.

The Eviden KMS is deployed in AWS infrastructure, solving the XKS scaling problem, as it benefits from a stable high bandwidth network and can easily scale to reliably support large amount of transactions from the AWS KMS.

The Confidential KMS is available as a ready-to-deploy product from the AWS Marketplace.

HSM

The HSM is responsible for storing the Master keys and securing the Eviden KMS keys. It is deployed in the customer premises or offered as a managed service by Atos. See the HSM integration documentation for more details.

Deployment

1. Deploy a Eviden KMS in your AWS tenant. You can find the product on the AWS Marketplace and follow the deployment instructions in the product documentation.

2. Configure the KMS for use with AWS XKS by filling up the aws_xks_config section of the configuration file with the following values:

   [aws_xks_config]
   # set this to true
   aws_xks_enable = true
   # this is the region you Eviden KMS is deployed in
   aws_xks_region = "us-east-1"
   # keep this to this value
   aws_xks_service = "xks-kms"
   # used for sigv4. The values set here must match the values configured
   # when setting up the KMS as an external keystore for AWS KMS (see next step)
   aws_xks_sigv4_access_key_id = "AKIAIOSFODNN7EXAMPLE"
   aws_xks_sigv4_secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
   

3. Configure the KMS to act as an External Key Store for AWS KMS. Follow the instructions in the AWS documentation to create an External Key Store.

4. Create an external key in AWS KMS and specify the key store created in the previous step as the key store for the key.

   

5. Enforce the correct permissions for the key on the Eviden KMS. Make sure the user used by AWS has the permissions for Encrypt, Decrypt and GetAttributes. For instance, when using DynamoDB, the user should be called something like dynamodb.amazonaws.com, for Salesforce, it is the user configured as part of the setup. In doubt, or for testing, grant theses permissions to all users (*).

Migrating an AWS External Key Store to a New Eviden KMS Instance

This guide describes how to migrate an AWS External Key Store (XKS) from one Eviden KMS instance (Server A, the source) to another (Server B, the target). This is typically required when moving to a new server, a new region, or upgrading infrastructure.

The migration must be performed with minimal downtime. During the transition window, AWS KMS marks the key store as DISCONNECTED, meaning any AWS service that attempts to use an XKS key will receive a KMSInvalidStateException until the connection is restored on Server B.

Prerequisites

• Server B must be deployed and configured with AWS XKS enabled (see the XKS deployment guide).
• You must know the AWS principal ARN that was granted permissions on each key (e.g. dynamodb.amazonaws.com, arn:aws:iam::123456789012:user/Alice).
• The SigV4 credentials configured on Server B must match (or be updated in) the AWS XKS key store settings.

Step 1 — Export all XKS keys from Server A

On Server A, export every key used by the XKS integration in json-ttlv format (the default). This format preserves all KMIP metadata and can be re-imported identically on Server B.

For each key (replace <KEY_ID> with the actual unique identifier or tag):

# Export a single key to a local file
ckms -c /path/to/server_a.toml \
  sym keys export \
  --key-id <KEY_ID> \
  keys/<KEY_ID>.json

Security note: The exported file contains the raw key material in KMIP JSON TTLV format. Store these files securely (encrypted storage, restricted filesystem permissions) and delete them once the import on Server B is complete.

Step 2 — Disconnect the XKS key store in AWS KMS

Before switching the endpoint, disconnect the external key store in the AWS Management Console or via the AWS CLI. This prevents AWS from sending requests to Server A while the endpoint is being updated.

Using the AWS CLI:

aws kms disconnect-custom-key-store \
  --custom-key-store-id <CUSTOM_KEY_STORE_ID>

Confirm that the key store status is DISCONNECTED:

aws kms describe-custom-key-stores \
  --custom-key-store-id <CUSTOM_KEY_STORE_ID> \
  --query 'CustomKeyStores[0].ConnectionState'

Expected output:

"DISCONNECTED"

Alternatively, from the AWS Management Console, open the key store and click Key store actions → Disconnect:

Type disconnect in the confirmation dialog and click Disconnect key store:

A success banner confirms the key store is now disconnected:

Step 3 — Configure Server B

Ensure Server B's configuration file contains the correct AWS XKS parameters. The SigV4 credentials must match the values registered in the AWS key store configuration. If you are rotating the credentials, update both the KMS config and the AWS key store settings in the same operation (step 4).

[aws_xks_config]
aws_xks_enable = true
aws_xks_region = "eu-west-1"           # region where your new KMS is deployed
aws_xks_service = "xks-kms"
aws_xks_sigv4_access_key_id = "YOUR_AWS_KEYID"
aws_xks_sigv4_secret_access_key = "YOUR_AWS_SECRETKEY"
aws_xks_kek_user = "admin"

Start (or restart) Server B after updating the configuration.

Step 4 — Update the XKS proxy URI in AWS KMS

Update the external key store to point to Server B's public endpoint. This can be done via the AWS Management Console (KMS → Custom key stores → Edit) or with the AWS CLI:

aws kms update-custom-key-store \
  --custom-key-store-id <CUSTOM_KEY_STORE_ID> \
  --xks-proxy-uri-endpoint "https://<SERVER_B_PUBLIC_HOSTNAME>" \
  --xks-proxy-authentication-credential \
    "AccessKeyId=YOUR_AWS_KEYID,RawSecretAccessKey=YOUR_AWS_SECRETKEY"

If you are keeping the same SigV4 credentials, the --xks-proxy-authentication-credential argument can be omitted.

Alternatively, from the AWS Management Console, click Key store actions → Edit:

Update the Proxy URI endpoint field with Server B's hostname, then click Update external key store:

Check the acknowledgement checkbox and confirm:

A success banner confirms the endpoint has been updated:

Step 5 — Import keys on Server B

On Server B, import each key exported in step 1. The --key-id parameter must preserve the exact same unique identifier that was used on Server A, because AWS KMS references keys by their ID in the XKS metadata endpoint path (/kms/xks/v1/keys/{key_id}/metadata).

ckms -c /path/to/server_b.toml \
  sym keys import \
  --key-id <KEY_ID> \
  keys/<KEY_ID>.json

Repeat for every XKS key.

Step 6 — Re-grant access rights on Server B

The Eviden KMS access control is per-instance: permissions granted on Server A are not transferred automatically. For each imported key, re-grant the operations required by AWS KMS (get_attributes, encrypt, decrypt).

# Grant the required permissions to the AWS principal ARN
ckms -c /path/to/server_b.toml \
  access-rights grant \
  --id <KEY_ID> \
  <AWS_PRINCIPAL_ARN> \
  get_attributes encrypt decrypt

Step 7 — Reconnect the XKS key store

Once Server B is ready and all keys are imported with the correct permissions, reconnect the AWS external key store:

aws kms connect-custom-key-store \
  --custom-key-store-id <CUSTOM_KEY_STORE_ID>

Poll until the status returns CONNECTED:

aws kms describe-custom-key-stores \
  --custom-key-store-id <CUSTOM_KEY_STORE_ID> \
  --query 'CustomKeyStores[0].ConnectionState'

Expected output:

"CONNECTED"

If the connection fails, check Server B's logs for SigV4 authentication errors or TLS issues. Verify the aws_xks_sigv4_access_key_id and aws_xks_sigv4_secret_access_key values match exactly what was provided to update-custom-key-store.

Step 8 — Verify the migration

Test an encrypt/decrypt round-trip through AWS KMS using one of the migrated keys to confirm end-to-end connectivity:

# Encrypt a small test payload
aws kms encrypt \
  --key-id <AWS_KMS_KEY_ARN> \
  --plaintext "SGVsbG8gV29ybGQ=" \
  --output text \
  --query CiphertextBlob \
  > /tmp/ciphertext.b64

# Decrypt it back
aws kms decrypt \
  --key-id <AWS_KMS_KEY_ARN> \
  --ciphertext-blob fileb://<(base64 -d /tmp/ciphertext.b64) \
  --output text \
  --query Plaintext | base64 -d

Expected output: Hello World

Post-migration cleanup

Once the migration is validated:

1. Delete the exported key files from your local filesystem:

   rm keys/*.json
   

2. Shut down Server A (or reconfigure it to no longer serve the XKS endpoints).

3. If applicable, revoke access rights on Server A to prevent any residual use:

   ckms -c /path/to/server_a.toml \
     access-rights revoke \
     --id <KEY_ID> \
     <AWS_PRINCIPAL_ARN> \
     get_attributes encrypt decrypt
   

AWS KMS - Bring Your Own Key (BYOK)

Eviden KMS provides an aws byok command in its CLI (also available in the ui) to facilitate the import of an AWS wrapping key (KEK) in Eviden KMS, and the export of the wrapped keys for direct import in AWS KMS. To use the AWS KMS terminology, the key that will be created in the Eviden KMS will be called the external key material as stated in the AWS KMS docs.

The key material refers to the actual cryptographic key bytes that form the basis of a KMS key. While AWS KMS keys include additional metadata, policies, and access controls, the BYOK process allows Eviden KMS users to maintain full control over key generation while leveraging AWS KMS's infrastructure for other usages.

Table of Contents

Overview

Since AWS KMS is a managed service where private key material never leaves AWS HSMs, the key import process requires:

1. Creating a KMS key with EXTERNAL origin (no key material)
2. Download the wrapping public key and import token from AWS
3. Wrap your key material using Eviden KMS
4. Import the wrapped key material into AWS KMS

Supported wrapping algorithms:

Wrapping Key Specs:

• RSA_2048 (Note: cannot be used to wrap ECC_NIST_P521 keys with RSAES_OAEP_SHA*_)
• RSA_3072
• RSA_4096

⚠️ WARNING: Invalid combinations of wrapping algorithms, key material types may lead to errors. Ensure that your selected key material type is supported by the chosen wrapping algorithm and that the wrapping key spec is compatible with both.

Prerequisites

• An active AWS account
• Either: AWS CLI installed and configured on your machine (recommended) or an access to AWS Management Console and open the AWS Key Management Service (AWS KMS) console at https://console.aws.amazon.com/kms.
• A running Eviden KMS instance.
• Either: Eviden KMS CLI installed and configured on your machine or an access to the Eviden KMS UI of your deployed KMS instance.
• Any tool to convert base64 values to their binary counterparts (e.g. openssl, python, etc).

Creating an AES key and importing it using the AWS CLI and the Eviden CLI

1. Create a KMS key with EXTERNAL origin

To use the AWS KMS API to create a symmetric encryption KMS key with no key material, send a CreateKey request with the Origin parameter set to EXTERNAL :

    aws kms create-key --origin EXTERNAL

If successful, the output should look like :

{
    "KeyMetadata": {
        "AWSAccountId": "447182645454",
        "KeyId": "350e35ef-ac51-4dbb-82a4-9bc50b0ea42b",
        "Arn": "arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b",
        "CreationDate": "2026-02-18T15:05:59.358000+01:00",
        "Enabled": false,
        "Description": "",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "KeyState": "PendingImport",
        "Origin": "EXTERNAL",
        "KeyManager": "CUSTOMER",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ],
        "MultiRegion": false
    }
}

Copy the key ARN, you will need it in the next step. In this example, the key ARN is arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b.

Note: If no key spec is specified, a symmetric key is created by default. To create a different key, pass the key-spec argument like below for an ECC_NIST_P384 key :

    aws kms create-key \
        --origin EXTERNAL \
        --key-spec ECC_NIST_P384 \
        --description "External NIST-P384 key for signing"

2. Create a symmetric key in Eviden KMS

ckms sym keys create symmetric_key_test1

Response:

The symmetric key was successfully generated.
        Unique identifier: symmetric_key_test1

3. Download wrapping public key and import token from AWS

After you create a AWS KMS key with no key material, download a wrapping public key and an import token for that KMS key by using the AWS KMS console or the GetParametersForImport API. The wrapping public key and import token are an indivisible set that must be used together.

A very detailed example on how to do this is detailed on this page, please refer to it for more info.

The command you should use is the following :

aws kms get-parameters-for-import \
    --key-id arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b \
    --wrapping-algorithm RSAES_OAEP_SHA_256 \
    --wrapping-key-spec RSA_4096

Response:

{
    "KeyId": "arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b",
    "ImportToken": "<YourBase64EncodedToken>",
    "PublicKey": "<YourBase64EncodedPublicKey>",
    "ParametersValidTo": "2026-02-19T15:07:13.227000+01:00"
}

As mentioned in the AWS documentation for importing key material, you will have to convert the base64 values to their binary counterparts before importing them. This can be done with the method of your choice, the most straightforward method (If you have openssl on your cli), would be to copy the token and paste it with the following command to get the file token.bin :

echo -n "<YourBase64EncodedToken>" | openssl enc -d -base64 -A -out token.bin

In a similar manner, you can use the command if you want to keep your public key as a binary blob :

echo -n "<YourBase64EncodedPublicKey>" | openssl enc -d -base64 -A -out kek.bin

4. Import the AWS KEK into Eviden KMS

ckms aws byok import \
    --kek-base64 "<YourBase64EncodedPublicKey>" \
    --wrapping-algorithm RSAES_OAEP_SHA_256 \
    --key-arn "<YourKeyArn>" \
    --key-id aws_kek_1

Feel free to change the key id to whatever you want, we will call the kek aws_kek_1 in this example.

Alternative : importing the kek as file

ckms aws byok import \
    --kek-file kek.bin \
    --wrapping-algorithm RSAES_OAEP_SHA_256 \
    --key-arn arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b \
    --key-id aws_kek_1

Response:

The PublicKey in file /tmp/ca9f45ad-8596-45a6-bc57-5591e662cb61 was successfully imported with id: aws_kek_1.
        Unique identifier: aws_kek_1
        Tags:
                - aws
                - wrapping_algorithm:RsaesOaepSha256
                - key_arn:arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b

5. Export the wrapped key material from Eviden KMS

# Provide token file simply to display the correct AWS CLI command for import
# If the output file is not specified, the CLI returns base64 encoded encrypted key material
ckms aws byok export \
    symmetric_key_test1 \
    kek_test1 \
    token.bin \
    EncryptedKeyMaterial.bin

Response:

The encrypted key material was successfully written to 512 for key symmetric_key_test1.

To import into AWS KMS using the API, run:
aws kms import-key-material \
--key-id arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b \
--encrypted-key-material fileb://EncryptedKeyMaterial.bin \
--import-token fileb://token.bin \
--expiration-model KEY_MATERIAL_DOES_NOT_EXPIRE

6. Import the wrapped key material into AWS KMS

If you have filled all the fields on the previous step, you can directly use the command that the Eviden CLI automatically generated for you:

aws kms import-key-material \
    --key-id arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b \
    --encrypted-key-material fileb://EncryptedKeyMaterial.bin \
    --import-token fileb://token.bin \
    --expiration-model KEY_MATERIAL_DOES_NOT_EXPIRE

Response:

{
    "KeyId": "arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b",
    "KeyMaterialId": "60a5374a2457941eaf5c26b75fea0236bcdc5ddbe70c4aa15046e6fdda49e334"
}

Receiving this response means that the key material has been successfully imported into AWS KMS.

Creating an RSA key and importing it using the AWS CLI and the Eviden CLI

For this example, we will create an 2048 bits RSA key material, wrapped using a 4096 kek with RSAES_OAEP_SHA_256.

First, Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at https://console.aws.amazon.com/kms and complete the necessary steps to create a KMS key with external key material. Be mindful to provide the correct key spec - otherwise the console will expect a symmetric key by default. For this example, we will use RSA_2048.

The next step is to download the wrapping public key and import token. Be mindful that an RSA_AES_KEY_WRAP_SHA wrapping algorithm is required for wrapping RSA private key material (except in China Regions). Choosing RSAES_OAEP_SHA_256 will work for this example.

Once this is done, create your key on the cosmian KMS like follow, we call it rsa_key_material :

Then, navigate to the AWS - Import Kek section and fill with the adequate data. In this example, we paste the kek in the base64 format for convenience, and call it aws_kek_2.

Finally, export the wrapped key material from Eviden KMS to import it into AWS KMS.

We named the file to export EncryptedKeyMaterial.bin. You can import the wrapped key material using the AWS CLI or the AWS Management Console.

An in depth explanation of the import process can be found in the AWS documentation to Import key material (console).

Automated BYOK Scripts

To facilitate testing and automating the BYOK flow, we provide ready-to-use Bash scripts that demonstrate the end-to-end process of creating an AWS KMS key, generating the corresponding key material using the Eviden CLI, and performing the import/export procedures.

The following scripts are available for download:

• RSA BYOK Script: Automates the import of RSA private key material. Supports RSA key sizes: 2048, 3072, and 4096. Find run_rsa_byok.sh on repository

• ECC BYOK Script: Automates the import of Elliptic Curve private key material. Supports NIST curves: p256, p384, and p521. Find run_ecc_byok.sh on repository

• AES BYOK Script: Automates the import of 256-bit AES symmetric key material. Find run_aes_byok.sh on repository

Usage

Each script requires the cosmian CLI to be available either in your PATH, the current directory, or specified via the COSMIAN_KMS_CLI environment variable. Also, ensure the aws CLI is available in your PATH, authenticated, and configured.

Example usage:

# Make the script executable
chmod +x run_rsa_byok.sh

# Run the script with the desired key size and an optional description
./run_rsa_byok.sh 2048 "My RSA External Key"

Eviden KMS provides a azure byok command in its CLI to facilitate the import of an Azure wrapping key (KEK) in Eviden KMS, and the export of the wrapped keys in the .byok format for easy import in Azure Key Vault.

Follow this Azure documentation, for a description of Bring Your Own Key (BYOK) in Azure Key Vault,

The vault must be a premium Azure Key Vault, and the user performing the operations must have the role of Crypto Officer.

Table of Contents

Create two test keys in the Eviden KMS

These keys will later be exported wrapped by the Azure (KEK) key, and imported into Azure Key Vault.

Create an RSA Key

The key will be a 4096-bit key.

ckms rsa keys create --size_in_bits 4096 TestRSAKey

   Public key unique identifier: TestRSAKey_pk
   Private key unique identifier: TestRSAKey

Create an Elliptic Curve Key

The key will be created on the NIST P-256 curve.

ckms ec keys create --curve nist-p256 TestECKey

   Public key unique identifier: TestECKey_pk
   Private key unique identifier: TestECKey

Create an Azure Key Encryption Key (KEK)

This key will be used to wrap the KMS RSA and EC private keys on export.

Using the Azure console:

Navigate to the Key Vault (say MyPremiumKeyVault) and create a 4096-bit RSA key.

Make sure to select Generate Key Encryption Key for importing HSM-protected Keys.

Using the az CLI:

The supported operations must be restricted to import.

az keyvault key create --kty RSA-HSM --size 4096 --name KEK-BYOK --ops import --vault-name MyPremiumKeyVault

In the azoutput, the key identifier (kid) will be something like: "https://mypremiumkeyvault.vault.azure.net/keys/KEK-BYOK/664f5aa2797a4075b8e36ca4500636d8"

Please take note of the kid for next steps.

Export the Key Encryption (Public) Key

The KEK public key must be exported, then imported into the KMS.

Using the Azure console:

Edit the KEK by double-clicking on it.

Please take note of the key identifier (kid), which will be required later.

Download the public key and rename the file KEK-BYOK.public.pem.

Using the az CLI:

az keyvault key download --name KEK-BYOK --vault-name MyPremiumKeyVault --file KEK-BYOK.public.pem

Import the key encryption key in Eviden KMS

The KMS CLI provides an azure byok command to facilitate both the import of the key encryption key in Eviden KMS, and the export of the wrapped keys in the .byok format for easy import in Azure Key Vault.

ckms azure byok import KEK-BYOK.public.pem \
https://hsmbackedkeyvault.vault.azure.net/keys/BYOK_KEK/5e617a4d39c74f47b0b7d345f6a49d1b \
BYOK_KEK

The PublicKey in file KEK-BYOK.public.pem was imported with id: BYOK_KEK
          Unique identifier: BYOK_KEK

  Tags:
    - azure
    - kid:https://hsmbackedkeyvault.vault.azure.net/keys/BYOK_KEK/5e617a4d39c74f47b0b7d345f6a49d1b

Please note the presence of the azure and kid: tags on the key. These identify the key as an Azure Key Encryption Key (KEK) in the Eviden KMS.

Export the wrapped keys from the Eviden KMS

The KMS CLI azure byok export command will generate a .byok file containing the wrapped private key, which can be directly imported into Azure Key Vault.

Export the RSA key

ckms azure byok export TestRSAKey BYOK_KEK

The byok file was written to "TestRSAKey.byok" for key TestRSAKey

Export the EC key

ckms azure byok export TestECKey BYOK_KEK

The byok file was written to "TestECKey.byok" for key TestECKey

Upload the byok transfer blob in Azure Key Vault

Wrapped private RSA keys can be imported using either the console or the az LI. Elliptic curve keys can only be imported using the az CLI.

For an RSA Private Key

Using the Azure console:

Using the az CLI:

az keyvault key import --vault-name MyPremiumKeyVault --name TestRSAKey --byok-file TestRSAKey.byok \
--ops sign verify

For an EC Private Key

The key type and curve must be specified on import for elliptic curve keys.

az keyvault key import --vault-name MyPremiumKeyVault --name TestECKey --byok-file TestECKey.byok \
--kty EC --curve P-256  --ops sign verify

Eviden KMS implements the Azure External Key Manager (EKM) Proxy API, enabling it to serve as an external key management service for an Azure Managed HSM.

This integration allows organizations to maintain complete physical control over their encryption keys outside of Azure infrastructure while seamlessly integrating with Azure services that support Customer Managed Keys (CMK).

The Eviden KMS implementation follows and implements the Microsoft EKM Proxy API Specification for v0.1-preview.

High level architecture

The customer's Azure services (configured with Customer Managed Keys) communicate with Azure Managed HSM to perform encryption/decryption operations. A full list of Azure services that support CMK can be consulted on this page.

With this integration, your protected secrets remain under your complete control while maintaining compatibility with Azure's managed services.

The following diagram illustrates a possible use case where Eviden KMS acts as the EKM Proxy :

Api specification

URL format

All requests and responses for Azure EKM APIs are sent as JSON objects over HTTPS. Each request includes context information to associate Azure Managed HSM logs and audits with Eviden KMS logs.

The URI format for EKM Proxy API calls is:

https://{public-KMS-URI}/azureekm/[path-prefix]/{api-specific-paths}?api-version={client-api-version}

The parameters between brackets {} can be edited on the KMS configuration and must follow the following constraints :

Path Prefix:

• Maximum 64 characters
• Allowed characters: letters (a-z, A-Z), numbers (0-9), slashes (/), and dashes (-)

External Key ID:

• Referenced as {key-name} in the endpoints below
• Maximum 64 characters
• Allowed characters: letters (a-z, A-Z), numbers (0-9), and dashes (-)

Endpoints

Supported algorithms

⚠️ Notice: For RSA operations, always use the private key reference as {key-name} in all endpoints, including wrap operations. The KMS will automatically derive and use the associated public key for encryption (wrap) operations. Passing the public key ID might lead to errors.

Getting started

Azure Managed HSM Setup

You must have an Azure Managed HSM Pool already created and activated in your Azure subscription. Refer to the Azure Managed HSM documentation for setup instructions.

Once the configuration is done, you will need the root CA certificate that the Azure Managed HSM uses for client authentication. This certificate will be configured in Eviden KMS to validate incoming mTLS connections.

Let's save the root CA as mhsm-root-ca.pem - We will need it in the next step.

Eviden KMS setup

Follow the Eviden KMS installation guide to install the KMS server on your infrastructure. The KMS server typically uses the configuration file located at /etc/cosmian/kms.toml when installed manually with default parameters.

Alternatively, you can deploy a pre-configured Eviden Confidential VM like explained in this guide.. For confidential VMs, the KMS configuration file is located in the encrypted LUKS container at /var/lib/cosmian_vm/data/app.conf.

Environment variables can also be used for all the configurations below.

The following guide will consider running Eviden KMS on confidential VM in non-FIPS mode.

mTLS Configuration

Configure mutual TLS authentication to accept connections from Azure Managed HSM by adding of editing to following lines in your configuration file: For detailed information about TLS client certificate authentication, see the TLS Client Certificate configuration guide.

[tls]
# Your server certificate and private key (PKCS#12 format)
tls_p12_file = "/etc/cosmian/server-cert.p12"
tls_p12_password = "your-secure-password"

# The certificate downloaded in the previous section
# This validates the client certificate presented by Azure MHSM
clients_ca_cert_file = "/etc/cosmian/mhsm-root-ca.pem"

Note : If you have a server's key and certificate files, you can convert them to PKCS#12 format using openssl:

openssl pkcs12 -export \
  -in server.crt \
  -inkey server.key \
  -out server-cert.p12 \
  -name "cosmian-kms-server" \
  -passout pass:your-secure-password

Azure EKM Configuration

[azure_ekm_config]
# Enable Azure EKM endpoints
azure_ekm_enable = true

# Optional: Path prefix for multi-tenant isolation (max 64 chars: a-z, A-Z, 0-9, /, -)
azure_ekm_path_prefix = "cosmian0"

# The fields below will be reported in the /info endpoint, edit according to your needs
azure_ekm_proxy_vendor = "Eviden"
azure_ekm_proxy_name = "EKM Proxy Service v0.1-preview"
azure_ekm_ekm_vendor = "Eviden"
azure_ekm_ekm_product = "Eviden KMS"

# WARNING: Only set to true for testing! Never in production.
azure_ekm_disable_client_auth = false

Configuration Parameters:

Grant the Managed HSM identity access rights on the KMS

When Azure Managed HSM connects to the EKM proxy over mTLS, Eviden KMS authenticates it as a regular KMIP user, using the Subject CN of the client certificate as the username (see TLS Client Certificate configuration and the Authentication guide). This identity is generally of the form <hsm-name>.managedhsmclient.azure.net — check your own Managed HSM client certificate to confirm its exact Subject CN.

Because the external key is owned by whichever KMS user created it, you must explicitly grant this Managed HSM identity the rights to read and use that key, using ckms access-rights grant:

ckms access-rights grant <hsm-name>.managedhsmclient.azure.net -i <kms-key-uid> get get_attributes encrypt decrypt

Without this step, Azure's key registration call (see below) fails with a KeyNotFound-type error, because the KMS rejects the Managed HSM identity's request for an object it does not own and has not been granted access to.

Connect Azure Managed HSM to the EKM proxy

The following az keyvault ekm-connection commands configure the Managed HSM side of the connection to your Eviden KMS.

First, create the EKM connection on the Managed HSM, pointing it at your Eviden KMS:

az keyvault ekm-connection create \
  --hsm-name <hsm-name> \
  --host <kms-fqdn>:443 \
  --path-prefix /azureekm/<azure_ekm_path_prefix> \
  --server-ca-certificate <path-to-kms-tls-ca-or-server-cert.pem>

⚠️ Port 443 is required. The --host argument's own help text states: "EKM proxy host (FQDN or FQDN:port). If port is omitted, 443 is assumed." In practice, the Managed HSM EKM proxy calls have been observed to require port 443 — make sure your Eviden KMS is reachable on port 443 (in addition to any other port you use for KMIP/administrative access), even if [http] port in your KMS configuration is set to a different value.

--path-prefix must match azure_ekm_path_prefix. If you configured azure_ekm_path_prefix = "cosmian0" on the KMS side, the Azure-side --path-prefix must be the corresponding path (e.g. /azureekm/cosmian0). A mismatch here causes requests to fail to route, without necessarily producing an obvious error on the Azure side.

Verify the connection:

az keyvault ekm-connection check --hsm-name <hsm-name>

A successful check returns the /info payload reported by the KMS (apiVersion, proxyVendor, proxyName, ekmVendor, ekmProduct).

Register the external key and grant Azure RBAC

Register the KMS key as an external Managed HSM key, referencing its KMS UID:

az keyvault key create \
  --hsm-name <hsm-name> \
  --name <azure-key-name> \
  --external-key-id <kms-key-uid>

The consuming Azure service (for example, a Storage account's managed identity) then needs the Managed HSM Crypto Service Encryption User role (built-in Managed HSM local RBAC role, which grants the keys/wrap, keys/unwrap, and keys/read data actions) on that key:

az keyvault role assignment create \
  --hsm-name <hsm-name> \
  --role "Managed HSM Crypto Service Encryption User" \
  --assignee <consuming-service-principal-id> \
  --scope /keys/<azure-key-name>

Testing the integration

For testing purposes or for debugging, you can temporarily disable client authentication by commenting out the following configuration fields:

[tls]
# Comment this field to disable client auth and allow incoming requests from anyone
# clients_ca_cert_file = "/etc/cosmian/mhsm-root-ca.pem"

[azure_ekm_config]
# Set to true to bypass mTLS for local testing only — NEVER use in production
azure_ekm_disable_client_auth = true

Restart the KMS server:

sudo systemctl restart cosmian-kms

Test the /info endpoint:

curl -X POST "https://ekm.yourdomain.com/azureekm/cosmian0/info?api-version=0.1-preview" \
  -H "Content-Type: application/json" \
  -d '{
    "request_context": {
      "request_id": "test-request-123",
      "correlation_id": "test-correlation-456",
      "pool_name": "test-pool"
    }
  }'

Expected response (if you used the config above):

{
  "api_version": "0.1-preview",
  "proxy_vendor": "Eviden",
  "proxy_name": "EKM Proxy Service v=0.1-preview",
  "ekm_vendor": "Eviden",
  "ekm_product": "Eviden KMS v5.15.0"
}

Troubleshooting

Microsoft Double Key Encryption (DKE)

Microsoft Double Key Encryption (DKE) is a feature of Microsoft 365 that allows you to protect your most sensitive data by encrypting data on the client computer before sending it to Microsoft servers. One of the keys used to encrypt remains under your control and makes the data unreadable by Microsoft. This key is kept inside your instance of Eviden KMS which exposes the required API to integrate with Microsoft DKE.

See How it works for details on the cryptographic process.

Microsoft Prerequisites

The DKE feature is currently only available for the Office Windows clients. In addition, to use Microsoft Double Key Encryption (DKE) you must have a Microsoft 365 Business Premium license and must have access to the Microsoft Purview compliance portal.

How it works

Once DKE is configured, the whole process consists in assigning a specific sensitivity label to a document. The label will indicate that the document is encrypted and that the key to decrypt it is stored in your Eviden KMS.

Please check the dedicated Microsoft documentation for a complete overview of the feature.

From a cryptographic standpoint, the feature works as follows:

Before saving an encrypted document, the Office client will:

1. Generate an ephemeral 128-bit AES key and use it to encrypt the document
2. Call the Eviden KMS to get your 2048-bit RSA public key (the Office client will cache the key for 24 hours)
3. Use that key to wrap the AES key using the PKCS#11 CKM_RSA_PKCS_OAEP (NIST 800 56B Rev2) algorithm; the hashing algorithm is set to SHA-256 (see the list of supported algorithms for details)
4. Send the wrapped AES key and the encrypted document to Microsoft servers, where Azure RMS will also wrap the wrapped AES key with their own key (hence the "double key" acronym)

Retrieving an encrypted document works as follows, the Office client will:

1. Request Azure RMS to perform the first unwrapping using their key, to recover the wrapped AES key
2. Download the encrypted document and the wrapped AES key
3. Call your Eviden KMS to unwrap the AES key using your private RSA key. Please note that the private RSA key never leaves the Eviden KMS.
4. Decrypt the document using the recovered AES key and display it.

Note: The Eviden KMS implementation of the PKCS#11 CKM_RSA_PKCS_OAEP algorithm is FIPS compliant. The DKE API is therefore available on the Eviden server running in FIPS mode.

Configuring the Eviden KMS server

The Eviden KMS server needs to be started with the --ms-dke-service-url <MS_DKE_SERVICE_URL> option.

The <MS_DKE_SERVICE_URL>should contain the external URL of this server as configured in Azure App Registrations for the DKE Service

The URL should be something like https://kms.my_domain.com/ms_dke

Alternatively, you can set the KMS_MS_DKE_SERVICE_URL environment variable to the same value, or set the corresponding entry in the server TOML configuration file.

The Office client does not send any authentication information when calling the Eviden KMS. Firewalling the Eviden KMS server to only accept requests from valid Office clients is critical.

It is possible to confidentially run the Eviden KMS server in the cloud inside an Eviden VM. However, due to the lack of authentication, and thus the need to firewall the server, one should make sure to use OS-level firewalling and not rely on the cloud provider's firewalling capabilities, particularly if running on Azure.

Create an RSA key with tag dke_key

Using the KMS CLI, create a 2048-bit RSA key with the tag dke_key:

ckms rsa keys create --tag dke_key --size_in_bits 2048

The tag can be changed to any value, but it must be used in the URL of the sensitivity label in the Microsoft Purview compliance portal. See Create a sensitivity label for encryption for details.

Rotate the DKE key

If later on you need to rotate the DKE key, you can use the KMS CLI to create a new key with a new tag. You must then create a new sensitivity label where the Double Key Encryption URL ends with the new tag value. See Create a sensitivity label for encryption for details.

Users should now select the new label when creating new documents. As long as the old key is available in the Eviden KMS, users will still be able to open documents encrypted with the old key.

Configuring Microsoft DKE in Purview

Please follow the main documentation provided by Microsoft. The following paragraphs add details and tips to the process.

Activating the protection service from Azure Information Protection

The protection service must be activated in order to use DKE. If not activated, "Group and Sites" will not be available in the scopes of the sensitivity label.

Run PowerShell as Admin

Install-Module -Name AIPService

In case of troubles with the execution policy, try

powershell -ExecutionPolicy ByPass

Get the status of the AIP service

Import-Module AIPService
Get-AIPService

You may have to connect to it first

Connect-AipService

If it is disabled, enable it

Enable-AipService

More options for phased deployments here.

Microsoft Entra configuration for encrypted content

Check if there is anything to configure.

Activate sensitivity labels for MS 365 groups

Sensitivity labels must be activated for MS 365 groups which are also called unified groups. The main documentation on configuring sensitivity labels is available here.

The objective is to set the EnableMIPLabels parameter to True at the Entra ID Directory level (which is set to False by default), using Group.Unified template.

The EnableMIPLabels flag indicates whether sensitivity labels published in Microsoft Purview compliance portal can be applied to Microsoft 365 groups. For more information, see Assign Sensitivity Labels for Microsoft 365 groups.

To verify the current value of the EnableMIPLabels parameter, run the following command:

$Setting = Get-AzureADDirectorySetting | ? { $_.DisplayName -eq "Group.Unified"}
&Setting.Values

See this doc and Enable sensitivity label support in PowerShell which will probably require configuring groups first.

De-activate co-authoring in Microsoft Purview

Do NOT click the box on this page, doing so will prevent the use of DKE in Sensitivity Labels.

If you need to deactivate co-authoring, you can do so by running the following commands:

Install-Module -Name PSWSMan # if not already installed
Install-WSMan
Install-Module -Name ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement
Connect-IPPSSession -UserPrincipalName you_admin_user@your_domain.com
Set-PolicyConfig -EnableLabelCoauth:$false

Create a sensitivity label for encryption

Navigate to Purview then Solutions > Information protection > Labels

Follow these instructions to create the label. Select Use Double Key Encryption on the encryption configuration screen and make sure you do not activate co-authoring.

Activating the label (scope) for meetings does not seem to work.

Windows CNG Key Storage Provider (KSP)

Microsoft Intune integration — The Cosmian KMS CNG KSP integrates natively with Microsoft Intune SCEP and PKCS certificate profiles. When Intune provisions a device certificate, the private key is created and permanently stored in Cosmian KMS — never on the endpoint. See the Intune integration section for setup details.

Intune + CNG KSP architecture

sequenceDiagram
    participant Admin as IT Administrator
    participant Intune as Microsoft Intune<br/>(Cloud UEM)
    participant Endpoint as Windows Endpoint<br/>(Intune-managed)
    participant KSP as cosmian_cng.dll<br/>(CNG KSP)
    participant KMS as Cosmian KMS<br/>(KMIP 2.1)
    participant SCEP as SCEP / PKCS<br/>Certificate Authority

    Admin->>Intune: 1. Create SCEP certificate profile<br/>KSP = "Cosmian KMS Key Storage Provider"
    Intune->>Endpoint: 2. Push certificate profile
    Endpoint->>KSP: 3. NCryptCreatePersistedKey()
    KSP->>KMS: 4. KMIP CreateKeyPair<br/>(private key stays in KMS)
    KMS-->>KSP: 5. Public key + key UUID
    KSP-->>Endpoint: 6. Key handle (public key blob)
    Endpoint->>SCEP: 7. Submit CSR<br/>(public key only)
    SCEP-->>Endpoint: 8. Signed certificate
    Note over Endpoint,KMS: All subsequent Sign / Decrypt operations<br/>are forwarded to Cosmian KMS via the KSP
    Endpoint->>KSP: 9. NCryptSignHash() (e.g. TLS handshake)
    KSP->>KMS: 10. KMIP Sign
    KMS-->>KSP: 11. Signature
    KSP-->>Endpoint: 12. Signature bytes

What is it?

Cosmian KMS provides a Windows CNG Key Storage Provider (KSP) DLL — cosmian_cng.dll — that stores private keys inside Cosmian KMS rather than the local Windows machine store.

A Key Storage Provider is a pluggable module defined by the Windows Cryptography API: Next Generation (CNG) framework (introduced in Windows Vista / Server 2008). CNG replaces the older CAPI (CryptoAPI). Any application that calls the standard NCrypt* family of functions — including the Windows certificate enrollment engine, Schannel (TLS), and Code Signing — automatically uses whichever KSP is associated with a given key, with no application changes required. By deploying cosmian_cng.dll, all private key material is kept inside Cosmian KMS: it never exists on the device disk.

Why use it?

Who should use it?

• Enterprise IT / Security teams deploying Microsoft Intune device certificates where device private keys must be hardware-protected or centrally managed.
• PKI administrators who need a hardware-security-module (HSM)-equivalent experience without deploying a physical HSM on every endpoint.
• Compliance officers who need full audit logs of every private key usage on corporate endpoints.
• Windows developers integrating with any NCrypt-based API (Schannel, Code Signing, S/MIME, BitLocker recovery) who want keys protected by a remote KMS.

When to use it?

Use the CNG KSP when:

• You are enrolling device certificates through Microsoft Intune SCEP or PKCS profiles and you want the private key to remain inside Cosmian KMS rather than in the Windows software KSP or TPM.
• You need to remotely wipe a key (e.g. lost device): destroy the key in the KMS and all signing / decryption operations on that device fail immediately.
• Your organisation is subject to regulations (FIPS 140-3, Common Criteria, eIDAS, NIS2) that mandate private key custody inside a certified key store.
• You want a single, centralised, KMIP 2.1-compliant inventory of all device keys with metadata and access-control policies.

Do not use the CNG KSP for keys that must be available offline (e.g. full-disk encryption unlock keys), because operations require a live HTTPS connection to the KMS.

How it works

CNG plug-in mechanism

Windows CNG defines the NCRYPT_KEY_STORAGE_FUNCTION_TABLE interface: a struct of 30 function pointers that Windows calls for every key operation. A KSP DLL exports a single entry point:

SECURITY_STATUS GetKeyStorageInterface(
    LPCWSTR pszProviderName,
    NCRYPT_KEY_STORAGE_FUNCTION_TABLE **ppFunctionTable,
    DWORD dwFlags
);

cosmian_cng.dll implements this interface entirely in Rust. When Windows loads the DLL, it calls GetKeyStorageInterface to obtain the function table, and from that point on every NCrypt* call is handled by the corresponding Rust function.

Request flow

sequenceDiagram
    participant App as Windows Application<br/>(Intune SCEP, MMC, certutil)
    participant DLL as cosmian_cng.dll
    participant KMS as Cosmian KMS<br/>(HTTPS / KMIP 2.1)

    App->>DLL: NCrypt* call<br/>(OpenStorageProvider, SignHash, …)
    Note over DLL: 1. Validate handle (magic check)<br/>2. Translate NCrypt params → KMIP request<br/>3. Block on shared Tokio runtime
    DLL->>KMS: KMIP operation<br/>(CreateKeyPair, Sign, Decrypt, …)
    KMS-->>DLL: KMIP response
    Note over DLL: 4. Translate KMS response → NCrypt buffer<br/>5. Return SECURITY_STATUS
    DLL-->>App: SECURITY_STATUS + output buffer

Private keys never leave the KMS: only the public key blob (BCRYPT_RSAKEY_BLOB or BCRYPT_ECCKEY_BLOB) is serialised and returned to Windows for certificate construction.

Provider and key context objects

Both types carry a magic number (0xC05_1A_AC) that is validated on every handle dereference — a stale or forged handle returns NTE_INVALID_HANDLE instead of causing undefined behaviour.

Key lifecycle

flowchart LR
    subgraph Key Creation
        A[CreatePersistedKey] -->|allocates PendingCreation context| B[SetKeyProperty]
        B --> C[FinalizeKey]
        C -->|calls KMS CreateKeyPair,<br/>tags key with cng-ksp::name| D["Key exists in KMS<br/>(Persisted state)"]
    end

flowchart LR
    subgraph Key Lookup
        E[OpenKey] -->|look up KMS UUID<br/>by tag cng-ksp::name| F[allocate CngKeyCtx]
    end

flowchart LR
    subgraph Key Operations
        G[SignHash] -->|digested_data = pre-hashed input| H[KMS Sign]
        I[Decrypt] --> J[KMS Decrypt]
        K[ExportKey] -->|SPKI DER → BCRYPT blob| L[KMS export public key only]
        M[DeleteKey] -->|revoke + destroy both key UUIDs| N[KMS Destroy]
    end

Key naming and tagging

Each key is tagged in the KMS with two vendor tags (namespace Cosmian):

Authentication

The DLL reads ckms.toml using the same search order as the ckms CLI:

1. Path in the CKMS_CONF environment variable.
2. ckms.toml in the same directory as cosmian_cng.dll.
3. %APPDATA%\.cosmian\ckms.toml.

The configuration file supports bearer-token OAuth 2.0, mTLS (PKCS#12 client certificate), or unauthenticated (for local dev/test only).

SECURITY_STATUS error mapping

Architecture

flowchart LR
    App["Windows Application<br/>(Intune SCEP, MMC, certutil)"] -->|NCrypt API calls| DLL["cosmian_cng.dll<br/><br/>NCRYPT_KEY_STORAGE_FUNCTION_TABLE<br/>GetKeyStorageInterface()"]
    DLL -->|"CreateKeyPair / Sign / Decrypt<br/>Locate / Destroy"| KMS["Cosmian KMS<br/>(REST / KMIP 2.1)"]
    style DLL fill:#f5f5f5,stroke:#333
    style KMS fill:#e8f4e8,stroke:#2d7d2d

Private keys never touch the local machine. Only public key blobs are returned to Windows.

Supported algorithms

Installation

1. Install the Cosmian KMS CLI

The cosmian_cng.dll is bundled inside the Cosmian KMS CLI installer alongside ckms.exe. Download and run the installer for your platform:

# Download the CLI installer (adjust the version number as needed)
Invoke-WebRequest `
    -Uri "https://package.cosmian.com/kms/5.25.0/windows/x86_64/non-fips/static-openssl/cosmian-kms-cli-non-fips-static-openssl_5.25.0_x86_64.exe" `
    -OutFile "$env:TEMP\cosmian-kms-cli.exe"

# Run the installer (accepts the default installation directory)
Start-Process -FilePath "$env:TEMP\cosmian-kms-cli.exe" -ArgumentList "/S" -Wait

The installer places both files in the default installation directory:

C:\Users\<username>\AppData\Local\Cosmian KMS CLI\ckms.exe
C:\Users\<username>\AppData\Local\Cosmian KMS CLI\cosmian_cng.dll

Ensure the installation directory is on your PATH (the installer does this automatically):

$env:PATH += ";$env:LOCALAPPDATA\Cosmian KMS CLI"

2. Configure the KMS connection

Run the interactive configuration wizard to create ckms.toml:

ckms configure

The wizard prompts for the KMS server URL and authentication method (none, bearer token, PEM client certificate, or PKCS#12 client certificate). It writes the configuration to %APPDATA%\.cosmian\ckms.toml.

3. Verify the DLL

Before registering the KSP, confirm that the DLL loads correctly and can reach the KMS server:

ckms cng verify --dll "$env:LOCALAPPDATA\Cosmian KMS CLI\cosmian_cng.dll"

Expected output (with a running KMS):

=== Cosmian CNG KSP Verification ===

Loading DLL: C:\Users\<user>\AppData\Local\Cosmian KMS CLI\cosmian_cng.dll

  [OK]   OpenProvider
── RSA key pair + sign + export + lookup ──
  [OK]   RSA key pair + sign + export + lookup
  ...
─────────────────────────────────────────
All 15 verification step(s) PASSED.

If any step shows [FAIL] with NTE_FAIL (0x8009002A), the DLL cannot reach the KMS server — check ckms.toml and network connectivity before proceeding.

4. Register the KSP (requires Administrator)

# From an elevated PowerShell prompt:
ckms cng register --dll "$env:LOCALAPPDATA\Cosmian KMS CLI\cosmian_cng.dll"

This performs the following steps:

1. Copies cosmian_cng.dll to %SystemRoot%\System32 (CNG resolves provider DLLs from that directory)

2. Calls BCryptRegisterProvider to create the proper registry structure:

   HKLM\SYSTEM\CurrentControlSet\Control\Cryptography\Providers\
       Cosmian KMS Key Storage Provider\
           UM\
               Image        REG_SZ     "cosmian_cng.dll"
               00010001\
                   (Default)   REG_SZ         "CRYPT_KEY_STORAGE_INTERFACE"
                   Functions   REG_MULTI_SZ   "KEY_STORAGE"
   

3. Calls BCryptAddContextFunctionProvider to make the provider discoverable by NCryptOpenStorageProvider and certutil -csplist

5. Verify registration

ckms cng status
# Expected: Cosmian KMS CNG KSP: REGISTERED

# Also verify Windows sees the provider:
certutil -csplist | Select-String "Cosmian"
# Expected output includes: "Cosmian KMS Key Storage Provider"

Using the KSP

Create a key pair via NCrypt API

The KSP is automatically available to any Windows application that calls NCryptOpenStorageProvider with the provider name "Cosmian KMS Key Storage Provider".

NCRYPT_PROV_HANDLE hProv;
NCryptOpenStorageProvider(
    &hProv,
    L"Cosmian KMS Key Storage Provider",
    0
);

NCRYPT_KEY_HANDLE hKey;
NCryptCreatePersistedKey(hProv, &hKey, BCRYPT_RSA_ALGORITHM, L"my-key", 0, 0);
NCryptSetProperty(hKey, NCRYPT_LENGTH_PROPERTY, (PBYTE)&keyLength, sizeof(DWORD), 0);
NCryptFinalizeKey(hKey, 0);
// The private key is now stored in Cosmian KMS
// FinalizeKey returns only after the KMS confirms creation

Intune SCEP device certificate

Microsoft Intune uses the Windows CNG CSR pipeline. Once the KSP is registered, configure the Intune SCEP profile to use the Cosmian KMS Key Storage Provider as the key storage location. The private key backing the device certificate will be created and permanently stored in Cosmian KMS.

List all CNG KSP keys in the KMS

ckms cng list-keys

Unregister the KSP

# Elevated PowerShell:
ckms cng unregister

Logging

Log output is written to cosmian_cng.log in the same directory as the DLL by default — no additional configuration is required. If the DLL directory is not writable, the log file is created in %APPDATA%\.cosmian\cosmian_cng.log instead. Logging to a file always happens without any configuration.

Set the COSMIAN_CNG_KSP_LOGGING_LEVEL environment variable to control verbosity: trace, debug, info (default), warn, or error.

Key naming and tag convention

Each key created through the KSP is tagged in the KMS with:

• cng-ksp — identifies all KSP-managed keys.
• cng-ksp::<key_name> — identifies the key by its CNG name (the string passed to NCryptCreatePersistedKey / NCryptOpenKey).

Use ckms cng list-keys or the standard ckms locate command to find keys:

ckms locate --tag "cng-ksp::my-key"

Security considerations

• Private keys are never stored locally; they exist only in Cosmian KMS.
• All key operations require an authenticated connection to the KMS.
• The NCRYPT_ALLOW_PLAINTEXT_EXPORT_FLAG is off by default; private keys cannot be exported in plaintext.
• Use mTLS or bearer-token authentication in ckms.toml for production deployments.
• Run ckms cng register as Administrator. The DLL path stored in the registry is read by the Windows LSASS process — only trusted, signed DLLs should be registered.
• Consider restricting read access to ckms.toml so that unprivileged users cannot extract the KMS server URL or client certificate.

Microsoft Intune integration

Microsoft Intune is Microsoft's cloud-based Unified Endpoint Management (UEM) service. It lets IT administrators manage devices (Windows, macOS, iOS, Android) and enforce security policies — including deploying certificates — without on-premises infrastructure. When Intune provisions a certificate on a Windows endpoint, the private key is generated locally via a Key Storage Provider. By default Windows uses its built-in software KSP, which stores keys in the registry.

With the Cosmian KMS CNG KSP registered on the device, Intune can be configured to use it instead: the private key is created and permanently stored in Cosmian KMS rather than on the device. This gives the organisation centralised custody, FIPS 140-3 compliance, real-time revocation, and a full audit trail — all without any change to the Intune enrollment workflow itself.

SCEP certificate profile

1. In the Microsoft Intune admin center, create a SCEP certificate profile for Windows 10/11.

2. Set Key storage provider (KSP) to "Enroll to Custom KSP, otherwise fail" and enter the provider name exactly as:

   Cosmian KMS Key Storage Provider
   

3. Ensure the ckms.toml configuration file and the DLL are deployed to managed endpoints via an Intune Win32 app or PowerShell script before the certificate profile is applied.

4. The Intune SCEP agent will call NCryptCreatePersistedKey on the Cosmian KSP, then send the resulting CSR (public key only) to the SCEP server. The private key never leaves Cosmian KMS.

PKCS certificate profile

Set Key storage provider (KSP) to "Enroll to Custom KSP, otherwise fail" and enter the same provider name. The Intune PKCS connector will use the Cosmian KSP to generate the key pair on the device.

Imported PFX certificate (PFXImport PowerShell module)

For importing existing PFX certificates via the IntunePfxImport PowerShell module, follow these steps on the Certificate Connector server:

1. Ensure the KMS server is running and reachable (e.g. http://localhost:9998).

2. Register the KSP (see Installation above):

   ckms cng register --dll "$env:LOCALAPPDATA\Cosmian KMS CLI\cosmian_cng.dll"
   

3. Verify Windows discovers the provider:

   certutil -csplist | Select-String "Cosmian"
   # Expected: "Cosmian KMS Key Storage Provider"
   

4. Import the IntunePfxImport module (from the IntunePfxImportUtilities release folder):

   Import-Module .\IntunePfxImport.psd1
   

5. Create the encryption key pair in Cosmian KMS:

   Add-IntuneKspKey `
       -ProviderName "Cosmian KMS Key Storage Provider" `
       -KeyName "PFXEncryptionKey" `
       -MakeExportable
   

   This calls NCryptCreatePersistedKey → NCryptSetProperty(Export Policy) → NCryptFinalizeKey on the Cosmian KSP. The RSA key pair is created and stored exclusively in Cosmian KMS. The -MakeExportable flag sets the NCRYPT_ALLOW_EXPORT_FLAG so the public key can be exported for use on other connector servers.

6. Export the public key (if multiple connector servers share the key):

   Export-IntunePublicKey `
       -ProviderName "Cosmian KMS Key Storage Provider" `
       -KeyName "PFXEncryptionKey" `
       -FilePath "C:\temp\PFXEncryptionKey.pfx"
   

7. Import PFX certificates to Intune using the key:

   $userPFXObject = New-IntuneUserPfxCertificate `
       -PathToPfxFile "C:\temp\userA.pfx" `
       $SecureFilePassword `
       "userA@contoso.com" `
       "Cosmian KMS Key Storage Provider" `
       "PFXEncryptionKey" `
       "smimeEncryption"
   Import-IntuneUserPfxCertificate -CertificateList $userPFXObject
   

Remote key revocation for lost devices

When a device is lost or decommissioned:

# From the KMS administrator workstation:
ckms locate --tag "cng-ksp::intune-device-<serial>"
ckms revoke --id <uuid> "Device decommissioned"
ckms destroy --id <uuid>

Once the key is destroyed in the KMS, any subsequent sign or decrypt attempt from the device returns NTE_FAIL, effectively revoking the private key without requiring a certificate revocation list (CRL) propagation delay.

Integration testing

The CNG KSP is tested at three levels — all runnable without Azure credentials or an Intune tenant.

Prerequisites

No Azure account, Intune license, or SCEP infrastructure is needed — all tests run against a local Cosmian KMS server with a SQLite backend.

Test layers

Running the full test suite

From an elevated PowerShell prompt at the repository root:

.\.github\scripts\windows\test_cng_ksp.ps1

The script performs the following steps:

sequenceDiagram
    participant PS as PowerShell script
    participant Build as Cargo build
    participant KMS as Local KMS server
    participant Reg as Windows Registry
    participant Verify as cng_verify.exe
    participant Tests as cargo test
    participant Intune as IntunePfxImport module

    PS->>Build: 1. Build KMS server, cosmian_cng.dll, cng_verify, ckms
    Build-->>PS: Binaries ready
    PS->>KMS: 2. Start KMS (SQLite, port 9998)
    PS->>PS: 3. Write ckms.toml (server_url = localhost:9998)
    PS->>KMS: 4. GET /version (smoke-test)
    KMS-->>PS: 200 OK
    PS->>Reg: 5. ckms cng register (write HKLM KSP key)
    Reg-->>PS: Registry key created
    PS->>Verify: 6. Run cng_verify.exe (NCrypt surface tests)
    Verify->>KMS: NCrypt* calls via cosmian_cng.dll
    KMS-->>Verify: Key operations
    Verify-->>PS: All tests passed
    PS->>Tests: 7. cargo test --lib (in-process backend tests)
    Tests->>KMS: KMIP operations
    Tests-->>PS: Tests passed
    PS->>KMS: 8. ckms cng list-keys / ckms cng status
    KMS-->>PS: Key list and status
    PS->>Intune: 8b. Add-IntuneKspKey + Export-IntunePublicKey
    Intune->>KMS: NCryptCreatePersistedKey → NCryptFinalizeKey → NCryptExportKey
    KMS-->>Intune: Key created + public blob exported
    Intune-->>PS: Intune PFX workflow passed
    PS->>PS: 9. Parse KMS logs for ERROR / PANIC
    PS->>Reg: 10. ckms cng unregister (remove HKLM KSP key)
    PS->>KMS: Stop KMS server

Test coverage

The cng_verify tool exercises the following NCrypt operations against a live KMS:

Environment variables

Testing the Intune enrollment flow

The automated tests above validate the CNG KSP DLL itself — the same code path that Intune SCEP uses when it calls NCryptCreatePersistedKey and NCryptSignHash. To test the full Intune → endpoint → KMS flow you need:

This is typically validated manually or in a dedicated staging environment, not in CI.

Troubleshooting

Glossary