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.
- About RESTful Services
The Oracle Key Vault tasks that you can automate using RESTful services include endpoint enrollment, virtual wallet management, and key management. - 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. - Enabling RESTful Services
After checking the endpoint requirements, and enabling network services, you can enable RESTful services and then download the RESTful software utility. - Managing the RESTful Services Configuration File
You can use a configuration file to execute RESTful service commands either individually or in a group. - Disabling RESTful Services
You should enable RESTful Services for short periods during endpoint registration and enrollment only. - RESTful Services Administrative Commands
The RESTful services administrative commands are designed for administrators who manage endpoints and endpoint groups. - 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.
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:
-
Enable RESTful services from the Oracle Key Vault management console.
-
Download the RESTful service utility
okvrestservices.jar
. -
Create a configuration file, and then set the properties for the services that you want to run.
-
Execute the service using the RESTful service utility
okvrestservices.jar
, the configuration file, and service command plus options. -
To run multiple RESTful service commands you must:
-
Create a script, and write the RESTful commands into the script.
-
Execute the services using the RESTful service utility
okvrestservices.jar
, the configuration file, and the script file.
-
-
Disable RESTful services when you are finished enrolling and provisioning endpoints.
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.
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.
- 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. - Step 2: Enable Network Services
You must configure web access for RESTful clients by their IP addresses to access the Oracle Key Vault server. - Step 3: Enable RESTful Services
After you have enabled the network services, you can enable the RESTful services. - Step 4: Download the RESTful Software Utility
The RESTful software utility is in theokvrestservices.jar
file.
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.
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.
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.
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:
- Log in as a user with the System Administrator role.
- Click RESTful Service Utility under Downloads in the left sidebar.
The Download RESTful Utility page appears.
- Click Download in the top right.
A directory window appears with a prompt to save the utility file
okvrestservices.jar
in a local directory. - Save the file to a secure location.
- From the Endpoint Enrollment and Software Download of the Oracle Key Vault management console:
- Connect to the Oracle Key Vault management console.
The login page to the Oracle Key Vault management console appears. Do not log in.
- In the lower-right corner of the login page under Login, click Endpoint Enrollment and Software Download.
- Click the Download OKV Automation Utility tab.
- Click the Download button.
- Download the
okvrestservices.jar
to a secure location.
- Connect to the Oracle Key Vault management console.
- Using a command-line HTTP client such as
wget
orcurl
. 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
- From the Home page of the Oracle Key Vault management console:
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.
- 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. - Configuration File Creation Guidelines
You should follow the recommended guidelines to avoid script execution errors. - Creating the RESTful Services Configuration File
You must set properties in the configuration file that the RESTful service utility will use to run commands. - Examples of Configuration Files
You can create a configuration file that uses an IP address and a host name. - 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. - 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. - 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.
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.
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.
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.
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.
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.
- configuration file (for example,
config.ini
) ewallet.p12
andcwallet.sso
wallet filesrun-me.sh
script
The following procedure explains how to create these components.
13.5 Disabling RESTful Services
You should enable RESTful Services for short periods during endpoint registration and enrollment only.
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.
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 |
---|---|
|
Adds an endpoint to an endpoint group. The endpoint must already exist. |
|
Sets access mappings on a virtual wallet for an endpoint |
|
Sets access mappings on a virtual wallet for an endpoint group |
|
Checks the status of an endpoint, endpoint group, or wallet |
|
Adds an endpoint to Oracle Key Vault. When added, the endpoint is in the Registered state. |
|
Adds a new endpoint group |
|
Adds a unique endpoint to Oracle Key Vault. |
|
Adds a unique endpoint group to Oracle Key Vault. |
|
Adds a unique virtual wallet to Oracle Key Vault |
|
Adds a virtual wallet to Oracle Key Vault |
|
Removes an endpoint from Oracle Key Vault |
|
Deletes an endpoint group |
|
Removes the virtual wallet from Oracle Key Vault |
|
Downloads the endpoint software |
|
Removes an endpoint from an endpoint group |
|
Removes access mappings on a virtual wallet for an endpoint |
|
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 |
|
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 |
|
Changes the endpoint description |
|
Changes the endpoint's email |
|
Changes the endpoint group |
|
Changes the endpoint group description |
|
Changes the endpoint name |
|
Changes the endpoint platform |
|
Changes the endpoint type |
|
Changes access mappings on a virtual wallet for an endpoint |
|
Changes access mappings on a virtual wallet for an endpoint group |
|
Changes the virtual wallet description |
|
Changes the virtual wallet name |
|
Downloads and installs the endpoint software |
|
Reenrolls an endpoint |
|
Reenrolls all endpoints |
|
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 |
---|---|---|
|
Optional |
Adds a user to wallet |
|
Optional |
Deletes a user from a wallet |
|
Optional |
Performs the operation without prompting for confirmation |
|
Required |
Stands for the absolute path to the wallet location |
|
Optional |
Lists the users who have access to a wallet |
|
Optional |
Modifies a user's password |
|
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.
- create_endpoint Command
Thecreate_endpoint
command adds a new endpoint to Oracle Key Vault. - create_unique_endpoint Command
Thecreate_unique_endpoint
command adds a new unique endpoint to Oracle Key Vault. - delete_endpoint Command
Thedelete_endpoint
command removes an endpoint from Oracle Key Vault. - download Command
Thedownload
command downloads the endpoint software (okvclient.jar
) to a directory that you name. - get_enrollment_token Command
Theget_enrollment_token
command retrieves an enrollment token for a registered endpoint. - modify_endpoint_desc Command
Themodify_endpoint_desc
command changes the description of an endpoint. - modify_endpoint_email Command
Themodify_endpoint_email
command changes the email address for the endpoint. - modify_endpoint_name Command
Themodify_endpoint_name
command changes the name of an endpoint. - modify_endpoint_platform Command
Themodify_endpoint_platform
command changes the platform for an endpoint. - modify_endpoint_type Command
Themodify_endpoint_type
command changes the endpoint type. - provision Command
Theprovision
command downloads and installs the endpoint software in the specified directory, which must exist. - re_enroll Command
There_enroll
command re-enrolls a previously enrolled endpoint in order to upgrade the endpoint software. - re_enroll_all Command
There_enroll_al
command re-enrolls all previously enrolled endpoints in order to upgrade the endpoint software.
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 |
---|---|---|
|
Required |
The name of the endpoint that you want to add. See Naming Guidelines for Objects. |
|
Optional |
A user friendly description of the endpoint. If the description contains spaces, you must enclose it within double quotation marks. |
|
Required |
The endpoint platform. Allowed values are:
|
|
Required |
Type of the endpoint. Allowed values are:
|
|
Optional |
Email address of the endpoint administrator. Enclose this value in double quotation marks. |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
The name of the endpoint that you want to add. See Naming Guidelines for Objects. |
|
Optional |
A user friendly description of the endpoint. If the description contains spaces, then you must enclose it within double quotation marks. |
|
Required |
The endpoint platform. Allowed values are:
|
|
Required |
Type of the endpoint. Allowed values are:
|
|
Required |
Email address of the endpoint administrator. Enclose this value in double quotation marks. |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax |
|
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
Optional |
Forces the deletion and suppresses the confirmation message |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
Required |
Absolute path to the download directory for the endpoint software. For example, if you specify |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
Required |
New description string for this endpoint enclosed within double quotation marks |
|
Required |
Specifies the absolute path to the configuration file |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
Required |
The new email address for this endpoint. Enclose this value in double quotation marks. |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Current name of the endpoint. |
|
Required |
New name for this endpoint. See Naming Guidelines for Objects. |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
Required |
Platform of the server for this endpoint. Values are as follows:
|
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
Required |
Type of the endpoint. Values are as follows:
|
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint. |
|
Required |
Existing directory in which to download and install the endpoint software |
|
Required if |
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.
|
|
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 |
|
Required |
The endpoint credentials to connect to the Oracle Key Vault server are stored in an auto-login wallet. |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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.
- add_epg_member Command
Theadd_epg_member
command adds an existing endpoint to an endpoint group. - create_endpoint_group Command
Thecreate_endpoint_group
command creates a new endpoint group. - create_unique_endpoint_group Command
Thecreate_unique_endpoint_group
command creates a new endpoint group. - delete_endpoint_group Command
Thedelete_endpoint_group
command removes an endpoint group from Oracle Key Vault. - drop_epg_member Command
Thedrop_epg_member
command removes an endpoint from an endpoint group. - modify_endpoint_group_desc Command
Themodify_endpoint_group_desc
command changes the description of an endpoint group. - modify_endpoint_group_name Command
Themodify_endpoint_group_name
command changes the name of an endpoint group.
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
Required |
Name of the endpoint group |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint group. See Naming Guidelines for Objects. |
|
Optional |
A user-friendly description of the endpoint group enclosed within double quotation marks |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint group. See Naming Guidelines for Objects. |
|
Optional |
A user-friendly description of the endpoint group enclosed within double quotation marks |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint group |
|
Optional |
Force the deletion and suppresses the confirmation message |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
Required |
Name of the endpoint group |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint group |
|
Required |
The new description string for the endpoint group enclosed within double quotation marks |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Current name of the endpoint group. |
|
Required |
New endpoint group name. See Naming Guidelines for Objects. |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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.
- add_wallet_access_ep Command
Theadd_wallet_access_ep
command grants an endpoint a level of access to a virtual wallet. - add_wallet_access_epg Command
Theadd_wallet_access_epg
command grants an endpoint group a level of access to a virtual wallet. - create_unique_wallet Command
Thecreate_unique_wallet
command creates a unique virtual wallet. - create_wallet Command
Thecreate_wallet
command creates a virtual wallet. - delete_wallet Command
Thedelete_wallet
command deletes a wallet from Oracle Key Vault. - drop_wallet_access_ep Command
Thedrop_wallet_access_ep
command removes an endpoint's access to a wallet. - drop_wallet_access_epg Command
Thedrop_wallet_access_epg
command removes an endpoint group's access to virtual wallet. - get_default_wallet Command
Theget_default_wallet
command gets the default wallet associated with an endpoint. - get_object_name Command
Theget_object_name
command retrieves the name of a managed object if the object status isACTIVE
. - get_wallets Command
Theget_wallets
command gets all the virtual wallets associated with an endpoint. - modify_wallet_access_ep Command
Themodify_wallet_access_ep
command changes the virtual wallet access level to an endpoint. - modify_wallet_access_epg Command
Themodify_wallet_access_epg
command modifies the virtual wallet access level to an endpoint group. - modify_wallet_desc Command
Themodify_wallet_desc
command modifies the description of an existing virtual wallet. - modify_wallet_name Command
Themodify_wallet_name
command modifies the virtual wallet name. - set_default_wallet Command
Theset_default_wallet
command sets the default wallet for an endpoint.
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
Required |
Name of the virtual wallet |
|
Required |
Level of access for the virtual wallet. Values are as follows:
|
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint group |
|
Required |
Name of the virtual wallet |
|
Required |
Level of access for the virtual wallet. Values are as follows:
|
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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. The create_unique_wallet
command always appends _OKVxx
to the wallet’s name, thus preventing any name conflicts.
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.
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 |
---|---|---|
|
Required |
The name of the unique wallet that you want to create. See Naming Guidelines for Objects. |
|
Optional |
A descriptive name for the unique wallet enclosed within double quotation marks |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the virtual wallet. See Naming Guidelines for Objects. |
|
Optional |
A descriptive name for the virtual wallet enclosed within double quotation marks |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the virtual wallet |
|
Optional |
Forces the deletion without prompting for confirmation |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
Required |
Name of the virtual wallet |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint group |
|
Required |
Name of the virtual wallet |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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
get_default_wallet -e endpoint_name
get_default_wallet --ep_name endpoint_name
Parameters
Parameter | Required? | Description |
---|---|---|
-e, |
Required | Endpoint name, whose default wallet to get |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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
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 |
---|---|---|
|
Required |
Unique identifier |
|
Required |
Specifies the object type to check. Valid values include:
|
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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
get_wallets -e endpoint_name
get_wallets --ep_name endpoint_name
Parameters
Parameter | Required? | Description |
---|---|---|
-e, |
Required | Endpoint name, whose virtual wallets to get |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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
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 |
---|---|---|
|
Required |
Name of the endpoint |
|
Required |
Name of the virtual wallet |
|
Required |
Level of access for the virtual wallet. Values are as follows:
|
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the endpoint group |
|
Required |
Name of the virtual wallet |
|
Required |
Level of access for the virtual wallet. Values are as follows:
|
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the virtual wallet |
|
Required |
The new description string for the virtual wallet enclosed within double quotation marks |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Current name of the wallet |
|
Required |
New virtual wallet name. See Naming Guidelines for Objects. |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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 |
---|---|---|
|
Required |
Name of the virtual wallet |
|
Required |
Endpoint name for whom default wallet is set |
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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
Thecheck_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 utilityokvrestservices.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 |
---|---|---|
|
Required if |
UID (universally unique ID) of the managed object. You can use |
|
Required if |
Specifies the name of the object to check. You can use |
|
Required |
Specifies the object type to check. Valid values include:
|
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration fil |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax |
|
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
java -jar okvrestservices.jar --config conf_file --service check_object_status --type EP --uid 7C3DC1FF-213A-4FBE-BF4A-98A04F8D05DF
Parent topic: General Status and Help Information Commands
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 |
---|---|---|
|
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 |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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]
Parent topic: General Status and Help Information Commands
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
Parent topic: General Status and Help Information Commands
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.
- get_cluster_info Command
Theget_cluster_info
command retrieves status information about a cluster. - get_cluster_node_info Command
Theget_cluster_node_info
command retrieves status information about the nodes in the cluster.
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 |
---|---|---|
|
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. |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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]
Parent topic: Multi-Master Cluster Information Commands
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
, orDISABLED
- 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 |
---|---|---|
|
Optional |
Retrieves the details of a specific node. |
|
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. |
|
Optional |
Specifies the password for the Oracle Key Vault user account specified in the If you omit this option, then you will be prompted to enter the password interactively. For greater security, omit this option. |
|
Required |
Specifies the absolute path to the configuration file. |
|
Required |
Specifies the RESTful service that you want to execute listed in RESTful Services Command Syntax. |
|
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]
Parent topic: Multi-Master Cluster Information Commands
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.
- About Error Reporting
The status of command execution, passed and failed, is reported promptly on the command line and written to the log file. - Command Line Error Reporting
Error reporting captures both faulty actions, such as incorrect passwords, and successful command executions. - 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.
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.
- 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 usingokvrestservice.jar
commands. - Oracle Key Vault Key Management REST Client API Using OKVRESTSERVICE
To call the KM REST client API usingOKVRESTSERVICE
(okvrestservice.jar
), you must include thekmip
option. - List of Key Management REST Client Tool Commands
The RESTful key management client tools perform tasks such as creating and activating keys. - Key Creation and Registration Commands
The key creation and registration commands perform tasks such as registering different types of security objects. - Key Attribute Management Commands
The key attribute management commands perform tasks such as adding, modifying, and deleting standard and custom attributes. - Key Life Cycle Management Commands
The key life management commands perform tasks such as activating and revoking managed cryptographic objects. - Wallet Commands
The wallet commands control wallet memberships.
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.
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 |
---|---|
|
Cryptographic algorithm to use. Choices are:
|
|
Specifies the absolute path to the configuration file |
|
User name |
|
The attribute list file. The file format is:
|
|
Group member |
|
Attribute index |
|
Key lengths supported:
|
|
Cryptographic usage mask. Valid values include the following settings, which are described in the Key Management Interoperability Protocol (KMIP) Specification version 1.1.
|
|
Attribute name |
|
Path to object file to register |
|
Revoke code values include:
|
|
Revoke reason message |
|
Object type to register |
|
UUID (Universally Unique ID) of the managed object |
|
Attribute value |
|
Wallet name |
|
Maximum number of UIDs to display |
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 |
---|---|
|
Activates a managed cryptographic object |
|
Adds a new attribute for an object and sets its value |
|
Adds a custom attribute specifying name, type, and value |
|
Adds a user to a wallet |
|
Gets all attribute names and values |
|
Creates a new key |
|
Deletes an attribute of a managed object |
|
Deletes a custom attributes |
|
Deletes a user from a wallet |
|
Requests the server to destroy the key data for the managed object |
|
Retrieves one or more attribute values of an object |
|
Requests a digital certificate from the server |
|
Retrieves an encryption key from the server |
|
Retrieves an object that contains secret data |
|
Retrieves all available attribute names and values |
|
Lists all available attribute names only |
|
Lists virtual wallets |
|
Searches for one or more managed objects |
|
Modifies the value of an attribute for a managed object |
|
Modifies a custom attribute |
|
Queries the server regarding its supported capabilities |
|
Registers a digital certificate |
|
Registers a key |
|
Registers an object containing data that the server may not be able to interpret |
|
Registers an object containing secret data |
|
Revokes a managed cryptographic object. |
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.
- create_key Command
Thecreate_key
command creates a new key. - get_cert Command
Theget_cert
command retrieves a digital certificate. - get_key Command
Theget_key
command retrieves an encryption key. - get_opaque Command
Theget_opaque
command retrieves an object that contains secret data. - get_secret Command
Theget_secret
command retrieves an object that contains secret data. - reg_cert Command
Thereg_cert
command registers a certificate. - reg_key Command
Thereg_key
command registers a key. - reg_opaque Command
Thereg_opaque
command registers opaque objects. - reg_secret Command
Thereg_secret
command registers secret data such as passwords or random seeds.
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 |
---|---|---|
|
Required |
Cryptographic algorithm |
|
Required |
Key length |
|
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"
Parent topic: Key Creation and Registration Commands
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 |
---|---|---|
|
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
Parent topic: Key Creation and Registration Commands
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 |
---|---|---|
|
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
Parent topic: Key Creation and Registration Commands
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 |
---|---|---|
|
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
Parent topic: Key Creation and Registration Commands
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 |
---|---|---|
|
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
Parent topic: Key Creation and Registration Commands
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 |
---|---|---|
|
Required |
Object type |
|
Required |
Key length |
|
Required |
Algorithm |
|
Required |
Cryptographic usage mask |
|
Required |
Path to object attributes file |
|
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
Parent topic: Key Creation and Registration Commands
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 |
---|---|---|
|
Required |
Key length |
|
Required |
Algorithm |
|
Required |
Cryptographic usage mask |
|
Required |
Path to key file |
|
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
Parent topic: Key Creation and Registration Commands
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 |
---|---|---|
|
Required |
Cryptographic usage mask |
|
Required |
Path to object file |
|
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
Parent topic: Key Creation and Registration Commands
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 |
---|---|---|
|
Required |
Object type |
|
Required |
Cryptographic usage mask |
|
Required |
Path to object attributes file |
|
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
Parent topic: Key Creation and Registration Commands
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.
- add_attr Command
Theadd_attr
command adds an attribute to a managed object. - add_custom_attr Command
Theadd_custom_attr
command adds a custom attribute to an object. - all_attr Command
Theall_attr
command retrieves all attributes of an object. - del_attr Command
Thedel_attr
command deletes an attribute from a managed object. - del_custom_attr Command
Thedel_custom_attr
command deletes a custom attribute. - get_attr Command
Theget_attr
command retrieves an attribute or list of attributes of an object. - list_attr Command
Thelist_attr
command retrieves a list of attributes of an object. - mod_attr Command
Themod_attr
command modifies an object's attributes. - mod_custom_attr Command
Themod_custom_attr
command modifies a custom attribute.
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 |
---|---|---|
|
Required |
Universally unique ID (UUID) of the managed object |
|
Required |
Attribute name. Modifiable attributes include:
|
|
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"
Parent topic: Key Attribute Management Commands
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 |
---|---|---|
|
Required |
Universally unique ID (UUID) of the managed object |
|
Required |
Custom attribute name. Must include the prefix |
|
Required |
Object type. Can be |
|
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
Parent topic: Key Attribute Management Commands
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 |
---|---|---|
|
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
Parent topic: Key Attribute Management Commands
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 |
---|---|---|
|
Required |
Universally unique ID (UUID) of the managed object |
|
Required |
Attribute name. Modifiable attributes include:
|
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
Parent topic: Key Attribute Management Commands
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 |
---|---|---|
|
Required |
Universally unique ID (UUID) of the managed object |
|
Required |
Attribute name. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons. |
|
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
Parent topic: Key Attribute Management Commands
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 |
---|---|---|
|
Required |
Universally unique ID (UUID) of the managed object |
|
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"
Parent topic: Key Attribute Management Commands
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 |
---|---|---|
|
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
Parent topic: Key Attribute Management Commands
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 |
---|---|---|
|
Required |
Universally unique ID (UUID) of the managed object |
|
Required |
Attribute name. Modifiable attributes include:
|
|
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"
Parent topic: Key Attribute Management Commands
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 |
---|---|---|
|
Required |
Universally unique ID (UUID) of the managed object |
|
Required |
Attribute name. Enclose this value in double quotation marks if the value contains spaces, slashes, or colons. |
|
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. |
|
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
Parent topic: Key Attribute Management Commands
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
Theactivate
command activates a managed cryptographic object. - destroy Command
Thedestroy
command destroys a managed object. - locate Command
Thelocate
command locates managed objects. - revoke Command
Therevoke
command revokes a managed object such as a key or a certificate. - query Command
Thequery
command identifies supported operations and objects.
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 |
---|---|---|
|
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
Parent topic: Key Life Cycle Management Commands
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 |
---|---|---|
|
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
Parent topic: Key Life Cycle Management Commands
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 |
---|---|---|
|
Optional |
Unique identifier |
|
Optional |
Group member |
|
Optional |
Object state. For a list of valid object state values, see KMIP REST service options that are available when you use |
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
Parent topic: Key Life Cycle Management Commands
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 |
---|---|---|
|
Required |
Unique identifier |
|
Required |
Revoke code |
|
Optional |
Reason to revoke. When the revoke code is |
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"
Parent topic: Key Life Cycle Management Commands
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
Parent topic: Key Life Cycle Management Commands
13.7.7 Wallet Commands
The wallet commands control wallet memberships.
- add_member Command
Theadd_member
command add a wallet membership. - del_member Command
Thedel_member
command deletes a wallet membership. - list_wallet Command
Thelist_wallet
command lists wallets that are managed by the endpoint used to connect to Oracle Key Vault.
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 |
---|---|---|
|
Required |
Universally unique ID (UUID) of the managed object |
|
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 |
---|---|---|
|
Required |
Universally unique ID (UUID) of the managed object |
|
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