# Encryption Service

### Overview <a href="#overview" id="overview"></a>

Encryption Service is used to secure sensitive data that is being stored in the database. The encryption services uses envelope encryption.

### Pre-requisites <a href="#pre-requisites" id="pre-requisites"></a>

Before you proceed with the documentation, make sure the following pre-requisites are met -

* *Java 17.*
* Kafka server is up and running.

### Key Functionalities <a href="#key-functionalities" id="key-functionalities"></a>

Encryption Service offers following features :

1. Encrypt - The service will encrypt the data based on given input parameters and data to be encrypted. The encrypted data will be mandatorily of type string.
2. Decrypt - The decryption will happen solely based on the input data (any extra parameters are not required). The encrypted data will have identity of the key used at the time of encryption, the same key will be used for decryption.
3. Sign - Encryption Service can hash and sign the data which can be used as unique identifier of the data. This can also be used for searching gicen value from a datastore.
4. Verify - Based on the input sign and the claim, it can verify if the the given sign is correct for the provided claim.
5. Rotate Key - Encryption Service supports changing the key used for encryption. The old key will still remain with the service which will be used to decrypt old data. All the new data will be encrypted by the new key.

### Configuration Details <a href="#configuration-details" id="configuration-details"></a>

Following are the properties in application.properties file in egov-enc-service which are configurable.

<table><thead><tr><th width="306.66666666666663">Property</th><th>Default Value</th><th>Remarks</th></tr></thead><tbody><tr><td><code>master-password</code></td><td>asd@#$@$!132123</td><td>Master password for encryption/ decryption. It can be any string.</td></tr><tr><td><code>master.salt</code></td><td>qweasdzx</td><td>A salt is random data that is used as an additional input to a one-way function that hashes data, a password or passphrase. It needs to be an alphanumeric string of length 8.</td></tr><tr><td><code>master.initialvector</code></td><td>qweasdzxqwea</td><td>An initialization vector is a fixed-size input to a cryptographic primitive. It needs to be an alphanumeric string of length 12.</td></tr><tr><td><code>size.key.symmetric</code></td><td>256</td><td>Default size of Symmetric key.</td></tr><tr><td><code>size.key.asymmetric</code></td><td>1024</td><td>Default size of Asymmetric key.</td></tr><tr><td><code>size.initialvector</code></td><td>12</td><td>Default size of Initial vector.</td></tr><tr><td><code>master.password.provider</code></td><td>software</td><td>Name of the implementation to be used for encrypting DEKs</td></tr><tr><td><pre><code>aws.kms.access.key
</code></pre></td><td>NA</td><td>AWS access key to access the KMS service (Note: this field is required only if <code>master.password.provider</code> is set to kms)</td></tr><tr><td><pre><code>aws.kms.secret.key
</code></pre></td><td>NA</td><td>AWS secret to access the KMS service (Note: this field is required only if <code>master.password.provider</code> is set to kms)</td></tr><tr><td><pre><code>aws.kms.region
</code></pre></td><td>NA</td><td>AWS region to access the KMS service (Note: this field is required only if <code>master.password.provider</code> is set to kms)</td></tr><tr><td><pre data-full-width="true"><code>aws.kms.master.password.key.id
</code></pre></td><td>NA</td><td>Id of the KMS key to be used for encrypting the DEK (Note: this field is required only if <code>master.password.provider</code> is set to kms)</td></tr></tbody></table>

### Deployment Details <a href="#deployment-details" id="deployment-details"></a>

1. [Deploy](https://docs.digit.org/platform/accelerators/concepts/deployment-key-concepts/deploying-digit-services) the latest version of Encryption Service

   **Note**: This video will give you an idea of how to deploy any Digit-service. Further you can find the latest builds for each service in out latest [release document](https://docs.digit.org/platform/platform/releases/digit-2.9-lts/service-build-updates) here.
2. Add [Role-Action](https://github.com/egovernments/playground-mdms-data/blob/master/data/pg/ACCESSCONTROL-ROLEACTIONS/roleactions.json) mapping for API’s.

### Integration <a href="#integration" id="integration"></a>

#### Integration Scope <a href="#integration-scope" id="integration-scope"></a>

The Encryption service is used to encrypt sensitive data that needs to be stored in the database. For each tenant, a different data encryption key (DEK) is used. The DEK is encrypted using Key Encryption Keys (KEK). Currently, there are two implementations of encrypting the data encryption keys available. The first one is using AWS KMS service and the second one is using a master password. For any custom implementation, the *MasterKeyProvider* interface in the service should be extended. Based on the *master.password.provider* flag in *appication.properties* you can enable which implementation of *MasterKeyProvider* interface to use

#### Integration Benefits <a href="#integration-benefits" id="integration-benefits"></a>

* Can perform encryption without having to re-write encryption logic every time in every service.

#### Steps to Integration <a href="#steps-to-integration" id="steps-to-integration"></a>

1. To integrate, the host of encryption-services module should be overwritten in the helm chart.
2. `/crypto/v1/_encrypt` should be added as an endpoint for encrypting input data in the system
3. `/crypto/v1/_decrypt` should be added as the decryption endpoint.
4. `/crypto/v1/_sign` should be added as the endpoint for providing a signature for a given value.
5. `/crypto/v1/_verify` should be added as the endpoint for verifying whether the signature for the provided value is correct.
6. `/crypto/v1/_rotatekey` should be added as an endpoint to deactivate the keys and generate new keys for a given tenant.

### Reference Docs <a href="#reference-docs" id="reference-docs"></a>

#### Doc Links <a href="#doc-links" id="doc-links"></a>

| Title                     | Link                                                                                                                                                                   |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Swagger Documentation | [Swagger Documentation](https://editor.swagger.io/?url=https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/enc-service-contract.yml#!/) |

#### API List <a href="#api-list" id="api-list"></a>

a) `POST /crypto/v1/_encrypt`

Encrypts the given input value/s OR values of the object.

b) `POST /crypto/v1/_decrypt`

Decrypts the given input value/s OR values of the object.

c) `/crypto/v1/_sign`

Provide signature for a given value.

d) `POST /crypto/v1/_verify`

Check if the signature is correct for the provided value.

e) `POST /crypto/v1/_rotatekey`

Deactivate the keys for the given tenant and generate new keys. It will deactivate both symmetric and asymmetric keys for the provided tenant.

## Play around with the APIs : [DIGIT-Playground](https://digit-api.apidog.io/doc-507201)