9 Oracle Cloud Database as a Service Endpoints

Oracle Key Vault deployed on-premises can manage the TDE master keys for Oracle Cloud Database as a Service instances in a hybrid cloud topology.

9.1 About Managing Database as a Service Endpoints

An Oracle Key Vault appliance deployed on-premises can now manage TDE master keys for Database as a Service instances in the Oracle Cloud. This provides physical separation of keys from the encrypted data, and gives on-premises administrators control and visibility of how encryption keys are used to access encrypted data in the cloud. This also meets compliance requirements where encryption keys must be managed on-premises or separate from systems containing encrypted data.

Parent topic: Oracle Cloud Database as a Service Endpoints

9.2 Preparing a Database as a Service Instance to be an Oracle Key Vault Endpoint

Oracle Cloud - Database as a Service provides users with fully functional Oracle database instances that use computing and storage resources provided by Oracle Compute Cloud Service. It eliminates the need to purchase, build, and manage silos of server and storage systems. It also makes database resources and capabilities available online so users can consume them whenever and wherever they are needed.

See Also:

Using Oracle Database Cloud - Database as a Service - Before You Begin with Database as a Service

Parent topic: Oracle Cloud Database as a Service Endpoints

9.2.1 Setup a Database Cloud Service Instance

Instruction for setting up a Database as a Service instance can be found in the Oracle Database Cloud Service (Database as a Service) documentation. Please refer to the links in See Also to setup a Database as a Service instance.

Once set up, your Oracle Database as a Service instance should have the following default values:

A public IP address
Two users: oracle and opc (Oracle Public Cloud)
SSH access to both users: oracle and opc

See Also:

Using Oracle Database Cloud - Database as a Service: Creating a Database Deployment
Using Oracle Database Cloud - Database as a Service: Connect to a Compute Node through SSH
Using Oracle Database Cloud - Database as a Service: Viewing Detailed Information for a Database Deployment

Parent topic: Preparing a Database as a Service Instance to be an Oracle Key Vault Endpoint

9.2.2 Create Low Privileged Operating System User on Database as a Service

By default, Database as a Service instances are provisioned with the users: oracle and opc . These users have more privileges than necessary to create the SSH tunnel, so Oracle recommends that you create another low privileged OS user named okv on the Database as a Service instance. Oracle Key Vault will use user okv to setup a SSH tunnel and communicate with the Database as a Service instances.

To create the low privileged okv user:

Run the SSH utility:
```
$ ssh -i <private-key-file> opc@node-ip-address
```
where:

private-key-file is the path to the SSH private key file of the opc user.

node-ip-address is the public IP address of the Database as a Service compute node in x.x.x.x format.
If this is the first time you are connecting to the compute node, the SSH utility prompts you to confirm the public key.

In response to the prompt, enter yes.
Create the Oracle Key Vault user:
```
$ sudo adduser okv
```
Append the Oracle Key Vault user okv to the AllowUsers parameter in the SSH configuration file sshd_config in /etc/ssh/:
```
$ sudo vi /etc/ssh/sshd_config
  AllowUsers oracle opc okv
```
Restart the SSH daemon:
```
$ sudo /sbin/service sshd restart
```

Grant the Oracle Key Vault user okv permission to execute /sbin/fuser as root.

Edit and add the necessary entries to /etc/sudoers file as shown below:

sudo chmod 740 /etc/sudoers
sudo vi /etc/sudoers

Add the following entry:

okv     ALL=(root) NOPASSWD:/sbin/fuser 
sudo chmod 440 /etc/sudoers

The /etc/sudoers would look something like:

## Allow root to run any commands anywhere 
root    ALL=(ALL)       ALL  
okv     ALL=(root) NOPASSWD:/sbin/fuser

Create the authorized_keys file for the okv user and set appropriate permissions for this file.

$ sudo su -s /bin/sh okv -c "mkdir ~/.ssh"
$ sudo su -s /bin/sh okv -c "chmod 700 ~/.ssh"
$ sudo su -s /bin/sh okv -c "touch ~/.ssh/authorized_keys"
$ sudo su -s /bin/sh okv -c "chmod 640 ~/.ssh/authorized_keys" su okv

Copy the SSH public key of Oracle Key Vault from the ADD SSH Tunnel page to the authorized_keys file in /home/okv/.ssh/authorized_keys.

See Also:

Figure 9-2
Using Oracle Database Cloud - Database as a Service: Connect to a Compute Node using SSH

Parent topic: Preparing a Database as a Service Instance to be an Oracle Key Vault Endpoint

9.3 Set up an SSH Tunnel between Key Vault and Database as a Service Instance

An on-premises Oracle Key Vault communicates with Oracle Cloud Database as a Service instances using a secure SSH tunnel. You can set up the SSH tunnel only after you set up the Database as a Service instance. You will need the Database as a Service instance's public IP address and name of the OS user you wish to use to establish the tunnel.

The following procedure assumes that you followed Oracle's recommendation and created a low privilege user named okv. It creates an SSH tunnel between Key Vault and the Database as a Service instance.

To set up the SSH connection:

Login to the Oracle Key Vault Server. The home page appears
Click System.

The Status page appears.
Click SSH Tunnel Settings from the left side bar.

The SSH Tunnel Settings page appears.

Figure 9-1 SSH Tunnel Settings

Description of "Figure 9-1 SSH Tunnel Settings "
Click Add.

The Add SSH Tunnel page appears.

Figure 9-2 Add SSH Tunnel

Description of "Figure 9-2 Add SSH Tunnel "
Copy the text in SSH Public Key and save it. You will need to transport it to the Database as a Service instance and add it to the authorized_keys file of the Database as a Service user okv at /home/okv/.ssh/authorized_keys.
In Remote Host Details enter information in the following fields:
- Tunnel Name - Choose a descriptive name that identifies the tunnel, based on the Database as a Service instance to be associated with it.
- IP Address - Public IP address of the Database as a Service instance
- Port - enter a port number if you want to use a particular port number, or use the displayed default
- Username - Enter okv for the username
Note that you can complete these fields only after you set up your Database as a Service instance and obtain the public IP address and username.
Click Add.

The SSH Tunnel Settings page appears. It displays the SSH Tunnel just created and pre-existing SSH tunnels.

Figure 9-3 SSH Tunnel Settings

Description of "Figure 9-3 SSH Tunnel Settings"

It lists the tunnels created with the name, IP address, port, and registration time of each.

Clicking Add redirects you to the Add SSH Tunnel page.
Click a tunnel name to see the SSH Tunnel Details page.
Figure 9-4 SSH Tunnel Details - Disable

Description of "Figure 9-4 SSH Tunnel Details - Disable"

This page displays the following details for the tunnel:
- Tunnel Name
- IP Address
- Port
- Username
- SSH Tunnel Status - a green upward pointing arrow indicates an active tunnel and a downward pointing arrow indicates an inactive tunnel
- Disable, Cancel, and Delete
To delete a tunnel, check the box by the tunnel you want to delete and click Delete. You can delete more than one tunnel by selecting multiple boxes. A confirmation message appears. If you confirm, it deletes the selected tunnels.

The SSH Tunnel Settings page displays the remaining tunnels.

Figure 9-5 SSH Tunnel Settings Post Tunnel Deletion

Description of "Figure 9-5 SSH Tunnel Settings Post Tunnel Deletion"
Click Disable to disable the tunnel. When you disable the tunnel, the endpoints associated with this tunnel will no longer be able to communicate with Key Vault.

A confirmation message appears. If you confirm, the status changes to disabled indicated by a downward pointing arrow. The Disable button is replaced by an Enable button.

Figure 9-6 SSH Tunnel Details - Enable

Description of "Figure 9-6 SSH Tunnel Details - Enable"

Parent topic: Oracle Cloud Database as a Service Endpoints

9.4 Manageability of SSH Tunnel

The SSH tunnel is kept alive even if there is no activity between Key Vault and the Database as a Service instance. In case the tunnel drops off, it is automatically restarted.

An alert will be sent out if the tunnel is not available for any reason. An administrative user may elect to receive these alerts by email by configuring SMTP settings on Key Vault.

Parent topic: Oracle Cloud Database as a Service Endpoints

9.5 Register and Enroll Database as a Service Instance as Key Vault Endpoint

The Oracle Database as a Service instance must be enrolled before it can communicate with Oracle Key Vault server. The enrollment of Database as a Service endpoints is similar to the enrollment of on-premises endpoints with the following exceptions:

Database as a Service endpoints should be registered with an endpoint type of “Oracle Database Cloud Service".
Database as a Service endpoints have a primary tunnel IP associated with them. You must select the SSH tunnel with the same public IP address of the Database as a Service instance.
The platform must be Linux. This is automatically selected and cannot be modified.
You must download the jar file on-premises and transfer it to the Database as a Service instance using an out-of-band method like SCP or FTP.

To register and enroll a Database as a Service instance as an endpoint:

Click the Endpoints tab. The Endpoints page appears.
Click Add.

The Register Endpoint page appears.

Figure 9-7 Register Endpoint

Description of "Figure 9-7 Register Endpoint"
Enter the following endpoint details:
- Endpoint Name
- Type - must be Oracle Database Cloud Service
- Platform - Linux is automatically selected
- Description - meaningful description to identify endpoint
- Administrator Email - Optional field to receive endpoint related alerts
Click Register.

After a short delay the Endpoints page shows the new endpoint in Registered state with an Enrollment Token.
Click Endpoint Name. The Endpoint Details page appears.

Associate a default wallet with the registered endpoint now before enrolling the endpoint.
Copy the Enrollment Token. You will need it to download the endpoint software and enroll the endpoint (next step).
Log out of Oracle Key Vault and open a new session.

The login page appears. Do not log in.
Click Endpoint Enrollment and Software Download immediately below Login. The Enroll Endpoint & Download Software page appears.

Figure 9-8 Enroll Database as a Service Endpoint

Description of "Figure 9-8 Enroll Database as a Service Endpoint"

The fields are populated with the values that were chosen by the Key Vault system administrator while registering the endpoint. You can change these values while completing the enrollment of the endpoint. Note that you must select the Primary SSH Tunnel for Database as a Service endpoints from the drop down list. This is the only difference in the enrollment process from on-premises endpoints.
Enter the Enrollment Token and click Submit Token to validate the token.
Click Enroll to download the file okvclient.jar. to your local system. You must then move it to a secure directory on the Cloud Database as a Service instance with appropriate permissions in place so it cannot be read or copied by others.
```
$ scp -i <path-to-private-key-file> <path-to-okvclient.jar-on-local-mc> oracle@node-ip-address:<path-to-okvclient.jar-on-cloud-db-instance>
```
Where:

path-to-okvclient.jar-on-local-mc refers to the location of okvclient.jar on an on-premises local machine.

path-to-okvclient.jar-on-cloud-db-instance refers to the location of okvclient.jar on the oracle cloud database as a service instance.
Ensure that you have the necessary administrative privileges to install software on the endpoint.
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.
Run the Shell utility ORAENV or source ORAENV command to set the correct environment variables on Oracle Database servers.
Check that the environment variables ORACLE_BASE and ORACLE_HOME are correctly set.

If you used ORAENV to set these variables, 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.
Navigate to the directory in which you saved the okvclient.jar file.
Run the java command to install the okvclient.jar file.
```
java -jar okvclient.jar -d /home/oracle/okvutil -v
```
In this command:
- The -d argument specifies the directory location for the endpoint software and configuration files, in this case /home/oracle/okvutil.
  
  The environment variable $OKV_HOME refers to the directory where the endpoint software is installed, in this case /home/oracle/okvutil.
- The -v argument writes the installation logs to the $OKV_HOME/log/okvutil.deploy.log file at the server endpoint.
Note:
-o is an optional argument that allows you to overwrite the symlink reference to okvclient.ora, when okvclient.jar is deployed in a directory other than the original directory. This argument is used only when re-enrolling an endpoint.
The installation process prompts for a password. You can enter a password to create a password-protected wallet or create an auto-login wallet without a password as described below:
- 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.
  
  Create a password-protected wallet by entering a password between 8 and 30 characters. Then press Enter.
- Create an auto-login wallet by simply clicking Enter.
  
  No password will be required when the endpoint connects to Oracle Key Vault. An auto-login wallet enables endpoint provisioning without human intervention.
```
Enter new Key Vault endpoint password (<enter> for auto-login): Key_Vault_endpoint_password
Confirm new endpoint password: Key_Vault_endpoint_password
```
The installation proceeds and completes with the following message:
```
The Oracle Key Vault endpoint software installed successfully.
```
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.
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.

If you are planning to use a TDE direct connection, then run root.sh on Oracle Linux x86-64, Solaris, AIX, and HP-UX (IA) installations. The liborapkcs.so file is copied to the following directory: /opt/oracle/extapi/64/hsm/oracle/1.0.0

On Windows installations, run root.bat. The liborapkcs.dll file is copied to C:\oracle\extapi\64\hsm\oracle\1.0.0

Log in as the root user and run the root.sh script. On Windows installations, run root.bat.
```
$ sudo bin/root.sh
```
```
bin\root.bat
```
Or:
```
$ su -
# bin/root.sh
```
On Windows platforms, you are prompted for the version of the RDBMS in use when you execute root.bat. Switch out of user root after completing this step.
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.

If the endpoint is able to connect to Key Vault, a No objects found message appears:
```
$ ./okvutil list
No objects found
```
If a Server connect failed message appears at any time, you must troubleshoot the installation for possible issues. First check that environment variables are correctly set.

You can get help on the endpoint software with the -h option:

java -jar okvclient.jar -h

The following output appears:

Oracle Key Vault Release 12.2.0.6.0 (2017-12-15 15:36:49.839 PDT)
Production on Fri Dec 15 19:55:31 PDT 2017
Copyright (c) 1996, 2017 Oracle. All Rights Reserved.
Usage: java -jar okvclient.jar [-h | -help] [[-v | -verbose] [-d <destination directory>] [-o]]

After installation Oracle recommends that you securely delete the endpoint software file okvclient.jar.
Click Endpoints to see the enrolled endpoint.

Figure 9-9 Database as a Service Endpoints Among other Endpoints

Description of "Figure 9-9 Database as a Service Endpoints Among other Endpoints"
Click the Endpoint Name to see all the details for the endpoint on one page.

Figure 9-10 Database as a Service Endpoint Details

Description of "Figure 9-10 Database as a Service Endpoint Details"

9.6 Suspend a Database Cloud Service's Access to Oracle Key Vault

When using an on-premises Key Vault to manage the TDE master keys for Database as a Service endpoints, the master keys are never stored persistently in Oracle Cloud. This gives the on-premises Key Vault administrator the ability to control access to the encrypted data in the cloud.

The on-premises Oracle Key Vault administrator can suspend Database as a Service endpoints with a single click. This means that the Oracle Key Vault Server rejects all requests from the suspended endpoints. Since the endpoint cannot request keys from the Oracle Key Vault server, its ability to access encrypted data is lost once key cached in memory times out. For Oracle Database Cloud Service endpoints, this time out is 5 minutes by default.

The on-premises Oracle Key Vault administrator can resume a suspended endpoint. This means that the Oracle Key Vault server can start servicing requests from the reinstated endpoint. The reinstated endpoint can now retrieve keys from the Oracle Key Vault server and access sensitive data.

Caution:

The SUSPEND operation is a disruptive operation as it results in operational discontinuity and should be used with care. Usually, this option should be exercised only if there is a strong indication of abnormal activity in the Database as a Service instance.

You can only suspend enrolled endpoints. Endpoints in Registered state may not be suspended. Note that if you try to suspend endpoints that are already suspended, no operation will be performed. The endpoints will continue to be in suspended state.

To suspend endpoints (you can suspend multiple endpoints simultaneously):

Click Endpoints. The Endpoints page appears (Figure 9-9).
Check the boxes by the endpoints you wish to suspend.
Click Suspend. A confirmation message appears. Confirm the action by clicking Yes.
Click Endpoints to see the suspended endpoints. The status of suspended endpoints will be highlighted in red.

Figure 9-11 Suspended Endpoints

Description of "Figure 9-11 Suspended Endpoints"

Parent topic: Oracle Cloud Database as a Service Endpoints

9.7 Resume a Database Cloud Service's Access to Oracle Key Vault

You can reinstate the connection between suspended Database Cloud Service endpoints and Key Vault. When you resume these endpoints their status will change to Enrolled. Note that resuming enrolled endpoints will not change their enrolled status.

To resume a Database Cloud Service's Access to Key Vault:

Click Endpoints. The Endpoints page appears.

The suspended endpoints have status Suspended in red.
Check the boxes by the endpoints you wish to resume.
Click Resume.

A confirmation message appears. Confirm the action by clicking Yes.
Click Endpoints to see the re-enrolled endpoints. Their status is Enrolled.

Figure 9-12 Resumed Endpoints Showing Enrolled Status

Description of "Figure 9-12 Resumed Endpoints Showing Enrolled Status"

Parent topic: Oracle Cloud Database as a Service Endpoints

9.8 Resuming a Database Endpoint Configured with a Password-based Keystore

A Database as a Service endpoint configured with auto-login keystore support will begin operations as soon as the endpoint is resumed. On the other hand, the Database as a Service endpoint configured with password keystore will not resume operations after the endpoint is resumed on the Oracle Key Vault server. The keystore on the Database as a Service instance was closed because Key Vault suspended the endpoint. You should open the password-based keystore on the Database as a Service instance to resume operations.

Parent topic: Oracle Cloud Database as a Service Endpoints