Managing CAKM for Oracle TDE 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.

In this article, you will learn how to:

• Define application

• View application

• Edit application

• Delete application

Defining Application

1. Log on to the CipherTrust Manager GUI as administrator.

2. Open Application Data Protection.

3. In the left pane, click Applications. The list of applications is displayed on the screen.

4. On the Applications page, click Add Application. The Add Application wizard is displayed.

Follow step-by-step instructions to define an application for your CAKM For Oracle TDE client.

Add General Info

1. On the General Info screen of the Add Application Wizard, specify a unique Name for the application.

2. Select the Connector Type as CAKM For Oracle TDE from the drop-down list.

3. Click Next to go to the Settings screen.

Configure Parameters

On the Settings screen of the Add Application Wizard, configure the following parameters:

• Client configuration

• Server configuration

Client Configuration

These parameters are required to initialize CAKM For Oracle TDE clients.

a. Logging

Field	Description	Mandatory	Default
Log Level	The level of logging to determine verbosity of clients logs. Options — ERROR — WARN — INFO — DEBUG	Yes	WARN
Log Rotation	Determines the frequency of log rotation. Possible values are: — Daily: Rotates the log file everyday. — Size: Rotates the log file after it reaches the size defined by Log Size Limit.	No	Daily
Log File Path	Complete path along with the file name for storing logs. The path must be absolute and the file name should contain .log extension. The format of log file should be: <absolute_path>/<file_name>.log	No	Logs are saved to the default path.

b. Local Encryption

Field	Description	Mandatory	Default
Key Cache Expiry	Determines the minimum amount of time a key can be cached.	Yes	43200 seconds

c. Connection Configuration

Field	Description	Mandatory	Default
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. The minimum permitted heartbeat interval is 5 seconds; however, for improved efficiency, it is recommended to set it to a value greater than 30 seconds.	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 -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.

d. Certificate Renewal

Field	Description	Mandatory	Default
Certificate Auto Renewal	Turn on the Certificate Auto Renewal toggle to automatically renew the client certificate before it expires in the user environment. The process of certificate auto renewal is explained here.	No	By default, the toggle is off.

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.	No	Application Data Protection Clients

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	Select the user.	No	No default
City	Name of the city.	No	No default
Country	Name of the country.	No	No default
State	Name of the state.	No	No default
Organization Name	Organization name.	No	No default
Organization Unit	Organization unit.	No	No default
Email	Valid email id.	No	No default
Certificate Duration	Validity period of a client certificate.	No	730 days

1. Click Next to go to Confirmation page.

Confirmation

1. On the Confirmation screen, verify the application details. This screen displays general information and settings .

2. If you want to modify any detail, click Edit and update the details.

3. Click Save. A message stating Application is successfully created is displayed on the screen. At this step, a Registration Token is returned. The clients will use this token to get registered on the CipherTrust Manager.

4. Click Close to exit the wizard. The newly defined application is added to the list of Applications.

After defining the application, register your CAKM for Oracle TDE client using the generated registration token, as detailed in Quick Start document of CAKM for Oracle TDE x.x.x or higher.

After understanding the steps for defining an application, the next step is to define an application and generate a registration token for your CDB. A CDB can contain zero or multiple PDBs. Based on the selected mode, users may open the HSM wallet using either the same registration token as the CDB or separate tokens for each PDB. See Use Cases.

Use Cases

Scenario 1: CDB with Data (No PDBs)

In this scenario, the user has a CDB containing data, primarily in one region, and no PDBs are present.

Oracle Database Instance is SID.

Steps

1. Define an application for your CDB. See Defining Application.

When defining application:

• The application name must contain the CDB name present in the Oracle database.

• When configuring server settings, in the Group Permissions field, select the group(s) which contains all the keys associated with your CDB.

• Pass the registration token in the Oracle query as shown below.

      ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<Registration token>";
  

  Replace <Registration token> with the actual value.

Scenario 2: CDB with Multiple PDBs in United Mode

In this scenario, the CDB has four united PDBs namely PDB1, PDB2, PDB3, and PDB4. The united mode PDBs use a shared keystore in the CDB root.

Oracle Database Instance is SID.

Steps

1. Define an application for your CDB. See Defining Application.

When defining application:

• The application name must contain the CDB name present in the Oracle database.

• When configuring server settings, in the Group Permissions field, select the group(s) that contain all the keys associated with your CDB.

• Pass the registration token in the Oracle query as shown below.

      ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<Registration token>";
  

  Replace <Registration token> with the actual value.

For PDBs operating in the united mode, there’s no need to create a separate registration token, as they share the same wallet and key permissions as the CDB. As a result, all queries from united mode PDBs will use the CDB’s registration token.

Scenario 3: CDB with Multiple PDBs in Isolated Mode

In this scenario, the CDB has four isolated mode PDBs namely PDB1, PDB2, PDB3, and PDB4. The isolated mode allows a PDB to have its own independent keystore, separate from the CDB root's.

Oracle Database Instance is SID.

Steps

1. Define an application for your CDB. See Defining Application.

When defining application:

• The application name must contain the CDB name present in the Oracle database.

• When configuring server settings, in the Group Permissions field, select the group(s) that contain all the keys associated with your CDB.

• Pass the registration token in the Oracle query as shown below.

      ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<Registration token>";
  

  Replace <Registration token> with the actual value.

Isolated mode PDBs can use either same wallet credentials or individual wallet credentials.

• When using the same wallet credentials, use the CDB’s registration token.

• When using individual wallet credentials, distinct registration tokens must be created for each PDB. In this scenario, four different registration tokens should be generated.

• Define an application for your PDB. See Defining Application.

When defining application:

• The application name must contain the PDB name present in the Oracle database.

• When configuring server settings, in the Group Permissions field, select the group(s) that contain all the keys associated with your PDB.

• Pass the registration token in the Oracle query as shown below.

      ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<Registration token>";
  

  Replace <Registration token> with the actual value.

Scenario 4: CDB with Multiple PDBs in Mixed Mode

In this scenario, the CDB has four mixed mode PDBs namely PDB1, PDB2, PDB3, and PDB4, where:

• PDB1 and PDB2 are in united mode

• PDB3 and PDB4 are in isolated mode

Oracle Database Instance is SID.

Steps

Define an application for your CDB. See Defining Application.

1. When defining application:

2. The application name must contain the CDB name present in the Oracle database.

3. When configuring server settings, in the Group Permissions field, select the group(s) that contain all the keys associated with your CDB.

4. Pass the registration token in the Oracle query as shown below.

       ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<Registration token>";
   

   Replace <Registration token> with the actual value.

   For PDB1 and PDB2, there’s no need to create a separate registration token, as they share the same wallet and key permissions as the CDB. As a result, all queries from the united mode PDBs will use the CDB’s registration token.

   For PDB3 and PDB4, the database user can select either individual wallet credentials or same wallet credentials.

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.

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

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.

On the detailed view of applications page, you can also:

• Refresh clients

• Remove revoked clients

Modifying Application

To modify settings and of an application:

1. Open Application Data Protection.

2. In the left pane, click Applications. The list of applications is displayed on the screen.

3. Click the name of the application that you want to modify. The <Application-name> screen shows the clients and settings associated with the application.

4. Click the Settings tab. You can modify the client and server configurations.

5. Click Update. A message Application updated successfully is displayed.

Deleting Application

1. Open Application Data Protection.

2. In the left pane, click Applications. The list of applications is displayed on the screen.

3. Click the overflow icon () corresponding to the application that you want to delete.

4. Click Delete. A dialog box appears prompting to confirm the action.

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