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 clustering and load balancing.

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

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

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

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

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

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

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

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

16. Safety and environmental compliance

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

    2. Compliance with RoHS2 and WEEE.

17. 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)

18. Physical characteristics

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

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

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

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

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>

Introduction

Modular Open Source Identity Platform (MOSIP) integrates a suite of Mock Services designed to emulate key functionalities of MOSIP services within the framework. In the development, testing, and demonstration phases, Mock Services will make available a controlled environment to evaluate MOSIP features. Developers and testers can refer to this documentation to gain a comprehensive understanding of the structure and functionality of each Mock Service within the MOSIP framework.

Benefits of using Mock Services

1. Faster Development and Testing: Enables rapid development and testing cycles without need to access to production systems.

2. Reduced Costs: Avoids the need for production resources, lowering development and testing costs.

3. Controlled Environment: Testing with Mock Services provides consistent and predictable behavior, ideal to isolate and troubleshoot.

4. Data Privacy: Sensitive data remains secure, as development and testing occur with mock data.

This document details each of the Mock Services and explains its significance within the MOSIP architecture.

Mock Services in MOSIP

Below mentioned are the current set of mock services available in MOSIP.

1. Mock MDS (MOSIP Device Services)

   • Simulates device services for testing, authentication, and delete registration functionalities.

   • Allows developers to interact with a device-service environment without a physical device.

2. Mock MV (Manual Verification)

   • Reproduces the manual verification process for testing and validation purposes.

   • Enables the testing of manual verification workflows without human intervention.

3. Mock ABIS (Automated Biometric Identification System)

   • Simulates the functionality of the Automated Biometric Identification System (ABIS).

   • Facilitates testing of biometric matching, searching, and integrating with ABIS without accessing production data.

   • Maintains resident biometric uniqueness through de-duplication.

   • Interfaces with MOSIP via message queues in JSON format.

   • Supports 1:N de-duplication and adheres to ABIS API Specifications.

4. Mock SDK (Software Development Kit)

   • Replicates MOSIP's Biometric Software Development Kit (SDK) for testing and debugging.

   • Allows developers to integrate biometric functionalities into applications without connecting to a physical device.

   • Used for 1:N match, quality, and extraction, etc.

   • Simulation is available as Mock BioSDK, installed in the MOSIP sandbox.

   • Exposes REST APIs for 1:1 match and quality check at the MOSIP backend.

5. Mock SMTP (Simple Mail Transfer Protocol)

   • Simulates an SMTP server for testing email notifications without sending actual emails.

   • Enables the testing of communication workflows and email content.

   Mock SMTP Server

   • Is installed as part of the default MOSIP installation.

   • Mimics real SMTP server behavior for testing and development purposes.

Modules utilizing MOSIP Mock Services

MOSIP uses Mock Services in the following modules:

Registration Client

The Registration Client module uses below mentioned Mock Services during the execution of the registration process. To capture biometric data, check the quality of the captured biometric data, etc., the following services are run:

• Mock MDS (MOSIP Device Service): The Registration Client module interacts with Mock MDS to capture biometric data during the registration. This facilitates the development of simulated biometrics, which are crucial for finalizing the registration process and generating the Unique Identification Number (UIN).

• Mock SDK (Software Development Kit): The Registration Client module interacts with mock SDK to perform 1:N match for biometrics, extracts biometric templates, and checks the quality of the captured biometrics.

Registration Processor

Mock Services help Registration Processor to process packets by providing support to emulate key functionalities such as search for the duplicate biometric data, to perform manual verification, and to check the quality of the captured biometric data.

Mentioned below are the services utilized by the Registration Processor module to facilitate the functions.

• Mock ABIS (Automated Biometric Identification System): Registration Processor module interacts with mock ABIS for testing matching performance and error handling.

• Mock MV (Manual Verification): Registration Processor module interacts with Mock MV to process the packets that are marked for manual verification.

• Mock SDK (Software Development Kit): Registration Processor module interacts with Mock SDK to check the quality of the captured biometrics and for authentication purposes.

ID Authentication

ID Authentication module also utilizes the mock services during development, testing, and demonstration phases. It uses Mock SDK to carry out the biometric authentication.

Furthermore, the development and improvement of Mock Services is an ongoing and evolving process.

Overview

Properties that are shared across all modules are written in the file application-default.properties.

Module-specific properties are written in respective *.properties files in mosip-config

Config server

Config server is a Spring Cloud Config Server that serves the above properties to modules during run-time. The property files are downloaded when an application starts. The config server is installed as part of sandbox installation.

Some of the important properties that must be reviewed and modified for a specific deployment are listed below.

Modules

Configurations of each MOSIP module will be available here:

• Administration

• Commons

• Datashare

• ID Authentication

• ID Repository

• Key Manager

• Packet Manager

• Partner Management

• Pre-registration

• Registration Client

• Registration Processor

• Resident Services

• Resident Mobile Application

• WebSub

Database

Refer to Postgres DB configuration.

HSM

Refer to HSM configuration.

Languages

Mandatory Languages - Languages that the user has to fill (can be auto translated) during the pre-registration & registration.

Optional Languages - Languages that are not mandatory but provided as a choice to the user.

User selected Language - The language that the user selected at the time of login. The choices shown are union of Mandatory and Optional languages. The labels and alerts will be use the user selected language

Prefered Language - During registration of a registrant (user for whom identity is requested), he can choose his prefered language. This preference use used for all further notification (email, SMS or any other notification).

Languages for the entire system are configured in application prorperties file:

mosip.mandatory-languages=eng,tam
mosip.optional-languages=fra,ara

The i18n file for the respective language has to be added to the artifactory Artifactory. The language codes are as per ISO 639-2

Overview

WebSub provides a common mechanism for communication between publishers of any kind of Web content and their subscribers, based on HTTP web hooks. Subscription requests are relayed through hubs, which validate and verify the request. Hubs then distribute new and updated content to subscribers when it becomes available. WebSub was previously known as PubSubHubbub. For more information, read W3C WebSub.

WebSub in MOSIP

In MOSIP, WebSub is used to share data with services and partners. Kafka message broker has been used to implement the WebSub APIs. Message brokers are a natural fit for the implementation of WebSub hubs as they serve a similar purpose.

The relationship of WebSub with other services is explained here. NOTE: The numbers do not signify sequence of operations or control flow.

1. Topic is registered and published or subscribed by MOSIP Services.

2. Content delivery and Intent Verification is done by WebSub to Mosip Services.

3. Content delivery and Intent Verification is done by WebSub to Partners.

4. Topic is registered and published or subscribed by the Partners.

5. Data and metadata needed for delivery, delivery reports and other functionalities are stored in Kafka.

Refer WebSub repo for further details.

Developer Guide

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

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

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

Overview

Below is a list of tools required in WebSub:

1. Ballerina (Swan-Lake)

2. Any IDE (like Vs Code)

3. Kafka

4. Postman (any HTTP Client)

5. Git

Software setup

Source code setup

Importing and building

1. Open the hub and consolidator folders where Ballerina.toml is present.

2. Open the command prompt from the same folder.

3. Run the command bal build to build the hub and consolidator.

4. Open the project in VS Code either by open with vs code or from File -> Open Folder.

Environment setup

2. Run Configure and run Kafka, update KAFKA_BOOTSTRAP_NODE in Config.toml to point to your Kafka.

Initialization and utilization of module

1. WebSub consists of consolidator and hub.

2. Consolidator should be started first, Got to consolidator -> java -jar target/bin/<Jarname>. (Config.toml should be in the same place where you are running this command).

3. Start WebSub with the same approach.