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 lombok.jar and settings.xml.

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

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 Code Contributions.

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.

4. After building, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.

5. After successful importing of project, update the project by right-click on Project → Maven → Update Project.

Environment setup

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

1. Clone mosip-config repository.

2. Refer KeyManager-DB-deploy 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.

  Copy

  # For PKCS11 provide Path of config file.
  # For PKCS12 keystore type provide the p12/pfx file path. P12 file will be created internally so provide only file path and file name.
  # For Offline & JCE property can be left blank, specified value will be ignored.
  mosip.kernel.keymanager.hsm.config-path=/config/softhsm-application.conf
  # Passkey of keystore for PKCS11, PKCS12
  # For Offline & JCE property can be left blank. JCE password use other JCE specific properties.
  mosip.kernel.keymanager.hsm.keystore-pass={cipher}2d6aa328be521b2be6f33f476f7df2ea39c7ae1a3e2146ec169c5fac3225da3f

• Secrets can be encrypted using config server.

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

1. Download kernel-config-server.jar. For Windows, download config-server-start.bat, 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.
3. To verify the config-server, hit the below URL:

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:

   Copy

   spring.cloud.config.uri=<config server uri>
   spring.cloud.config.label=<branch of config repo>
   spring.profiles.active=default

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

4. For API documentation, refer here.

5. The API's can be tried with the help of Swagger-UI and Postman.

6. Swagger-UI service can be accessed from (https/http)://(<domain>/<host>:<port>)/<context-path>/swagger-ui/index.html?configUrl=<contect-path>/v3/api-docs/swagger-config for instance https://dev2.mosip.net/v1/auditmanager/swagger-ui/index.html?configUrl=/v1/keymanager/v3/api-docs/swagger-config.

7. The API's can be tried using Postman. URLs and Body structures can be found in swagger or curl command can be copied and imported in Postman.

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.

5. Must have secure key wrapping, backup, replication, and recovery.

6. Must support 2048, 4096-bit RSA private keys, and 256-bit AES keys on the FIPS 140-2 Level 3 Certified Memory of the Cryptographic Module.

7. Must support at least 10000+ 2048 RSA private keys on FIPS 140-2 Level 3 Certified Memory of the Cryptographic Module.

8. Must support clustering and load balancing.

9. Should support the cryptographic separation of application keys using logical partitions.

10. Must support M of N multi-factor authentication.

11. PKCS#11, OpenSSL, Java (JCE), Microsoft CAPI, and CNG

12. Minimum dual Gigabit Ethernet ports (to service two network segments) and, optionally, 10G Fibre ports could be available.

13. Asymmetric public key algorithms: RSA, Diffie-Hellman, DSA, KCDSA, ECDSA, ECDH, and ECIES

14. Symmetric algorithms: AES, ARIA, CAST, HMAC, SEED, Triple DES, DUKPT, and BIP32

15. Hash/message digest: SHA-1, SHA-2 (224, 256, 384, 512 bits).

16. Full Suite B implementation with fully licensed ECC, including Brainpool, custom curves, and safe curves

17. Safety and environmental compliance

    1. Compliance with UL, CE, and FCC Part 15 Class B.

    2. Compliance with RoHS2 and WEEE.

18. Management and monitoring

    1. Support remote administration —including adding applications, updating firmware, and checking the status— from NoC.

    2. Syslog diagnostics support

    3. Command Line Interface (CLI) or Graphical User Interface (GUI)

    4. Support the SNMP monitoring agent.

19. Physical characteristics

    1. Standard 1U 19-inch rack mount with integrated PIN ENTRY Device or Smart Card or any equivalent security.

20. Performance

    1. RSA 2048 signing performance: 10,000 per second.

    2. RSA 2048 key generation performance: 10+ per second.

    3. RSA 2048 encryption or decryption performance: 20000+ per second.

    4. RSA 4096 signing performance: 2000+ per second.

    5. RSA 4096 key generation performance: 2+ per second.

    6. RSA 4096 encryption or decryption performance: 20000+ per second.

21. Should be able to backup keys, replicate keys, and store keys in offline locker facilities for DR. The total capacity is in line with the total number of keys prescribed.

22. Clustering minimum of 20 HSMs.

23. Less than 30 seconds for key replication across the cluster.

24. A minimum of 30 logical partitions and their license should be included in the cost.

Guide to Integrate HSM

Configuration

• Keystore

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

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

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

• JCE

  • mosip.kernel.keymanager.hsm.jce.className

  • mosip.kernel.keymanager.hsm.jce.keyStoreType

  • mosip.kernel.keymanager.hsm.jce.keyStoreFile

  • mosip.kernel.keymanager.hsm.jce.<ANY_OTHER_PARAM_01>

  • mosip.kernel.keymanager.hsm.jce.<ANY_OTHER_PARAM_02>

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

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 zero-knowledge encryption

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 mosip_keymgr/key_alias table. The key_store 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 Admin portal.

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 mosip_keymgr/key_policy_def table before generating keys.

Key revoke/rotate

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

You can revoke Base key by invoking revokeKey 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.

• Finally, the encrypted random key with prepended thumbprint will be concated with encrypted registration packet using #KEY_SPLITTER# as separator.

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.

• Decrypt the registration packet using the decrypted random key.

• Returns the decrypted data to REG_PROC.

Encryption in Registration Client

• 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.

• Returns the certificate to Sync data service. If key pair is already available and is valid, returns the available certificate.

• Sync data service sends the certificate to Registration Client.

• The registration packet will be encrypted using the certificate received from the server after collecting all the required data for registration, including adding the digital signatures required to the registration data, and before saving/writing the data on the Registration Client hard-disk.

• REG_PROC sends request to decrypt the data to Key Manager service with same app_id and ref_id.

Developer Guide

To know more about the developer setup, read Key Manager Developers Guide.

API

Refer API Documentation.

Source code

Github repo.