Overview

The Hardware Security Module (HSM) is a highly secure physical device specifically designed and used for cryptographic processing and strong authentication. It encrypts, decrypts, creates, stores, and manages digital keys and is used for signing and authentication. HSMs may be accessed via PKCS11 and JCE interfaces.

To simulate HSM, the default sandbox installation uses SoftHSM. SoftHSM supports PKCS11 but not JCE.

JCE

JCE is a Java keystore class implementation that connects to HSMs. HSM vendors should provide JCE support.

Specification

MOSIP highly recommends the following specifications for HSM:

1. Must support cryptographic offloading and acceleration.

2. Should provide authenticated multi-role access control.

3. Must have a strong separation of administration and operator roles.

4. Capability to support client authentication.

Guide to Integrate HSM

Configuration

• Keystore

  • mosip.kernel.keymanager.hsm.keystore-type

  • mosip.kernel.keymanager.hsm.config-path

Overview

The Key Manager Service provides secure storage, provisioning and management of secret data. It provides all the cryptographic operations like encryption/decryption and digital signature/verification making one trust store for all partner trust path validation. It manages the lifecycle of encryption/decryption keys, including generation, distribution, administration, and deletion.

This includes keying material such as symmetric keys, asymmetric keys, certificates and algorithm data. It is a web-based key management solution that helps consolidate, control, manage, monitor, all key generation and maintenance of key life cycle required in MOSIP.

Key Manager interfaces with key store like Hardware Security Module (HSM) and mosip_keymgr DB.

Encryption algorithms

• RSA-2048 for all data encryption

• AES-256 for

Key hierarchy

Root and Module keys reside in HSM while Base key pair reside in the DB encrypted by Module keys. All references (aliases) containing metadata of keys are present in table. The table contains encrypted Base keys.

The keys are identified as tuple of app_id and ref_id.

• app_id (or applicationId): Typically, module name e.g. REGISTRATION.

• ref_id (or referenceId): Specified only for Base keys (except SIGN*). Eg. 10001_110011

* SIGN: TBD

Key generation process

Root and Module keys are generated by any one of these methods:

1. Using Key Generator job or

2. Using Key Manager option in .

After the deployment, the initial set of pre-requisite keys has to be generated by the Administrator to complete the Key Manager setup. This generation is a one-time activity, and afterwards, the Key Manager will auto-generate all the required Root key and Module master keys upon expiry of key duration.

Base keys are auto-generated (and updaded on expiry) - the administrator is not required to request for generation. The keys reside in the DB. A new key pair is generated if not found in the DB.

Validity

The default validity of the keys may be modified by updating before generating keys.

Key revoke/rotate

You can revoke Root or Module key by invoking API with force attribute as true. API invalidates existing key and immediately generates new key.

You can revoke Base key by invoking API with the respective applicationId and referenceId.

Encryption process

• Random AES 256-bit key will be generated, generated random key will be used to encrypt the actual registration packet.

• Random generated key will be encrypted using the certificate received from server. Certificate contains RSA 2048 bit key.

• Certificate Thumbprint will be computed.

• Thumbprint will be prepend to encrypted random key for key identification.

Decryption process

• Registration packet data will be split to get the encrypted random key, encrypted registration data, certificate thumbprint.

• Identifies the respective private key to decryption process.

• Identified private key will be decrypted with the mapped master key.

• Decrypted private key will be used to decrypt the encrypted random key.

Encryption in Registration Client

• sends request to sync data service for the client configuration data.

• Sync Data service requests Key Manager service to provide the reg-client specific certificate. Key identifier will be APP_ID - REGISTRATION, REF_ID - CENTER-ID_MACHINE-ID.

• Key Manager service generate a new key pair, encrypts the private key with REGISTRATION master key and creates a new certificate using same master.

Developer Guide

To know more about the developer setup, read .

API

Refer .

Source code

.

Overview

To get an overview of Key Manager, refer Key Manager.

Below is a list of tools required in Key Manager:

1. JDK 11

2. Any IDE (like Eclipse, IntelliJ IDEA)

3. Apache Maven (zip folder)

4. PostgreSQL

5. Any DB client (like DBeaver, pgAdmin)

6. Postman (any HTTP Client)

7. Git

8. Any Editor (like Vscode, Notepad++ etc optional)

9. lombok.jar (jar file)

10. settings.xml (document)

Software setup

1. Download and .

2. Unzip Apache Maven and move settings.xml to "conf" folder <apache maven unzip path>\conf.

3. Install Eclipse, open the lombok.jar file and then click Install/Update.

4. Check the Eclipse installation folder to see if the lombok.jar is added.

5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs.

Source code setup

For the code setup, clone the repository and follow the guidelines mentioned in the .

Importing and building

1. Open the project folder where pom.xml is present.

2. Open the command prompt from the same folder.

3. Run the command mvn clean install -Dgpg.skip=true -DskipTests=true to build the project.

Environment setup

1. Download and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close.

1. Clone .

2. Refer to deploy local DB.

3. Key Manager uses two property files, kernel-default and application-default, configure them accordingly. For instance,

• Key Manager needs a Keystore to store keys. Supported Keystore types: PKCS11, PKCS12, Offline, JCE.

• Secrets can be encrypted using .

• Update URL's in property files.(It can be either pointed to any remotely or locally deployed services)

1. Download . For Windows, download , Linux users can run java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:{mosip-config-mt_folder_path}/config -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 {jarName} .

2. Run the server by opening the config-server-start.bat file.

http://localhost:51000/config/{spring.profiles.active}/{spring.cloud.config.name}/{spring.cloud.config.label} for instance http://localhost:51000/config/kernel/env/master.

Initialization and utilization of module

1. Key Manager REST service consists of bootstrap.properties file in src/main/resources.

2. Below properties needed to be modified in order to connect to the config server:

3. Services can be run using Run As -> Spring Boot App/Java Application.

Overview

In MOSIP every cryptographic key is referred by an Application ID and Reference ID.

Refer Key Manager for further details.

Various keys used in MOSIP

Partner keys

Device specific keys