9 Managing Oracle Key Vault Endpoints

Oracle Key Vault endpoints are computer systems like database or application servers, where keys and credentials are used to access data.

• Overview of Managing Endpoints
  You can manage endpoints in both standalone environments and multi-master clusters in much the same way, except that multi-master clusters have more restrictions.
• Managing Endpoints
  You can enroll, reenroll, suspend, and delete endpoints.
• Default Wallets and Endpoints
  You can use a default wallet, which is a type of virtual wallet, with an endpoint.
• Managing Endpoint Access to a Virtual Wallet
  You can grant an endpoint access to a virtual wallet, and revoke or modify access when it is no longer necessary.
• Managing Endpoint Groups
  An endpoint group is a named group of endpoints that share a common set of wallets.
• Managing Endpoint Details
  Endpoint details refers to endpoint name, type, description, platform, and email, and adding the endpoint to a group, or upgrading the endpoint software.
• Upgrading Endpoints
  You can perform endpoint upgrades from either the Oracle Key Vault management console login page or from the endpoint.

9.1 Overview of Managing Endpoints

You can manage endpoints in both standalone environments and multi-master clusters in much the same way, except that multi-master clusters have more restrictions.

• About Managing Endpoints
  You must register and enroll an endpoint to communicate with Oracle Key Vault.
• How a Multi-Master Cluster Affects Endpoints
  There are restrictions on endpoints in a multi-master cluster.

9.1.1 About Managing Endpoints

You must register and enroll an endpoint to communicate with Oracle Key Vault.

Afterward, keys in the endpoint can be uploaded to Oracle Key Vault and be shared with other endpoints and then downloaded from these endpoints so that users can access their data. Only a user with the System Administrator role can add an endpoint to Oracle Key Vault. After the endpoint is added, the endpoint administrator can enroll the endpoint by downloading and installing the endpoint software at the endpoint. The endpoint can then use the utilities packaged with the endpoint software to upload and download security objects to and from Oracle Key Vault.

All users can create virtual wallets but only a user with Key Administrator role can grant endpoints access to security objects contained in virtual wallets. The Key Administrator can also create endpoint groups to enable shared access to virtual wallets. When you grant an endpoint group access to a virtual wallet, all the member endpoints will have access to the virtual wallet. For example, you can grant all the nodes in an Oracle Real Application Clusters (Oracle RAC) database access to a virtual wallet by putting them in an endpoint group. This saves you the step of granting each node access to the virtual wallet.

If you have a large deployment, then install at least four Oracle Key Vault servers, and when you enroll the endpoints, balance them across these four servers to ensure high availability. For example, if a data center has 1000 database endpoints to register, and you have Oracle Key Vault four servers to accommodate them, then enroll 250 endpoints with each of the four servers.

When you name an endpoint, remember that an Oracle Key Vault user name cannot be the same as an Oracle Key Vault endpoint name.

The two administrative roles as they pertain to endpoints are as follows:

• A user with the System Administrator role:
  • Manages the endpoint metadata such as the name, type, platform, description, and email notifications
  • Manages the endpoint lifecycle, which consists of enrolling, suspending, reenrolling, and deleting endpoints
• A user with the Key Administrator role:
  • Manages the endpoint group lifecycle, which consists of creating, modifying, and deleting endpoint groups
  • Manages the lifecycle of security objects, which consists of creating, modifying and deleting security objects

9.1.2 How a Multi-Master Cluster Affects Endpoints

There are restrictions on endpoints in a multi-master cluster.

• An endpoint can only be enrolled from the same node where it was most recently created or re-enrolled.
• An endpoint gets its initial and subsequent endpoint node scan list update based on the cluster subgroup to which the creator node belongs. Oracle Key Vault creates the endpoint node scan list when you first add nodes from the same cluster subgroup as the creator node. Oracle Key Vault adds the other nodes later.
• You cannot assign a default wallet to an endpoint if one or both of them (wallet and endpoint) is in the PENDING state and if the assignment is attempted from a non-creator node. After both the endpoint and wallet are in the ACTIVE state, this restriction ends.

9.2 Managing Endpoints

You can enroll, reenroll, suspend, and delete endpoints.

• Types of Endpoint Enrollment
  The first step in enrolling an endpoint is to add the endpoint to Oracle Key Vault.
• Endpoint Enrollment in a Multi-Master Cluster
  Endpoints of a cluster are the client systems of the multi-master cluster.
• Adding an Endpoint as an Oracle Key Vault System Administrator
  A user who has been granted the System Administrator role can add an endpoint by using the Endpoints tab.
• Adding Endpoints Using Self-Enrollment
  The self-enrollment process immediately sends the endpoint to the Enrolled status without the intermediate Registered status.
• Deleting, Suspending, or Reenrolling Endpoints
  When endpoints no longer use Oracle Key Vault to store security objects, you can delete them, and then re-enroll when they are needed.

9.2.1 Types of Endpoint Enrollment

The first step in enrolling an endpoint is to add the endpoint to Oracle Key Vault.

There are two methods for adding, also known as registering, an endpoint:

• Initiated by an administrator

  An Oracle Key Vault user who has the System Administrator role initiates the enrollment from the Oracle Key Vault side by adding the endpoint to Oracle Key Vault. When the endpoint is added, a one-time enrollment token is generated. This token can be communicated to the endpoint administrator in two ways:

  • Directly from Oracle Key Vault by email. To use email notification you must configure SMTP in email settings.
  • Out-of-band method, such as email or telephone.

  The endpoint administrator uses the enrollment token to download the endpoint software and complete the enrollment process on the endpoint side. In a multi-master cluster, the same node that is used to add the endpoint must be used to enroll the endpoint.

  After the enrollment token is used to enroll an endpoint, it cannot be used again for another enrollment. If you must reenroll an endpoint, then the reenrollment process will generate a new one-time enrollment token for this purpose.

• Self-enrolled

  Endpoints may enroll themselves during specific times without human administrative intervention. Endpoint self-enrollment is useful when the endpoints do not share security objects, and use Oracle Key Vault primarily to store and restore their own security objects. Another use for endpoint self-enrollment is testing.

  A self-enrolled endpoint is created with a generic endpoint name in this format: ENDPT_001. In a cluster, a self-enrolled endpoint is created with a generic endpoint name in this format: ENDPT_xx_001, where xx is a 2-digit node identifier or node number. Initially, a self-enrolled endpoint has access only to the security objects that it uploads or creates. It does not have access to any virtual wallets. You can later grant the endpoint access to virtual wallets after verifying its identity.

  Endpoint self-enrollment is disabled by default, and must be enabled by a user with the System Administrator role. A best practice is to enable self-enrollment for short periods, when you expect endpoints to self enroll, and then disable it when the self-enrollment period ends.

9.2.2 Endpoint Enrollment in a Multi-Master Cluster

Endpoints of a cluster are the client systems of the multi-master cluster.

Endpoint enrollment is divided into two steps. First you add the endpoint and then you enroll it.

The Oracle Key Vault server that becomes the initial node can have endpoints already enrolled, especially if it was upgraded from a previous release. These existing endpoints initialize, or seed, the cluster. During induction, the endpoints enrolled in the cluster are replicated to a newly added node. During induction, Oracle Key Vault removes endpoints that were previously enrolled in all candidate nodes added to the cluster.

Endpoints can only be enrolled on a read-write node.

After you enroll the endpoint, the new endpoint will have a cluster-wide presence. You can add endpoints of the Oracle Key Vault multi-master cluster to any read-write node.

Note:

An endpoint must be enrolled on the same node where it was most recently added or re-enrolled.

New endpoints added concurrently to the multi-master cluster on different nodes could have name conflicts. Oracle Key Vault automatically resolves the endpoint name conflicts, and then displays the conflicts in a Conflicts Resolution page, similar to the following figure. From here, a system administrator can choose to rename them.

Description of the illustration endpoint-name-conflicts-screenshot.png

9.2.3 Adding an Endpoint as an Oracle Key Vault System Administrator

A user who has been granted the System Administrator role can add an endpoint by using the Endpoints tab.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
2. Click the Endpoints tab.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.

   
   Description of the illustration endpoints-endpoints.png

   The Endpoints page displays the list of registered and enrolled endpoints with the following endpoint details: name, type, description, platform, status, enrollment token, and alert. The endpoint status can be either Registered or Enrolled:

   • Registered Status: The endpoint has been added and the one-time enrollment token has been generated. This token will be displayed in the corresponding Enrollment Token column.
   • Enrolled Status: The one-time enrollment token has been used to download the endpoint software. The Enrollment Token column displays a dash (-) to indicate that the enrollment token has been used.
   • Created By: The user who created the endpoint.
   • Creator Node: The node on which the endpoint was created.
   • Name Status: The state of the endpoint. The state will be either ACTIVE or PENDING.
3. Click Add on the Endpoints page.
   The Register Endpoint page appears. The Make Unique checkbox only appears in multi-master clusters mode.

   
   Description of the illustration register-endpoint.png

4. In the Endpoint Name field, enter a name for the endpoint.
   The name can have letters, numbers, and underscores. The endpoint name is not case-sensitive. For example, a name entered as app_server1 will show up APP_SERVER1 in the endpoints table. The endpoint will be identified by this name throughout. The maximum length is 30 characters.
5. If you are using a multi-master cluster, then choose whether to select the Make Unique checkbox.

   Make Unique helps to control naming conflicts with names across the multi-master cluster environment. Endpoints that were created before an Oracle Key Vault conversion to a cluster node are not affected by naming conflicts.

   • If you select Make Unique, then the endpoint will be active immediately and users can use this endpoint.
   • If you do not select Make Unique, then the endpoint will be created in the PENDING state. Oracle Key Vault will then begin a name resolution operation and may rename the endpoint to a name that is unique across the cluster. If there is a naming collision, then the collision will be reported on the Conflicts page on any node in the cluster. The endpoint will then be renamed to a unique name. You will need to go to a read-write node of the cluster and either accept the renamed endpoint or change the endpoint name. If you change the endpoint name, then this will restart the name resolution operation and the endpoint will return to a PENDING state. An endpoint in the PENDING state cannot be used to perform most operations.
6. From the Type drop-down list, select the type of endpoint.
   Supported types are Oracle Database, Oracle Database Cloud Service, Oracle (non-database), Oracle ACFS, MySQL Database, and Other. An example of Other is a third-party KMIP endpoint. If you are using Oracle Advanced Security Transparent Data Encryption (TDE) and want to use Oracle Key Vault to manage a TDE master encryption key or wallet, then you must set Type to Oracle Database.
7. Complete the following endpoint information:
   • Platform: Supported platform choices are Linux, Solaris SPARC, Solaris x64, AIX, AIX 5.3, HPUX, and Windows.
   • Description: Optionally, enter a useful identifying description such as the host name, IP address, function, or location of the endpoint.
   • Administrator Email: Optionally, enter the email address of the endpoint administrator to have the enrollment token and other endpoint-related alerts sent directly from Oracle Key Vault. You must have SMPT configured to use the email notificaiton feature.
8. Click Register.
   The Endpoints page appears listing the new endpoint with a status of Registered. The Enrollment Token column displays the one-time enrollment token.

   
   Description of the illustration endpoint-registered-status.png

9. Click the Endpoint Name to see details for the endpoint.
   The Endpoint Details page appears.

   
   Description of the illustration screenshot_endpoint_details.png

   The Send Enrollment Token button on the Endpoint Details page only appears for an endpoint whose Status is Registered.

   There are two ways to send the one-time enrollment token to the endpoint administrator:

   • If you did configure SMTP and entered the email address, you can have Oracle Key Vault send the enrollment token directly to the endpoint administrator, shown in the next step, where you click the Send Enrollment Token button.
   • If you did not configure SMTP or enter the email address, then you must use an out-of-band method to send the enrollment token to the endpoint administrator.

   The endpoint must be enrolled and the endpoint jar file must be downloaded from the node on which the endpoint was most recently created or reenrolled.

10. Click Send Enrollment Token.
    At this stage, the endpoint’s administrator can complete the enrollment process for the endpoint. When the enrollment token is used to download and install the endpoint software on the endpoint side, the endpoint status changes from Registered to Enrolled.

9.2.4 Adding Endpoints Using Self-Enrollment

The self-enrollment process immediately sends the endpoint to the Enrolled status without the intermediate Registered status.

• About Adding Endpoints Using Self-Enrollment
  Oracle Key Vault associates a self-enrolled attribute with all endpoints that are enrolled through endpoint self-enrollment.
• Adding an Endpoint Using Self-Enrollment
  You can configure the self-enrollment process for endpoints from the Oracle Key Vault management console.

9.2.4.1 About Adding Endpoints Using Self-Enrollment

Oracle Key Vault associates a self-enrolled attribute with all endpoints that are enrolled through endpoint self-enrollment.

Self-enrolled endpoints go directly to Enrolled status without the intermediate Registered status when they download the endpoint software. You can recognize self-enrolled endpoints by their system generated names in the format ENDPT_001. In a multi-master cluster, system generated endpoint names are in the format ENDPT_node_id_sequential_number, where node_id is a value such as 01 or 02. For example, ENDPT_01_001 can be the generated name of an endpoint.

Endpoint self-enrollment is disabled by default and must be enabled by a user who has the System Administrator role.

A best practice is to enable endpoint self-enrollment for limited periods when you expect endpoints to enroll. After the expected endpoints have been enrolled, you should disable endpoint self-enrollment.

9.2.4.2 Adding an Endpoint Using Self-Enrollment

You can configure the self-enrollment process for endpoints from the Oracle Key Vault management console.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
2. Select the Endpoints tab, and then Settings from the left side bar.
   The Endpoint Settings page appears.

   
   
   Description of the illustration endpoint_settings.png
   

3. Check the box to the right of Allow Endpoint Self-Enrollment.
4. Click Save.

   
   Description of the illustration endpoints-endpoints.png

9.2.5 Deleting, Suspending, or Reenrolling Endpoints

When endpoints no longer use Oracle Key Vault to store security objects, you can delete them, and then re-enroll when they are needed.

• About Deleting Endpoints
  Deleting an endpoint removes it permanently from Oracle Key Vault.
• Deleting One or More Endpoints
  The Endpoints page enables you to delete a group of endpoints from Oracle Key Vault at one time.
• Deleting One Endpoint (Alternative Method)
  The Endpoint Details page provides a consolidated view for the selected endpoint including a mechanism to delete the endpoint from Oracle Key Vault.
• Suspending an Endpoint
  You can suspend an endpoint temporarily for security reasons, and then reinstate the endpoint once the threat has passed.
• Reenrolling an Endpoint
  When you reenroll an endpoint, the enrollment process automatically upgrades the endpoint software.

9.2.5.1 About Deleting Endpoints

Deleting an endpoint removes it permanently from Oracle Key Vault.

However, security objects that were previously created or uploaded by that endpoint will remain in Oracle Key Vault. Similarly, security objects that are associated with that endpoint also remain. To permanently delete or reassign these security objects, you must be a user with the Key Administrator role or authorized to merge these objects by managing wallet privileges. The endpoint software previously downloaded at the endpoint also remains on the endpoint until the endpoint administrator removes it.

You cannot delete an endpoint that is in the PENDING state unless you are the user who created it. You must delete it on the node on which it was created.

9.2.5.2 Deleting One or More Endpoints

The Endpoints page enables you to delete a group of endpoints from Oracle Key Vault at one time.

You can also delete a single endpoint from this page.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
2. Select the Endpoints tab to get to the Endpoints page.
   The Endpoints page lists all the endpoints currently registered or enrolled.
3. Select the check boxes to the left of the endpoints you want to delete.
4. Click Delete.
5. Click OK in the confirmation dialog box that appears.

9.2.5.3 Deleting One Endpoint (Alternative Method)

The Endpoint Details page provides a consolidated view for the selected endpoint including a mechanism to delete the endpoint from Oracle Key Vault.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
2. Select the Endpoints tab to get to the Endpoints page.
   The Endpoints page lists all the endpoints currently registered or enrolled.
3. Click the endpoint name you want to delete.
   The Endpoint Details page appears.
4. Click Delete.
5. Click OK to confirm.

9.2.5.4 Suspending an Endpoint

You can suspend an endpoint temporarily for security reasons, and then reinstate the endpoint once the threat has passed.

When you suspend an endpoint, its status will change from Enrolled to Suspended. You cannot suspend an endpoint that is in the PENDING state unless you are the user who created it.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
2. Select the Endpoints tab to get to the Endpoints page.
   The Endpoints page lists all the endpoints currently registered or enrolled.
3. Click on the endpoint name you want to suspend. The Endpoint Details page appears.
4. Click Suspend.
5. In the confirmation window, click OK.
   When you suspend an endpoint, its Status on the Endpoints page will be Suspended.
6. To enable the endpoint, perform Steps 1-4.
   From the Endpoint Details pane click Enable. The endpoint Status on the Endpoints page will now read Enrolled.

The following rules apply to suspending an endpoint in a multi-master cluster:

• For regular endpoints, the endpoint will continue to operate until all suspend operation requests have reached all nodes in the cluster.
• You can suspend the endpoint on any node.
• For cloud-based endpoints, the endpoint will continue to operate until the suspend operation has reached all nodes from where the reverse SSH tunnel is established.
• You can potentially suspend the endpoint on any node from the cloud-based endpoint from where the reverse SSH tunnel is established.

9.2.5.5 Reenrolling an Endpoint

When you reenroll an endpoint, the enrollment process automatically upgrades the endpoint software.

You must also reenroll an endpoint to accommodate changes such as pairing a primary Oracle Key Vault server with a new secondary server in a primary-standby configuration. The action of reenrolling an endpoint will immediately disallow any connections from the endpoint's old deployment. If you are reenrolling an endpoint, Oracle recommends that you immediately download okvclient.jar and deploy it in a directory that is separate from the existing deployment. When you deploy the software, use the -o option to overwrite the symbolic link pointing to the old okvclient.ora. You cannot reenroll an endpoint that is in the PENDING state unless you are the user who created it.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
2. Select the Endpoints tab to access the Endpoints page.
   The Endpoints page lists all of the endpoints in Key Vault.
3. Check the boxes to the left of the endpoints that you want to reenroll.
4. Click Reenroll.

   After you deploy the okvclient.jar file, the The endpoint software for Oracle Key Vault installed successfully message should appear. If instead the The endpoint software for Oracle Key Vault upgraded successfully message appears, then the reenrollment was performed in the old deployment directory, and as a result, the endpoint software was upgraded but not successfully reenrolled.

   You can overwrite the symbolic link reference that points to okvclient.ora in the new directory by using the okvclient.jar option -o.

   A new enrollment token will be generated for each reenrolled endpoint and appear in the corresponding Enrollment Token column. You can use this one-time token to reenroll the endpoint. You must download the endpoint jar file from the same node on which the endpoint was reenrolled.

9.3 Default Wallets and Endpoints

You can use a default wallet, which is a type of virtual wallet, with an endpoint.

• Associating a Default Wallet with an Endpoint
  A default wallet is a type of virtual wallet to which security objects are uploaded when a wallet is not explicitly specified.
• Setting the Default Wallet for an Endpoint
  Setting a default wallet for an endpoint automatically uploads the endpoint's security objects to the wallet if another wallet is not explicitly specified.

9.3.1 Associating a Default Wallet with an Endpoint

A default wallet is a type of virtual wallet to which security objects are uploaded when a wallet is not explicitly specified.

Default wallets are useful for sharing with other endpoints such as nodes in an Oracle Real Application Clusters (Oracle RAC), or primary and standby nodes in Oracle Data Guard by having all endpoints use the same default wallet.

If you want to use the default wallet, then you must set after you register the endpoint before you enroll it. If you decide to use a default wallet after enrollment, then you must remove the default wallet and subsequently reenroll the endpoint.

An enrollment status of registered means that the endpoint has been added to Oracle Key Vault, but the endpoint software has not yet been downloaded and installed. When the status is registered, then you must associate the default wallet with the endpoint.

The endpoint's enrollment status becomes enrolled when you download and install the endpoint software to the endpoint. If you set the default wallet after you enroll the endpoint, then you must re-enroll the endpoint to ensure that all future security objects created by the endpoint are automatically associated with that wallet.

In a multi-master cluster, you can only assign the default wallet on the same node where the endpoint and wallet were created when either are still in the PENDING state. After both are in the ACTIVE state, then there are no restrictions. After the default wallet is assigned and the endpoint is enrolled, the default wallet can be accessed from any node, as long as both are in the ACTIVE state and the information has been replicated to that node.

9.3.2 Setting the Default Wallet for an Endpoint

Setting a default wallet for an endpoint automatically uploads the endpoint's security objects to the wallet if another wallet is not explicitly specified.

Oracle requires that you set the default wallet right after registering the endpoint, and before downloading the endpoint software.

1. Log in to the Oracle Key Vault management console as an administrator who has the Key Administrator role.
2. Select the Endpoints tab, and then click on the endpoint name.
   The Endpoint Details page appears.
3. In the Default Wallet pane, select Choose Wallet.

   
   Description of the illustration default-wallet-screenshot.png

   The Add Default Wallet page appears displaying a list of available wallets.

   
   Description of the illustration add_default_wlt.png

4. Select a wallet from the list to be the default wallet by clicking the option to the left of the wallet, and then click Select.
   The selected wallet name appears in the Default Wallet pane.

   
   Description of the illustration post_def_wlt_select.png

5. Click Save.

9.4 Managing Endpoint Access to a Virtual Wallet

You can grant an endpoint access to a virtual wallet, and revoke or modify access when it is no longer necessary.

• Granting an Endpoint Access to a Virtual Wallet
  An endpoint must have Read and Modify and Manage Wallet privileges on the wallet before security objects can be uploaded or downloaded.
• Revoking Endpoint Access to a Virtual Wallet
  You can revoke access to a virtual wallet for an endpoint by using the Endpoints tab.
• Viewing Wallet Items Accessed by Endpoints
  The term wallet items refers to the security objects to which the endpoint has access.

9.4.1 Granting an Endpoint Access to a Virtual Wallet

An endpoint must have Read and Modify and Manage Wallet privileges on the wallet before security objects can be uploaded or downloaded.

You can grant an endpoint access to a virtual wallet as soon as the endpoint has been added to Oracle Key Vault, when it is still in registered status.

1. Log in to the Oracle Key Vault management console as an administrator who has the Key Administrator role.
2. Select the Endpoints tab to get to the Endpoints page.
3. On the Endpoints page, select the endpoint that must have access to the virtual wallet.
   The Endpoint Details page appears with the Access to Wallets pane.

   
   Description of the illustration ep_dtls4_acc_to_wlts.png

4. In the Access to Wallets pane, which lists the wallets the endpoint already has access to, click Add to add another wallet to this list.
   The Add Access to Endpoint page appears.

   
   Description of the illustration add_wlt_acc_ep.png

5. Select a wallet from the available list of wallets shown on the Add Access to Endpoint page.
6. Select the Access Level in the Select Access Level pane.
7. Click Save.

9.4.2 Revoking Endpoint Access to a Virtual Wallet

You can revoke access to a virtual wallet for an endpoint by using the Endpoints tab.

1. Log in to the Oracle Key Vault management console as an administrator who has the Key Administrator role.
2. Select the Endpoints tab to display the Endpoints page.
3. On the Endpoints page, select the endpoint name, which will display the Endpoint Details page.
   Locate the Access to Wallets pane on this page. The Access to Wallets pane shows a list of wallets that the endpoint has access to.
4. Select the wallet that you want to revoke access to.
5. Click Remove.
6. In the confirmation dialog box, click OK.

9.4.3 Viewing Wallet Items Accessed by Endpoints

The term wallet items refers to the security objects to which the endpoint has access.

1. Log in to the Oracle Key Vault management console as an administrator who has the Key Administrator role.
2. Select the Endpoints tab to get to the Endpoints page,
3. Click the Endpoint Name to access Endpoint Details.
   The Access to Wallet Items pane in Endpoint Details lists the wallet items that the endpoint has access to.

   
   Description of the illustration ep_details_wall_items.png

9.5 Managing Endpoint Groups

An endpoint group is a named group of endpoints that share a common set of wallets.

• How a Multi-Master Cluster Affects Endpoint Groups
  You can create endpoint groups on any node and they will have a cluster-wide presence.
• Creating an Endpoint Group
  Endpoints that must share a common set of security objects stored in wallets can be grouped into an endpoint group.
• Modifying Endpoint Group Details
  You can add endpoints and access mappings to an endpoint group after creating the endpoint group.
• Granting an Endpoint Group Access to a Virtual Wallet
  You can grant an endpoint group access to a virtual wallet.
• Adding an Endpoint to an Endpoint Group
  You can add an endpoint to a named endpoint group.
• Removing an Endpoint from an Endpoint Group
  When you remove an endpoint from an endpoint group, this removes access to wallets that are associated with that endpoint group.
• Deleting Endpoint Groups
  You can delete endpoint groups if their member endpoints no longer require access to the same virtual wallets.

9.5.1 How a Multi-Master Cluster Affects Endpoint Groups

You can create endpoint groups on any node and they will have a cluster-wide presence.

You can add, update, or delete endpoint groups in any node, but in read-write mode only.

The Oracle Key Vault server that becomes the initial node can have endpoints groups already created. These endpoint groups are used to initialize, or seed, the cluster. During induction, the endpoint groups in the cluster are replicated to a newly added node. Endpoint groups previously created in all other nodes added to the cluster will be removed during induction.

New endpoint groups added concurrently to the multi-master cluster on different nodes may have name conflicts. Oracle Key Vault automatically resolves any endpoint group name conflicts. These conflicts are displayed in a Conflicts Resolution page and key administrators can choose to rename them.

9.5.2 Creating an Endpoint Group

Endpoints that must share a common set of security objects stored in wallets can be grouped into an endpoint group.

For example, endpoints using Oracle Real Application Clusters (Oracle RAC), Oracle GoldenGate, or Oracle Active Data Guard may need to share keys for access to shared data.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role.
2. Select the Endpoints tab, then Endpoint Groups.

   The Endpoint Groups page appears.

   
   Description of the illustration endpoint-groups-screenshot.png

3. Click Create Endpoint Group.

   The Create Endpoint Group page appears.

   
   Description of the illustration create-endpoint-group-screenshot.png

4. Enter the name of the new group and a brief description.
5. If you are using a multi-master cluster, then choose whether to select the Make Unique checkbox.

   Make Unique helps to control naming conflicts with names across the multi-master cluster environment. Endpoint groups that were created before an Oracle Key Vault conversion to a cluster node are not affected by naming conflicts.

   • If you select Make Unique, then the endpoint group will be active immediately and users can use this endpoint group. Clicking Make Unique also displays a list of endpoints that you can add to the endpoint group.
   • If you do not select Make Unique, then the endpoint group will be created in the PENDING state. Oracle Key Vault will then begin a name resolution operation and may rename the endpoint group to a name that is unique across the cluster. If there is a naming collision, then the collision will be reported on the Conflicts page on any node in the cluster. The endpoint group will then be renamed to a unique name. You will need to go to a read-write node of the cluster and either accept the renamed endpoint group or change the endpoint name. If you change the endpoint group name, then this will restart the name resolution operation and the endpoint group will return to a PENDING state. An endpoint group in the PENDING state cannot be used to perform most operations.
6. In the Select Members pane, which lists all the endpoints, check the boxes to the left of each endpoint to add the endpoint to the group.
7. Click Save to complete creating the endpoint group.

   The new endpoint group now appears in the Endpoint Groups page.

9.5.3 Modifying Endpoint Group Details

You can add endpoints and access mappings to an endpoint group after creating the endpoint group.

An endpoint can belong to more than one endpoint group. You cannot add one endpoint group to another endpoint group.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role.
2. Select the Endpoints tab, and then select Endpoint Groups.
   The Endpoint Groups page appears.
3. Click the edit pencil icon in the Details column corresponding to the endpoint group.
   The Endpoint Group Details page appears.

   
   Description of the illustration epg_details_pg.png

4. Modify the description as needed.

   Add or remove access to wallets or endpoint group members by clicking Add or Remove.

5. Click Save.

9.5.4 Granting an Endpoint Group Access to a Virtual Wallet

You can grant an endpoint group access to a virtual wallet.

In a multi-master cluster, you cannot grant access an endpoint group that is in the PENDING state to a virtual wallet.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role.
2. Select the Endpoints tab, and then Endpoint Groups.
3. Click the pencil icon in the Details column corresponding to the endpoint group.
   The Endpoint Group Details page appears.
4. In the Access to Wallets pane, click Add.
5. Select a virtual wallet from the available list.
6. Select an Access Level:
   • Read Only: This level grants the endpoint group read access to the virtual wallet and its items.
   • Read and Modify: This level grants the endpoint group read and write access to the virtual wallet and its items.
7. Select the Manage Wallet check box if you want endpoints to:
   • Add or remove objects from the virtual wallet.
   • Grant other endpoints or endpoint groups access to the virtual wallet.
8. Click Save.

9.5.5 Adding an Endpoint to an Endpoint Group

You can add an endpoint to a named endpoint group.

In a multi-master cluster, you cannot add an endpoint that is in the PENDING state to an endpoint group. Also, you cannot add an endpoint to an endpoint group that is in the PENDING state.

1. Log in to the Oracle Key Vault management console as an administrator who has the Key Administrator role.
2. Select the Endpoints tab.
   The Endpoints page appears.
3. Select the endpoint you want to add to a group.
   The Endpoint Details page appears.
4. Click Add in Endpoint Group Membership.

   The Add Endpoint Group Membership page appears.

   
   Description of the illustration add_ep_epg.png

   A list of endpoint groups is displayed under Endpoint Group Name.

5. Check the boxes to the left of the endpoint groups you want to add the endpoint to.
6. Click Save.

   The Endpoint Group Membership pane displays the checked endpoint group.

   
   Description of the illustration post_add_ep_epg.png

9.5.6 Removing an Endpoint from an Endpoint Group

When you remove an endpoint from an endpoint group, this removes access to wallets that are associated with that endpoint group.

The removal process completes the removal unless the endpoint has been separately granted access to the wallets, directly or through another endpoint group. In a multi-master cluster, you can remove multiple endpoints at the same time. In a multi-master cluster, you cannot remove an endpoint from an endpoint group that is in the PENDING state.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role.
2. Select the Endpoints tab, and then select Endpoint Groups.
   The Endpoint Groups page appears.
3. Click the edit pencil icon next in the Details column corresponding to the endpoint group.
   The Endpoint Group Details page appears.
4. In the Endpoint Group Members pane, check the boxes to the left of the endpoint names to be removed.
5. Click Remove.
6. In the confirmation dialog box, click OK.

9.5.7 Deleting Endpoint Groups

You can delete endpoint groups if their member endpoints no longer require access to the same virtual wallets.

This action removes the shared access of member endpoints to wallets, not the endpoints themselves. You can only delete an endpoint group that is in the PENDING state if it has no members or access to wallets.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role.
2. Select the Endpoints tab, and then select Endpoint Groups.
   This brings up the Endpoint Group page.
3. Check the boxes to the left of the endpoint group name.
4. Click Delete.
5. In the confirmation dialog box, click OK.

9.6 Managing Endpoint Details

Endpoint details refers to endpoint name, type, description, platform, and email, and adding the endpoint to a group, or upgrading the endpoint software.

• About Endpoint Details
  The Endpoint Details page provides a consolidated view of the endpoint.
• Modifying Endpoint Details
  You can modify the endpoint name, endpoint type, description, platform, and email.
• Global Endpoint Configuration Parameters
  Oracle Key Vault provides endpoint-specific configuration parameters that you can set in the Oracle Key Vault management console.

9.6.1 About Endpoint Details

The Endpoint Details page provides a consolidated view of the endpoint.

To access this page, you can select the Endpoints tab and then click the name of an endpoint. From here you can modify endpoint details and complete endpoint management tasks.

Description of the illustration screenshot-9.6.1.png

9.6.2 Modifying Endpoint Details

You can modify the endpoint name, endpoint type, description, platform, and email.

In a multi-master cluster, endpoint details can only be modified while the endpoint is in the PENDING state by the creator on the node on which it was created.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
2. Select the Endpoints tab.
   The Endpoints page is displayed.
3. Click the name of the endpoint to display the Endpoint Details page.
   
   Description of the illustration screenshot-9.6.2-step-3.png
4. Modify any of the following: endpoint name, endpoint type, description, platform, email as needed.
5. Click Save.

9.6.3 Global Endpoint Configuration Parameters

Oracle Key Vault provides endpoint-specific configuration parameters that you can set in the Oracle Key Vault management console.

• About Global Endpoint Configuration Parameters
  Users who have the System Administrator role can centrally update certain endpoint configuration parameters in the Oracle Key Vault management console. 
• Setting Global Endpoint Configuration Parameters
  You can set global endpoint configuration parameters in the Oracle Key Vault management console.

9.6.3.1 About Global Endpoint Configuration Parameters

Users who have the System Administrator role can centrally update certain endpoint configuration parameters in the Oracle Key Vault management console. 

This feature enables system administrators to set certain endpoint configuration parameters globally, that is, for all endpoints, or on a per-endpoint basis. It simplifies the process of managing multiple endpoints for system administrators.

Endpoint-specific parameters take precedence over global parameters. Global parameters take effect when endpoint-specific parameters are cleared. Oracle Key Vault uses the default system parameters if both global and endpoint specific parameters are cleared or not set from Oracle Key Vault management console.

The configuration parameter values set in the Oracle Key Vault management console are applied to endpoints dynamically. The next time that the endpoint contacts Oracle Key Vault server, the updated configuration parameters are applied to the endpoint. If there is an error, then the update is not applied. Both okvutil and the PKCS11 library can access and apply the endpoint configuration updates.

In a multi-master cluster, replication of configuration parameters depends on the replication lag. It is possible that an endpoint will not be able to get an update immediately because the node to which it is connected may not yet have received the new values of the parameters. The endpoint will refresh its configuration when it connects to a node that has new values or if it hasn't refreshed its configuration in the past hour.

9.6.3.2 Setting Global Endpoint Configuration Parameters

You can set global endpoint configuration parameters in the Oracle Key Vault management console.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
2. Select the Endpoints tab, and then Settings from the left side bar.

   The Endpoint Settings page appears.

   
   Description of the illustration endpoint_settings.png

3. In the Global Endpoint Configuration Parameters section, configure the following settings:
   • Endpoint Certificate Validity: Specify the number of days for which the current endpoint certificate is valid.
   • PKCS 11 In-Memory Cache Timeout: Specify the duration in minutes for which the master encryption key is available after it is cached in the in-memory cache.For more information about the PKCS 11 In-Memory Cache Timeout setting, see PKCS11_CACHE_TIMEOUT Parameter.

     PKCS 11 Cache Persistent Timeout: Specify the duration in minutes for which the master encryption key is available after it is cached in the persistent master encryption key cache. For more information about the PKCS 11 Cache Persistent Timeout setting, see PKCS11_PERSISTENT_CACHE_TIMEOUT Parameter.

   • PKCS 11 Persistent Cache Refresh Window: Specify the duration in minutes to extend the period of time for which the master encryption key is available after it is cached in the persistent master encryption key cache. For more information about the PKCS 11 Persistent Cache Refresh Window setting, see PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW Parameter.
   • Server Poll Timeout: Specify a timeout in seconds for a client's attempt to connect to an Oracle Key Vault server, before trying the next server in the list. The default value is 300 (milliseconds).
   • PKCS 11 Trace Directory Path: Specify a directory to save the trace files.
   • Expire PKCS11 Persistent Cache on Database Shutdown: Enables or disables the PKCS#11 persistent cache for a given endpoint database to automatically expire upon shutdown of the endpoint database. See EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN Parameter.
4. Click Save.

9.7 Upgrading Endpoints

You can perform endpoint upgrades from either the Oracle Key Vault management console login page or from the endpoint.

• Upgrading Endpoint Software from an Unenrolled Endpoint
  You can upgrade the endpoint software from the Oracle Key Vault management console login window.
• Upgrading Endpoint Software on an Enrolled Endpoint
  You should upgrade the endpoint software on an enrolled endpoint any time you upgraded to a new release of Oracle Key Vault.

9.7.1 Upgrading Endpoint Software from an Unenrolled Endpoint

You can upgrade the endpoint software from the Oracle Key Vault management console login window.

• Step 1: Prepare the Unenrolled Endpoint Environment
  Ensure that you have the correct privileges and that the endpoint has the correct configuration, such as Oracle environment variables.
• Step 2: Download the Oracle Key Vault Software onto the Unenrolled Endpoint
  To upgrade the endpoint software for an enrolled endpoint, you can download the endpoint software without having to reenroll the endpoint.
• Step 3: Install the Oracle Key Vault Software onto the Unenrolled Endpoint
  To upgrade the endpoint software for an enrolled endpoint, you can download the endpoint software without having to reenroll the endpoint.
• Step 4: Perform Post-Installation Tasks
  After you complete the installation, you can configure a TDE connection for the endpoint and verify that the endpoint software was installed correctly.

9.7.1.1 Step 1: Prepare the Unenrolled Endpoint Environment

Ensure that you have the correct privileges and that the endpoint has the correct configuration, such as Oracle environment variables.

1. Ensure that you have the necessary administrative privileges to install software on the endpoint.
2. Ensure that you have JDK 1.5 or later installed, and that the PATH environment variable includes the java executable (in the JAVA_HOME/bin directory).
   Oracle Key Vault supports JDK versions 1.5, 1.6, 7, and 8.
3. Run the shell utility oraenv or source oraenv command to set the correct environment variables on Oracle Database servers.
4. Check that the environment variables ORACLE_BASE and ORACLE_HOME are correctly set.
   If you used oraenv to set these variables, then you must verify that ORACLE_BASE points to the root directory for Oracle Databases, and that ORACLE_HOME points to a sub-directory under ORACLE_BASE where an Oracle database is installed.

9.7.1.2 Step 2: Download the Oracle Key Vault Software onto the Unenrolled Endpoint

To upgrade the endpoint software for an enrolled endpoint, you can download the endpoint software without having to reenroll the endpoint.

1. Log in to the endpoint server as the endpoint administrator.
2. Connect to the Oracle Key Vault management console.
   For example:

   https://192.0.2.254

   The login page to the Oracle Key Vault management console appears. Do not log in.

3. In the lower-right corner of the login page under Login, click Endpoint Enrollment and Software Download.

   The Enroll Endpoint & Download Software page appears.

   
   Description of the illustration ep_sw_download_page.png
4. At the top of the page, click the Download Endpoint Software Only tab.
5. In the Download Endpoint Software Only page, select the endpoint platform from the Platform drop down menu and click Download.
6. Save the file okvclient.jar to a desired location.

9.7.1.3 Step 3: Install the Oracle Key Vault Software onto the Unenrolled Endpoint

To upgrade the endpoint software for an enrolled endpoint, you can download the endpoint software without having to reenroll the endpoint.

1. Ensure that you are logged in to the endpoint server as the endpoint administrator.
2. Navigate to the directory in which you saved the okvclient.jar file.
3. Confirm that the target directory exists, and that it is empty.
4. Run the java command to install the okvclient.jar file.

   java -jar okvclient.jar -d /home/oracle/okvutil -v
   

   In this specification:

   • -d specifies the directory location for the endpoint software and configuration files, in this case /home/oracle/okvutil.

   • -v writes the installation logs to the /home/oracle/okvutil/log/okvutil.deploy.log file at the server endpoint.

   -o is an optional argument that enables you to overwrite the symbolic link reference to okvclient.ora when okvclient.jar is deployed in a directory other than the original directory. This argument is used only when you re-enroll an endpoint.

5. When you are prompted for a password, then perform either of the following two steps.
   The optional password goes into two places: okvutil and in ADMINISTER KEY MANAGEMENT. With okvutil, only users who know that password can upload or download content to and from Oracle Key Vault. With ADMINISTER KEY MANAGEMENT, it becomes the password that you must use in the IDENTIFIED BY password clause. If you choose not to give a password, then okvutil upload and download commands will not prompt for a password, and the password for ADMINISTER KEY MANAGEMENT becomes NULL.NULL is used for an auto-login wallet.
   The choices for handling the password are as follows:
   • If you want to create a password-protected wallet, at minimum enter a password between 8 and 30 characters and then press Enter. For better security, Oracle recommends that you include uppercase letters, lowercase characters, special characters, and numbers in the password. The following special characters are allowed: (.), comma (,), underscore (_), plus sign (+), colon (:), space.

     Enter new Key Vault endpoint password (<enter> for auto-login): Key_Vault_endpoint_password
     Confirm new endpoint password: Key_Vault_endpoint_password
     

     A password-protected wallet is an Oracle wallet file that store the endpoint's credentials to access Oracle Key Vault. This password will be required whenever the endpoint connects to Oracle Key Vault.

   • Alternatively, enter no password and then press Enter.

     No password will be required when the endpoint connects to Oracle Key Vault with okvutil. With the ADMINISTER KEY MANAGEMENT statement, the password becomes NULL.

   A successful installation of the endpoint software creates the following directories:

   • bin: contains the okvutil program, the root.sh and root.bat scripts, and the binary files okveps.x64 and okveps.x86

   • conf: contains the configuration file okvclient.ora

   • jlib: contains the Java library files

   • lib: contains the file liborapkcs.so

   • log: contains the log files

   • ssl: contains the TLS-related files and wallet files. The wallet files contain the endpoint credentials to connect to Oracle Key Vault.

     The ewallet.p12 file refers to a password-protected wallet. The cwallet.sso file refers to an auto-login wallet.

9.7.1.4 Step 4: Perform Post-Installation Tasks

After you complete the installation, you can configure a TDE connection for the endpoint and verify that the endpoint software was installed correctly.

1. Optionally, configure a TDE connection for the endpoint.
   On UNIX platforms, the liborapkcs.so file contains the library that the Oracle database uses to communicate with Oracle Key Vault. On Windows platforms, the liborapkcs.dll file contains the library that the Oracle database uses to communicate with Oracle Key Vault.
   • On Oracle Linux x86-64, Solaris, AIX, and HP-UX (IA) installations: Log in as the root and then execute either of the following commands:

     $ sudo bin/root.sh
     

     Or:

     $ su -
     # bin/root.sh
     

     This command creates the directory tree /opt/oracle/extapi/64/hsm/oracle/1.0.0, changes ownership and permissions, then copies the PKCS#11 library into this directory.

   • On Windows installations: Run the following command:

     bin\root.bat

     This command copies the liborapkcs.dll file to the C:\oracle\extapi\64\hsm\oracle\1.0.0 directory.

2. Use a command such as namei or ls -l to confirm that a softlink was created in $ORACLE_BASE/okv/$ORACLE_SID/okvclient.ora to point to the real file in the /conf subdirectory of the installation target directory.
   If the ORACLE_BASE environment variable has not been set, then the softlink was created in $ORACLE_HOME/okv/$ORACLE_SID.
3. Run the okvutil list command to verify that the endpoint software installed correctly, and that the endpoint can connect to the Oracle Key Vault server.

   $ ./okvutil list

   If the endpoint is able to connect to Key Vault, then the No objects found message appears. If a Server connect failed message appears, then you must troubleshoot the installation for possible issues. Check that environment variables are correctly set. To get help on the endpoint software, execute the following command:

   java -jar okvclient.jar -h
   
   

   Output similar to the following appears:

   Production on Fri Apr 12 15:03:01 PDT 2019
   Copyright (c) 1996, 2019 Oracle. All Rights Reserved.
   Usage:
     java -jar okvclient.jar [-h | -help] [[-v | -verbose] [-d <destination directory>] [-o]]
   
   Options:
     -h or -help : Display command help.
     -v or -verbose : Turn on the verbose mode. Logs will be written to files under
                      <destination directory>/log/ directory.
     -d <destination directory> : Specify the software installation directory.
     -o : Overwrite the current symbolic link to okvclient.ora.
   

4. After you complete the installation, securely delete the okvclient.jar endpoint software file.

9.7.2 Upgrading Endpoint Software on an Enrolled Endpoint

You should upgrade the endpoint software on an enrolled endpoint any time you upgraded to a new release of Oracle Key Vault.

This ensures that you have the latest software on both the Oracle Key Vault server and the endpoint. Oracle highly recommends this for optimum performance. Oracle Key Vault servers can work with endpoint software from the previous major release, but may not work properly with endpoint software that is older. To upgrade the software on an already enrolled endpoint you can download and install the software okvclient.jar on the endpoint. You do not need to re-enroll the endpoint.

1. Log in to the endpoint server as the endpoint administrator.
2. Connect to the Oracle Key Vault management console.

   For example:

   https://192.0.2.254

   The login page to the Oracle Key Vault management console appears. Do not log in.

   
   
   Description of the illustration ep_enroll_sw_dwnload.png
   

3. In the lower-right corner of the login screen, under Login, click Endpoint Enrollment and Software Download.
4. In the Enroll Endpoint & Download Software page, click Download Endpoint Software Only.
   The Download Endpoint Software Only page appears.

   
   Description of the illustration download-endpoint-software-only.png

5. Select the Platform from the drop-down list and then click Download.
   A directory window appears, and prompts you to save the endpoint software file okvclient.jar. Navigate to the folder where you want to save the file.
6. Save the file to an appropriate directory.
7. Verify that the file is downloaded.

After you complete these steps, you can install the Oracle Key Vault software on the endpoint, using the same steps that can be used for an unenrolled endpoint.