13 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 mostly the same way, except that multi-master clusters have more restrictions.
• Managing Endpoints
  You can enroll, reenroll, suspend, and delete endpoints.
• 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.
• 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.

13.1 Overview of Managing Endpoints

You can manage endpoints in both standalone environments and multi-master clusters in mostly 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
  You should be aware of how a multi-master cluster affects endpoints, both in the way an endpoint connects to it and with restrictions.

13.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 or the Create Endpoint privilege 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 the Key Administrator role can grant endpoints access to security objects contained in virtual wallets. A Key Administrator user can grant access to any wallet in an endpoint. A user with the Key Administrator role or Create Endpoint Group privilege can also create endpoint groups to enable shared access to virtual wallets. Any user (including users who created the endpoint) who has the manage wallet permission on a wallet can grant access to that wallet to an endpoint. 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 administrative roles and privileges as they pertain to endpoints are as follows:

• Endpoint creation: A user with the System Administrator role can create endpoints anywhere in the Oracle Key Vault system. A user with the Create Endpoint privilege can create their own endpoints.
• Endpoint management: A user with the System Administrator role can manage endpoints anywhere in the Oracle Key Vault system. A user with the Manage Endpoint privilege can manage his or her own endpoints. This includes endpoints that the user was explicitly granted the Manage Endpoint privilege on, or endpoints that the user created and continues to have the Manage Endpoint privileges on. This management includes the following duties:
  • Managing the endpoint metadata such as the name, type, platform, description, and email notifications
  • Managing the endpoint life cycle, which consists of enrolling, suspending, reenrolling, and deleting endpoints
• Endpoint group creation: A user with the Key Administrator role can create endpoint groups anywhere in the Oracle Key Vault system. A user with the Create Endpoint Group privilege can create his or her own endpoint groups.
• Endpoint group management: A user with the Key Administrator role can manage endpoint groups anywhere in the Oracle Key Vault system. A user with the Manage Endpoint Group privilege can manage his or her own endpoint groups. The endpoint groups that a user can manage include those that the user was explicitly granted the Manage Endpoint Group privilege on, or those that the user created and continues to have the Manage Endpoint Group privilege on. This management includes the following duties:
  • Managing the endpoint group lifecycle, which consists of creating, modifying, and deleting endpoint groups
  • Managing the life cycle of security objects, which consists of creating, modifying and deleting security objects

13.1.2 How a Multi-Master Cluster Affects Endpoints

You should be aware of how a multi-master cluster affects endpoints, both in the way an endpoint connects to it and with restrictions.

In a multi-master configuration, when an endpoint attempts to make a connection to Oracle Key Vault, it performs the following actions:

• First, it obtains the list of server IPs from its configuration file (okvclient.ora).
• Next, it picks one at random, preferentially from those in the same cluster subgroup as the endpoint.

Be aware of the following restrictions with how endpoints work in multi-master clusters:

• An endpoint can only be enrolled from the same node where it was most recently created or re-enrolled.
• 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.

13.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 or Create Endpoint User
  A user who has been granted the System Administrator role or the Create Endpoint privilege 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.

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

13.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, information about the endpoints that were enrolled in the cluster is replicated to the newly added node. During induction, Oracle Key Vault removes information about the 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. From here, a system administrator can choose to rename them.

13.2.3 Adding an Endpoint as an Oracle Key Vault System Administrator or Create Endpoint User

A user who has been granted the System Administrator role or the Create Endpoint privilege 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 or the Create Endpoint privilege.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.

   
   Description of the illustration 21_endpoint_page.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. This listing of endpoints depends on who is logged in. For a user with the System Administrator role, all the endpoints will be listed. For a user with the Create Endpoint privilege, only endpoints to which the user has access will appear. The buttons listed above the table also depend on the user's role or privilege status. 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. If you do not have the System Administrator role (that is, you have the Manage Endpoint privilege), then you can only view enrollment tokens for those endpoints that the you can manage.
   • Created By: The user who created the endpoint. If the user no longer exists, or if the endpoint was created in a version before this information was stored, then this field will show ANONYMOUS.
   • 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. On the Endpoints page, click Add.
   The Register Endpoint page appears. The Make Unique check box only appears in multi-master clusters mode.

   
   Description of the illustration 21_add_endpoint.png

4. In the Endpoint Name field, enter a name for the endpoint.
   See Naming Guidelines for Objects.
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, HP-UX, 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 SMTP configured to use the email notification feature.
   • Cluster Subgroup: For a multi-master cluster environment, select a subgroup for the endpoint. If you select No Cluster Subgroup, then the endpoint will not be a part of any cluster subgroup. If you select the option suffixed with (from Creator Node), the endpoint will be a part of the cluster subgroup to which its creator node belongs, even if the creator node's cluster subgroup changes. All other options assign an endpoint to an existing cluster subgroup, to which it will belong regardless of its creator node's cluster subgroup.
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 21_endpoint_registered.png

9. If you had logged in as a user with the Create Endpoint privilege, and if this is the first endpoint that you have registered, then log out of the Oracle Key Vault management console and log back in again.
   Logging out and an again makes the full set of privileges for this endpoint available to you. After you log in, click the Endpoints tab, and then Endpoints in the left navigation window to access the Endpoints page.
10. Click the endpoint name to see details for the endpoint.
    The Endpoint Details page appears.

    
    Description of the illustration 21_endpoint_details.png

    The Send Enrollment Token button on the Endpoint Details page only appears for an endpoint whose Status is Registered. (If you are not a user with the System Administrator role, then you cannot view the enrollment token or the Send Enrollment Token button. If you have the Manage Endpoint privilege, then you can only view the token and have access to the Send Enrollment Token button.)

    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.

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

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

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

13.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 navigation bar.
   The Endpoint Settings page appears.

   
   
   Description of the illustration 21_endpoint_settings.png
   

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

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

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

13.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 or the Manage Endpoint privilege on that endpoint.
   A user who has the Manage Endpoint privilege can only delete endpoints on which this user has been granted the Manage Endpoint privilege. To see which endpoints that a user can manage, select the Users tab, then select Manage Users. Check the User Details page for the user in question, and scroll down to the Access to Endpoints area.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page lists all the endpoints currently registered or enrolled.
3. In the Endpoints page, select the check boxes to the left of the endpoints that you want to delete.
4. Click Delete.
5. In the confirmation window, click OK.

13.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 or the Manage Endpoint privilege on that endpoint.
   A user who has the Manage Endpoint privilege can only delete endpoints on which this user has been granted the Manage Endpoint privilege. To see which endpoints that a user can manage, select the Users tab, then select Manage Users. Check the User Details page for the user in question, and scroll down to the Access to Endpoints area.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. Click the endpoint name that you want to delete.
   The Endpoint Details page appears.
4. Click Delete.
5. In the confirmation window, click OK.

13.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 or the Manage Endpoint privilege.
   A user who has the Manage Endpoint privilege can only suspend endpoints that he or she created.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. In the Endpoints page, select the check boxes to the left of the endpoints that you want to suspend.
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-3.
   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.

13.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 the endpoint.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role or the Manage Endpoint privilege.
   A user who has the Manage Endpoint privilege can only reenroll endpoints that he or she created.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. In the Endpoints page, 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.

13.3 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.
• Modifying Configuration Parameters for an Individual Endpoint
  A user who has the System Administrator role or the Manage Endpoint privilege can set configuration parameters for individual endpoints.

13.3.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. (The following screen shows a partial view.)

Description of the illustration 21_endpoint_details.png

13.3.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 or the Manage Endpoint privilege.
   A user who has the Manage Endpoint privilege can only modify endpoints that this user has created. To see which endpoints that a user can manage, select the Users tab, then select Manage Users. Check the User Details page for the user in question, and scroll down to the Access to Endpoints area.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. In the Endpoints page, click the name of the endpoint.
   The Endpoint Details page appears.
   Description of the illustration 21_endpoint_details1.png
4. In the Endpoint Details page, modify any of the following: Endpoint Name, Type, Description, Platform, Administrator Email, Cluster Subgroup (for multi-master cluster environments only), or Strict IP Check.
   The Strict IP Check setting is enabled by default for any endpoint that was created in Oracle Key Vault. If you select this check box, then Oracle Key Vault checks if the endpoint is connecting to it using the same IP that was used when the endpoint software was first deployed. If you disable this check box, then Oracle Key Vault allows the endpoint to connect to it using any IP address. Oracle recommends that you enable this setting unless otherwise required.
   See Naming Guidelines for Objects.
5. Click Save.

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

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

Note:

Users who have the Manage Endpoint privilege can modify the configuration parameters individually for each endpoint to which they have access. To do so, go to the Details page for the endpoint, scroll to the bottom, and then modify the endpoints from there.

13.3.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 navigation bar.

   The Endpoint Settings page appears.

   
   Description of the illustration 21_endpoint_settings.png

3. In the Global Endpoint Configuration Parameters section, configure the following settings:
   • Endpoint Certificate Validity ( in days ): Specify the number of days for which the current endpoint certificate is valid.
   • PKCS 11 In-Memory Cache Timeout ( in minutes ): 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 Persistent Cache Timeout ( in minutes ): 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 ( in minutes ): 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 ( in milliseconds ): 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.

13.3.4 Modifying Configuration Parameters for an Individual Endpoint

A user who has the System Administrator role or the Manage Endpoint privilege can set configuration parameters for individual endpoints.

A user with the System Administrator role can set configuration parameters for any endpoint. A user with the Manage Endpoint privilege can only set configuration parameters for the endpoints for which the user has the Manage Endpoint privilege.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role or the Manage Endpoint privilege.
2. Select the Endpoints tab, and then Endpoints from the left navigation bar.
3. In the Endpoints page, select the endpoint that you want to modify.
4. In the Endpoint Details page, scroll down to the Endpoint Configuration Parameters area.
5. Modify the configuration parameters as necessary.
   The configuration parameters are the same as the configuration parameters that can be modified globally.
6. Click Save.

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

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

13.4.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 a user who has the Key Administrator role or the Manage Endpoint privilege.
   If you are logging on as a user with the Manage Endpoint privilege, then you must have full wallet access (Read/Write/Manage Wallet) on the wallet that you want to set as the endpoint's default wallet.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. In the Endpoints page, click the name of the endpoint that you want.
4. In the Default Wallet pane, select Choose Wallet.

   
   Description of the illustration 21_wallet_default_none.png

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

   
   Description of the illustration 21_wallet_default_select.png

5. 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 21_wallet_default_selected.png

6. Click Save.

13.5 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 the 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.

13.5.1 Granting an Endpoint Access to a Virtual Wallet

An endpoint must have the 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 or the Manage Endpoint privilege on the endpoint.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
3. On the Endpoints page, select the endpoint that must have access to the virtual wallet.
   The Endpoint Details page appears. Scroll down the page to the Access to Wallets pane.

   
   Description of the illustration 21_access_to_wallets.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 Select Wallet page appears. A user with the Manage Endpoint privilege can only view the wallets to which this user has access.

   
   Description of the illustration 21_wallet_default_select.png

5. Select a wallet from the available list of wallets shown on the Add Access to Endpoint page.
6. In the Select Access Level pane, select the appropriate level of access.
7. Click Save.

13.5.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 or the Manage Endpoint privilege.
   If you have the Manage Endpoint privilege on the given endpoint, then you must have the same or a higher level of access to the wallet.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
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 window, click OK.

13.5.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 or the Manage Endpoint privilege.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. In the Endpoints page, click the name of the endpoint to access the Endpoint Details page, and then scroll down to the Access to Wallet Items pane.
   The Access to Wallet Items pane lists the wallet items that the endpoint has access to.

   
   Description of the illustration 21_access_to_wallets.png

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

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

13.6.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 or the Manage Endpoint Group privilege.
   A user who has the Manage Endpoint Group privilege will only be able to manage the endpoint groups that he or she created.
2. Select the Endpoints tab, then Endpoint Groups in the left navigation bar.
   The Endpoint Groups page appears.

   
   Description of the illustration 21_endpoint_groups.png

3. Click Create.
   The Create Endpoint Group page appears.

   
   Description of the illustration 21_create_endpoint_group.png

4. Enter the name of the new group and a brief description.
   Ensure that you follow the correct naming guidelines for objects.
5. If you are using a multi-master cluster, then choose whether to select the Make Unique check box.
   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. Click Save to complete creating the endpoint group.
   The new endpoint group now appears in the Endpoint Groups page.
7. If you had logged in as a user with the Create Endpoint Group privilege, and if this is the first endpoint group that you have created, then log out of the Oracle Key Vault management console and log back in again.
   Logging out and an again makes the full set of privileges for this endpoint group available to you.

13.6.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 or the Manage Endpoint Group privilege.
   A user who has the Manage Endpoint Group privilege can only modify endpoint groups that he or she created.
2. Select the Endpoints tab, then Endpoint Groups in the left navigation bar.
   The Endpoint Groups page appears.
3. Click the edit pencil icon in the Edit column corresponding to the endpoint group.
   The Endpoint Group Details page appears.

   
   Description of the illustration 21_endpoint_group_details.png

4. Modify the endpoint name as necessary.
   See Naming Guidelines for Objects.
5. Modify the description as needed.
6. Add or remove access to wallets or endpoint group members by clicking Add or Remove.
7. Click Save.

13.6.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 to 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 or the Manage Endpoint Group privilege.
   A user who has the Manage Endpoint Group privilege can grant endpoint group access to wallets for only endpoint groups that the user created.
2. Select the Endpoints tab, then Endpoint Groups in the left navigation bar.
   The Endpoint Groups page appears.
3. Click the pencil icon in the Edit 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.

13.6.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 or Manage Endpoint Group privilege.
   A user who has the Manage Endpoint Group privilege can only add endpoints to endpoint groups that he or she created.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears.
3. Select the endpoint you want to add to a group.
   The Endpoint Details page appears.
4. Scroll to Endpoint Group Membership and then click Add.

   The Add Endpoint Group Membership page appears.

   
   Description of the illustration 21_add_endpoint_group_membership.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 21_added_endpoint_group_membership.png

13.6.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 or the Manage Endpoint Group privilege.
   A user who has the Manage Endpoint Group privilege can only remove endpoints from endpoint groups that he or she created.
2. Select the Endpoints tab, then Endpoint Groups in the left navigation bar.
   The Endpoint Groups page appears.
3. In Endpoint Groups, click the edit pencil icon next in the Edit 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 window, click OK.

13.6.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 or the Manage Endpoint Group privilege.
   A user who has the Manage Endpoint Group privilege can only remove endpoint groups that he or she created.
2. Select the Endpoints tab, then Endpoint Groups in the left navigation bar.
   The Endpoint Groups page appears.
3. Check the boxes to the left of the endpoint group names that you want to delete.
4. Click Delete.
5. In the confirmation window, click OK.