Skip to content

Safe Keeping

Introduction

The Safe Keeping module's APIs are designed to make it easier to manage secrets in custody, also known as Critical Security Parameter (CSP).

The Safe Keeping module enables shared custody of secrets stored in the HSM. These secrets are generated with high security, on approved hardware, guaranteeing high entropy and protection against a variety of attacks, including side channel attacks.

Architecture

The Safe Keeping module operates in 3 stages.

  1. Generating secrecy;
  2. Dividingshares of the secret using Shamir's secret sharing algorithm;
  3. Recovery of the secret from the parts generated in the previous step.

Generating secrecy

At this stage, the secret is generated in a partition (user) of the HSM, securely and with high entropy, and exists only in the HSM.

Each partition has credential authentication with a username and password and additional authentication can optionally be configured, such as:

  • M of N of partition;
  • 2fA with OTP (One Time Password) tokens in the format OATH;
  • 2fA with X.509 certificates;

You can combine one or more types of partition authentication as required.

The secret can be generated according to various security levels and the needs of the project. It must be chosen carefully so that the level of security is equivalent at other points in the project. A security level that is too low can weaken the security of the data being protected, while a security level that is too high can slow down operations unnecessarily.

See the table below for an idea.

Security level Size in bytes Corresponding Physical Quantity
64 bits 8 Grains of sand on Earth.
96 bits 12 Atoms in the human body.
112 bits 14 Diameter of the observable universe in thousandths of a millimeter.
128 bits 16 Oxygen atoms in the Earth's atmosphere.
160 bits 20 Atoms on Earth.

Dividing the secret

At this stage, theshares of the secret are divided using the Shamir algorithm(Shamir Shared Secret) in the M of N scheme.

The M of N scheme means that from a group of N parts, M parts are needed to recompose the secret.

The parts, also known as shares or shadows, are generated in such a way that it is impossible to recompose the secret with fewer than M parts.

The generation of parts is usually done in a ceremony, where each part is distributed to a member of the organization and stored securely. This prevents collusion between members of the organization. The way the shares are distributed, the choice of members and other details of the ceremony are defined according to each business.

The parts are slightly larger than the security level because they contain metadata from the M of N scheme. Each part is available in Base62 format to facilitate annotation.

Note

It is recommended to generate checksums for each part at this point. This makes it easier to verify the typing of the parts at the time of retrieval.

Recovering the secret

The secret is recomposed using M of the N parts generated in the previous step.

In this case, a secret recovery ceremony takes place. It is necessary for each custodian (Cardholder of a party) to insert their part for the recovery of the secret. This ceremony is defined according to each deal.

The secret varies in size depending on the security level used, and is available in Base62 format for easy annotation.

Note

It is recommended that you check the checksums of each part at this point. This avoids typing errors at a critical moment.

API Safe Keeping

Specific API documentation for the Safe Keeping module, with functions, classes and examples.