# Key Manager

## Overview

The Key Manager in Inji Certify is a critical component which is used as an embedded library responsible for secure cryptographic key lifecycle management.

It handles:

* Generation of asymmetric and symmetric keys.
* Storage and encryption of private keys.
* Certificate management (self-signed and externally signed).
* Digital signing operations (e.g., signing Verifiable Credentials).
* Key rotation and revocation.
* Secure integration with hardware-backed key stores (e.g., HSM).

By consolidating these cryptographic operations in one trusted service, Certify ensures the integrity, confidentiality, and long-term security of all cryptographic materials.

## Capabilities & Responsibilities

Below are the main capabilities and how Key Manager supports them in Inji Certify:

### Key Generation

* The Key Manager generates various types of keys: root/master keys, module-level keys, and application-specific (base) keys.
* Asymmetric algorithms such as RSA, ECC, Ed25519 etc. are used based on the VC configuration.
* Root and module master keys can be generated at the time of installation of Inji Certify
* Base keys (application-specific) are auto-generated as needed.

### Secure Storage

* Private keys are stored securely in a key store. In Inji implementation, a Hardware Security Module (HSM) is used to store root and master keys, while base keys are stored in a database encrypted by module keys.
* Key metadata (aliases, identifiers) is maintained in a key-alias table; the encrypted key material resides in a key-store table.
* The Key Manager supports integration with HSMs via PKCS#11 or JCE.

### Certificate Management

* Self-Signed Certificates: When no external CA is provided, the Key Manager can generate self-signed certificates. For example, root key is self-signed.
* CSR Generation: It supports generating CSR (Certificate Signing Requests) for any key, so that you can obtain a certificate signed by an external CA.
* Uploading Externally-Signed Certificates: Once you obtain a CA-signed certificate, you can upload it to the Key Manager, updating existing certificate with CA signed certificate.

### Signing & Cryptographic Operations

For signing credential (VC) issuance, the Key Manager uses the appropriate key (module or base) and the associated certificate to sign the VC payload.

### Key Rotation

* Automatic Rotation: Keys have default validity periods. For example, in MOSIP, root keys are valid for \~5 years, module keys for \~3 years, base keys for \~2 years.
* Forced Rotation: Admins can force key regeneration via APIs (e.g., a generateMasterKeyAPI) with a “force” flag. Existing keys are invalidated and new ones generated.
* On expiry, key manager automatically generates new keys and ensures that cryptographic operations switch over to the new valid keys.
* Duration of key rotation is configurable which is handled through a table named as 'key-policy-def'.
* Key manager has the capability to pre generate keys before expiry. Duration for the pre generation is a configurable which is handled through a table named as 'key-policy-def'.

### Certificate Expiry Handling

In case of externally CA signed certificate is used for key generation, and certificate expires, the system falls back: Key Manager re-generate keys using a self-signed certificate (or whatever default mechanism is configured).

* Mitigation: To avoid lapse in trust or broken signing, users (issuer administrators) must proactively upload a new valid certificate before the current one expires.

### Integration with Hardware Security Module (HSM)

The Key Manager is designed to work with HSMs, ensuring that root and module keys never leave secure hardware.

* For setups without HSM, the Key Manager also supports other keystore types (PKCS12), configurable via properties. (This option is not recommended during the production environment).
* Role of Key Manager Specifically in VC Signing Workflow (In Certify).
* Putting the above capabilities in the context of Verifiable Credential (VC) issuance in Inji Certify:
  * Initial Setup (If PKI is already existing)
  * The system admin uses Inji Certify API which internally uses KeyManager service to generate a master signing key pair.
  * The admin can request a CSR from Inji Certify API for the generated signing key (via generateCSR), so they can share it to be externally singed by CA
  * Once the certificate is signed, they upload the CA certificate to Inji Certify, then upload their signed certificate, binding it to the key.

### Credential Issuance

When Certify issues a VC, it calls Key Manager to sign the credential payload.

* Key Manager uses the private key associated with the signing key (which is backed by the uploaded certificate) to compute a digital signature.
* The signed VC thus has cryptographic integrity and can be verified by relying parties using the public certificate.

## Key Benefits for Inji Certify

* Security & Trust: All signing keys are managed securely; private keys are never exposed, especially when using HSM.
* Flexibility: Support both self-signed workflows (for simplicity) and externally-CA-signed certificates (for integration into existing PKI).
* Operational Control: Administrators have full control over key lifecycles, rotation, and certificate management.
* Interoperability: By using standard cryptography and certificate formats, Certify’s VCs can be validated by any compliant verifier.
* Resilience: With key-rotation and fallback mechanisms, the system can recover from certificate expiry.

For deeper technical details about the Key Manager component itself, you can refer to the MOSIP documentation [here](https://docs.mosip.io/1.2.0/id-lifecycle-management/supporting-components/keymanager).