Managing DPG Applications
An application definition contains necessary configurations that are required for a client to function smoothly. A registration token generated while defining the application is used to register the clients with the CipherTrust Manager.
The application definition includes:
Configuration parameters: required to initialize and configure the client.
CSR parameters: required to create or renew client certificates and keys.
CA parameters: required to issue and install digital certificates and CSR.
DPG policy: determines when and how to protect data moving through DPG.
In this article, you will learn how to:
Defining Application
Log on to the CipherTrust Manager GUI as administrator.
Open Application Data Protection.
In the left pane, click Applications. The list of applications is displayed on the screen.
On the Applications page, click Add Application. The Add Application wizard is displayed.
Follow the steps to define an application for your DPG client.
Add General Info
On the General Info screen of the Add Application Wizard, specify a unique Name for the application.
Select Connector Type as DPG from the drop-down list.
Click Next to go to the Settings screen.
Configure Parameters
On the Settings screen of the Add Application Wizard, configure:
Client Configuration
These parameters are required to initialize DPG clients.
a. Authentication Method
Field | Description | Mandatory | Default |
---|---|---|---|
Scheme Name | Authentication method used to validate the identity of the application users. Following methods are allowed: — Basic: In this scheme, username and password are passed into the authorization request header. The username and password are encoded in Base64 format. — Bearer: In this scheme, a security token (a cryptic string) is granted to the application users. The application user must send this token in the authorization request header when making any reveal request to DPG. | Yes | Basic |
Token Field | Name of the field that contains the username in authorization token based on which the level of access control over reveal operation will be identified. | No. Mandatory only when Bearer is selected as the authentication method. | No default |
b. Logging
Field | Description | Mandatory | Default |
---|---|---|---|
Log Level | The level of logging to determine verbosity of client logs. Options — INFO — WARN — ERROR — DEBUG | Yes | WARN |
c. Local Encryption
Field | Description | Mandatory | Default |
---|---|---|---|
Key Cache Expiry | Determines the minimum amount of time a key can be cached. | Yes | 43200 seconds |
d. Connection Configuration
Note
If you are using DPG 1.2 and lower versions, configure the following parameters on the CipherTrust Manager UI.
Field | Description | Mandatory | Default |
---|---|---|---|
Maximum Idle Connection | Specifies the maximum number of idle (keep-alive) connections for all hosts. A value of 0 means no limit. | Yes | 10000 |
Maximum Idle Connection Per Host | Specifies the maximum idle (keep-alive) connections to keep for each host. | Yes | 10000 |
Dial Timeout | Specifies the maximum duration (in seconds) the DPG server will wait for a connection with the Application Server to succeed. | Yes | 10 |
Dial Keep Alive | Specifies the interval (in seconds) between keep-alive probes for an active network connection. | Yes | 10 |
Connection Idle Timeout | Specifies the duration for which a connection is allowed to be idle in the connection pool before it gets automatically closed. | Yes | 600000 |
Connection Retry Interval | Specifies the time to wait before trying to reconnect to a disabled server. | Yes | 600000 |
Connection Timeout | Connection timeout value for clients. | Yes | 60000 |
Connection Read Timeout | Read timeout value for clients. | Yes | 7000 |
Size of Connection Pool | The maximum number of connections that can persist in a connection pool. | Yes | 300 |
Load Balancing Algorithm | Determines how the client selects a Key Manager from a load balancing group. Options — round-robin — random | Yes | round-robin |
Heartbeat Interval | Time interval (in seconds) after which the client needs to send heartbeat notification to the CipherTrust Manager to get updated policies and configurations. | Yes | 300 seconds |
Heartbeat Timeout Count | Number of continuously missed heartbeats after which a client marks itself as unhealthy. After this count, the CipherTrust Manager revokes the client and the client stops performing any cryptographic operations. | Yes | 5 minutes If this parameter is set to -1, the client will continue to send the heartbeats until it is alive and the CipherTrust Manager will not revoke the client. The container will never be marked as unhealthy. |
The CipherTrust Manager updates status of all the clients after every 5 minutes based on the number of missed heartbeats.
Note
For DPG 1.3 and higher versions, following parameters should be configured on the CipherTrust Manager UI.
Field | Description | Mandatory | Default |
---|---|---|---|
Connection Timeout | Connection timeout value for clients. | Yes | 60000 |
Heartbeat Interval | Time interval (in seconds) after which the client needs to send heartbeat notification to the CipherTrust Manager to get updated policies and configurations. | Yes | 300 seconds |
Heartbeat Timeout Count | Number of continuously missed heartbeats after which a client marks itself as unhealthy. After this count, the CipherTrust Manager revokes the client and the client stops performing any cryptographic operations. | Yes | 5 minutes -1 client will continue to send the heartbeats until it is alive and the CipherTrust Manager will not revoke the client. The container will never be marked as unhealthy. |
The CipherTrust Manager updates status of all the clients after every 5 minutes based on the number of missed heartbeats.
e. SSL Configuration
Field | Description | Mandatory | Default |
---|---|---|---|
TLS Enabled | Determines whether to enable TLS. If check-box is selected, DPG will communicate with the upstream server over TLS else, TCP will be used. | Yes | Not selected (not configurable) |
TLS Skip Verify | This field is always selected; DPG doesn't verify the upstream server certificates. | Yes | Always selected (not configurable) |
f. Performance Metrics
Field | Description | Mandatory | Default |
---|---|---|---|
Enable Performance Metrics | When the Enable Performance Metrics toggle is turned on, the administrators can generate metrics logs for DPG. | No | By default, the toggle is on. |
Network Configuration
Note
This step is only required for DPG 1.2 and lower versions, skip this for DPG 1.3 and higher versions.
Ensure the NAE interface with TLS, verify client cert, user name taken from client cert, auth request is optional mode is created on the CipherTrust Manager. Refer to CipherTrust Manager Interfaces for detailed instructions.
Field | Description | Mandatory | Default |
---|---|---|---|
Select Interface | Select interface name form the available list. The firewall rules must allow communication for the selected NAE Interface port. Selecting or unselecting the NAE Interface port will reset the Common Name in CSR parameters. | No | No default |
Server Configuration
These parameters are required to configure server settings such as CA, CSR, and Connection configurations.
a. Group Permissions
Field | Description | Mandatory | Default |
---|---|---|---|
Client Groups | Clients associated with the application will get permissions based on the selected groups. | Optional | No Default |
b. CA Parameter
Field | Description | Mandatory | Default |
---|---|---|---|
Local CA | Select the CA from the available options. The selected CA will issue and sign the digital certificate. It can be either a root CA or a domain CA. For instructions on using domain CA, see Using domain CA as trusted entity. | No | CipherTrust Root CA |
c. CSR Parameters
Field | Description | Mandatory | Default |
---|---|---|---|
Common Name | This is the DPG user who will interact with CM. — For DPG 1.2 and lower versions, NAE-XML interface is used. — For DPG 1.3 and higher versions, REST interface is used. | Yes | No default |
City | Name of the city. | Yes | No default |
Country | Name of the country. | Yes | No default |
State | Name of the state. | Yes | No default |
Organization Name | Organization name. | Yes | No default |
Organization Unit | Organization unit. | Yes | No default |
Valid email id. | Yes | No default | |
Certificate Duration | Validity period of a client certificate. | Yes | 730 days |
Certificate auto renewal | Turn on the Certificate auto renewal toggle to automatically renew the CA certificate before it expires in the user environment. The process of certificate auto renewal is explained here. | No | By default, the toggle is off. |
- Click Next to go to the Policy page.
Note
Before moving to the next step, we recommend you read about DPG policies. For a detailed overview, expand the DPG Policies section below.
DPG Policies
DPG policy is a set of rules that determines when and how to protect/reveal sensitive data moving through DPG. DPG can protect/reveal any data that is transferred through HTTP with REST architecture in the JSON format. The sensitive data is specified at JSON path or in URL parameters. DPG allows you to configure on which data cryptographic operations is to be performed in HTTP methods. Protection of the sensitive data is governed by the Protection Policy associated with the DPG policy. At the time of reveal operation, DPG reads the access policy and displays the data according to the rules configured for the user set. The DPG policy is created and managed from the CipherTrust Manager UI or API playground.
DPG policy specifications
DPG allows association of different protection policies based on sensitive data. Each sensitive data to be protected/revealed will have their own protection policy.
DPG allows you to reveal the output in different formats for different user sets.
A user can choose the data to be protected or revealed in any combination of URL path, the REST methods, and their request/response.
Each application has its own DPG policy.
DPG can be configured to perform cryptographic operations for these methods.
PUT
POST
GET
PATCH
DELETE
Create and Associate Policy
On the DPG Policy page, click Add Endpoint.
On the Create Endpoint screen, perform the following steps:
Enter the API URL. This is the URL of the application for which the DPG will protect the data.
Select Method from the drop-down list. Supported methods are:
POST
GET
PUT
PATCH
DELETE
Note
You must configure JSON path/URL parameters separately for each method.
Click Add Token to configure JSON path/URL. For same method, you can configure Request and Response simultaneously.
On the Create Token in Request screen, enter/select the following details.
Field Description Name Specify the complete JSON path/URL parameters to be protected/revealed. Location Location of the data to be protected/revealed.
Possible options are:
— JSON: If data to be protected is in JSON body.
— URL: If data to be protected is in URL parameters.Operation Cryptographic operation to be performed.
Possible options
— Protect
— RevealProtection Policy Select the protection policy form the drop-down list. If protection policy doesn't exist, click Add Protection Policy and click Select. Refer to Managing Protection Polices for details. External Version Header Specify the name of the parameter that will store the version header details (type, protection policy version, and key version). This parameter appears on the UI only when the selected protection policy uses external version header. Access Policy This parameter appears on the UI if operation type is Reveal. Select the access policy from the drop-down list. If access policy doesn't exist, click Add Access Policy and click Select. Refer to Managing Access Policies for details. If the JSON body has an array of objects, specify the sensitive tokens in the format shown in the below example:
{ "Name": "John", "CreditCard":[ { "CCNumber": "1234-5678-9012-3456", "CVV": "123", "Expiry": "12/03" } ], "Amount" : "250" }
In this example, CreditCard is the array of objects (CCNumber, CVV, Expiry). To protect/reveal CCNumber, specify the token as
CreditCard.[*].CCNumber
in the request/response of the DPG policy. Similarly, to protect/reveal CVV, use the following format:CreditCard.[*].CVV
.Note
If a set of data is already protected with a protection policy, ensure to reveal the data with the same protection policy.
Click Create. The newly created policy is listed on the DPG Policy page.
Now, to configure JSON path/URL parameters for other methods, click Add Endpoint and repeat steps a to g else, click Next to go to the Confirmation screen.
The below diagrams show that different methods require separate endpoint configurations.
Confirmation
On the Add Application page, verify the application details. The Confirmation screen displays general information, settings, and DPG policy.
If you want to modify any detail, click Edit and update the details.
Click Add. A message stating, Application created successfully is displayed on the screen. At this step, a Registration Token is generated. The clients will use this token to get registered on the CipherTrust Manager.
Click Close to exit the setup. The newly defined application is added to the list of Applications.
After defining the application, register your DPG client with the CipherTrust Manager using the generated registration token, as detailed in its Quick Start.
Viewing Application
The Applications page shows the unified view for all the applications defined on the CipherTrust Manager. Refer to Single Pane of Glass for details.
Viewing details of application
Click application name to view its details. The detailed view shows:
Clients tab: provides insight into details of clients registered within an application.
Settings tab: provides information about the parameters that were used to define application for a client.
Policy Tab: Shows the policy associated with the client.
Clients tab
The Clients tab displays the list of clients registered with an applications, their status, version, name, and so on. It provides the count of:
The Total Active clients.
The number of clients in Error state.
The number of clients in Warning state.
The number of clients in Healthy state.
The number of Revoked clients.
Click each tab to filter the clients by their status.
Client status
The CipherTrust Manager updates status of all the DPG clients after every 5 minute based on the number of missed heartbeats. A client can be in one of the following states:
State | Description |
---|---|
Healthy | A healthy client sends heartbeat on regular heartbeat_interval . |
Errors | Client notifies the CipherTrust Manager that it is in error state and it can't process any request. |
Warnings | The CipherTrust Manager moves a client to warning whenever the client skips sending heartbeat based on the defined heartbeat_interval . The client can continue performing the cryptographic operations. |
Revoked | CipherTrust Manager will revoke a client if the number of missed heartbeat count = Heartbeat Timeout Count *heartbeat_interval . The client can no longer perform any cryptographic operations. |
The Clients tab also shows the following details:
Column | Description |
---|---|
Status | Health status of the clients. Click here for details. |
Name | Name of the client. |
Client Version | The version of the client protecting the application. |
Last Connection | Date and time when the CipherTrust Manager received the last heartbeat from the client. |
Creation Date | Date and time when the client was registered on the CipherTrust Manager. |
Settings tab
The Settings tab shows the configuration details for client. Refer to Managing DPG Applications.
Policy tab
The policy tab shows the DPG policies associated with the application. ()
On the detailed view of applications page, you can also:
Refresh clients
Remove revoked clients
Modifying Application
To modify settings and of an application:
Open Application Data Protection.
In the left pane, click Applications. The list of applications is displayed on the screen.
Click the name of the application that you want to modify. The <Application-name> screen shows the clients, settings, and policy associated with the application.
Click the Settings tab. You can modify the client, server, and network configurations.
Click the Policy tab. You can add/delete endpoints.
Click Update. A message Application updated successfully is displayed.
Deleting Application
Open Application Data Protection.
In the left pane, click Applications. The list of applications is displayed on the screen.
Click the overflow icon (
) corresponding to the application that you want to delete.
Click Delete. A dialog box appears prompting to confirm the action.
Click Delete. A message, <Application_name> has been deleted appears on screen.
Warning
Deleting an application also deletes all the associated clients. This action may impact the operations performed by the clients. So, before deleting an application, ensure all the mapped clients are not in use.