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 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 1.7.0.21 or later (the Java Runtime Environment (JRE) is provided with Oracle Database release 12.2, so you do not need to install the JRE if you already have Oracle Database release 12.2 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 a JRE version 1.7.0.21 or later, and then set JAVA_HOME and PATH appropriately. OpenJDK is not supported.

    • For the provision command, a soft link from /usr/bin/java either to the extra JRE installation (for older databases before Oracle Database release 12.2.0.1) or $ORACLE_HOME/jdk/jre/bin/java for Oracle Database release 12.2.0.1 and later. You can confirm by executing namei /usr/bin/java at the command line.
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 Oracle Key Vault wrapper script, set the OKV_RESTCLI_CONFIG variable.
    OKV_RESTCLI_CONFIG sets the location of the okvrestcli.ini configuration file. The wrapper script for Linux platforms is okv and the wrapper 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 execute RESTful services 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 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 execute Oracle Key Vault RESTful services 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 commands without the need for you to manually enter them at the command line each time that you want to execute 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 execute 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 execute 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 execute managed-object RESTful services utility commands, which must always be executed 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 execute the command.

    Oracle Key Vault does not use the user 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.

  • 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 executed. 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 execute 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 execute 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 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 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 execute 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 execute the RESTful services 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 = ./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 Executing Oracle Key Vault RESTful Services Commands

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

Parent topic: Getting Started with Oracle Key Vault RESTful Services

2.3.1 RESTful Services Command Syntax

The RESTful services command syntax operates using the okv command.

The syntax used for RESTful services 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 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 Oracle Key Vault wrapper script okv itself. This frees you of the necessity of having to specify this configuration file every time that you execute 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 commands support JSON input. In this guide, the commands that support JSON provide an example of how to use JSON.

Parent topic: Executing Oracle Key Vault RESTful Services Commands

2.3.2 Ways of Executing RESTful Services Commands

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

Parent topic: Executing Oracle Key Vault RESTful Services Commands

2.3.2.1 Executing RESTful Services Commands Using the Command Line

You execute the RESTful services 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.3.2.2 Executing RESTful Services Commands Using the JSON Syntax

The RESTful services 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 execute the RESTful services command using JSON input, you must first prepare a JSON input file with the command-specific parameter values and then execute the command using parameter --from-json json-input-file.json.

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

  1. Generate JSON input designed specifically for the command, by executing 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"
    }
  }
}
  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"
    }
  }
}

  3. To perform the action, execute 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 execute 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 executing 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" : {
      "attributes" : {
        "contactInfo" : "pfitch@example.com",
        "deactivationDate" : "2024/12/31 09:00:00",
        "name" : "PROD-HRDB-MKEY",
        "protectStopDate" : "2024/09/30 09:00:00"
      }
    }
  }
}

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

      okv managed-object attribute add --from-json add_attributes.json --uuid 2359E04F-DA61-4F7C-BF9F-913D3369A93A
2.3.2.3 Naming Conventions for Parameters Executed 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.3.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 execute 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.
  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_CONFIG=./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

java -jar ./lib/okvrestcli.jar "$@"

    In this specification:

    • Uncomment the line export OKV_RESTCLI_CONFIG=./conf/okvrestcli.ini.
    • Ensure that you have set the JAVA_HOME environment variable to a Java Runtime Environment (JRE) installation with the minimum version 1.7.0.21. For Oracle Database release 12.2.0.1 and later, you can use the Java installation under $ORACLE_HOME. OpenJDK is not supported.
  5. Edit the conf/okvrestcli.ini file.
    For example: 
    [Default]
log_property=./conf/okvrestcli_logging.properties
server=192.0.2.181
okv_client_config=./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. Execute 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/.*}
cat > /home/oracle/okv-ep.sh << EOF
#!/bin/bash
mkdir -pv ${ORACLE_BASE}/product/okv
okv manage-access wallet create --wallet ${ORACLE_SID^^} --unique FALSE
okv admin endpoint create --endpoint ${EP_NAME} --description "$HOSTNAME, $(hostname -i)" --type ORACLE_DB --platform LINUX64 --unique FALSE
okv manage-access wallet set-default --wallet ${ORACLE_SID^^} --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.
    2. 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.)
    3. okv manage-access wallet create creates a (shared) virtual wallet in Oracle Key Vault. Here, the wallet name equals uppercase($ORACLE_SID).
    4. 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.
    5. okv manage-access wallet set-default sets the default wallet, associating the endpoint created in step d with the shared wallet created in step c.
    6. 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, and bin, conf, and lib directories.
    • secondary.zip contains secondary-run-me.sh, ewallet.p12, cwallet.sso, and bin, conf, and lib directories.
  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 execute the scripts:
    • Execute the primary-run-me.sh script on single-instance databases and the first Oracle RAC instance. For an Oracle Data Guard environment, execute the script on the lead node of the primary Oracle RAC database.
    • Execute 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: Executing Oracle Key Vault RESTful Services Commands

2.4 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 are in a multi-master cluster environment that has any nodes that have not yet been upgraded to Oracle Key Vault release 18.5 or later, then use a maximum of 24 bytes for the object name.
  • The names of users, user groups, endpoints, and endpoint groups are not case sensitive. For example, pfitch and PFITCH 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.5 Using RESTful Services with LDAP Users

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

When an LDAP user executes the Oracle Key Vault RESTful services commands, Oracle Key Vault first authenticates the user before command is executed. 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