Encryption Client Library
Overview
The enc-client library is a supplementary java library provided to support encryption-related functionalities so that every service does not need to pre-process the request before calling the encryption service.
Pre-requisites
MDMS Service
Encryption Service
Kafka
Important Note
The MDMS configurations explained below are fetched by this library at boot time. So after you make changes in the MDMS repo and restart the MDMS service, you would also need to RESTART THE SERVICE which has imported the enc-client library. For example, the report service is using the enc-client library so after making configuration changes to Security Policy pertaining to any report, you will have to restart the report service.
Key Functionalities
Encrypt a JSON Object - The
encryptJson
function of the library takes any Java Object as an input and returns an object which has encrypted values of the selected fields. The fields to be encrypted are selected based on an MDMS Configuration.This function requires the following parameters:
Java/JSON object - The oject whose fields will get encrypted.
Model - It is used to identify the MDMS configuration to be used to select fields of the provided object.
Tenant Id - The encryption key will be selected based on the passed tenantId.
Encrypt a Value - The
encryptValue
function of the library can be used to encrypt single values. This method also required a tenantId parameter.Decrypt a JSON Object - The
decryptJson
function of the library takes any Java Object as an input and returns an object that has plain/masked or no values of the encrypted fields. The fields are identified based on the MDMS configuration. The returned value(plain/masked/null) of each of the attribute depends on the user’s role and if it is aPlainAccess
request or a normal request. These configurations are part of the MDMS.This function required following parameters:
Java/JSON object - The object containing the encrypted values that are to be decrypted.
Model - It is used to select a configuration from the list of all available MDMS configurations.
Purpose - It is a string parameter that passes the reason of the decrypt request. It is used for Audit purposes.
RequestInfo - The requestInfo parameter serves multiple purposes:
User Role - A list of user roles are extracted from the requestInfo parameter.
PlainAccess Request - If the request is an explicit plain access request, it is to be passed as a part of the requestInfo. It will contain the fields that user is requesting for decryption and the id of record.
While decrypting Java object, this method also audits the request.
Configurations
All the configurations related to enc-client library are stored in the MDMS. These master data are stored in DataSecurity
module. It has two types of configurations:
Masking Patterns
Security Policy
Masking Patterns
The masking patterns for different types of attributes(mobile number, name, etc.) are configurable in MDMS. It contains the following attributes:
patternId
- It is the unique pattern identifier. This id is referred to in the SecurityPolicy MDMS.pattern
- This defines the actual pattern according to which the value will be masked.
Here is a link to a sample Masking Patterns master data.
Security Policy
The Security Policy master data contains the policy used to encrypt and decrypt JSON objects. Each of the Security Policy contains the following details:
model
- This is the unique identifier of the policy.uniqueIdentifier
- The field defined here should uniquely identify records passed to thedecryptJson
function.attributes
- This defines a list of fields from the JSON object that needs to be secured.roleBasedDecryptionPolicy
- This defines attribute-level role-based policy. It will define visibility for each attribute.
Visibility
The visibility is an enum with the following options:
PLAIN - Show text in plain form.
MASKED - The returned text will contain masked data. The masking pattern will be applied as defined in the Masking Patterns master data.
NONE - The returned text will not contain any data. It would contain string like “Confidential Information”.
It defines what level of visibility should the decryptJson
function return for each attribute.
Attribute
The Attribute defines a list of attributes of the model that are to be secured. The attribute is defined by the following parameters:
name
- This uniquely identifies the attribute out of the list of attributes for a given model.jsonPath
- It is the json path of the attribute from the root of the model. This jsonPath is NOT the same as Jayway JsonPath library. This uses/
and*
to define the json paths.patternId
- It refers to the pattern to be used for masking which is defined in the Masking Patterns master.defaultVisibility
- It is an enum configuring the default level of visibility of that attribute. If the visibility is not defined for a given role, then this defaultVisibility will apply.
Unique Identifier
This parameter is used to define the unique identifier of that model. It is used for the purpose of auditing the access logs. (This attribute’s jsonPath should be at the root level of the model.)
Role-Based Decryption Policy
It defines attribute-level access policies for a list of roles. It consists of the following parameters:
roles
- It defines a list of role codes for which the policy will get applied. Please make sure not to duplicate role codes anywhere in the other policy. Otherwise, any one of the policies will get chosen for that role code.attributeAccessList
- It defines a list of attributes for which the visibility differs from the default for those roles.There are two levels of visibility:
First level Visibility - It applies to normal search requests. The search response could have multiple records.
Second level Visibility - It is applied only when a user explicitly requests for plain access of a single record with a list of fields required in plain.
Second level visibility can be requested by passing plainAccessRequest
in the RequestInfo
.
Plain Access Request
Any user will be able to get plain access to the secured data(citizen’s PII) by requesting through the plainAccessRequest
parameter. It takes the following parameters:
recordId
- It is the unique identifier of the record that is requested for plain access.fields
- It defines a list of attributes that are requested for plain access.
Audit Service
Every decrypt request is audited. Based on the uniqueIdentifier
defined as part of the Security Policy, it lists out the identifiers of the records that were decrypted as part of the request.
Each Audit Object contains the following attributes: