Getting Started with Oracle Key Vault RESTful Services

After you download the RESTful services utility and customize its configuration files, you can begin to use the Oracle Key Vault RESTful services utility commands.

Enabling or Disabling Oracle Key Vault RESTful Services

You enable and disable RESTful services from the Oracle Key Vault management console.

Enabling RESTful Services

After checking the endpoint requirements, and enabling network services, you can enable RESTful services, download the RESTful software utility, and then customize its configuration files.

Step 1: Check the Endpoint System Requirements

Before you can provision endpoints with the RESTful command-line interface, you must have the tools to transfer data securely across the network.

  1. Log in to the endpoint host as an endpoint administrator.

  2. Ensure that you have the following tools:

    • OpenSSL 1.0.1p or later

    • JAVA 8 or later. If you plan to deploy RESTful services on a database server with Oracle Database release 12.2.0.1 or later, then you can use the embedded Java Runtime Environment (JRE) in $ORACLE_HOME/jdk/jre.

      For database installations from Oracle release 12.2.0.1 and later, set JAVA_HOME to $ORACLE_HOME/jdk/jre, and add JAVA_HOME/bin to the PATH. For earlier database releases, download and install JAVA 8 or later, and then set JAVA_HOME and PATH appropriately. OpenJDK is not supported.

Step 2: Enable Network Services

You must configure web access for RESTful clients by their IP addresses to access the Oracle Key Vault server.

You can allow all IP addresses or restrict access to a subset of IP addresses that you designate in this step. Note, that this option will also restrict access to the Oracle Key Vault management console.

  1. Log in to the Oracle Key Vault management console as a user with the System Administrator role.

  2. Select System, then Settings from the left sidebar.

    The Settings page appears. Go to the Network Details section.

  3. For Web Access select one of the IP address options for the RESTful client:

    • All to allow all IP addresses.

    • IP address(es) to designate a set of IP addresses. After you select this option, enter the IP addresses in the next field, separating each IP address by a space.

  4. Click Save.

Step 3: Enable RESTful Services

After you enable the network services, you can enable the RESTful services.

In a multi-master cluster environment, enabling RESTful services on one node will enable it for the entire cluster.

  1. Log in to the Oracle Key Vault management console as a user with the System Administrator role.

  2. Select System, then Settings from the left sidebar.

    The Settings page appears. Go to the System Configuration section, then to theRESTful Services section within it.

  3. From the options, select IP address(es) or All.

    Note: If you select the IP address(es) option, then provide the allowed list of IP address(es) in the text box.

  4. Click Save.

Step 4: Download the RESTful Services Utility

The RESTful services utility is in the okvrestclipackage.zip file.

Note: Classic RESTful services are deprecated starting with Oracle Key Vault release 21.5.

In addition to the new RESTful service utility introduced in the Oracle Key Vault 21.1 release, Oracle Key Vault continues to support earlier implementation of the RESTful service utility that you can download as Classic RESTful Service Utility.

wget --no-check-certificate https://ip_address:5695/okvrestclipackage.zip
curl -k https://ip_address:5695/okvrestclipackage.zip -o okvrestclipackage.zip
curl -O -k https://ip_address:5695/okvrestclipackage.zip

Step 5: Configure the RESTful Services Utility

After you have downloaded the RESTful services utility, you must modify a couple of files that are included in its ZIP file.

  1. Move the okvrestclipackage.zip file to the Oracle Key Vault home directory (OKV_HOME) in the endpoint.

    You can move the zip file to any secure location, but having it in the Oracle Key Vault home directory in the endpoint is convenient for managing the Oracle Key Vault RESTful files in a central location. This guide assumes that you downloaded the zip file onto the endpoint.

  2. Unzip the okvrestclipackage.zip file.

    For example:

    unzip okvrestclipackage.zip

    The following directory structure is created:

    • Directory where you placed the okvrestclipackage.zip file, such as the OKV_HOME directory

      • bin

        • okv

        • okv.bat

      • lib

        • okvrestcli.jar

      • conf

        • okvrestcli.ini

        • okvrestcli_logging.properties

  3. In the RESTful services command line utility script, set the OKV_RESTCLI_CONFIG variable.

    OKV_RESTCLI_CONFIG sets the location of the okvrestcli.ini configuration file. The RESTful services command line utility script for Linux platforms is okv and the utility script for Microsoft Windows is okv.bat.

  4. Set the JAVA_HOME environment variable to a Java Runtime Environment (JRE) installation with the minimum version 1.7.0.21.

Next, you are ready to modify the okvrestcli.ini and okvrestcli_logging.properties configuration files for your environment.

Related Topics

Disabling RESTful Services

You should enable RESTful services for short periods during when administrative tasks are performed.

RESTful Services are disabled by default. After you have performed administrative tasks using the RESTful services, you should disable RESTful services.

  1. Log in to the Oracle Key Vault management console as a user with the System Administrator role.

  2. Select System, then Settings from the left sidebar.

    The Settings page appears. Go to the System Configuration section, then to the RESTful Services section within it.

  3. Un-check the box to the right of Enable in the RESTful Services section.

  4. In the System Settings page, click the Save.

Oracle Key Vault RESTful Services Configuration and Logging Files

Oracle Key Vault provides two files, okvrestcli.ini and okvrestcli_logging.properties, that you can use to specify required or optional settings for when you run RESTful services utility commands.

okvrestcli.ini Configuration File

The okvrestcli.ini file enables you to control global settings that are used in the Oracle Key Vault RESTful services utility commands.

About the okvrestcli.ini Configuration File

The okvrestcli.ini file enables you to configure commonly used settings when you run Oracle Key Vault RESTful services utility commands.

These are settings such as the user’s name or the IP address of an Oracle Key Vault server. The RESTful service utility requires these kinds of configuration parameters in the okvrestcli.ini file to be set for each command execution. The settings that you set in this file are automatically applied to all Oracle Key Vault RESTful services utility commands without the need for you to manually enter them at the command line each time that you want to run the command.

The configuration parameters in the okvrestcli.ini are grouped together in different sections called named profiles. Each section includes the profile name and list of the parameters that are associated with the profile. When you run the command with a named profile (using the --profile profile_name parameter), the configuration parameters listed under the named profile apply for the execution of the command. The configuration parameters listed under the [DEFAULT] profile represent default parameter settings that apply when either no named profile is specified or the parameter is not listed under the named profile.

By default, the okvrestcli.ini is in the same location where you downloaded the Oracle Key Vault RESTful services utility, in the OKV_HOME/conf directory of the endpoint.

Related Topics

okvrestcli.ini Configuration Parameters

The okvrestcli.ini parameters cover settings such as the name of a user, the location of the okvclient.ora file, and so on.

The okvrestcli.ini parameters are as follows:

[DEFAULT] and Named Profiles in the okvrestcli.ini File

The [DEFAULT] and named profile sections of the okvrestcli.ini file enable you to maintain different sets of configuration parameter settings that can be applied when executing commands in different contexts.

The okvrestcli.ini file is organized as one or more named profile sections. A named profile section represents a collection of configuration parameter settings that are logically group together. A named profile section includes:

You apply the configuration parameter settings listed under a named profile by specifying the profile name in the command line with parameter --profile profile_name.

The [DEFAULT] profile lists the default values of the okvrestcli.ini parameters. The parameter settings under the [DEFAULT] profile apply when either no named profile is specified during command execution or the parameter is not listed under the named profile, and assuming you do not specify the parameter in the command line.

The following example shows the use of profiles that is suitable for connecting to Oracle Key Vault using identities of different endpoints. This is useful in an environment where you have isolated PDB endpoints configured on the same host. This okvrestcli.ini file has a named profile for each PDB endpoint that points to respective okvclient.ora file.

[DEFAULT]
log_property=/usr/local/okv/logging.property
server = 192.0.2.191

[HR_PDB]
okv_client_config=/usr/local/okv/hr_ep/okvclient.ora

[FIN_PDB]
okv_client_config=/usr/local/okv/finance_ep/okvclient.ora

[SALES_PDB]
okv_client_config=/usr/local/okv/sales_ep/okvclient.ora

To create a key using HR_DB endpoint, you use the [HR_DB] profile:

okv managed-object key create --profile HR_DB --algorithm AES --length 256 --mask "ENCRYPT,DECRYPT" --wallet hr_wallet

This command uses the okv_client_config parameter from [HR_DB] profile. Other configuration parameters (for example, log_property and server) are applied from the [DEFAULT] profile.

This example shows the use case of using profiles in a multi-master cluster environment where you create a profile for each node in the cluster to use settings that are specific to that node. The following example contains profiles for three nodes in a cluster:

[DEFAULT]
log_property=/usr/local/okv/logging.property
user=okvadmin
server=192.0.2.191

[NODE1]
server=192.0.2.191

[NODE2]
server=192.0.2.192

[NODE3]
server=192.0.2.193

To run a command on NODE2, you use the [NODE2] profile:

okv server status get --profile NODE2

This command uses the server entry from [NODE2] profile. The other configuration parameter settings are used from the [DEFAULT] profile.

Before you work with [DEFAULT] settings and profiles, ensure that you understand the precedence order of the okvrestcli.ini parameters.

Precedence Order of okvrestcli.ini Parameters

When you run an Oracle Key Vault RESTful service command, the configuration parameter values are determined on the basis of an order of precedence.

Parameter Precedence Order

The order of precedence for okvrestcli.ini configuration file parameters (except for the server entry) is as follows:

  1. Parameter value is specified by the user in the command line.

  2. Parameter value is specified in the profile section. User includes the --profile parameter in the command line.

  3. Parameter value is specified in the [DEFAULT] profile. User makes no reference in the command line.

Examples of How Parameter Precedence Works

The following examples show how parameter precedence works for the following okvrestcli.ini file, which contains different settings for the user parameter under the [DEFAULT] and [HR] profiles.

[DEFAULT]
user= psmith

[HR]
user=jgreenberg

server Parameter Precedence Order

The server parameter has a slightly different precedence behavior from the other okvrestcli.ini parameter settings, because in addition to the okvrestcli.ini file, its setting can come from the okvclient.ora file. The location of the okvclient.ora file is specified with the okv_client_config parameter in okvrestcli.ini. The server entry that is specified directly takes precedence over the server entry from the okv_client_config parameter.

The order of precedence for the server entry is as follows:

  1. server parameter value is specified by the user in the command line.

  2. Server information is obtained from the okvclient.ora file. User specifies this file by including the okv_client_config parameter in the command line.

  3. server parameter value is specified in the profile section. User includes the --profile parameter in the command line.

  4. Server information is obtained from the okvclient.ora file, which is set by the okv_client_config parameter from a profile section. User specifies this profile by using the --profile parameter in the command line.

  5. server parameter value is specified in the [DEFAULT] profile. User makes no reference in the command line.

  6. Server information is obtained from the okvclient.ora file that is specified with okv_client_config parameter in the [DEFAULT] section. User makes no reference in the command line.

Examples of How the server Parameter Precedence Order Works

The following examples show how the server parameter precedence works based on various ways that this parameter can be set:

Using an Alternative Configuration File

You can use an alternative parameter configuration file from the okvrestcli.ini configuration file.

By default, Oracle Key Vault uses the okvrestcli.ini configuration file to control commonly used settings for the Oracle Key Vault RESTful services utility commands. You can create your own version of this configuration file and specify it in the command line execution.

Related Topics

okvrestcli_logging.properties Log File Parameter Settings

The okvrestcli_logging.properties log file determines how logging is handled for Oracle Key Vault RESTful services activities.

Modifying the okvrestcli_logging.properties is optional. If you do not configure it, then Oracle Key Vault creates and updates a default logging file when you run the RESTful services utility commands.

By default, the okvrestcli_logging.properties file is in the location you downloaded the Oracle Key Vault RESTful services utility, in the OKV_HOME/conf directory of the endpoint.

The parameter settings for okvrestcli_logging.properties are as follows:

An example of these settings is as follows:

handlers= java.util.logging.FileHandler

# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = /usr/local/okv/okvrest.log
java.util.logging.FileHandler.limit = 200000
java.util.logging.FileHandler.count = 1
#java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.FileHandler.formatter = com.oracle.okv.rest.log.OkvFormatter

# Limit the message that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = FINER
#java.util.logging.ConsoleHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.ConsoleHandler.formatter = com.oracle.okv.rest.log.OkvFormatter

Getting Help Information for RESTful Services Utility Commands

At the command line (but not in JSON), you can find detailed help information for each component of an okv RESTful services utility command.

okv category Component Help Information

Entering okv --help returns help information for the category component of the okv command.

Syntax: okv --help

Example Input: okv --help

Example Output:

Oracle Key Vault REST CLI Version 21.12.0.0.0 Built 10/13/2025 12:34
Usage: okv <category> <resource> <action> [<rest-cli-parameters>] [<parameters>]

Command:
  <category> :
    managed-object                -     Commands that endpoints can execute to manage security objects.
    backup                        -     Administration commands to manage Oracle Key Vault appliance backup and restore.
    admin                         -     Administration commands to manage client wallets and endpoints.
    manage-access                 -     Access management commands to manage wallets and endpoint groups.
    server                        -     Monitoring commands to retrieve static or dynamic information about an Oracle Key Vault server.
    cluster                       -     Monitoring commands to retrieve static or dynamic information about a cluster or a cluster node.
    primary-standby               -     Monitoring commands to retrieve static or dynamic information about the Oracle Key Vault primary-standby configuration.
    crypto                        -     Commands to perform cryptographic operations.
    metrics                       -     Commands to perform metrics operations.
    util                          -     Command to perform json parser operations.

<rest-cli-parameters>:
    --client_wallet <arg>       Client wallet.
    --config <arg>              OKV REST CLI configuration file
                                (okvrestcli.ini) location.
    --from-json <arg>           Input file in JSON.
    --generate-json-input       Generate JSON input template file.
    --help                      List available options.
    --okv_client_config <arg>   OKV Client configuration file
                                (okvclient.ora) location.
    --output_format <arg>       Command output format, 'text' or 'json
    --profile <arg>             Profile name in configuration file
                                (okvrestcli.ini).
    --server <arg>              OKV server IP address or hostname.
    --user <arg>                Username.
    --version <arg>             Version for backward compatibility.

rest-cli-parameters shows the list of parameters that apply to all commands.

okv resource Component Help Information

Entering okv category --help returns detailed information about the resource components for the specified category.

Syntax: okv category --help

Example Input: okv admin --help

Example Output:

Oracle Key Vault REST CLI Version 21.12.0.0.0 Built 10/13/2025 12:34
Usage: okv admin <resource> <action> [<rest-cli-parameters>] [<parameters>]

Command:
  <category> : admin
  <resource> :
    endpoint                      -     Commands to manage endpoints.
    client-wallet                 -     Commands to manage client wallets.

okv action Component Help Information

Entering okv category resource --help returns detailed information about the action component of an okv command with the specified category and resource.

Syntax: okv category resource --help

Example Input: okv admin endpoint --help

Example Output:

Oracle Key Vault REST CLI Version 21.12.0.0.0 Built 10/13/2025 12:34
Usage: okv admin endpoint <action> [<rest-cli-parameters>] [<parameters>]

Command:
  <category> : admin
  <resource> : endpoint
  <action> :
    create                        -     Add a new endpoint to the Oracle Key Vault.
    delete                        -     Remove an endpoint from the Oracle Key Vault.
    update                        -     Update the settings of an endpoint.
    check-status                  -     Display the current state of an endpoint. The state will be either ACTIVE or PENDING.
    get                           -     Retrieve information about an endpoint.
    list                          -     Display a list of endpoints.
    download                      -     Download the endpoint software (okvclient.jar) to the specified directory.
    provision                     -     Download and install the endpoint software in the specified directory.
    re-enroll                     -     Re-enroll a previously enrolled endpoint.
    suspend                       -     Suspend an endpoint.
    resume                        -     Resume an endpoint.
    get-enrollment-token          -     Retrieve an enrollment token for a registered endpoint.
    re-enroll-all                 -     Re-enroll all previously enrolled endpoints.

okv option Component Help Information

Entering okv category resource action --help returns detailed information about the option component of an okv command with the specified category, resource, and action.

Syntax: okv category resource action --help

Example Input: okv admin endpoint provision --help

Example Output:

Oracle Key Vault REST CLI Version 21.12.0.0.0 Built 10/13/2025 12:34

Usage: okv admin endpoint provision [<rest-cli-parameters>] <parameters>

The okv admin endpoint provision command downloads and installs the endpoint software for an endpoint in the specified directory.

Command:
  <category> : admin
  <resource> : endpoint
  <action>   : provision

Required Parameters:
    --endpoint <arg>   Name of the endpoint.
    --location <arg>   Path to the location where to install the endpoint
                       software. For Transparent Data Encryption (TDE)
                       environments, specify WALLET_ROOT/okv as the
                       installation directory.

Optional Parameters:
    --auto-login <arg>   Enter one of the following values:
                         TRUE: to enable auto-login authentication
                         FALSE: (default) to store the endpoint
                         credentials that are used to connect to the
                         Oracle Key Vault server in a password-protected
                         wallet. When --auto-login is set to FALSE, then
                         you will be promoted to enter a password
                         interactively.
          --arch/arch    This option can have the value db26ai to
                         install the endpoint software to manage the
                         Oracle 23ai databases.

Running Oracle Key Vault RESTful Services Utility Commands

Oracle Key Vault provides a variety of ways to run RESTful services utility commands.

RESTful Services Utility Command Syntax

The RESTful services utility command syntax operates using the okv command.

The syntax used for RESTful services utility commands is as follows:

okv category resource action rest-cli-configuration-parameters command-parameters

In this specification:

In this guide, commands are identified using okv followed by category, resource, action, and if the command requires them, rest-cli-configuration-parameters command-parameters. For example, to create an endpoint, you would use the okv admin endpoint create command. This command’s full syntax is as follows:

okv admin endpoint create --endpoint endpoint_name --description "description" --email email_address --platform platform --type type --unique TRUE|FALSE

The Oracle Key Vault RESTful services utility commands syntax follows these rules:

Note: For backward compatibility, the RESTful services utility command line interface that existed before Oracle Key Vault release 21.1 is still supported. You can download okvrestclipackage.zip to use that interface.

Most of the RESTful services utility commands support JSON input. In this guide, the commands that support JSON provide an example of how to use JSON.

Ways of Running RESTful Services Utility Commands

You can run the Oracle Key Vault RESTful services utility commands either by directly specifying command-specific parameters in the command line, or by using the JSON syntax.

Running RESTful Services Utility Commands Using the Command Line

You run the RESTful services utility commands from the command line by specifying all command-specific parameters in the command line.

For example, okv manage-access endpoint-group add-endpoint has the endpoint-group and endpoint parameters:

okv manage-access endpoint-group add-endpoint --endpoint-group endpoint_group_name --endpoint endpoint_member

When specifying REST CLI configuration parameters in the command line, you must specify REST CLI configuration parameters before any command-specific parameters. In the following example, --profile hr is one of the rest_cli_configuration_parameters, and it is followed by the command_parameters for the okv managed-object key create command.

okv managed-object key create --profile hr --algorithm AES --length 128 --mask "ENCRYPT,DECRYPT,EXPORT"

Related Topics

Running RESTful Services Utility Commands Using the JSON Syntax

The RESTful services utility commands support JSON syntax, and after you have generated the JSON output, you can use it in combination with a command line execution of the command.

To run the RESTful services command using JSON input, you must first prepare a JSON input file with the command-specific parameter values and then run the command using parameter --from-json json-input-file.json.

The recommended process of running RESTful services utility commands using JSON input is as follows:

  1. Generate JSON input designed specifically for the command, by running the command with the --generate-json-input parameter. For example:

    okv managed-object key create --generate-json-input

    The generated JSON input for this command is as follows:

    {
  "service" : {
    "category" : "managed-object",
    "resource" : "key",
    "action" : "create",
    "options" : {
      "algorithm" : "#3DES|AES",
      "length" : "#112,168(3DES)|128,192,256(AES)",
      "mask" : [ "#ENCRYPT", "#DECRYPT", "#SIGN", "#VERIFY", "#WRAP_KEY", "#UNWRAP_KEY", "#EXPORT", "#DERIVE_KEY", "#GENERATE_CRYPTOGRAM", "#VALIDATE_CRYPTOGRAM", "#TRANSLATE_ENCRYPT", "#TRANSLATE_DECRYPT", "#TRANSLATE_WRAP", "#TRANSLATE_UNWRAP" ],
      "wallet" : "#VALUE",
      "attributes" : {
        "name" : {
          "value" : "#VALUE",
          "type" : "#text|uri"
        },
        "activationDate" : "#NOW|YYYY-MM-DD HH:mm:ss",
        "deactivationDate" : "#NOW|YYYY-MM-DD HH:mm:ss",
        "extractable" : "#TRUE|FALSE"
      },
      "customAttributes" : [ {
        "name" : "#VALUE",
        "value" : "#VALUE",
        "type" : "#TEXT|NUMBER|BYTE_STRING"
      } ],
      "cryptoParameters" : [ {
        "blockCipherMode" : "#VALUE",
        "paddingMethod" : "#VALUE",
        "hashingAlgorithm" : "#VALUE",
        "keyRoleType" : "#VALUE"
      } ]
    }
  }
}

  2. Save generated input to a file and then edit it so that you can perform the task. You must modify the values that begin with #. For this example, you could call the file create_key.json and then edit it to use the following values:

    {
  "service": {
    "category": "managed-object",
    "resource": "key",
    "action": "create",
    "options": {
      "algorithm": "AES",
      "length": "256",
      "mask": [
        "ENCRYPT",
        "DECRYPT"
      ],
      "wallet": "hr_wallet",
      "attributes": {
         "extractable" : "FALSE"
      }
    }
  }
}

  3. To perform the action, run the okv managed-object key create command with the --from-json parameter to specify the name of the JSON input file that you just edited.

    For example, to run the okv managed-object key create command by using the default configuration settings:

    okv managed-object key create --from-json create_key.json

    When using JSON input, you can also specify command parameters in the command line. The command parameters specified in the command line have higher precedence over the same parameters specified in the JSON input file.

    • Example 1: To create a key but with a different length than what is specified in the JSON file create_key.json, specify the length parameter in the command line:

      okv managed-object key create --from-json create_key.json --length 128

      Overriding command parameters in the command line allows use of the same JSON file for running the same command but with different parameters without having to modify the JSON input file.

    • Example 2: To apply the same attribute values for multiple managed objects, you specify the attribute settings in the input JSON file and specify the UUID of the object in the command line. Consider the following JSON input file add_attributes.json:

      {
  "service" : {
    "category" : "managed-object",
    "resource" : "attribute",
    "action" : "add",
    "options" : {
      "uuid" : "2359E04F-DA61-4F7C-BF9F-913D3369A93A",
      "attributes" : {
        "contactInfo" : "psmith@example.com",
        "deactivationDate" : "2024-12-31 09:00:00",
        "name" : {
          "value" : "prod-hrdb-mkey",
          "type" : "text"
         },
        "protectStopDate" : "2024-09-30 09:00:00"
      }
    }
  }
}

      To apply this attribute to an object with UUID 2359E04F-DA61-4F7C-BF9F-913D3369A93A, you run:

      okv managed-object attribute add --from-json add_attributes.json --uuid 2359E04F-DA61-4F7C-BF9F-913D3369A93A

Related Topics

Specifying the RESTful Services Utility Commands Output Format

You can use the REST CLI parameter –output_format to choose the output format between JSON and text.

By default, the output of RESTful services utility commands is in the JSON format. However, for certain commands, you can specify the --output_format text to produce the command output in the text format.

For example: Below command returns the UUID of the newly created key as the text output:

okv managed-object key create --output_format text --algorithm AES --length 25609285F83-CC1F-4FAF-BF6C-E2262733F369

Note: The --output_format text is only supported for these commands:

Naming Conventions for Parameters Specified at the Command Line and in JSON Files

The command parameters when specified on the command line use a different naming convention from the naming convention that is used in the JSON syntax.

The parameters in the JSON syntax use the camelCase naming convention (for example, walletUser, clientWallet). The naming convention for the parameters in the command line use follows these rules in general:

The corresponding command line parameter names for the parameters walletUser and clientWallet from the JSON syntax are --wallet-user and --client-wallet, respectively.

Creating a Script to Automatically Enroll Oracle Databases as Endpoints

You can create a script that database administrators can run to automatically enroll Oracle Database endpoints in Oracle Key Vault.

An Oracle Key Vault administrator can create a set of scripts and files that database administrators can later download from a shared location, and run on their database servers to automatically on-board their databases into Oracle Key Vault, without any further intervention by the Oracle Key Vault administrators. As the Oracle Key Vault administrator, you will package the following:

The following procedure explains how to create these components.

  1. Download the RESTful services package and store it in your working directory, where you will also create the other files.

    curl -O -k https://Oracle_Key_Vault_IP_address:5695/okvrestclipackage.zip

  2. If you have not done so already, then create a user and grant the Create Endpoint privilege to it.

    Use the Oracle Key Vault management console to create this user. For the procedure in this topic, this user will be named restuser_ron and will have the Create Endpoint privilege. A user with the System Administrator role creates the restuser_ron account and then grants the user the Create Endpoint privilege. Finally, the restuser_ron user must log in and change the one-time password to a permanent password. If you are preparing your Oracle Key Vault cluster to on-board ADB-on-ExaCC, additionally, the key administrator needs to grant the Create Endpoint Group privilege to restuser_Ron .

  3. Unzip the downloaded okvrestclipackage.zip file into a directory where you will create the other files.

    After you unzip the okvrestclipackage.zip file, you can use the tree command to see the contents of the unzipped directory structure.

    $ tree
bin

-- okv

-- okv.bat
lib
-- okvrestcli.jar
conf

-- okvrestcli.ini

-- okvrestcli_logging.properties

  4. Edit the bin/okv file.

    For example:

    #!/bin/bash
export OKV_RESTCLI_DIR=$(dirname "${0}")/..
#export OKV_RESTCLI_CONFIG=$OKV_RESTCLI_DIR/conf/okvrestcli.ini
if [ -z "$JAVA_HOME" ]
then
  echo "JAVA_HOME environment variable is not set."
  exit 1
fi

if [ -z "$OKV_RESTCLI_CONFIG" ]
then
  echo "OKV_RESTCLI_CONFIG environment variable is not set."
  exit 1
fi

export OKV_RESTCLI_JAR=$OKV_RESTCLI_DIR/lib/okvrestcli.jar
$JAVA_HOME/bin/java -jar $OKV_RESTCLI_JAR "$@"

    In this specification:

    • Uncomment the line export OKV_RESTCLI_CONFIG=$OKV_RESTCLI_DIR/conf/okvrestcli.ini.

  5. Edit the conf/okvrestcli.ini file.

    For example:

    [Default]
log_property=/usr/local/okv/conf/okvrestcli_logging.properties

server=192.0.2.181
okv_client_config=/usr/local/okv/conf/okvclient.ora

user=restuser_ron

client_wallet=/home/oracle

    In this specification:

    • server is the IP address of the Oracle Key Vault server (for example, 192.0.2.181).

    • user is the is the user name of the Oracle Key Vault user that you created in Step 2.

    • client_wallet is an absolute path to a wallet that will contain the permanent password of the restuser_ron user. Because you are including the user option, the command will pick up the user’s credentials from the wallet to establish a connection with the Oracle Key Vault server.

  6. Run the following command, which creates a wallet and inserts the password of the restuser_ron user into it.

    okv admin client-wallet add --client-wallet /home/oracle --wallet-user restuser_ron
Password: restuser_ron_password

    This command creates the password-protected wallet ewallet.p12 and the auto-login wallet cwallet.sso in the /home/oracle directory.

  7. Create a script similar to the run-me.sh script, which is part of the package that an Oracle Key Vault administrator creates for the database administrators to download.

    The run-me.sh creates the shell script okv-ep.sh, which contains unique names for the virtual wallet and the associated endpoints. Use the naming convention that your site normally uses for names of wallets and other components.

    $ more run-me.sh
#!/bin/bash
export EP_NAME=${ORACLE_SID^^}_on_${HOSTNAME/.*}
export WALLET_NAME=${ORACLE_SID^^}
curl -Ok https://192.0.2.181:5695/okvrestclipackage.zip
unzip -Vj okvrestclipackage.zip lib/okvrestcli.jar -d ./lib
cat > /home/oracle/okv-ep.sh  << EOF
#!/bin/bash
mkdir -pv ${ORACLE_BASE}/product/okv
okv manage-access wallet create --wallet ${WALLET_NAME} --unique FALSE
okv admin endpoint create --endpoint ${EP_NAME} --description "$HOSTNAME, $(hostname -i)" --type ORACLE_DB --platform
 LINUX64 --subgroup "USE CREATOR SUBGROUP" --unique FALSE --strict-ip-check TRUE
okv manage-access wallet set-default --wallet ${WALLET_NAME} --endpoint ${EP_NAME}
expect << _EOF
    set timeout 120
    spawn okv admin endpoint provision --endpoint ${EP_NAME} --location ${ORACLE_BASE}/product/okv --auto-login FALSE
    expect "Enter Oracle Key Vault endpoint password: "
    send "change-on-install\r"
    expect eof
_EOF
EOF
chmod +x okv-ep.sh
more ./okv-ep.sh

    In this specification:

    1. export ... creates the endpoint name from uppercase(ORACLE_SID)_on_short_hostname and a WALLET_NAME from uppercase (ORACLE_SID). In an Oracle Real Application Clusters (Oracle RAC) environment, replace ORACLE_SID with an uppercase (ORACLE_UNQNAME).

    2. curl ... downloads the correct, current version of the Oracle Key Vault RESTful services package when the database administrator executes the run-me script.

    3. unzip ... extracts only the okvrestcli.jar file and places it into the ./lib directory.

    4. mkdir -pv ${ORACLE_BASE}/product/okv creates the installation directory for Oracle Key Vault client software. For Oracle Database release 18c and later, this is equal to WALLET_ROOT/okv. (/product/okv is an example directory.)

    5. okv manage-access wallet create creates a (shared) virtual wallet in Oracle Key Vault. Here, the wallet name equals uppercase($ORACLE_SID).

    6. okv admin endpoint create creates an endpoint, named after the endpoint created in the export command in Step a, with type=ORACLE_DB, platform=LINUX64, free text fully_qualified_hostname, IP address. The --subgroup option determines the preferred Oracle Key Vault read/write pair that the database endpoint will connect to first. Here, it is the Oracle Key Vault subgroup where the endpoint will be enrolled.

    7. okv manage-access wallet set-default sets the default wallet, associating the endpoint created in Step f with the shared wallet created in Step e.

    8. expect executes the okv admin endpoint provision command and automatically inserts a password when prompted. The benefit of using expect is that the password cannot be retrieved using the ps command.

  8. Duplicate the run-me.sh script so that you will have a primary script and a secondary script, to be used for different situations.

    The primary script will be used for single-instance databases and the first Oracle RAC instance. The secondary script will be used for the remaining Oracle RAC nodes of a primary database and all nodes of the corresponding standby Oracle RAC database. This secondary script will associate the endpoints with the shared wallet that was created on the first instance.

    1. Rename the run-me.sh script to primary-run-me.sh.

    2. Copy primary-run-me.sh to a new file named secondary-run-me.sh.

    3. Open secondary-run-me.sh and remove the following line:

      okv manage-access wallet create --wallet ${ORACLE_SID^^} --unique FALSE

  9. Make the scripts executable.

    $ chmod +x primary-run-me.sh
$ chmod +x secondary-run-me.sh

  10. Test each of the scripts to ensure that they can create a okv-ep.sh file.

    $ ./primary-run-me.sh
$ ./secondary-run-me.sh

  11. Confirm that the names for the virtual wallets and endpoints follow your naming convention by executing the following command:

    $ more okv-ep.sh

  12. Create two .zip file packages for each of the scripts.

    Each package must have the following contents:

    • primary.zip contains primary-run-me.sh, ewallet.p12, cwallet.sso, as well as the bin and conf directories. Do not include the ./lib directory. The ./lib library will be created and populated on demand when the primary-run-me.sh script is executed.

    • secondary.zip contains secondary-run-me.sh, ewallet.p12, cwallet.sso, as well as the ./bin and ./conf directories. Do not include the ./lib directory. The ./lib library will be created and populated on demand when the secondary-run-me.sh script is executed.

  13. Make these two .zip files available to the database administrators for them to download from a shared file server.

  14. Instruct the database administrators where to download and run the scripts:

    • Run the primary-run-me.sh script on single-instance databases or the first Oracle RAC instance. For an Oracle Data Guard environment, run the script on the lead node of the primary Oracle RAC database.

    • Run the secondary-run-me.sh script on all the remaining Oracle RAC nodes of a primary database and all nodes of the corresponding standby Oracle RAC database.

Related Topics

Naming Guidelines for Objects

The naming guidelines affect the following Oracle Key Vault objects: users, user groups, endpoints, endpoint groups, and virtual wallets.

The naming conventions for these objects are as follows:

How to Set the Date and Time in RESTful Services Utility Commands

You specify the date or timestamp, and duration using the supported formats.

Duration Format

The duration format specifies a time period or a time interval. This format is based on a subset of the ISO-8601 standard. The syntax is as follows:

PnYnMnDTnHnMnS

or

PnW

In this specification:

Examples:

Date and Time Formats

The date and time formats that are used in the RESTful services utility are in UTC. The four ways of setting the date and time are as follows:

Note: Setting the date-time attributes (such as ActivationDate, DeactivationDate, ProcessStartDate, and ProtectStopDate) for a security object to the epoch time has the same effect of not setting the attribute at all. For example, if you set the ActivationDate attribute of a security object to 1970-01-01 00:00:00 to immediately activate the object, then the object remains in the Pre-Active state. This is because Oracle Key Vault treats the epoch value of the attribute as if the attribute is not set at all. Listing the attributes of an object does not include date-time attributes that are set to epoch time value.

Using RESTful Services with LDAP Users

Both regular Oracle Key Vault administrators and properly authorized LDAP users can log in to a server to run Oracle Key Vault RESTful services utility commands.

When an LDAP user runs the Oracle Key Vault RESTful services utility commands, Oracle Key Vault first authenticates the user before command is run. The user’s authorization that is effective for the session is determined during authentication process.

Related Topics