1. RESTful Services Administrator's Guide
  2. Getting Started with Oracle Key Vault RESTful Services

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

2.1 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.
  • Disabling RESTful Services
    You should enable RESTful services for short periods during when administrative tasks are performed.

Parent topic: Getting Started with Oracle Key Vault RESTful Services

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

Parent topic: Enabling or Disabling Oracle Key Vault RESTful Services

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

2.1.1.2 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.
2.1.1.3 Step 3: Enable RESTful Services

After you have enabled 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 the RESTful Services section within it.

  3. Check the box to the right of Enable.
  4. Click Save.
2.1.1.4 Step 4: Download the RESTful Services Utility

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

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.
  • Use one of the following methods to download the Oracle Key Vault RESTful services utility okvrestclipackage.zip file:
    • From the Home page of the Oracle Key Vault management console:
      1. Log in as a user with the System Administrator role.
      2. Select the System tab.
      3. In the left sidebar, select Settings.
      4. Under System Configuration, select RESTful Services.
      5. In the RESTful Services dialog box, select Download.

        To download the Oracle Key Vault Classic RESTful Service Utility, click Download Classic Utility. For information about using this version, see the release 18.6 version of Oracle Key Vault Administrator's Guide

      6. In the Opening okvrestclipackage.zip dialog box, select Save to save the okvrestclipackage.zip file locally.
    • From the Endpoint Enrollment and Software Download of the Oracle Key Vault management console:
      1. Connect to the Oracle Key Vault management console.

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

      2. In the lower-right corner of the login page under Login, click Endpoint Enrollment and Software Download.
      3. Click the Download RESTful Service Utility tab.
      4. Click the Download button.

        To download the Classic RESTful Service Utility, click Download Classic Utility.

      5. Download the okvrestclipackage.zip to a secure location.
    • Using a command-line HTTP client such as wget or curl. In a primary-standby configuration, enter the IP address of the primary database. For example:
      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
2.1.1.5 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.

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

Parent topic: Enabling or Disabling Oracle Key Vault RESTful Services

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

Parent topic: Getting Started with Oracle Key Vault RESTful Services

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

Parent topic: Oracle Key Vault RESTful Services Configuration and Logging Files

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

2.2.1.2 okvrestcli.ini Configuration Parameters

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

The okvrestcli.ini parameters are as follows:

  • server: Determines the target Oracle Key Vault server where command is sent for execution. Enter the IP address of this server. Server information can also be obtained from the okvclient.ora file when you set the okv_client_config parameter.

    In a multi-master deployment of an Oracle Key Vault cluster, Oracle Key Vault dynamically updates the server information in the endpoint's configuration file okvclient.ora based on the endpoint's cluster subgroup setting, as well as any changes to the cluster topology or the state of the Oracle Key Vault cluster nodes. Using the server information from endpoint's okvclient.ora enables Oracle Key Vault to automatically select the best Oracle Key Vault node to run the REST commands without you having to constantly update the SERVER parameter in okvrestcli.ini.

  • okv_client_config: Specifies the full path of the okvclient.ora file for an endpoint. By default, this file is located in the $OKV_HOME/conf directory. This parameter is mandatory if you want to run managed-object RESTful services utility commands, which must always be run with the identity of an endpoint. The Oracle Key Vault RESTful services utility uses only the following information from the okvclient.ora file:

    • server information: IP address or host name of Oracle Key Vault server(s).
    • SSL_WALLET_LOC: location of the wallet that the endpoint uses.

    This is a string value and is required.

  • user: Specifies the Oracle Key Vault user who is executing the RESTful services command. The user must have appropriate privileges to run the command.

    Oracle Key Vault does not use the user parameter when the RESTful services utility commands for the managed-object category are run. These commands are always run with the identity of an endpoint that is set with the okv_client_config parameter.

  • client_wallet: Specifies the absolute path to a wallet which contains user credentials. This wallet can be used to log into the Oracle Key Vault server without having to manually specify the user’s password. The user information is obtained from the user parameter. The client_wallet parameter enables implementation and use of automation scripts that need to run in an unattended mode.

    Oracle Key Vault does not use the client_wallet parameter when the RESTful services utility commands for the managed-object category are run. These commands are always executed with the identity of an endpoint that is set with the okv_client_config parameter.

  • password: Specifies the password of the user executing the RESTful services utility commands. If client_wallet is specified, then the password parameter is not required. If both client_wallet and password parameters are specified, then the password parameter takes precedence over client_wallet.

    Oracle Key Vault does not use the password parameter when the RESTful services utility commands for the managed-object category are executed. These commands are always executed with the identity of an endpoint that is set with the okv_client_config parameter.

  • log_property: Specifies the full path of the Java logging property file. If this parameter is not set, then when you execute a RESTful command, Oracle Key Vault generates a log file with the default name in the current directory with the INFO level along with the message in a log file saying log_property is not configured. The default log property file is a part of the downloaded okvrestclipackage.zip file. This file enables you to customize the log file and its format. This is a string value and it is optional.

2.2.1.3 [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:

  • Named profile section header denoted as [profile_name]
  • Listing of configuration parameters under the name profile header

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.

2.2.1.4 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
  • Example 1: To specify the default user, psmith, simply omit any reference to this user from the command line. 
    okv manage-access endpoint-group add-endpoint --endpoint-group epg_1 --endpoint ep_1
  • Example 2: To override the default user and specify user jgreenberg, who is in the HR profile, specify the HR profile in the command line. 
    okv manage-access endpoint-group add-endpoint --profile HR --endpoint-group epg_1 --endpoint ep_1
  • Example 3: To override all the user settings in okvrestcli.ini, include the --user setting in the command line. 
    okv manage-access endpoint-group add-endpoint --user kjones --endpoint-group epg_1 --endpoint ep_1

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:

  • Example 1: Assume that the okvrestcli.ini configuration file has the following setting:
    
[DEFAULT]
server=192.0.2.190

    To use this default setting (that is, to use IP address 192.0.2.190), omit any reference to it from the command line.

    okv manage-access endpoint-group add-endpoint --endpoint-group epg_1 --endpoint ep_1
  • Example 2: Assume that the okvrestcli.ini configuration file has the following setting:
    [DEFAULT]
okv_client_config=/usr/local/okv/okvclient/okvclient.ora

    The okv_client_config parameter points to an okvclient.ora file that contains the server setting that you want to use. Because okv_client_config is in the [DEFAULT] section, to use this okvclient.ora, omit the reference to it from the command line. 

    okv manage-access endpoint-group add-endpoint --endpoint-group epg_1 --endpoint ep_1
  • Example 3: Assume that the okvrestcli.ini configuration file has the following settings for the default and for a profile called [NODE_1]:
    [DEFAULT]
okv_client_config=/usr/local/okv/okvclient/okvclient.ora

[NODE_1]
server=192.0.2.191

    To override the default server setting from okv_client_config with the [NODE_1] profile setting of 192.0.2.191, include the --profile parameter in the command line. 

    okv manage-access endpoint-group add-endpoint --profile node_1 --endpoint-group epg_1 --endpoint ep_1
  • Example 4: Assume that the okvrestcli.ini configuration file has the following settings:
    [DEFAULT]
server = 192.0.2.191

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

    To override the default and use the server setting in the okvclient.ora file, as with Example 3, include the --profile parameter in the command. 

    okv manage-access endpoint-group add-endpoint --profile hr --endpoint-group epg_1 --endpoint ep_1
  • Example: 5: Assume that the okvrestcli.ini configuration file is as follows:
    [DEFAULT]
server = 192.0.2.191

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

    To override all of these settings, directly specify the appropriate server IP address setting in the command line. 

    okv manage-access endpoint-group add-endpoint --server 192.0.2.192 --endpoint-group epg_1 --endpoint ep_1

    This works with the okv_client_config parameter setting as well. 

    okv manage-access endpoint-group add-endpoint --okv_client_config /usr/local/okv/okvclient/okvclient.ora --endpoint-group epg_1 --endpoint ep_1

    The following example uses both a named profile (HR) and the --server parameter. The --server parameter overrides the server information from the okvclient.ora file specified in the [HR] profile. 

    okv managed-object key create --profile HR --server 192.0.2.192 --algorithm AES --length 256 --mask "ENCRYPT,DECRYPT" --wallet hr_wallet
2.2.1.5 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.
  • To use a different configuration file, include the --config parameter when you run the command. Add the --config parameter before the command-specific parameters, as follows:
    okv managed-object key create --config full_path_to_conf_file --algorithm AES --length 128 --mask "ENCRYPT,DECRYPT,EXPORT"

    Follow the same precedence rules that you would follow for the okvrestcli.ini file. For example, suppose the new configuration file has a profile that you want to use called [HR]. You would specify it as follows: 

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

2.2.2 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:

  • java.util.logging.FileHandler.pattern specifies one of the following patterns for generating the output file name. The default is %h/java%u.log.
    • / is the local path name separator.
    • %h is the value of the user.home system property.
    • %g is the generation number to distinguish rotated logs.
    • %u is a unique number to resolve conflicts.
    • %% translates to a single percent sign %.
  • java.util.logging.FileHandler.limit specifies an approximate maximum amount to write (in bytes) to any one file. If this is zero, then there is no limit. The default is 200000.
  • java.util.logging.FileHandler.count specifies how many output files to cycle through. The defaults is 5.
  • java.util.logging.FileHandler.formatter specifies the name of a Formatter class to use. The default is java.util.logging.XMLFormatter.
  • java.util.logging.ConsoleHandler.level specifies the default level for the handler. The default to INFO.

    The available logging levels are ALL, TRACE, FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE, and OFF.

    Any logging at INFO and above provides complete details. If you set the logging level to SEVERE, then you will only see messages with the SEVERE logging level, which generally correspond to serious problems. To diagnose the issue, you may need more details and that can be obtained with levels that produce more information, not just the occurrences of the serious issues.

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

Parent topic: Oracle Key Vault RESTful Services Configuration and Logging Files

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

Parent topic: Getting Started with Oracle Key Vault RESTful Services

2.3.1 okv category Component Help Information

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

Syntax: okv --help or okv -help

Example Input: okv --help or okv -help

Example Output:

Oracle Key Vault REST CLI Version 21.5.0.0.0 Built 11/09/2022 17:44
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.                      

<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
    --password <arg>            User password.
    --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.

Parent topic: Getting Help Information for RESTful Services Utility Commands

2.3.2 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.4.0.0.0 Built 12/13/2021 01:19
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.

Parent topic: Getting Help Information for RESTful Services Utility Commands

2.3.3 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.4.0.0.0 Built 12/13/2021 01:19
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.

Parent topic: Getting Help Information for RESTful Services Utility Commands

2.3.4 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.4.0.0.0 Built 12/13/2021 01:19

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

Parent topic: Getting Help Information for RESTful Services Utility Commands

2.4 Running Oracle Key Vault RESTful Services Utility Commands

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

Parent topic: Getting Started with Oracle Key Vault RESTful Services

2.4.1 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:

  • category refers to the type of command you are executing, such as managed-object, admin, cluster, or backup commands.
  • resource is a type of resource on which you are executing the command, such as endpoint, wallet, or certificate.
  • action is the action to perform on the resource, such as create, add, locate, or delete.
  • rest-cli-configuration-parameters include parameters such as --user, --client_wallet, and so on, that you specify in the REST CLI configuration file. These parameters apply to all commands.
  • command-parameters are parameters that a command may need, such as the --description or --email parameters when you create an endpoint

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 the these rules:

  • It requires that you specify the command in this order: okv category resource action rest-cli-configuration-parameters command-parameters. You must specify the category, resource, and action in the order shown here. REST CLI configuration parameters must be specified before any command-specific parameters.
  • It enables the configuration file (okvrestcli.ini) to be identified by using the OKV_RESTCLI_CONFIG environment variable. You set this variable in the RESTful services command line utility script okv itself. This frees you of the necessity of having to specify this configuration file every time that you run the command.

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.

Parent topic: Running Oracle Key Vault RESTful Services Utility Commands

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

Parent topic: Running Oracle Key Vault RESTful Services Utility Commands

2.4.2.1 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"
2.4.2.2 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", "#WRAP_KEY", "#UNWRAP_KEY", "#EXPORT", 
         "#DERIVE_KEY", "#GENERATE_CRYPTOGRAM", "#VALIDATE_CRYPTOGRAM", 
         "#TRANSLATE_ENCRYPT", "#TRANSLATE_DECRYPT", "#TRANSLATE_WRAP",
         "#TRANSLATE_UNWRAP" ],
      "wallet": "#VALUE",
      "attributes": {
         "extractable" : "#TRUE|FALSE"
      }
    }
  }
}
  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 key_create.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
2.4.2.3 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:
  • okv managed-object certificate get
  • okv managed-object certificate register
  • okv managed-object certificate-request get
  • okv managed-object certificate-request register
  • okv managed-object key create
  • okv managed-object key get
  • okv managed-object key register
  • okv managed-object object activate
  • okv managed-object object destroy
  • okv managed-object object locate
  • okv managed-object object revoke
  • okv managed-object opaque get
  • okv managed-object private-key register
  • okv managed-object public-key get
  • okv managed-object public-key register
  • okv managed-object secret get
  • okv managed-object secret register
  • okv managed-object wallet add-member
  • okv managed-object wallet delete-member
  • okv managed-object wallet list
2.4.2.4 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 parameter name is prefixed by two hyphens (for example, --user)
  • Each word is separated by a hyphen (for example, --endpoint-group)
  • All words are in lowercase (for example, --endpoint)

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

2.4.3 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:
  • Oracle Key Vault RESTful services package
  • ewallet.p12 and cwallet.sso wallet files
  • run-me.sh script

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

Parent topic: Running Oracle Key Vault RESTful Services Utility Commands

2.5 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:

  • You can include the following characters in the names of endpoints, endpoint groups, user groups, and virtual wallets: letters (a–z, A–Z), numbers (0-9), underscores (_), periods (.), and hyphens (-).
  • You can include the following characters in the names of users: letters (a–z, A–Z), numbers (0-9), and underscores (_).
  • In most environments, the maximum number of bytes allowed for the name length is 120 bytes. If you have an Oracle Key Vault cluster with version 18.4 and older, the maximum object names length is 24 bytes.
  • The names of users, user groups, endpoints, and endpoint groups are not case sensitive. For example, psmith and PSMITH are considered the same user in Oracle Key Vault.
  • The names of virtual wallets are case sensitive. For example, wallet_hr and WALLET_HR are considered two separate wallets in Oracle Key Vault.

Parent topic: Getting Started with Oracle Key Vault RESTful Services

2.6 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:

  • P is the duration designator (for period) placed at the start of the duration representation.
  • n is a numeric value.
  • The capital letter following the Pn is a date or time value. Date value is as follows:
    • Y means the number of calendar years.
    • M means the number of calendar months.
    • D means the number of calendar days.
    • W means the number of weeks. This option cannot be specified with any other option including time values.
  • T indicates that the remaining values represent time values, as follows:
    • nH means n hours.
    • nM means n minutes.
    • nS means n seconds.

Examples:

  • 10 minutes: PT10M
  • 2 hours 30 minutes: PT2H30M
  • 5 hours: PT5H
  • 3 days: P3D
  • 45 seconds: PT45S
  • 5 hours, 10 minutes: PT5H10M
  • 4 weeks: P4W

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:

  • timestamp. This format is compatible with ISO 8601. This example translates to "start the activation date at 9 a.m. on December 31, 2024":
    "activationDate" : "2024-12-31 09:00:00",
  • NOW. The following example sets the activation date to the current time when the command is run:
    "activationDate" : "NOW",
  • timestamp+duration. This example translates to "start the activation date at 1 p.m. on December 31, 2024":
    "activationDate" : "2024-12-31 09:00:00+PT4H",
  • NOW+duration. The following example translates to "set the activate date 10 minutes from now":
    "activationDate" : "NOW+PT10M",

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.

Parent topic: Getting Started with Oracle Key Vault RESTful Services

2.7 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.
  • When executing a RESTful service command, provide the user name and domain name of the user with the --user parameter using the following methods:
    • The LDAP user name in any of the supported formats (shown below) and the domain name separate by a vertical-bar (|).
      • sAMAccountName|LDAP_domain_name

        Example: psmith|hr.example.com

      • NetBiosDomainName\\sAMAccountName|LDAP_domain_name.

        Example: hr\\psmith|hr.example.com

        The double backslash (\\) interprets hr\\psmith as hr\psmith.

      • userPrincipalName|LDAP_domain_name

        Example: psmith@hr.example.com|hr.example.com

    • The user principal name of the LDAP user.

      Example: psmith@hr.example.com

Related Topics

Parent topic: Getting Started with Oracle Key Vault RESTful Services