1. Administrator's Guide
  2. Oracle Key Vault Administration and Key Management with RESTful Services

13 Oracle Key Vault Administration and Key Management with RESTful Services

The Oracle Key Vault RESTful Services utility automates Oracle Key Vault administration tasks for a large distributed deployment.

13.1 About RESTful Services

The Oracle Key Vault tasks that you can automate using RESTful services include endpoint enrollment, virtual wallet management, and key management.

Though the Oracle Key Vault management console user interface is efficient for managing several endpoints, the process of defining access control mappings between endpoints and virtual wallets is a manual one, with human administrators having to click through the user interface.

A large distributed enterprise deployment often requires automation through scripting to enable mass deployment. The RESTful services feature in Oracle Key Vault enables you to enroll and provision hundreds of endpoints, and define access control mappings between endpoints and their respective virtual wallets, to facilitate faster deployment with less human intervention. Additionally, you can automate the management of users, user groups, and endpoint groups with this feature.

With RESTful services, you can enroll and provision endpoints, create endpoint groups, and define access control mappings between endpoints, endpoint groups and virtual wallets. You can execute a single service command from the command line, or execute multiple service commands from a script. To run the service commands from the command line or the script, you will need a configuration file with certain properties set. In order to run the RESTful Service utility, the endpoint must have at minimum Java Runtime Environment version 1.7.0.21 installed.

You can use RESTful services in both Oracle Real Application Clusters (Oracle RAC) and multitenant environments. The configuration process in these environments is identical to the single instance environment. In an Oracle RAC environment, Oracle Key Vault virtual wallets must be shared between the Oracle RAC instances. In other words, each Oracle RAC-enabled database will have one virtual wallet in Oracle Key Vault. All endpoints that belong to that database will have that virtual wallet as their default wallet.

After you use RESTful services to enroll and provision endpoints, you should disable the RESTful services to minimize the number of entry points to Oracle Key Vault.

You will follow these general steps to use the RESTful services execution process:

  1. Enable RESTful services from the Oracle Key Vault management console.

  2. Download the RESTful service utility okvrestservices.jar.

  3. Create a configuration file, and then set the properties for the services that you want to run.

  4. Execute the service using the RESTful service utility okvrestservices.jar, the configuration file, and service command plus options.

  5. To run multiple RESTful service commands you must:

    1. Create a script, and write the RESTful commands into the script.

    2. Execute the services using the RESTful service utility okvrestservices.jar, the configuration file, and the script file.

  6. Disable RESTful services when you are finished enrolling and provisioning endpoints.

Parent topic: Oracle Key Vault Administration and Key Management with RESTful Services

13.2 Required Privileges for Using RESTful Services

The required RESTful services privileges are consistent with the privileges required to perform the same task in the Oracle Key Vault management console.

For example, if you want to add and manage endpoints, then you must have the System Administrator role or the Manage Endpoint privilege. If you want to manage endpoint groups, then you must have the Key Administrator role or Manage Endpoint Group privilege. If you want to work with wallets and keys, then you must have the Key Administrator role. These roles and privileges are required for connecting Oracle databases to Oracle Key Vault. For MySQL databases, you only need the Key Administrative role because MySQL does not use wallets. You do not need to have endpoint administrator privileges to use RESTful services.

The RESTful commands require either the System Administrator role, the Key Administrator role, the Manage Endpoint privilege, or the Manage Endpoint Group privilege. To simplify the use of RESTful services, you can create a user who has both of these roles or privileges. Typically, this user is an administrator who must self-register their databases with Oracle Key Vault by using scripts that will need to perform the actions that need both of these privileges.

Parent topic: Oracle Key Vault Administration and Key Management with RESTful Services

13.3 Enabling RESTful Services

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

Parent topic: Oracle Key Vault Administration and Key Management with RESTful Services

13.3.1 Step 1: Check the Endpoint System Requirements

Before you can provision endpoints with the REST API, you must have the tools to transfer data securely across the network.

  1. Log in to the endpoint as an endpoint administrator.
  2. Ensure that you have the following tools:
    • cURL version that supports Transport Layer Security (TLS) 1.2 or later
    • 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.

Parent topic: Enabling RESTful Services

13.3.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 the System Administrator role.
  2. Select System, then System Settings from the left sidebar.
    The Settings page appears. Go to the Network Services 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.

Parent topic: Enabling RESTful Services

13.3.3 Step 3: Enable RESTful Services

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

  1. Log in to the Oracle Key Vault management console as a user with the System Administrator role.
  2. Select System, then System Settings from the left sidebar.

    The Settings page appears. Go to the RESTful Services section.

  3. Check the box to the right of Enable.
  4. Click Save.

Parent topic: Enabling RESTful Services

13.3.4 Step 4: Download the RESTful Software Utility

The RESTful software utility is in the okvrestservices.jar file.

  • Use one of the following methods to download the okvrestservices.jar file:
    • From the Home page of the Oracle Key Vault management console:
      1. Log in as a user with the System Administrator role.
      2. Click RESTful Service Utility under Downloads in the left sidebar.

        The Download RESTful Utility page appears.

      3. Click Download in the top right.

        A directory window appears with a prompt to save the utility file okvrestservices.jar in a local directory.

      4. Save the file to a secure location.
    • 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 OKV Automation Utility tab.
      4. Click the Download button.
      5. Download the okvrestservices.jar 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/okvrestservices.jar  
curl -k https://ip_address:5695/okvrestservices.jar -o okvrestservices.jar 
curl -O -k https://ip_address:5695/okvrestservices.jar

Related Topics

Parent topic: Enabling RESTful Services

13.4 Managing the RESTful Services Configuration File

You can use a configuration file to execute RESTful service commands either individually or in a group.

Parent topic: Oracle Key Vault Administration and Key Management with RESTful Services

13.4.1 About Managing the RESTful Services Configuration File

The RESTful services key management commands are designed for administrators who are responsible for managing keys that are uploaded to Oracle Key Vault.

You must use a configuration file to run the RESTful service utility, okvrestservices.jar, whether you run the utility from the command line or from a script. You can use the okvclient.ora file that was created when you deployed the Oracle Key Vault client software, or you can create a new configuration file. In a multi-master cluster environment, you can use one of the read-write nodes having its own configuration file. However, Oracle recommends that you use okvclient.ora as an configuration file to take advantage of the Oracle Key Vault multi-master cluster capabilities.

Note:

Script mode is not available for the KMIP RESTful service.

Related Topics

Parent topic: Managing the RESTful Services Configuration File

13.4.2 Configuration File Creation Guidelines

You should follow the recommended guidelines to avoid script execution errors.

  • Be aware that the commands and syntax in the script are identical to those used on the command line.

  • Ensure that each line in the script is either a command or a line starting with the character #.

  • Put each command on its own line.

  • Start each line that does not have a command with the # character.

  • Use the # character for comments and blank lines.

  • Remember that the order in which command options appear do not matter.

  • Ensure that all required options have valid values.

  • Specify the -i or --script option when you execute the script.

  • Enclose descriptions that are used for the -d or --desc option in double quotation marks if they contain spaces.

Parent topic: Managing the RESTful Services Configuration File

13.4.3 Creating the RESTful Services Configuration File

You must set properties in the configuration file that the RESTful service utility will use to run commands.

  1. Use the okvclient.ora file in the default location or create a file using any descriptive name.
    The default location is the ssl directory where you deployed the okvclient.jar file.
    For example, for an endpoint named hr_db, it could be called hr_db_endpoint.conf.
  2. Open the file and set the properties shown in the following table.

    Table 13-1 Properties to Set in the Configuration File

    Property Value Option Description

    server

    string

    Required

    Specifies the Oracle Key Vault server host name or IP address. The RESTful service utility. It uses the standard HTTPS port 443, which is optional. Specifying only the IP address or only host name is sufficient.

    script

    string

    Optional (required only for multiple RESTful service commands)

    Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands. Not used by KM REST API.

    log_level

    string

    Required

    Specifies one of the following log levels:

    • all logs every message

    • severe logs critical errors

    • warning logs non-critical errors that might pose problems

    • info logs general information

    • fine logs detail; is useful for debugging

    • finest logs the most detailed logging information

    ssl_wallet_loc string Optional (required only if the configuration file is not okvclient.ora in KMIP REST) Specifies the path to the Secure Sockets Layter (SSL) deployment directory for okvlient.ora. It is the location ofewallet.p12 and cwallet.sso which are deployed from the okvclient.jar file.

    log

    string

    Optional

    Specifies the absolute path to the log file. Set this property if you want to create a custom log file in a location of your choice. If you omit this setting, then the results are logged in the default log file okvrestservices.log and placed in the current directory as the default log file location.

    usr

    string

    Optional

    Specifies for the Oracle Key Vault account user name. You will be prompted to enter the user name, if you omit setting this property. Typically this user has the System Administrator or Key Administrator role with the necessary privileges to run the commands. The usr property is not used by KM REST API as key access is determined by the endpoint privileges.

    pwd

    string

    Optional

    Specifies the user password. You will be prompted for the password, if you omit setting this property. For greater security, omit the password in the configuration file, and then enter it interactively when prompted. Not used by KM REST API.

    client_wallet

    string

    Optional

    Specifies the absolute path to the wallet in unattended mode. Because there is no human intervention in unattended mode, user credentials to log into the Oracle Key Vault server are placed in the wallet. If this option is used together with the usr option, the command will pick up the user's credentials from the wallet to establish connection with the Key Vault server. Not used by KM REST API.

  3. Save the configuration file to a secure location.

Parent topic: Managing the RESTful Services Configuration File

13.4.4 Examples of Configuration Files

You can create a configuration file that uses an IP address and a host name.

Example 13-1 Configuration File Using IP Address

server=192.0.2.254
usr=okvadmin
log=/absolute_path_to_log_file/log_file_name
log_level=warning
client_wallet=/path_to_wallet_that_contains_credentials_for_RESTadmin

Example 13-2 Configuration File Using Host Name

server=Prod-OKV-07.example.com
usr=okvadmin
log=/absolute_path_to_log_file/log_file_name
log_level=warning
client_wallet=/path_to_wallet_that_contains_credentials_for_RESTadmin

Parent topic: Managing the RESTful Services Configuration File

13.4.5 Executing a Single RESTful Command

If you only want to run a few commands, then run them individually from the command line using the -r or --service option.

  1. Log in to the endpoint where you want to execute the command.
  2. Ensure that the script property has no value in the configuration file
  3. Run the RESTful Service utility, specifying the configuration file with the -c option, the service with the -r or --service option, and the command specific options.
    For example: 
    java -jar okvrestservices.jar -c conf_file -r create_endpoint -e hr_db_ep -d "HR database endpoint" -q solaris64 -t oracle_db -m psmith@example.com
User: Key_Vault_user_name
Password: Key_Vault_user_password

    In this specification:

    • -c refers to the configuration file conf_file.

    • -r refers to the RESTful service create_endpoint.

    • -e refers to the endpoint name hr_db_ep.

    • -d refers to the description of the end point HR database endpoint.

    • -q refers to the endpoint platform solaris64.

    • -t refers to the endpoint type oracle_db.

    • -m refers to the endpoint email psmith@example.com.

In a multi-master cluster environment, you must use the okvclient.ora configuration file in the default location to take advantage of multi-master cluster features. You can still use your own configuration file instead of using okvclient.ora. However, it will connect in standalone mode, you you cannot take advantage of the multi-master cluster environment.

Note:

Command line options have priority over options that are specified in the configuration file or script. For example, if the property usr is specified in the configuration file and the command line, then the command line option will override the one in the configuration file.

Parent topic: Managing the RESTful Services Configuration File

13.4.6 Executing Multiple RESTful Administrative Commands Using a Script

To save time and effort, as well as ensuring accuracy, you can use a script to run a sequence of commands.

You can run a sequence of Oracle Key Vault administration commands from the command line one at a time. However, a more efficient way to run a sequence of commands is to write them into a script. Each command in the script file is interpreted as a service command. You must invoke the script with the -i or --script option and provide the path to the script file. This does not apply to executing key management commands using the KM REST API. You can define the script property in the configuration file to avoid entering it in the command line. You enter the script parameter only once, either in the configuration file or the command line.
  1. Log in to the endpoint where you want to execute the commands.
  2. Create the script file and add the service commands that you want to run into the script file.
    For example, write the following commands into the script file to create an endpoint, an endpoint group, and add the endpoint to the endpoint group:
    create_endpoint -e hr_db_ep -d "HR database endpoint" -q solaris64 -t oracle_db -m psmith@example.com 
create_endpoint_group -g hr_db_epg -d "HR endpoint group"
add_epg_member -g hr_db_epg -e hr_db_ep
  3. Save the script file with a descriptive name, such as create_hr_endpoint_group.txt.
  4. Edit the configuration file named conf_file and add the script property, and then set the property to the name of the script file and its full path.
    The configuration file should look similar to the following: 
    server=192.0.2.254
usr=okvadmin
log=/logs/okvrestservices.log
log_level=warning
script=/scripts/create_hr_endpoint_group.txt
client_wallet=/path_to_wallet_that_contains_credentials_for_RESTuser
  5. If the the script property was defined in the configuration file, then only specify the configuration file to run the RESTful service utility: 
    java -jar okvrestservices.jar -c conf_file 
User: Oracle_Key_Vault_user
Password: Oracle_Key_Vault_user_password

    If you did not set the script property in the configuration file (Step 4) then you must specify both the configuration and the script file to run the RESTful service utility: 

    java -jar okvrestservices.jar -c conf_file -i /scripts/create_hr_endpoint_group.txt
User: Oracle_Key_Vault_user
Password: Oracle_Key_Vault_user_password

The RESTful services utility executes one command at a time. If a command fails, then the script will exit. The log file displays the results of all executed commands with their line numbers and messages reported at run time. This information appears for all log levels. By default, the log file is created in the same directory where the commands are executed.

Related Topics

Parent topic: Managing the RESTful Services Configuration File

13.4.7 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:
  • configuration file (for example, config.ini)
  • ewallet.p12 and cwallet.sso wallet files
  • run-me.sh script

The following procedure explains how to create these components.

  1. Log in to the Oracle Key Vault server.
  2. 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/okvrestservices.jar
  3. 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.
  4. Create the configuration file (for example config.ini) to have the following settings:
    • server is the IP address of the Oracle Key Vault server from which you downloaded the okvrestservices.jar file.
    • usr is the user who has the Create Endpoint privilege. In this example that user is named restuser_ron.
    • log is the log file location, including the file name.
    • log_level is the log level for the configuration file. The setting finest is good because it logs detailed messages and it good for debugging.
    • 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 usr option, the command will pick up the user's credentials from the wallet to establish a connection with the Oracle Key Vault server.
    • script is an absolute path to the script file that you plan to run. This script contains the commands in the correct syntax that the RESTful services execute in Oracle Key Vault. But since all database administrators download that same collection of files, the script would use the same names for virtual wallets and endpoints in Oracle Key Vault. For each database that you want to configure as an endpoint, you must create a script that includes unique names for the virtual wallet and endpoints for this database instance in Oracle Key Vault. Hence, you must create this script on the server itself. One way to create unique names for virtual wallets and endpoints is to create them from the local environment variables of that database instance. You may need to find another method or naming convention to match your environment. A later step in this procedure provides an example of this script.

    For example, to create a config.ini file for an Oracle Key Vault server whose IP address is 192.0.2.181: 

    server=192.0.2.181
usr=restuser_ron
log=/home/oracle/OKVrest.log
log_level=finest
client_wallet=/home/oracle
script=/home/oracle/script.txt

    In this specification:

    • usr=restuser_ron refers to a user named restuser_ron, who has the Create Endpoint privilege.
    • client_wallet points to the location where the RESTful services can find the password for the restuser_ron user. An Oracle Key Vault administrator must create this wallet, which the restuser_ron account can do because this account is granted the Key Administrator role.
  5. Execute the following command, which creates a wallet and insert the password of the restuser_ron user into it. 
    java -jar okvrestservices.jar -c config.ini --client_wallet /home/oracle --add restuser_ron
Password: restuser_ron_password
    This command creates the password-protected wallet ewallet.p12 and the auto-login wallet cwallet.sso.
  6. Create the script that will be referred to in the script parameter in the config.ini file.
    Use the naming convention that your site normally uses for names of wallets and other components.

    The following shell script, called run-me.sh is part of the package that an Oracle Key Vault administrator creates for the database administrators to download. It creates a file script.txt that is referenced in the config.ini file and contains unique names for the virtual wallet and the associated endpoints. 

    $ more run-me.sh

#!/bin/bash
export EP_NAME=${ORACLE_SID^^}_on_${HOSTNAME/.*}
curl -O -k https://Oracle_Key_Vault_IP_address:5695/okvrestservices.jar
cat > /home/oracle/script.txt << EOF
create_wallet -w ${DB_NAME^^}
create_endpoint -e $EP_NAME -t ORACLE_DB -q LINUX64 -d "$HOSTNAME, $(hostname -i)"
set_default_wallet -e $EP_NAME -w ${DB_NAME^^}
provision -v temporary_password -e $EP_NAME -y /u01/opt/oracle/product/okv
EOF
more script.txt

    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. create_wallet ... creates a (shared) virtual wallet in Oracle Key Vault. Here, it has the uppercase(database name).
    4. create_endpoint ... creates an endpoint, named after the endpoint created in the export command in line a, with type=ORACLE_DB, OS=LINUX64, free text fully_qualified_hostname, IP address.
    5. set_default_wallet ... sets the default wallet, associating the created endpoint (from (line d) with the shared wallet (line c).
    6. provision ... download and install with a temporary password into the WALLET_ROOT/okv existing directory.
  7. 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: 
      
create_wallet -w ${DB_NAME^^}
  8. Make the scripts executable. 
    $ chmod +x primary-run-me.sh
$ chmod +x secondary-run-me.sh
  9. Test each of the scripts to ensure that they can create a script.txt file. 
    $ ./primary-run-me.sh
$ ./secondary-run-me.sh
  10. Confirm that the names for the virtual wallets and endpoints follow your naming convention by executing the following command:
    $ more script.txt
  11. 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 config.ini.
    • secondary.zip contains secondary-run-me.sh, ewallet.p12, cwallet.sso, and config.ini.
  12. Make these two .zip files available to the database administrators for them to download from a shared file server.
  13. Instruct the database administrators where to download and execute the scripts:
    • Execute the primary-run-me.sh script on single-instance databases or 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: Managing the RESTful Services Configuration File

13.5 Disabling RESTful Services

You should enable RESTful Services for short periods during endpoint registration and enrollment only.

RESTful Services are disabled by default. After you have enrolled the endpoints, you should disable RESTful services.
  1. Log in to the Oracle Key Vault management console as a user with the System Administrator role.
  2. From the System tab, select System Settings in the left sidebar.

    The System Settings page appears.

  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: Oracle Key Vault Administration and Key Management with RESTful Services

13.6 RESTful Services Administrative Commands

The RESTful services administrative commands are designed for administrators who manage endpoints and endpoint groups.

  • RESTful Services Command Syntax
    The RESTful services command syntax provides for both long and short styles.
  • RESTful Services Wallet Command Syntax
    The RESTful services wallet command syntax provides both long and short styles.
  • Endpoint Commands
    You must have the System Administrator role or the Manage Endpoint privilege use RESTful commands to manage endpoints.
  • Endpoint Group Commands
    You must have the Key Administrator role or the Manage Endpoint Group privilege to create and manage endpoint groups.
  • Virtual Wallet Commands
    Virtual wallet commands manage the virtual wallet lifecycle and define access control mappings between virtual wallets and endpoints or endpoint groups.
  • General Status and Help Information Commands
    These commands provide status information about specific Oracle Key Vault objects, information about the overall Oracle Key Vault system, and general help information.
  • Multi-Master Cluster Information Commands
    Users who have the System Administrator role can find general information (such as names and status) of multi-master clusters and their nodes.
  • Error Reporting
    The RESTful Service utility has robust error reporting to debug in order to run RESTful service commands quickly and successfully.

Parent topic: Oracle Key Vault Administration and Key Management with RESTful Services

13.6.1 RESTful Services Command Syntax

The RESTful services command syntax provides for both long and short styles.

You must be an endpoint administrator to use these commands. For endpoint-related commands, you can have the System Administrator role or the Manage Endpoint privilege. For endpoint group-related commands, you must have the Key Administrator role or the Manage Endpoint Group privilege.

You must use the java -jar command to run the RESTful Services utility okvrestservices and provide a path to the configuration file.

When you install the endpoint software on your server, use a manually created configuration file (such as the config.ini file). After the Oracle Key Vault client is installed, Oracle highly recommends that you use the automatically created and maintained okvclient.ora configuration file in Oracle_Key_Vault_installation_directory/conf to make use of Oracle Key Vault's cluster capabilities. The okvclient.ora does not have entries for the usr and client_wallet parameters to enable automated execution of RESTful commands in Oracle Key Vault. For this, add the -u username and -j client_wallet_location parameters to your RESTful commands.

The following table lists the common options used by all RESTful service commands.

Table 13-2 List of RESTful Administrative Service Commands

Command Name Description

add_epg_member

Adds an endpoint to an endpoint group. The endpoint must already exist.

add_wallet_access_ep

Sets access mappings on a virtual wallet for an endpoint

add_wallet_access_epg

Sets access mappings on a virtual wallet for an endpoint group

check_object_status

Checks the status of an endpoint, endpoint group, or wallet

create_endpoint

Adds an endpoint to Oracle Key Vault. When added, the endpoint is in the Registered state.

create_endpoint_group

Adds a new endpoint group

create_unique_endpoint

Adds a unique endpoint to Oracle Key Vault.

create_unique_endpoint_group

Adds a unique endpoint group to Oracle Key Vault.

create_unique_wallet

Adds a unique virtual wallet to Oracle Key Vault

create_wallet

Adds a virtual wallet to Oracle Key Vault

delete_endpoint

Removes an endpoint from Oracle Key Vault

delete_endpoint_group

Deletes an endpoint group

delete_wallet

Removes the virtual wallet from Oracle Key Vault

download

Downloads the endpoint software okvclient.jar to install it manually at the endpoint.

drop_epg_member

Removes an endpoint from an endpoint group

drop_wallet_access_ep

Removes access mappings on a virtual wallet for an endpoint

drop_wallet_access_epg

Removes access mappings on a virtual wallet for an endpoint group
get_cluster_info

Retrieves status information about a cluster
get_cluster_node_info

Retrieves status information about the nodes in the cluster

get_default_wallet Gets the default wallet for an endpoint

get_enrollment_token

Gets the enrollment token to download the endpoint software for the registered endpoint
get_system_info Returns the client tool version, the server version, and the deployment mode
get_wallets Gets all virtual wallets for an endpoint

modify_endpoint_desc

Changes the endpoint description

modify_endpoint_email

Changes the endpoint's email

modify_endpoint_group

Changes the endpoint group

modify_endpoint_group_desc

Changes the endpoint group description

modify_endpoint_name

Changes the endpoint name

modify_endpoint_platform

Changes the endpoint platform

modify_endpoint_type

Changes the endpoint type

modify_wallet_access_ep

Changes access mappings on a virtual wallet for an endpoint

modify_wallet_access_epg

Changes access mappings on a virtual wallet for an endpoint group

modify_wallet_desc

Changes the virtual wallet description

modify_wallet_name

Changes the virtual wallet name

provision

Downloads and installs the endpoint software okvclient.jar. After this, the endpoint is in the Enrolled state.

re_enroll

Reenrolls an endpoint

re_enroll_all

Reenrolls all endpoints

set_default_wallet

Sets the default wallet for an endpoint

Example 13-3 Specifying Short Form Options

Specify short form options by using a single hyphen before the option.

java -jar okvrestservices.jar -c path [-r RESTful_service | -i path]

Example 13-4 Specifying Long Form Options

Specify long form options by using a double hyphen before the option.

java -jar okvrestservices.jar --config path [--service RESTful_service | --script path]

Parent topic: RESTful Services Administrative Commands

13.6.2 RESTful Services Wallet Command Syntax

The RESTful services wallet command syntax provides both long and short styles.

The following example shows RESTful service commands that pertain to Oracle wallets specified by the --client_wallet option. This wallet stores the user name and password in unattended mode to enable automated endpoint provisioning with no human intervention.

This is different from the virtual wallet specified by the --wallet option that are part of the virtual wallet commands.

Table 13-3 Wallet Command Options

Option Required? Description

-A, --add

Optional

Adds a user to wallet

-D, --delete

Optional

Deletes a user from a wallet

-f, --force

Optional

Performs the operation without prompting for confirmation

-j, --client_wallet arg

Required

Stands for the absolute path to the wallet location

-L, --listuser

Optional

Lists the users who have access to a wallet

-M, --modify

Optional

Modifies a user's password

-w, --wallet_name arg

Required

Stands for the wallet name

Example 13-5 Wallet Command Syntax

Add the user's password into the client_wallet, so that the password can be hidden from the endpoint database administrator who runs the RESTful script: 

java -jar okvrestservices.jar -c path_to_configuration_file/rest.init --client_wallet absolute_path_to_wallet_location --add user

Change the credentials and password in the client_wallet, after ensuring that this password matches the password that was created for that user in the Users tab in the Oracle Key Vault management console: 

java -jar okvrestservices.jar -c path_to_configuration_file/rest.init --client_wallet absolute_path_to_wallet_location --modify user

Lists all Oracle Key Vault users whose credentials are stored in the client_wallet:

java -jar okvrestservices.jar --config path_to_configuration_file/rest.init --client_wallet absolute_path_to_wallet_location --listuser user

Delete a user's credentials from the client_wallet: 

java -jar okvrestservices.jar --config path_to_configuration_file/rest.init --client_wallet absolute_path_to_wallet_location --delete user

Parent topic: RESTful Services Administrative Commands

13.6.3 Endpoint Commands

You must have the System Administrator role or the Manage Endpoint privilege use RESTful commands to manage endpoints.

Parent topic: RESTful Services Administrative Commands

13.6.3.1 create_endpoint Command

The create_endpoint command adds a new endpoint to Oracle Key Vault.

After you add the endpoint, the endpoint will be in the Registered state.

Syntax

Short form:

create_endpoint -e endpoint_name -d "description" -q platform -m email_address -t type

Long form:

create_endpoint --ep_name endpoint_name --desc "description" --ep_platform platform --ep_email email_address --ep_type type

Parameters

Parameter Required? Description

-e, --ep_name

Required

The name of the endpoint that you want to add. See Naming Guidelines for Objects.

-d, --desc

Optional

A user friendly description of the endpoint. If the description contains spaces, you must enclose it within double quotation marks.

-q, --ep_platform

Required

The endpoint platform. Allowed values are:

  • linux64

  • solaris64

  • solaris_sparc

  • aix

  • hpux

  • hp-ux

  • windows

-t, --ep_type

Required

Type of the endpoint. Allowed values are:

  • oracle_db

  • oracle_non_db

  • other

-m, --ep_email

Optional

Email address of the endpoint administrator. Enclose this value in double quotation marks.

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

In this example, an endpoint called hr_db_ep is added with an optional identifying description 'HR database endpoint', of type oracle_db, on platform solaris64, and endpoint administrator email, psmith@example.com. 

java -jar okvrestservices.jar -c conf_file -r create_endpoint -e hr_db -d "HR database endpoint" -q solaris64 -t oracle_db -m psmith@example.com

Long Form Example

java -jar okvrestservices.jar --config conf_file --service create_endpoint --ep_name hr_db --desc "HR database endpoint" --ep_platform solaris64 --ep_type oracle_db --ep_email psmith@example.com

Parent topic: Endpoint Commands

13.6.3.2 create_unique_endpoint Command

The create_unique_endpoint command adds a new unique endpoint to Oracle Key Vault.

This command is only used in a multi-master cluster environment.

When you create the endpoint, a unique ID is returned. You an use this ID to check the status of the endpoint creation, whether it is in progress (PENDING) or complete (ACTIVE). If the status is PENDING, then it is not yet usable, so any actions performed on the endpoint will fail. If the status is ACTIVE, then the endpoint is usable. To check the status, execute the check_object_status command, specifying this unique ID by including the -x or --uid parameter. Next, if the status is ACTIVE, execute the get_object_name command to confirm the name of the endpoint after Oracle Key Vault performs name resolution for this name. If the name that you provided is already used in another node, then the name for this endpoint will have _OKVxx appended to it. For example, if you named the endpoint ep12, and there is a naming conflict, the name could be EP12_OKV01.

Syntax

Short form:

create_unique_endpoint -e endpoint_name -d "description" -q platform -m email_address -t type

Long form:

create_unique_endpoint --ep_name endpoint_name --desc "description" --ep_platform platform --ep_email email_address --ep_type type

Parameters

Parameter Required? Description

-e, --ep_name

Required

The name of the endpoint that you want to add. See Naming Guidelines for Objects.

-d, --desc

Optional

A user friendly description of the endpoint. If the description contains spaces, then you must enclose it within double quotation marks.

-q, --platform

Required

The endpoint platform. Allowed values are:

  • linux64

  • solaris64

  • solaris_sparc

  • aix

  • aix_53

  • hp-ux

  • windows

-t, --ep_type

Required

Type of the endpoint. Allowed values are:

  • oracle_db

  • oracle_non_db

  • oracle_acfs

  • mysql_db

  • other

-m, --ep_email

Required

Email address of the endpoint administrator. Enclose this value in double quotation marks.

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

In this example an endpoint called my_db_ep is added, with an optional identifying description 'My database endpoint', of type oracle_db, on platform solaris64, and endpoint administrator email, psmith@example.com. 

java -jar okvrestservices.jar -c conf_file -r create_unique_endpoint -e my_db -d "My database endpoint" -q solaris64 -t oracle_db -m psmith@example.com

Long Form Example

java -jar okvrestservices.jar --config conf_file --service create_unique_endpoint --ep_name my_db --desc "My database endpoint" --platform solaris64 --ep_type oracle_db --ep_email psmith@example.com

Parent topic: Endpoint Commands

13.6.3.3 delete_endpoint Command

The delete_endpoint command removes an endpoint from Oracle Key Vault.

A confirmation message appears asking if you are sure you want to delete the endpoint. You can use the -f or --force option to remove the endpoint without a confirmation message. Use the -f or --force option carefully, because it suppresses the confirmation message.

Syntax

Short form:

delete_endpoint -f -e endpoint_name

Long form:

delete_endpoint --force --ep_name endpoint_name

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-f, --force

Optional

Forces the deletion and suppresses the confirmation message

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example removes the sales_db_ep endpoint from Oracle Key Vault without confirmation. 

java -jar okvrestservices.jar -c conf_file -r delete_endpoint -f -e sales_db_ep

Long Form Example

java -jar okvrestservices.jar --config conf_file --service delete_endpoint --force --ep_name sales_db_ep

Parent topic: Endpoint Commands

13.6.3.4 download Command

The download command downloads the endpoint software (okvclient.jar) to a directory that you name.

The directory path is specified by the -o option. You can specify the absolute or relative path, or even set an environment variable to point to the path.

You can use either the download command or the provision command to enroll the endpoint. You cannot use both for a given endpoint.

Syntax

Short form:

download -e endpoint_name -o directory

Long form:

download --ep_name endpoint_name -dir directory

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-o, --dir

Required

Absolute path to the download directory for the endpoint software. For example, if you specify -o /tmp, then the endpoint software is downloaded to /tmp/endpoint_name/okvclient.jar.

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

In this example, the endpoint software, okvclient.jar, is downloaded to /home/oracle/downloads/hr_db_ep/okvclient.jar for an endpoint called hr_db_ep. 

java -jar okvrestservices.jar -c conf_file -r download -e hr_db_ep -o /home/oracle/downloads/

Long Form Example

java -jar okvrestservices.jar --config conf_file --service download --ep_name hr_db_ep --dir /home/oracle/downloads/

Parent topic: Endpoint Commands

13.6.3.5 get_enrollment_token Command

The get_enrollment_token command retrieves an enrollment token for a registered endpoint.

This command will work only for endpoints in the Registered state.

Syntax

Short form:

get_enrollment_token -e endpoint_name

Long form:

get_enrollment_token --ep_name endpoint_name

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

In this example, a registered endpoint called hr_db_ep gets the enrollment token that will be used to download and install the endpoint software to the endpoint. 

java -jar okvrestservices.jar -c conf_file -r get_enrollment_token -e hr_db_ep

Long Form Example

java -jar okvrestservices.jar --config conf_file --service get_enrollment_token --ep_name hr_db_ep

Parent topic: Endpoint Commands

13.6.3.6 modify_endpoint_desc Command

The modify_endpoint_desc command changes the description of an endpoint.

Syntax

Short form: 

modify_endpoint_desc -e endpoint_name -d "new_desc"

Long form:

modify_endpoint_desc --ep_name endpoint_name --desc "new_desc"

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-d, --desc

Required

New description string for this endpoint enclosed within double quotation marks

-c, --config

Required

Specifies the absolute path to the configuration file

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example changes the endpoint description for endpoint hr_db to HR database endpoint group. 

java -jar okvrestservices.jar -c conf_file -r modify_endpoint_desc -e hr_db -d "HR database endpoint group"

Long Form Example

java -jar okvrestservices.jar --config conf_file --service modify_endpoint_desc --ep_name hr_db --desc "HR database endpoint group"

Parent topic: Endpoint Commands

13.6.3.7 modify_endpoint_email Command

The modify_endpoint_email command changes the email address for the endpoint.

Syntax

Short form: 

modify_endpoint_email -e endpoint_name -m endpoint_email_address

Long form:

modify_endpoint_email --ep_name endpoint_name --ep_email endpoint_email_address

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-m, --ep_email

Required

The new email address for this endpoint. Enclose this value in double quotation marks.

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example changes the email of endpoint hr_db to tjones@example.com. 

java -jar okvrestservices.jar -c conf_file -r modify_endpoint_email -e hr_db -m tjones@example.com

Long Form Example

java -jar okvrestservices.jar --config conf_file --service modify_endpoint_email --ep_name hr_db --ep_email tjones@example.com

Parent topic: Endpoint Commands

13.6.3.8 modify_endpoint_name Command

The modify_endpoint_name command changes the name of an endpoint.

Syntax

Short form: 

modify_endpoint_name -e endpoint_name -n new_endpoint_name

Long form:

modify_endpoint_name --ep_name endpoint_name --ep_new_name new_endpoint_name

Parameters

Parameter Required? Description

-e, --ep_name

Required

Current name of the endpoint.

-n, --ep_new_name

Required

New name for this endpoint. See Naming Guidelines for Objects.

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example changes the name of endpoint hr_db to that of hr_db_ep. 

java -jar okvrestservices.jar -c conf_file -r modify_endpoint_name -e hr_db -n hr_db_ep

Long Form Example

java -jar okvrestservices.jar --config conf_file --service modify_endpoint_name --ep_name hr_db --ep_new_name hr_db_ep

Parent topic: Endpoint Commands

13.6.3.9 modify_endpoint_platform Command

The modify_endpoint_platform command changes the platform for an endpoint.

Syntax

Short form: 

modify_endpoint_platform -e endpoint_name -q endpoint_platform

Long form:

modify_endpoint_platform --ep_name endpoint_name --ep_platform endpoint_platform

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-q, --ep_platform

Required

Platform of the server for this endpoint. Values are as follows:

  • linux64

  • solaris64

  • solaris_sparc

  • aix

  • hpux

  • hp-ux

  • windows

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example changes the platform for endpoint hr_db to aix. 

java -jar okvrestservices.jar -c conf_file -r modify_endpoint_platform -e hr_db -q aix

Long Form Example

java -jar okvrestservices.jar --config conf_file --service modify_endpoint_platform --ep_name hr_db --ep_platform aix

Parent topic: Endpoint Commands

13.6.3.10 modify_endpoint_type Command

The modify_endpoint_type command changes the endpoint type.

Syntax

Short form:

modify_endpoint_type -e endpoint_name -t endpoint_type

Long form:

modify_endpoint_type --ep_name endpoint_name --ep_type endpoint_type

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-t, --ep_type

Required

Type of the endpoint. Values are as follows:

  • oracle_db

  • oracle_non_db

  • other

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example changes the endpoint type for endpoint hr_db to oracle_db. 

java -jar okvrestservices.jar -c conf_file -r modify_endpoint_type -e hr_db -t oracle_db

Long Form Example

java -jar okvrestservices.jar --config conf_file --service modify_endpoint_type --ep_name hr_db --ep_type oracle_db

Parent topic: Endpoint Commands

13.6.3.11 provision Command

The provision command downloads and installs the endpoint software in the specified directory, which must exist.

This directory should have read, write and execute permissions for the owner and its group. For example, if the Oracle Key Vault endpoint software is installed in an Oracle Database server, then this endpoint installation directory should have read, write, and execute permissions by the oracle user and the oinstall group. This ensures that processes can access directories appropriately at run time.

You must meet the following prerequisites to run this command:

  • You must be a user with system administrative privileges

  • You must ensure that the soft link/usr/bin/java points to $ORACLE_HOME/jdk/jre/bin/java.

  • You must know how the installation process determines the location of the okvclient.ora file.

You can use either the download command or the provision command to enroll the endpoint. You cannot use both for a given endpoint.

Syntax

Short form:

provision [-a|-v  account_pwd ] -e endpoint_name -o directory_path

Long form:

When password is used to authenticate:

provision --endpoint_password account_pwd -ep_name endpoint_name --dir directory_path

When no password is used (auto-login):

provision --autologin -ep_name endpoint_name --dir directory_path

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint.

-o, --dir

Required

Existing directory in which to download and install the endpoint software

-y, --okv_home

Required if -o, --dir option is not used

Oracle Key Vault home directory to be used for the wallet root on the client side. Choose between this parameter and -o, --dir. The only difference between using -o, --dir and -y, --okv_home is that -y, --okv_home does not create an endpoint directory.

-v, --endpoint_password

Optional

Endpoint password. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option (recommended for better security), then the provision command prompts you for the password interactively. You must supply the password used for the wallet during endpoint software installation to communicate with the Oracle Key Vault server over mutually authenticated Transport Layer Security (TLS). If you created an auto-login wallet without a password during the endpoint software installation, then the endpoint credentials are stored in an Oracle wallet.

-a, --autologin

Required

The endpoint credentials to connect to the Oracle Key Vault server are stored in an auto-login wallet.

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Examples

Auto-login mode:

In this example, the endpoint software is installed for endpoint hr_db_ep in the directory /home/oracle/okvutil without a password (in autologin mode). 

java -jar okvrestservices.jar -c conf_file -r provision -e hr_db_ep -o /home/oracle/okvutil/ -a

Password-protected mode:

In this example, the endpoint software is installed for endpoint hr_db_ep in the directory /home/oracle/okvutil with a password. Because the password option (-v --client_password) is omitted, the password must be entered on the command line when prompted. 

java -jar okvrestservices.jar -c conf_file -r provision -e hr_db_ep -o /home/oracle/okvutil/

Long Form Examples

java -jar okvrestservices.jar --config conf_file --service provision --autologin --ep_name hr_db_ep --dir /home/oracle/okvutil/ -a
java -jar okvrestservices.jar --config conf_file --service provision --ep_name hr_db_ep --dir /home/oracle/okvutil/

Parent topic: Endpoint Commands

13.6.3.12 re_enroll Command

The re_enroll command re-enrolls a previously enrolled endpoint in order to upgrade the endpoint software.

Syntax

Short form:

re_enroll -e endpoint_name

Long form:

re_enroll --ep_name endpoint_name

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

In this example, the endpoint hr_db_ep is reenrolled. 

java -jar okvrestservices.jar -c conf_file -r re_enroll -e hr_db_ep

Long Form Example

java -jar okvrestservices.jar --config conf_file --service re_enroll --ep_name hr_db_ep

Parent topic: Endpoint Commands

13.6.3.13 re_enroll_all Command

The re_enroll_al command re-enrolls all previously enrolled endpoints in order to upgrade the endpoint software.

Syntax

Short and long form:

re_enroll_all

Parameters

Parameter Required? Description

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

java -jar okvrestservices.jar -c conf_file -r re_enroll

Long Form Example

java -jar okvrestservices.jar --config conf_file --service re_enroll

Parent topic: Endpoint Commands

13.6.4 Endpoint Group Commands

You must have the Key Administrator role or the Manage Endpoint Group privilege to create and manage endpoint groups.

Parent topic: RESTful Services Administrative Commands

13.6.4.1 add_epg_member Command

The add_epg_member command adds an existing endpoint to an endpoint group.

Syntax

Short form:

add_epg_member -g endpoint_group_name -e endpoint_member

Long form:

add_epg_member --epg_name endpoint_group_name --ep_name endpoint_member

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-g, --epg_name

Required

Name of the endpoint group

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example shows an endpoint called hr_db_ep being added to endpoint group epg_hr.

java -jar okvrestservices.jar -c conf_file -r add_epg_member -g epg_hr -e hr_db_ep

Long Form Example

java -jar okvrestservices.jar --config conf_file --service add_epg_member --epg_name epg_hr --ep_name hr_db_ep

Parent topic: Endpoint Group Commands

13.6.4.2 create_endpoint_group Command

The create_endpoint_group command creates a new endpoint group.

Syntax

Short form:

create_endpoint_group -g endpoint_group_name -d "endpoint group description"

Long form:

create_unique_endpoint_group --epg_name endpoint_group_name --desc "endpoint grouop description"

Parameters

Parameter Required? Description

-g, --epg_name

Required

Name of the endpoint group. See Naming Guidelines for Objects.

-d, --desc

Optional

A user-friendly description of the endpoint group enclosed within double quotation marks

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example shows an endpoint group called epg_hr being created with the description HR endpoint group. 

java -jar okvrestservices.jar -c conf_file -r create_unique_endpoint_group --epg_name EPG3 --desc "EPG test"

Long Form Example

java -jar okvrestservices.jar --config conf_file --service create_endpoint_group --epg_name epg_hr --desc "HR endpoint group"

Parent topic: Endpoint Group Commands

13.6.4.3 create_unique_endpoint_group Command

The create_unique_endpoint_group command creates a new endpoint group.

This command is only used in a multi-master cluster environment.

When you create the endpoint group, a unique ID is returned. You an use this ID to check the status of the endpoint group creation, whether it is in progress (PENDING) or complete (ACTIVE). If the status is PENDING, then it is not yet usable, so any actions performed on the endpoint group will fail. If the status is ACTIVE, then the endpoint group is usable. To check the status, execute the check_object_status command, specifying this unique ID by including the -x or --uid parameter. Next, if the status is ACTIVE, execute the get_object_name command to confirm the name of the endpoint group after Oracle Key Vault performs name resolution for this name. If the name that you provided is already used in another node, then the name for this endpoint group will have _OKVxx appended to it. For example, if you named the endpoint group epg12, and there is a naming conflict, the name could be EPG12_OKV01.

Syntax

Short form:

create_unique_endpoint_group -g unique_endpoint_group_name -d "unique_endpoint group description"

Long form:

create_unique_endpoint_group --epg_name endpoint_group_name --desc "endpoint group description"

Parameters

Parameter Required? Description

-g, --epg_name

Required

Name of the endpoint group. See Naming Guidelines for Objects.

-d, --desc

Optional

A user-friendly description of the endpoint group enclosed within double quotation marks

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example shows an endpoint group called epg_hr being created with the description HR endpoint group. 

java -jar okvrestservices.jar -c conf_file -r create_unique_endpoint_group --epg_name EPG3 --desc "EPG test"

Long Form Example

java -jar okvrestservices.jar --config conf_file --service create_unique_endpoint_group --epg_name epg_hr --desc "HR endpoint group"

Parent topic: Endpoint Group Commands

13.6.4.4 delete_endpoint_group Command

The delete_endpoint_group command removes an endpoint group from Oracle Key Vault.

Syntax

Short form:

delete_endpoint_group -f -g endpoint_group

Long form:

delete_endpoint_group --force --endpoint_group

Parameters

Parameter Required? Description

-g, --epg_name

Required

Name of the endpoint group

-f, --force

Optional

Force the deletion and suppresses the confirmation message

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example deletes the endpoint group epg_hr. 

java -jar okvrestservices.jar -c conf_file -r delete_endpoint_group -f -g epg_hr

Long Form Example

java -jar okvrestservices.jar --config conf_file --service delete_endpoint_group --force --epg_name epg_hr

Parent topic: Endpoint Group Commands

13.6.4.5 drop_epg_member Command

The drop_epg_member command removes an endpoint from an endpoint group.

Syntax

Short form:

drop_epg_member -g endpoint_group -e endpoint_name

Long form:

drop_epg_member --epg_name endpoint_name --ep_name endpoint_group

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-g, --epg_name

Required

Name of the endpoint group

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example shows endpoint hr_db_ep being removed from endpoint group epg_hr. 

java -jar okvrestservices.jar -c conf_file -r drop_epg_member -e hr_db_ep -g epg_hr

Long Form Example

java -jar okvrestservices.jar --config conf_file --service drop_epg_member --ep_name hr_db_ep --epg_name epg_hr

Parent topic: Endpoint Group Commands

13.6.4.6 modify_endpoint_group_desc Command

The modify_endpoint_group_desc command changes the description of an endpoint group.

Syntax

Short form:

modify_endpoint_group_desc -g endpoint_group_name -d "endpoint_group_description"

Long form:

modify_endpoint_group_desc --epg_name endpoint_group_name --desc "endpoint_group_description"

Parameters

Parameter Required? Description

-g, --epg_name

Required

Name of the endpoint group

-d, --desc

Required

The new description string for the endpoint group enclosed within double quotation marks

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example shows the endpoint group epg_hr getting a description “HR DB endpoint group“. 

java -jar okvrestservices.jar -c conf_file -r modify_endpoint_group_desc -g epg_hr -d "HR DB endpoint group"

Long Form Example

java -jar okvrestservices.jar --config conf_file --service modify_endpoint_group_desc --epg_name epg_hr --desc "HR DB endpoint group"

Parent topic: Endpoint Group Commands

13.6.4.7 modify_endpoint_group_name Command

The modify_endpoint_group_name command changes the name of an endpoint group.

Syntax

Short form: 

modify_endpoint_group_name -g endpoint_group_name -z new_endpoint_group_name

Long form:

modify_endpoint_group_name  --epg_name epg endpoint_group_name --new_name new_endpoint_group_name

Parameters

Parameter Required? Description

-g, --epg_group_name

Required

Current name of the endpoint group.

-z, --new_name

Required

New endpoint group name. See Naming Guidelines for Objects.

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example changes the endpoint group name hr_db to hr_db_west. 

java -jar okvrestservices.jar modify_endpoint_name -g hr_db -z hr_db_west

Long Form Example

java -jar okvrestservices.jar modify_endpoint_name --epg_name hr_db --new_name hr_db_west

Parent topic: Endpoint Group Commands

13.6.5 Virtual Wallet Commands

Virtual wallet commands manage the virtual wallet lifecycle and define access control mappings between virtual wallets and endpoints or endpoint groups.

You must have the Key Administrator role to execute the wallet commands.

Parent topic: RESTful Services Administrative Commands

13.6.5.1 add_wallet_access_ep Command

The add_wallet_access_ep command grants an endpoint a level of access to a virtual wallet.

Syntax

Short form:

add_wallet_access_ep -e endpoint_name -w virtual_wallet_name -l wallet_access_level

Long form:

add_wallet_access_ep --ep_name endpoint_name --wallet_name virtual_wallet_name --access_level wallet_access_level

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-w, --wallet_name

Required

Name of the virtual wallet

-l, --access_level

Required

Level of access for the virtual wallet. Values are as follows:

  • ro: Read only

  • rm: Read and modify

  • ro_mw: Read only and manage virtual wallet

  • rm_mw: Read and modify and manage virtual wallet

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example adds the read-only access privilege on the wallet hr_wallet to endpoint hr_db_ep. 

java -jar okvrestservices.jar -c conf_file -r add_wallet_access_ep -e hr_db_ep -w hr_wallet -l ro

Long Form Example

java -jar okvrestservices.jar --config conf_file --service add_wallet_access_ep --ep_name hr_db_ep --wallet_name hr_wallet --access_level ro

Parent topic: Virtual Wallet Commands

13.6.5.2 add_wallet_access_epg Command

The add_wallet_access_epg command grants an endpoint group a level of access to a virtual wallet.

Syntax

Short form:

add_wallet_access_epg -g endpoint_group_name -w virtual_wallet_name -l virtual_wallet_access_level

Long form:

add_wallet_access_epg --epg_name endpoint_group_name --wallet_name virtual_wallet_name --access_level wallet_access_level

Parameters

Parameter Required? Description

-g, --epg_name

Required

Name of the endpoint group

-w, --wallet_name

Required

Name of the virtual wallet

-l, --access_level

Required

Level of access for the virtual wallet. Values are as follows:

  • ro: Read only

  • rm: Read and modify

  • ro_mw: Read only and manage virtual wallet

  • rm_mw: Read and modify and manage virtual wallet

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example shows read-only access being granted to endpoint group epg_hr. 

java -jar okvrestservices.jar -c conf_file -r add_wallet_access_epg -g epg_hr -w hr_wallet -l ro

Long Form Example

java -jar okvrestservices.jar --config conf_file --service add_wallet_access_epg -epg_name epg_hr --wallet_name hr_wallet --access_level ro

Parent topic: Virtual Wallet Commands

13.6.5.3 create_unique_wallet Command

The create_unique_wallet command creates a unique virtual wallet.

This command is only used in a multi-master cluster environment.

In order to use this command, the okvclient.ora file must be the configuration file that is referenced. When you create the wallet, a unique ID is returned. You an use this ID to check the status of the wallet creation, whether it is in progress (PENDING) or complete (ACTIVE). If the status is PENDING, then it is not yet usable, so any actions performed on the wallet will fail. If the status is ACTIVE, then the wallet is usable. To check the status, execute the check_object_status command, specifying this unique ID by including the -x or --uid parameter. Next, if the status is ACTIVE, execute the get_object_name command to confirm the name of the wallet after Oracle Key Vault performs name resolution for this name. If the name that you provided is already used in another node, then the name for this wallet will have _OKVxx appended to it. For example, if you named the wallet WALLET12, and there is a naming conflict, the name could be wallet12_OKV01.

Syntax

Short form:

create_unique_wallet -w wallet_name -d "wallet_description"

Long form:

create_unique_wallet --wallet_name wallet_name --desc "wallet_description"

Parameters

Parameter Required? Description

-w, --wallet_name

Required

The name of the unique wallet that you want to create. See Naming Guidelines for Objects.

-d, --desc

Optional

A descriptive name for the unique wallet enclosed within double quotation marks

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example creates a unique virtual wallet named my_wallet with the description My unique wallet. 

java -jar okvrestservices.jar -c conf_file -r create_unique_wallet -w my_wallet -d "My unique wallet"

Long Form Example

java -jar okvrestservices.jar --config conf_file --service create_unique_wallet --wallet  my_wallet --desc "My unique wallet"

Parent topic: Virtual Wallet Commands

13.6.5.4 create_wallet Command

The create_wallet command creates a virtual wallet.

Syntax

Short form:

create_wallet -w virtual_wallet_name -d "wallet_description"

Long form:

create_wallet --wallet_name wallet_name --desc "wallet_description"

Parameters

Parameter Required? Description

-w, --wallet_name

Required

Name of the virtual wallet. See Naming Guidelines for Objects.

-d, --desc

Optional

A descriptive name for the virtual wallet enclosed within double quotation marks

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example creates a wallet named hr_wallet with the description Virtual wallet for HR endpoint. 

java -jar okvrestservices.jar -c conf_file -r create_wallet -w hr_wallet -d "Virtual wallet for HR endpoint"

Long Form Example

java -jar okvrestservices.jar --config conf_file --service create_wallet --wallet hr_wallet --desc "Virtual wallet for HR endpoint"

Parent topic: Virtual Wallet Commands

13.6.5.5 delete_wallet Command

The delete_wallet command deletes a wallet from Oracle Key Vault.

Syntax

Short form:

delete_wallet -f -w virtual_wallet_name

Long form:

delete_wallet --force --wallet_name virtual_wallet_name

Parameters

Parameter Required? Description

-w, --wallet_name

Required

Name of the virtual wallet

-f, --force

Optional

Forces the deletion without prompting for confirmation

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example deletes the wallet hr_wallet without confirmation. 

java -jar okvrestservices.jar -c conf_file -r delete_wallet -f -w hr_wallet

Long Form Example

java -jar okvrestservices.jar --config conf_file --service delete_wallet --force --wallet_name hr_wallet

Parent topic: Virtual Wallet Commands

13.6.5.6 drop_wallet_access_ep Command

The drop_wallet_access_ep command removes an endpoint's access to a wallet.

Syntax

Short form:

drop_wallet_access_ep -e endpoint_name -w virtual_wallet_name

Long form:

drop_wallet_access_ep --ep_name endpoint_name --wallet_name virtual_wallet_name

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-w, --wallet_name

Required

Name of the virtual wallet

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example removes access to wallet hr_wallet for the endpoint hr_db_ep. 

java -jar okvrestservices.jar -c conf_file -r drop_wallet_access_ep -e hr_db_ep -w hr_wallet

Long Form Example

java -jar okvrestservices.jar --config conf_file --service drop_wallet_access_ep --ep_name hr_db_ep --wallet_name hr_wallet

Parent topic: Virtual Wallet Commands

13.6.5.7 drop_wallet_access_epg Command

The drop_wallet_access_epg command removes an endpoint group's access to virtual wallet.

Syntax

Short form:

drop_wallet_access_epg -g endpoint_group_name -w virtual_wallet_name

Long form:

drop_wallet_access_epg --epg_name endpoint_group_name --wallet_name virtual_wallet_name

Parameters

Parameter Required? Description

-g, --epg_name

Required

Name of the endpoint group

-w, --wallet_name

Required

Name of the virtual wallet

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example grants the endpoint group epg_hr the read, modify, and manage access privileges to wallet hr_wallet. 

java -jar okvrestservices.jar -c conf_file -r modify_wallet_access_epg -g epg_hr -w hr_wallet -l rm_mw

Long Form Example

java -jar okvrestservices.jar --config conf_file --service modify_wallet_access_epg --epg_name epg_hr --wallet_name hr_wallet -l rm_mw

Parent topic: Virtual Wallet Commands

13.6.5.8 get_default_wallet Command

The get_default_wallet command gets the default wallet associated with an endpoint.

Syntax

Short form: 
get_default_wallet -e endpoint_name
Long form: 
get_default_wallet --ep_name endpoint_name

Parameters

Parameter Required? Description
-e,-–ep_name Required Endpoint name, whose default wallet to get

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

To get the default wallet associated with an endpoint hr_db you must supply the endpoint name to the command as follows:
java -jar okvrestservvices.jar -c conf_file -r get_default_wallet -e hr_db

Long Form Example

java -jar okvrestservvices.jar -c conf_file -service get_default_wallet --ep_name hr_db

Parent topic: Virtual Wallet Commands

13.6.5.9 get_object_name Command

The get_object_name command retrieves the name of a managed object if the object status is ACTIVE.

This command is only used in a multi-master cluster environment.

Syntax

Short form:

get_object_name -b EP|EPG|WALLET -x uid

Long form:

 get_object_name --type EP|EPG|WALLET --uid uid

Parameters

Parameter Required? Description

-x, --uid

Required

Unique identifier

-b, --type arg

Required

Specifies the object type to check. Valid values include:

  • EP
  • EPG
  • WALLET

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

java -jar okvrestservices.jar -c conf_file -r get_object_name -b WALLET -u 7C3DC1FF-213A-4FBE-BF4A-98A04F8D05DF

Long Form Example

java -jar okvrestservices.jar --config conf_file --service get_object_name --type WALLET --uid 7C3DC1FF-213A-4FBE-BF4A-98A04F8D05DF

Parent topic: Virtual Wallet Commands

13.6.5.10 get_wallets Command

The get_wallets command gets all the virtual wallets associated with an endpoint.

Syntax

Short form: 
get_wallets -e endpoint_name
Long form: 
get_wallets --ep_name endpoint_name

Parameters

Parameter Required? Description
-e, -—ep_name Required Endpoint name, whose virtual wallets to get

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

To get all the virtual wallets associated with an endpoint hr_db, you must supply the endpoint name to the command as follows:
java -jar okvrestservvices.jar -c conf_file -r get_wallets -e hr_db

Long Form Example

java -jar okvrestservvices.jar -c conf_file -service get_wallets --ep_name hr_db

Parent topic: Virtual Wallet Commands

13.6.5.11 modify_wallet_access_ep Command

The modify_wallet_access_ep command changes the virtual wallet access level to an endpoint.

Syntax

Short form:

modify_wallet_access_ep -e endpoint_name -w virtual_wallet_name -l virtual_wallet_access_level

Long form:

modify_wallet_access_ep --ep_name endpoint_name --wallet_name virtual_wallet_name --access_level wallet_access_level

Parameters

Parameter Required? Description

-e, --ep_name

Required

Name of the endpoint

-w, --wallet_name

Required

Name of the virtual wallet

-l, --access_level

Required

Level of access for the virtual wallet. Values are as follows:

  • ro: Read only

  • rm: Read and modify

  • ro_mw: Read only, and manage virtual wallet

  • rm_mw: Read, modify, and manage virtual wallet

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example modifies the access level on wallet hr_db to read-only plus manage wallet. 

java -jar okvrestservices.jar -c conf_file -r modify_wallet_access_ep -e hr_db_ep -w hr_wallet -l ro_mw

Long Form Example

java -jar okvrestservices.jar --config conf_file --service modify_wallet_access_ep --ep_name hr_db_ep --wallet_name hr_wallet --access_level ro_mw

Parent topic: Virtual Wallet Commands

13.6.5.12 modify_wallet_access_epg Command

The modify_wallet_access_epg command modifies the virtual wallet access level to an endpoint group.

Syntax

Short form:

modify_wallet_access_epg -g endpoint_group_name -w virtual_wallet_name -l virtual_wallet_access_level

Long form:

modify_wallet_access_epg --epg_name endpoint_group_name --wallet_name virtual_wallet_name --access_level wallet_access_level

Parameters

Parameter Required? Description

-g, --epg_name

Required

Name of the endpoint group

-w, --wallet_name

Required

Name of the virtual wallet

-l, --access_level

Required

Level of access for the virtual wallet. Values are as follows:

  • ro: Read only

  • rm: Read and modify

  • ro_mw: Read only and manage virtual wallet

  • rm_mw: Read and modify and manage virtual wallet

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example grants the read, modify, and manage privileges on the endpoint group epg_hr for wallet hr_wallet. 

java -jar okvrestservices.jar -c conf_file -r modify_wallet_access_epg -g epg_hr -w hr_wallet -l rm_mw

Long Form Example

java -jar okvrestservices.jar --config conf_file --service modify_wallet_access_epg --epg_name epg_hr --wallet_name hr_wallet --access_level rm_mw

Parent topic: Virtual Wallet Commands

13.6.5.13 modify_wallet_desc Command

The modify_wallet_desc command modifies the description of an existing virtual wallet.

Syntax

Short form:

modify_wallet_desc -w virtual_wallet_name -d "wallet_desc"

Long form:

modify_wallet_desc --wallet_name virtual_wallet_name --desc "wallet_desc"

Parameters

Parameter Required? Description

-w, --wallet_name

Required

Name of the virtual wallet

-d, --desc

Required

The new description string for the virtual wallet enclosed within double quotation marks

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example gives the wallet hr_wallet a new description of HR endpoint virtual wallet. 

java -jar okvrestservices.jar -c conf_file -r modify_wallet_desc -w hr_wallet -d "HR endpoint virtual wallet"

Long Form Example

java -jar okvrestservices.jar --config conf_file --service modify_wallet_desc --wallet_name hr_wallet --desc "HR endpoint virtual wallet"

Parent topic: Virtual Wallet Commands

13.6.5.14 modify_wallet_name Command

The modify_wallet_name command modifies the virtual wallet name.

Syntax

Short form:

modify_wallet_name -w current_wallet_name -z new_wallet_name

Long form:

modify_wallet_name --wallet_name current_wallet_name --new_name new_wallet_name

Parameters

Parameter Required? Description

-w, --wallet_name

Required

Current name of the wallet

-z, --new_name

Required

New virtual wallet name. See Naming Guidelines for Objects.

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example change the name of the virtual wallet hr_db_wallet to hr_db_west_wallet. 

java -jar okvrestservices.jar -r modify_wallet_name -w hr_db_wallet -z hr_db_west_wallet

Long Form Example

java -jar okvrestservices.jar --service modify_wallet_name --wallet_name hr_db_wallet --new_name hr_db_west_wallet

Parent topic: Virtual Wallet Commands

13.6.5.15 set_default_wallet Command

The set_default_wallet command sets the default wallet for an endpoint.

Syntax

Short form:

set_default_wallet -e endpoint_name -w virtual_wallet_name

Long form:

set_default_wallet --ep_name --wallet_name virtual_wallet_name

Parameters

Parameter Required? Description

-w, --wallet_name

Required

Name of the virtual wallet

-e, --ep_name

Required

Endpoint name for whom default wallet is set

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --config

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example sets the default wallet hr_wallet for the endpoint hr_db. 

java -jar okvrestservices.jar -c conf_file -r set_default_wallet -e hr_db -w hr_wallet

Long Form Example

java -jar okvrestservices.jar --config conf_file --service set_default_wallet --ep_name hr_db --wallet_name hr_wallet

Parent topic: Virtual Wallet Commands

13.6.6 General Status and Help Information Commands

These commands provide status information about specific Oracle Key Vault objects, information about the overall Oracle Key Vault system, and general help information.

  • check_object_status Command
    The check_object_status command checks the status of an endpoint, an endpoint group, or a wallet.
  • get_system_info Command
    get_system_info, returns the client tool version, the server version, and the deployment mode.
  • Help Information
    You can find information about valid options and the available commands that the RESTful services utility okvrestservices.jar provides.

Parent topic: RESTful Services Administrative Commands

13.6.6.1 check_object_status Command

The check_object_status command checks the status of an endpoint, an endpoint group, or a wallet.

The status returned is either object_type exists or object_type does not exist, where object_type can be Endpoint, Endpoint Group, or Wallet. If the object exists, then an ACTIVE or PENDING status is included in the output. If the object does not exist, then no additional status appears.

Syntax

Short form:

check_object_status -b EP|EPG|WALLET -x uid|-N object_name

Long form:

check_object_status --type EP|EPG|WALLET --uid uid|--name object_name

Parameters

Parameter Required? Description

-x, --uid

Required if -N, --name is not used

UID (universally unique ID) of the managed object. You can use check_object_status with this parameter only in a multi-master cluster environment.

-N, --name

Required if -x, --uid is not used

Specifies the name of the object to check. You can use check_object_status with this parameter in either a standalone or a multi-master cluster environment.

-b, --type arg

Required

Specifies the object type to check. Valid values include:

  • EP
  • EPG
  • WALLET

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --conf

Required

Specifies the absolute path to the configuration fil

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

This example shows the status for an endpoint with the endpoint name specified.

java -jar okvrestservices.jar -c conf_file -r check_object_status -b EP -N EP-sales

Long Form Example

This example shows the status for an endpoint with the specified UID.
java -jar okvrestservices.jar --config conf_file --service check_object_status --type EP --uid 7C3DC1FF-213A-4FBE-BF4A-98A04F8D05DF
13.6.6.2 get_system_info Command

get_system_info, returns the client tool version, the server version, and the deployment mode.

Syntax

Short and long form:

get_system_info

Parameters

Parameter Required? Description

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --conf

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Examples

The deployment modes values are Standalone, Primary-Standby, or Cluster.

Examples are as follows: 

$ java -jar okvrestservices.jar --config rest.conf --service get_system_info
[Line 0 OK] [GET SYSTEM INFO] [REST Client Tool Version: 18.5.0.0.0]
[Line 0 OK] [GET SYSTEM INFO] [Server Version: 18.5.0.0.0]
[Line 0 OK] [GET SYSTEM INFO] [Deployment Mode: Standalone]
$ java -jar okvrestservices.jar -c rest.conf -r get_system_info
[Line 0 OK] [GET SYSTEM INFO] [REST Client Tool Version: 18.5.0.0.0]
[Line 0 OK] [GET SYSTEM INFO] [Server Version: 18.5.0.0.0]
[Line 0 OK] [GET SYSTEM INFO] [Deployment Mode: Primary-Standby]
$ java -jar okvrestservices.jar -c rest.conf -r get_system_info
[Line 0 OK] [GET SYSTEM INFO] [REST Client Tool Version: 18.5.0.0.0]
[Line 0 OK] [GET SYSTEM INFO] [Server Version: 18.5.0.0.0]
[Line 0 OK] [GET SYSTEM INFO] [Deployment Mode: Cluster]
13.6.6.3 Help Information

You can find information about valid options and the available commands that the RESTful services utility okvrestservices.jar provides.

For a list of valid options, you can use the -h or --help option with the RESTful services utility okvrestservices.jar. 

-bash-4.1$ java -jar okvrestservices.jar -help
usage: java -jar okvrestservices.jar --config <arg> [--service <arg> |--script <arg>
-A,--add <arg>       User to add to wallet
-c,--config <arg>    System configuration file for OKV REST Services Utility
-D,--delete <arg>    User to delete from wallet
-f,--force           Confirm to delete
-h,--help            Display all available options
-L,--listuser        List all user from wallet
-M,--modify <arg>    User to modify from wallet
-p,--pwd <arg>       OKV user password
-t,--twallet <arg>   Wallet location
-u,--usr <arg>       OKV username
-x,--script <arg>    Script file
-r,--service <arg>   Service name
-z,--list            Display all service commands

To see the list of RESTful service commands, include -H or --list at the command line. For example: 

-bash-4.1$ java -jar okvrestservices.jar -H

13.6.7 Multi-Master Cluster Information Commands

Users who have the System Administrator role can find general information (such as names and status) of multi-master clusters and their nodes.

Parent topic: RESTful Services Administrative Commands

13.6.7.1 get_cluster_info Command

The get_cluster_info command retrieves status information about a cluster.

This command retrieves the following information about the cluster:

  • Cluster name
  • Cluster version
  • Maximum disable node duration time
  • List of cluster subgroups
  • Names of nodes that are associated with the cluster

Syntax

Short and long form:

get_cluster_info

Parameters

Parameter Required? Description

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively.

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --conf

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

java -jar okvrestservices.jar -c conf_file -r get_cluster_info

[Line 0 OK] [GET CLUSTER INFO] [Cluster Name: cluster1, Cluster Version:
18.7.0.0.0, Maximum Disable Node Duration: 24 hrs, Cluster Subgroups: subgrp1,
Nodes: node1 node2]

Long Form Example

java -jar okvrestservices.jar --config conf_file --service get_cluster_info

[Line 0 OK] [GET CLUSTER INFO] [Cluster Name: cluster1, Cluster Version:
18.7.0.0.0, Maximum Disable Node Duration: 24 hrs, Cluster Subgroups: subgrp1,
Nodes: node1 node2]
13.6.7.2 get_cluster_node_info Command

The get_cluster_node_info command retrieves status information about the nodes in the cluster.

This command retrieves the following node information about the cluster:

  • Names and IDs of the nodes that are in the cluster
  • The subgroup to which each node belongs
  • IP addresses of each node
  • The mode in which the node is operating, such as read-write or read-only restricted
  • The name of the read-write peer of each node (if blank, it has no read-write peer)
  • The current status of the node: ACTIVE, PAIRING, ENABLING, or DISABLED
  • The date when the node was added to the cluster
  • If the node is disabled, the date of disablement
  • The current Oracle Key Vault version of each node

Syntax

Short form:

get_cluster_node_info [-N node_name]

Long form:

get_cluster_node_info [--name node_name]

Parameters

Parameter Required? Description

-N, --name arg

Optional

Retrieves the details of a specific node.

-u, --usr arg

Optional

Specifies the user name of the Oracle Key Vault account user, who has the System or Key Administrator role. If you omit this option, then you will be prompted to enter the user name interactively.

-p, --pwd arg

Optional

Specifies the password for the Oracle Key Vault user account specified in the --usr option. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option.

-c, --conf

Required

Specifies the absolute path to the configuration file.

-r, --service arg

Required

Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax.

-i, --script arg

Required for multiple RESTful service commands

Specifies the absolute path to the script file. You must set this property in order to run multiple RESTful service commands.

Short Form Example

java -jar okvrestservices.jar -c conf_file -r get_cluster_node_info

[Line 0 OK] [GET CLUSTER NODE INFO] 
[Node Name: node1, Node ID: 1, IP Address: 192.0.2.112, Mode: Read-Write,
Status: ACTIVE, Read-Write Peer: node2, Cluster Subgroup: subgrp1, Join Date:
2021-02-25 05:58:41.973977 UTC, Disable Date: -, Version: 18.7.0.0.0]
[Node Name: node2, Node ID: 2, IP Address: 192.0.2.113, Mode: Read-Write,
Status: ACTIVE, Read-Write Peer: node1, Cluster Subgroup: subgrp1, Join Date:
2021-02-25 05:51:43.75447 UTC, Disable Date: -, Version: 18.7.0.0.0]

java -jar okvrestservices.jar -c conf_file -r get_cluster_node_info -N node1
[Line 0 OK] [GET CLUSTER NODE INFO] 
[Node Name: node1, Node ID: 1, IP Address: 192.0.2.112, Mode: Read-Write,
Status: ACTIVE, Read-Write Peer: node2, Cluster Subgroup: subgrp1, Join Date:
2021-02-25 05:58:41.973977 UTC, Disable Date: -, Version: 18.7.0.0.0]

Long Form Example

java -jar okvrestservices.jar --config conf_file --service get_cluster_node_info

[Line 0 OK] [GET CLUSTER NODE INFO] 
[Node Name: node1, Node ID: 1, IP Address: 192.0.2.112, Mode: Read-Write,
Status: ACTIVE, Read-Write Peer: node2, Cluster Subgroup: subgrp1, Join Date:
2021-02-25 05:58:41.973977 UTC, Disable Date: -, Version: 18.7.0.0.0]
[Node Name: node2, Node ID: 2, IP Address: 192.0.2.113, Mode: Read-Write,
Status: ACTIVE, Read-Write Peer: node1, Cluster Subgroup: subgrp1, Join Date:
2021-02-25 05:51:43.75447 UTC, Disable Date: -, Version: 18.7.0.0.0]

java -jar okvrestservices.jar --config conf_file --service get_cluster_node_info --name node1
[Line 0 OK] [GET CLUSTER NODE INFO] 
[Node Name: node1, Node ID: 1, IP Address: 192.0.2.112, Mode: Read-Write,
Status: ACTIVE, Read-Write Peer: node2, Cluster Subgroup: subgrp1, Join Date:
2021-02-25 05:58:41.973977 UTC, Disable Date: -, Version: 18.7.0.0.0]

13.6.8 Error Reporting

The RESTful Service utility has robust error reporting to debug in order to run RESTful service commands quickly and successfully.

Parent topic: RESTful Services Administrative Commands

13.6.8.1 About Error Reporting

The status of command execution, passed and failed, is reported promptly on the command line and written to the log file.

The specific error will be reported, with corrective actions where appropriate. Error reporting is common to all REST commands.

The first thing to do when a command fails is to look into the log file. If you have not created a custom log file in a location of your choice, then you can look at the default log file, okvrestservices.log in the current directory, where command results will be written.

To see all the messages from the Oracle Key Vault server during command execution, you can set the appropriate logging level, log file name, and the log file location in the configuration file.

The RESTful service utility reports errors such as the failure to locate a file or an environment variable like JAVA_HOME, incorrect command syntax, and incorrect passwords.

Parent topic: Error Reporting

13.6.8.2 Command Line Error Reporting

Error reporting captures both faulty actions, such as incorrect passwords, and successful command executions.

Example 13-6 Error: Running a Service Command without the -r Option

java -jar okvrestservices.jar -c rest.ini modify_endpoint_desc -e ORDERS -b ORDERS_HR
Script or service option is required.

Example 13-7 Error: Incorrect Password

java -jar okvrestservices.jar -c rest.ini -r modify_endpoint_desc -e ORDERS -b ORDERS_HR
Password:
Invalid username or password. Try again after 5 seconds

Example 13-8 Successful Service Command Execution

java -jar okvrestservices.jar -c rest.ini -r modify_endpoint_desc -e ORDERS -b ORDERS_HR
Password:
[Line 0 OK] [MODIFY ENDPOINT DESC] [ORDERS:ORDERS_HR]

Example 13-9 Log File Entry

In addition to the helpful error and usage messages, an entry for the action is logged in the log file with the date.

Mar 02, 2019 7:23:55 PM com.oracle.okv.cloud.client.OKVAutomation checkpoint
INFO: [Line 0 OK] [MODIFY ENDPOINT DESC] [ORDERS:ORDERS_HR]

Parent topic: Error Reporting

13.6.8.3 Error Reporting while Running Commands from a Script

When you run multiple service commands from a script you will see the result on the command line as well as in the log file.

The following output shows the successful results of commands executed from a script.

Example 13-10 Results of Script Execution

java -jar okvrestservices.jar --config rest.ini --script initial_setup.api
Password:
[Line 1 OK] [CREATE ENDPOINT] [APP_SERVER_1:ORACLE_NON_DB:LINUX64]
[Line 2 OK] [CREATE ENDPOINT] [APP_SERVER_2:ORACLE_NON_DB:LINUX64]
[Line 11 OK] [CREATE WALLET] [ApplicationWallet]
[Line 12 OK] [CREATE WALLET] [FinanceWallet]
[Line 15 OK] [CREATE ENDPOINT GROUP] [APP_SERVER]
[Line 16 OK] [CREATE ENDPOINT GROUP] [FINANCE_RAC]
[Line 20 OK] [ADD EPG MEMBER] [APP_SERVER:APP_SERVER_2]
[Line 22 OK] [ADD EPG MEMBER] [FINANCE_RAC:FINANCE_RAC_NODE_1]
[Line 29 OK] [ADD WALLET ACCESS EPG] [APP_SERVER:ApplicationWallet:RM]
[Line 30 OK] [ADD WALLET ACCESS EPG] [FINANCE_RAC:FinanceWallet:RO]
[Line 31 OK] [ADD WALLET ACCESS EP] [HR_DATABASE_PRIMARY:HRWallet:RM_MW]

Parent topic: Error Reporting

13.7 Oracle Key Vault Key Management REST Client Tool Commands

The RESTful services key management commands are designed for users who need to manage keys that are uploaded to Oracle Key Vault.

These users must have the Key Administrator role.

Parent topic: Oracle Key Vault Administration and Key Management with RESTful Services

13.7.1 About Oracle Key Vault Key Management REST Client Tool Commands

The Oracle Key Vault key management REST client tool provides a simplified interface to Key Management Interoperability Protocol (KMIP) operations using okvrestservice.jar commands.

You can embed this tool in client shell scripts or in any programming language. Before you use KM REST client, you must download and deploy the endpoint software, okvclient.jar. The Oracle Key Vault key management REST server will reject the connection from any endpoint that was not deployed. The Oracle Key Vault key management REST API requires JRE 1.8 or later. You must have the Key Administrator role to execute the commands that this interface provides.

If you are using a multi-master cluster environment, then you must download the okvrestservices.jar file while connected in a read/write node. Oracle Key Vault does not allow okvrestservices.jar to be downloaded in read-only mode. Once it is downloaded in read/write mode, the client tool can connect in read/write mode or read-only mode.

Parent topic: Oracle Key Vault Key Management REST Client Tool Commands

13.7.2 Oracle Key Vault Key Management REST Client API Using OKVRESTSERVICE

To call the KM REST client API using OKVRESTSERVICE (okvrestservice.jar), you must include the kmip option.

The drop_wallet_access_epg command removes an endpoint group's access to virtual wallet.

Syntax

java -jar okvrestservices.jar kmip --config conf_file --service options_for_the_KMIP_API

KMIP REST Service Options

Option Description

-a, --algorithm

Cryptographic algorithm to use. Choices are:

  • 3DES
  • AES

-c, --config

Specifies the absolute path to the configuration file

-e, --user

User name

-f , --attr

The attribute list file. The file format is:

name1:value1

name2:value2

name3:value3

-g, --group

Group member

-i, --index

Attribute index

-l, --length
Key lengths supported:

  • 3DES: 112, 168

  • AES : 128, 192, 256

-m, --mask
Cryptographic usage mask. Valid values include the following settings, which are described in the Key Management Interoperability Protocol (KMIP) Specification version 1.1.

  • ENCRYPT

  • DECRYPT

  • WRAP_KEY

  • UNWRAP_KEY

  • EXPORT

  • DERIVE_KEY

  • GENERATE_CRYPTOGRAM

  • VALIDATE_CRYPTOGRAM

  • TRANSLATE_ENCRYPT

  • TRANSLATE_DECRYPT

  • TRANSLATE_WRAP

  • TRANSLATE_UNWRAP

-n, --attribute

Attribute name

-o, --object

Path to object file to register

-r, --code
Revoke code values include:

  • UNSPECIFIED

  • KEY_COMPROMISE

  • CA_COMPROMISE

  • AFFILIATION_CHANGED

  • SUPERSEDED

  • CESSATION_OF_OPERATION

  • PRIVILEGE_WITHDRAWN

-s, --reason

Revoke reason message

-t, --type

Object type to register

-u, --uid

UUID (Universally Unique ID) of the managed object

-v, --value

Attribute value

-w, --wallet

Wallet name

-x, --max

Maximum number of UIDs to display

Parent topic: Oracle Key Vault Key Management REST Client Tool Commands

13.7.3 List of Key Management REST Client Tool Commands

The RESTful key management client tools perform tasks such as creating and activating keys.

Table 13-4 RESTful Key Management Commands

Command Name Description

activate

Activates a managed cryptographic object

add_attr

Adds a new attribute for an object and sets its value

add_custom_attr

Adds a custom attribute specifying name, type, and value

add_member

Adds a user to a wallet

all_attr

Gets all attribute names and values

create_key

Creates a new key

del_attr

Deletes an attribute of a managed object

del_custom_attr

Deletes a custom attributes

del_member

Deletes a user from a wallet

destroy

Requests the server to destroy the key data for the managed object

get_attr

Retrieves one or more attribute values of an object

get_cert

Requests a digital certificate from the server

get_key

Retrieves an encryption key from the server

get_opaque

Retrieves an object that contains secret data

get_secret

Retrieves all available attribute names and values

list_attr

Lists all available attribute names only

list_wallet

Lists virtual wallets

locate

Searches for one or more managed objects

mod_attr

Modifies the value of an attribute for a managed object

mod_custom_attr

Modifies a custom attribute

query

Queries the server regarding its supported capabilities

reg_cert

Registers a digital certificate

reg_key

Registers a key

reg_opaque

Registers an object containing data that the server may not be able to interpret

reg_secret

Registers an object containing secret data

revoke

Revokes a managed cryptographic object.

Parent topic: Oracle Key Vault Key Management REST Client Tool Commands

13.7.4 Key Creation and Registration Commands

The key creation and registration commands perform tasks such as registering different types of security objects.

You must have the Key Administrator role to use these commands.

Parent topic: Oracle Key Vault Key Management REST Client Tool Commands

13.7.4.1 create_key Command

The create_key command creates a new key. 

You must provide a cryptographic algorithm, a key length, and a usage mask.

Syntax

Short form:

-s create_key -a  cryptographic_algorithm -l key_length -m cryptographic_usage_mask

Long form:

--service create_key --algorithm  cryptographic_algorithm --length key_length --mask crypographic_usage_mask

Parameters

Parameter Required? Description

-a, --algorithm

Required

Cryptographic algorithm

-l, --length

Required

Key length

-m, --mask

Required

Cryptographic usage mask, enclosed in double quotation marks

Short Form Example

This example creates an Advanced Encryption Standard (AES) key.

java -jar okvrestservices.jar kmip -c conf_file -s create_key -a AES -l 128 -m "ENCRYPT,DECRYPT,EXPORT"

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service create_key --algorithm AES --length 128  --mask "ENCRYPT,DECRYPT,EXPORT"
13.7.4.2 get_cert Command

The get_cert command retrieves a digital certificate.

Syntax

Short form:

-s get_cert -u UUID

Long form:

--service get_cert --uid UUID

Parameters

Parameter Required? Description

-u, --uid

Required

Universally unique ID (UUID) of the managed object

Short Form Example

java -jar okvrestservices.jar kmip -c conf_file -s get_cert -u D69D2F32-2DBB-4FF3-BF52-95487526E6EC

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service get_cert --uid D69D2F32-2DBB-4FF3-BF52-95487526E6EC
13.7.4.3 get_key Command

The get_key command retrieves an encryption key.

Syntax

Short form:

-s get_key -u UUID

Long form:

--service get_key --uid UUID

Parameters

Parameter Required? Description

-u, --uid

Required

Universally unique ID (UUID) of the managed object

Short Form Example

java -jar okvrestservices.jar kmip -c conf_file -s get_key -u D69D2F32-2DBB-4FF3-BF52-95487526E6EC

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service get_key --uid D69D2F32-2DBB-4FF3-BF52-95487526E6EC
13.7.4.4 get_opaque Command

The get_opaque command retrieves an object that contains secret data.

Syntax

Short form:

-s get_opaque -u UUID

Long form:

--service get_opaque --uid UUID

Parameters

Parameter Required? Description

-u, --uuid

Required

Universally unique ID (UUID) of the managed object

Short Form Example

java -jar okvrestservices.jar kmip -c conf_file -s get_opaque -u D69D2F32-2DBB-4FF3-BF52-95487526E6EC

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service get_opaque --uid D69D2F32-2DBB-4FF3-BF52-95487526E6EC
13.7.4.5 get_secret Command

The get_secret command retrieves an object that contains secret data.

Syntax

Short form:

-s get_secret -u UUID

Long form:

--service get_secret --uid UUID

Parameters

Parameter Required? Description

-u, --uid

Required

Universally unique ID (UUID) of the managed object

Short Form Example

java -jar okvrestservices.jar kmip -c conf_file -s get_secret -u D69D2F32-2DBB-4FF3-BF52-95487526E6EC

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service get_secret --uid D69D2F32-2DBB-4FF3-BF52-95487526E6EC
13.7.4.6 reg_cert Command

The reg_cert command registers a certificate.

Syntax

Short form:

-s reg_cert -t object_type -a algorithm -l key_length -m crypto_usage_mask -o path_to_cert file  [-f path_to_object_attr_file]

Long form:

--service reg_cert --type object_type --algorithm algorithm --length key_length --mask crypto_usage_mask --object path_to_cert_file  [-attr  path_to_cert_attr_file]

Parameters

Parameter Required? Description

-t, --type

Required

Object type

-l, --length

Required

Key length

-a, --algorithm

Required

Algorithm

-m, --mask

Required

Cryptographic usage mask

-o, --object

Required

Path to object attributes file

-f, --attr

Optional

Attribute list file

Short Form Example

java -jar okvrestservices.jar kmip -c conf_file -s reg_cert -t X_509 -a AES -l 128 -m ENCRYPT -o ./my_cert -f ./cert_attr_file.txt

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service reg_cert -t X_509 --algorithm AES --length 128 --mask ENCRYPT --object ./my_cert  --attr ./cert_attr_file.txt
13.7.4.7 reg_key Command

The reg_key command registers a key.

Syntax

Short form:

-s reg_key -a algorithm -l key_length -m crypto_usage_mask -o path_to_object_file  [-f path_to_object_attr_file>]

Long form:

--service reg_key --algorithm algorithm --length key_length --mask crypto_usage_mask --object path_to_object_file  [-attr path_to_object_attr_file]

Parameters

Parameter Required? Description

-l, --length

Required

Key length

-a, --algorithm

Required

Algorithm

-m, --mask

Required

Cryptographic usage mask

-o, --object

Required

Path to key file

-f, --attr

Optional

Attribute list file

Short Form Example

These examples locate an object based on the specified search criteria.

java -jar okvrestservices.jar kmip -c conf_file -s reg_key -a AES -l 128 -m "EXPORT" -o ./object.key  -f ./obj_key_attr_file.txt

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service reg_key --algorithm AES --length 128 --mask "EXPORT" --object ./object.key  --attr ./obj_key_attr_file.txt
13.7.4.8 reg_opaque Command

The reg_opaque command registers opaque objects.

Objects containing opaque data are not necessarily interpreted by the server.

Syntax

Short form:

-s reg_opaque -m crypto_usage_mask -o path_to_object_file [-f path_to_object_attr_file]

Long form:

--service reg_opaque --mask crypto_usage_mask --object path_to_object_file [--attr path_to_object_attr_file]

Parameters

Parameter Required? Description

-m, --mask

Required

Cryptographic usage mask

-o, --object

Required

Path to object file

-f, --attr

Optional

Attribute list file

Short Form Example

java -jar okvrestservices.jar kmip -c conf_file -s reg_opaque -m ENCRYPT -o ./my.opaque -f ./obj_attr_file.txt

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service reg_opaque --mask ENCRYPT --object ./my.opaque  --attr ./obj_attr_file.txt
13.7.4.9 reg_secret Command

The reg_secret command registers secret data such as passwords or random seeds.

Syntax

Short form:

-s reg_secret -t object_type -m crypto_usage_mask -o path_to_object_file  [-f path_to_object_attr_file]

Long form:

--service reg_secret --type object_type --mask crypto_usage_mask --object path_to_object_file  [--attr path_to_object_attr_file]

Parameters

Parameter Required? Description

-t, --type

Required

Object type

-m, --mask

Required

Cryptographic usage mask

-o, --object

Required

Path to object attributes file

-f, --attr

Optional

Attribute list file

Short Form Example

Example Contents of obj_attr_file.txt

java -jar okvrestservices.jar kmip -c conf_file -s reg_secret -t PASSWORD -m ENCRYPT -o ./secret.password -f ./obj_attr_file.txt
CONTACT_INFO=admin@example.com
NAME=John

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service reg_secret --type PASSWORD --mask ENCRYPT --object ./secret.password  --attr ./obj_attr_file.txt

13.7.5 Key Attribute Management Commands

The key attribute management commands perform tasks such as adding, modifying, and deleting standard and custom attributes.

You must have the Key Administrator role to use these commands.

Parent topic: Oracle Key Vault Key Management REST Client Tool Commands

13.7.5.1 add_attr Command

The add_attr command  adds an attribute to a managed object.

Syntax

Short form:

-s add_attr -u UUID -n attribute_name -v attribute_value

Long form:

--service add_attr --uid UUID --attribute attribute_name --value attribute_value

Parameters

Parameter Required? Description

-u, --uuid

Required

Universally unique ID (UUID) of the managed object

-n, --attribute

Required

Attribute name. Modifiable attributes include:

  • ACTIVATION_DATE

  • CONTACT_INFO

  • DEACTIVATION_DATE

  • NAME

  • PROCESS_START_DATE

  • PROTECT_STOP_DATE

-v, --value

Required

Attribute value. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

Short Form Example

These examples assign the value okv@example.com for the attribute CONTACT_INFO for the object specified by the UUID. 

java -jar okvrestservices.jar kmip -c conf_file -s add_attr -u 7D767505-2FBE-4F5E-BF81-F95A4FE88E03 -n CONTACT_INFO -v "okv@example.com"

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service add_attr --uid 7D767505-2FBE-4F5E-BF81-F95A4FE88E03 --attribute CONTACT_INFO --value "okv@example.com"
13.7.5.2 add_custom_attr Command

The add_custom_attr command adds a custom attribute to an object.

Syntax

Short form:

-s add_custom_attr -u UUID -n {X-|Y-}attribute_name -t attribute_type -v attribute_value

Long form:

--service add_custom_attr --uid UUID --attribute {X-|Y-}attribute_name --type attribute_type --value attribute_value

Parameters

Parameter Required? Description

-u, --uid

Required

Universally unique ID (UUID) of the managed object

-n, --attribute

Required

Custom attribute name. Must include the prefix X- or Y-. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

-t, --type

Required

Object type. Can be NUMBER or TEXT.

-v, --value

Required

Custom attribute value. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

Short Form Example

This example assigns the TEXT value OGG_MASTER_KEY_NAME to the custom attribute named x-OGG_MK_NAME for the object specified by the UUID. Enclose these values in double quotation marks if they contain a space. 

java -jar okvrestservices.jar kmip -c conf_file -s add_custom_attr -u D69D2F32-2DBB-4FF3-BF52-95487526E6EC -n x-OGG_MK_NAME -t TEXT -v OGG_MASTER_KEY_NAME

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service add_custom_attr --uid D69D2F32-2DBB-4FF3-BF52-95487526E6EC --attribute x-OGG_MK_NAME --type TEXT --value OGG_MASTER_KEY_NAME
13.7.5.3 all_attr Command

The all_attr command retrieves all attributes of an object.

Syntax

Short form:

-s all_attr -u UUID

Long form:

--service all_attr --uid UUID

Parameters

Parameter Required? Description

-u, --uid

Required

Universally unique ID (UUID) of the managed object

Short Form Example

These examples list all attribute values for the object specified by the UUID.

java -jar okvrestservices.jar kmip -c conf_file -s all_attr -u D69D2F32-2DBB-4FF3-BF52-95487526E6EC

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service all_attr --uid D69D2F32-2DBB-4FF3-BF52-95487526E6EC
13.7.5.4 del_attr Command

The del_attr command  deletes an attribute from a managed object.

Syntax

Short form:

-s del_attr -u UUID -n attribute_name

Long form:

--service del_attr --uid UUID --attribute attribute_name

Parameters

Parameter Required? Description

-u, --uuid

Required

Universally unique ID (UUID) of the managed object

-n, --attribute

Required

Attribute name. Modifiable attributes include:

  • ACTIVATION_DATE

  • CONTACT_INFO

  • DEACTIVATION_DATE

  • NAME

  • PROTECT_STOP_DATE

Short Form Example

These examples delete the attribute CONTACT_INFO for the object specified by the UUID. 

java -jar okvrestservices.jar kmip -c conf_file -s del_attr -u 7D767505-2FBE-4F5E-BF81-F95A4FE88E03 -n CONTACT_INFO

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service del_attr --uid 7D767505-2FBE-4F5E-BF81-F95A4FE88E03 --attribute CONTACT_INFO
13.7.5.5 del_custom_attr Command

The del_custom_attr command deletes a custom attribute.

Syntax

Short form:

-s del_custom_attr -u UUID -n attribute_name -i attribute_index

Long form:

--service del_custom_attr --uid UUID --attribute attribute_name --index attribute_index

Parameters

Parameter Required? Description

-u, --uid

Required

Universally unique ID (UUID) of the managed object

-n, --attribute

Required

Attribute name. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

-i, --index

Required

Attribute index

Short Form Example

These examples delete the value for the attribute named x-OGG_MK_NAME identified by the index 1 for the object specified by the UUID. 

java -jar okvrestservices.jar kmip -c conf_file -s del_custom_attr -u D69D2F32-2DBB-4FF3-BF52-95487526E6EC -n x-OGG_MK_NAME -i 1

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service del_custom_attr --uid D69D2F32-2DBB-4FF3-BF52-95487526E6EC --attribute x-OGG_MK_NAME --index 1
13.7.5.6 get_attr Command

The get_attr command retrieves an attribute or list of attributes of an object.

To find the available attributes, use the list_attr command.

Syntax

Short form:

-s get_attr -u UUID -n attribute name or list

Long form:

--service get_attr --uid UUID --attribute attribute name or list

Parameters

Parameter Required? Description

-u, --uid

Required

Universally unique ID (UUID) of the managed object

-n, --attribute

Required

Attribute name or a list of attributes in quotes separated by commas

Short Form Example

These examples list the attribute values for CRYPTO_USAGE_MASK, CONTACT_INFO , and NAME for the object specified by the UUID. 

java -jar okvrestservices.jar kmip -c conf_file -s get_attr -u D69D2F32-2DBB-4FF3-BF52-95487526E6EC -n "CRYPTO_USAGE_MASK,CONTACT_INFO,NAME"

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service get_attr --uid D69D2F32-2DBB-4FF3-BF52-95487526E6EC --attribute "CRYPTO_USAGE_MASK,CONTACT_INFO,NAME"
13.7.5.7 list_attr Command

The list_attr command retrieves a list of attributes of an object.

Syntax

Short form:

-s list_attr -u UUID

Long form:

--service list_attr --uid UUID

Parameters

Parameter Required? Description

-u, --uuid

Required

Universally unique ID (UUID) of the managed object

Short Form Example

These examples list all of the attribute values for the object specified by the UUID.

java -jar okvrestservices.jar kmip -c conf_file -s list_attr -u D69D2F32-2DBB-4FF3-BF52-95487526E6EC

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service list_attr --uid D69D2F32-2DBB-4FF3-BF52-95487526E6EC
13.7.5.8 mod_attr Command

The mod_attr command  modifies an object's attributes.

Syntax

Short form:

-s mod_attr -u UUID -n attribute_name -v attribute_value

Long form:

--service mod_attr --uid UUID --attribute attribute_name --value attribute_value

Parameters

Parameter Required? Description

-u, --uid

Required

Universally unique ID (UUID) of the managed object

-n, --attribute

Required

Attribute name. Modifiable attributes include:

  • ACTIVATION_DATE is the date and time when the managed object can first be used.

  • CONTACT_INFO is used for contact purposes only and not policy enforcement.

  • DEACTIVATION_DATE is the date and time when the managed object can no longer be used for any purpose.

  • NAME is a user-friendly name provided to identify and locate an object.

  • PROCESS_START_DATE is the date and time when a key object can first be used to process cryptographically protected data.

  • PROTECT_STOP_DATE is the date and time after which a key object will be used for applying cryptographic protection.

-v, --value

Required

Attribute value. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

Short Form Example

These examples modify the value for attribute PROCESS_START_DATE for the object specified by the UUID. 

java -jar okvrestservices.jar kmip -c conf_file -s mod_attr -u 7D767505-2FBE-4F5E-BF81-F95A4FE88E03 -n PROCESS_START_DATE -v "2030/10/1010:10:10"

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service mod_attr --uid 7D767505-2FBE-4F5E-BF81-F95A4FE88E03 --attribute PROCESS_START_DATE -value "2030/10/1010:10:10"
13.7.5.9 mod_custom_attr Command

The mod_custom_attr command modifies a custom attribute.

Syntax

Short form:

-s mod_custom_attr -u UUID -n attribute_name -i attribute_index -v attribute_value

Long form:

--service mod_custom_attr --uid UUID --attribute attribute_name --index attribute_index --value attribute_value

Parameters

Parameter Required? Description

-u, --uuid

Required

Universally unique ID (UUID) of the managed object

-n, --attrubute

Required

Attribute name. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

-i, --index

Required

Attribute index. The attribute index is a unique position for each attribute. This enables you to distinguish between attributes that have the same name with the index.

-v, --value

Required

Attribute value. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons.

Short Form Example

This examples changes the value for the custom attribute named x_OGG_MK_NAME to OGG_MASTER_KEY_NAME2 for the object specified by the UUID. 

java -jar okvrestservices.jar kmip -c conf_file -s mod_custom_attr -u D69D2F32-2DBB-4FF3-BF52-95487526E6EC -n x-OGG_MK_NAME -i 1 -v OGG_MASTER_KEY_NAME2

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service mod_custom_attr --uid D69D2F32-2DBB-4FF3-BF52-95487526E6EC --attribute x-OGG_MK_NAME --index 1 --value OGG_MASTER_KEY_NAME2

13.7.6 Key Life Cycle Management Commands

The key life management commands perform tasks such as activating and revoking managed cryptographic objects.

You must have the Key Administrator role to use these commands.

  • activate Command
    The activate command activates a managed cryptographic object.
  • destroy Command
    The destroy command destroys a managed object.
  • locate Command
    The locate command locates managed objects.
  • revoke Command
    The revoke command revokes a managed object such as a key or a certificate.
  • query Command
    The query command identifies supported operations and objects.

Parent topic: Oracle Key Vault Key Management REST Client Tool Commands

13.7.6.1 activate Command

The activate command activates a managed cryptographic object.

Syntax

Short form:

-s activate -u unique_identifier

Long form:

--service activate --uid  unique_identifier

Parameters

Parameter Required? Description

-u, --uid

Required

Unique identifier

Short Form Example

This example activates a managed object.

java -jar okvrestservices.jar kmip -c conf_file -s activate --uid 7D767505-2FBE-4F5E-BF81-F95A4FE88E03

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service activate --uid 7D767505-2FBE-4F5E-BF81-F95A4FE88E03
13.7.6.2 destroy Command

The destroy command destroys a managed object.

Syntax

Short form:

-s destroy -u unique_identifier 

Long form:

--service destroy --uid unique_identifier 

Parameters

Parameter Required? Description

-u, --uid

Required

Unique identifier

Short Form Example

This example destroys a managed object.

java -jar okvrestservices.jar kmip -c conf_file -s destroy -u D0ABC5A5-BB30-4F20-BFE2-54E3044F5296

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service destroy --uid D0ABC5A5-BB30-4F20-BFE2-54E3044F5296 
13.7.6.3 locate Command

The locate command locates managed objects.

Syntax

Short form:

-s locate [-x max_uid_# -g group_member –y object_state]

Long form:

--service locate [--max  max_uid_#  --group value –-state object_state]

Parameters

Parameter Required? Description

-x, --max

Optional

Unique identifier

-g, --group

Optional

Group member

-y, --state

Optional

Object state. For a list of valid object state values, see KMIP REST service options that are available when you use OKVRESTSERVICE.

Short Form Example

These examples locate an object based on the specified search criteria.

java -jar okvrestservices.jar kmip -c conf_file -s locate
java -jar okvrestservices.jar kmip -c conf_file -s locate -x 50

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service locate --state ACTIVE --group FRESH 
java -jar okvrestservices.jar kmip --config conf_file --service locate --state ACTIVE --group DEFAULT --max 1
13.7.6.4 revoke Command

The revoke command revokes a managed object such as a key or a certificate.

Syntax

Short form:

-s revoke -u unique_identifier -r revoke_code [-s revoke_reason]

Long form:

--service revoke --uid unique_identifier --code revoke_code [--reason revoke_reason]

Parameters

Parameter Required? Description

-u, --uid

Required

Unique identifier

-q, --code

Required

Revoke code

-r, --reason

Optional

Reason to revoke. When the revoke code is KEY_COMPROMISE, then you must provide compromise occurrence date by using the --compromise_date parameter. For a complete list of valid reasons, see the KMIP REST service options that are available when you use OKVRESTSERVICE.

Short Form Example

This example revokes a managed object.

java -jar okvrestservices.jar kmip -c conf_file -s revoke -u 7D767505-2FBE-4F5E-BF81-F95A4FE88E03 -r CA_COMPROMISE -s "security problem"

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service revoke --uid 7D767505-2FBE-4F5E-BF81-F95A4FE88E03 --code CA_COMPROMISE --reason "security problem"
13.7.6.5 query Command

The query command identifies supported operations and objects.

Syntax

Short form:

-s query

Long form:

--service query

Short Form Example

This example queries the server for supported operations and objects.

java -jar okvrestservices.jar kmip -c conf_file -s query

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service query

13.7.7 Wallet Commands

The wallet commands control wallet memberships.

Parent topic: Oracle Key Vault Key Management REST Client Tool Commands

13.7.7.1 add_member Command

The add_member command add a wallet membership.

Syntax

Short form:

-s add_member -w wallet -u UUID

Long form:

--service add_member --wallet wallet --uid UUID

Parameters

Parameter Required? Description

-u, --uid

Required

Universally unique ID (UUID) of the managed object

-w, --wallet

Required

Wallet name

Short Form Example

java -jar okvrestservices.jar kmip -c conf_file -s add_member -w WALLET -u D69D2F32-2DBB-4FF3-BF52-95487526E6EC

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service add_member --wallet WALLET --uid D69D2F32-2DBB-4FF3-BF52-95487526E6EC

Parent topic: Wallet Commands

13.7.7.2 del_member Command

The del_member command deletes a wallet membership.

Syntax

Short form:

-s del_member -w wallet -u UUID

Long form:

--service del_member --wallet wallet --uid UUID

Parameters

Parameter Required? Description

-u, --uid

Required

Universally unique ID (UUID) of the managed object

-w, --wallet

Required

Wallet name

Short Form Example

java -jar okvrestservices.jar kmip -c conf_file -s del_member -w WALLET -u D69D2F32-2DBB-4FF3-BF52-95487526E6EC

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service del_member --wallet WALLET --uid D69D2F32-2DBB-4FF3-BF52-95487526E6EC

Parent topic: Wallet Commands

13.7.7.3 list_wallet Command

The list_wallet command lists wallets that are managed by the endpoint used to connect to Oracle Key Vault.

Syntax

Short form:

-s list_wallet

Long form:

--service list_wallet

Short Form Example

java -jar okvrestservices.jar kmip -c conf_file -s list_wallet

Long Form Example

java -jar okvrestservices.jar kmip --config conf_file --service list_wallet

Parent topic: Wallet Commands