2 Getting Started with Oracle Key Vault RESTful Services
After you download the RESTful services utility and customize its configuration files, you can begin to use the Oracle Key Vault RESTful services utility commands.
- Enabling or Disabling Oracle Key Vault RESTful Services
You enable and disable RESTful services from the Oracle Key Vault management console. - Oracle Key Vault RESTful Services Configuration and Logging Files
Oracle Key Vault provides two files,okvrestcli.ini
andokvrestcli_logging.properties
, that you can use to specify required or optional settings for when you execute RESTful services utility commands. - Executing Oracle Key Vault RESTful Services Utility Commands
Oracle Key Vault provides a variety of ways to execute RESTful services utility commands. - Naming Guidelines for Objects
The naming guidelines affect the following Oracle Key Vault objects: users, user groups, endpoints, endpoint groups, and virtual wallets. - Using RESTful Services with LDAP Users
Both regular Oracle Key Vault administrators and properly authorized LDAP users can log in to a server to execute Oracle Key Vault RESTful services utility commands.
2.1 Enabling or Disabling Oracle Key Vault RESTful Services
You enable and disable RESTful services from the Oracle Key Vault management console.
- Enabling RESTful Services
After checking the endpoint requirements, and enabling network services, you can enable RESTful services, download the RESTful software utility, and then customize its configuration files. - Disabling RESTful Services
You should enable RESTful services for short periods during when administrative tasks are performed.
Parent topic: Getting Started with Oracle Key Vault RESTful Services
2.1.1 Enabling RESTful Services
After checking the endpoint requirements, and enabling network services, you can enable RESTful services, download the RESTful software utility, and then customize its configuration files.
- Step 1: Check the Endpoint System Requirements
Before you can provision endpoints with the RESTful command-line interface, you must have the tools to transfer data securely across the network. - 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 Services Utility
The RESTful services utility is in theokvrestclipackage.zip
file. - Step 5: Configure the RESTful Services Utility
After you have downloaded the RESTful services utility, you must modify a couple of files that are included in its zip file.
Parent topic: Enabling or Disabling Oracle Key Vault RESTful Services
2.1.1.1 Step 1: Check the Endpoint System Requirements
Before you can provision endpoints with the RESTful command-line interface, you must have the tools to transfer data securely across the network.
Parent topic: Enabling RESTful Services
2.1.1.2 Step 2: Enable Network Services
You must configure web access for RESTful clients by their IP addresses to access the Oracle Key Vault server.
Parent topic: Enabling RESTful Services
2.1.1.3 Step 3: Enable RESTful Services
After you have enabled the network services, you can enable the RESTful services.
Parent topic: Enabling RESTful Services
2.1.1.4 Step 4: Download the RESTful Services Utility
The RESTful services utility is in the okvrestclipackage.zip
file.
- Use one of the following methods to download the Oracle Key Vault RESTful services utility
okvrestclipackage.zip
file:- From the Home page of the Oracle Key Vault management console:
- Log in as a user with the System Administrator role.
- Select the System tab.
- In the left sidebar, select Settings.
- Under System Configuration, select RESTful Services.
- In the RESTful Services dialog box, select Download.
To download the Oracle Key Vault Classic RESTful Service Utility, click Download Classic Utility. For information about using this version, see the release 18.6 version of Oracle Key Vault Administrator's Guide
- In the Opening okvrestclipackage.zip dialog box, select Save to save the
okvrestclipackage.zip
file locally.
- From the Endpoint Enrollment and Software Download of the Oracle Key Vault management console:
- 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 RESTful Service Utility tab.
- Click the Download button.
To download the Classic RESTful Service Utility, click Download Classic Utility.
- Download the
okvrestclipackage.zip
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/okvrestclipackage.zip curl -k https://ip_address:5695/okvrestclipackage.zip -o okvrestclipackage.zip curl -O -k https://ip_address:5695/okvrestclipackage.zip
- From the Home page of the Oracle Key Vault management console:
Parent topic: Enabling RESTful Services
2.1.1.5 Step 5: Configure the RESTful Services Utility
After you have downloaded the RESTful services utility, you must modify a couple of files that are included in its zip file.
okvrestcli.ini
and okvrestcli_logging.properties
configuration files for your environment.
Parent topic: Enabling RESTful Services
2.1.2 Disabling RESTful Services
You should enable RESTful services for short periods during when administrative tasks are performed.
Parent topic: Enabling or Disabling Oracle Key Vault RESTful Services
2.2 Oracle Key Vault RESTful Services Configuration and Logging Files
Oracle Key Vault provides two files, okvrestcli.ini
and okvrestcli_logging.properties
, that you can use to specify required or optional settings for when you execute RESTful services utility commands.
- okvrestcli.ini Configuration File
Theokvrestcli.ini
file enables you to control global settings that are used in the Oracle Key Vault RESTful services utility commands. - okvrestcli_logging.properties Log File Parameter Settings
Theokvrestcli_logging.properties
log file determines how logging is handled for Oracle Key Vault RESTful services activities.
Parent topic: Getting Started with Oracle Key Vault RESTful Services
2.2.1 okvrestcli.ini Configuration File
The okvrestcli.ini
file enables you to control global settings that are used in the Oracle Key Vault RESTful services utility commands.
- About the okvrestcli.ini Configuration File
Theokvrestcli.ini
file enables you to configure commonly used settings when you execute Oracle Key Vault RESTful services utility commands. - okvrestcli.ini Configuration Parameters
Theokvrestcli.ini
parameters cover settings such as the name and password of a user, the location of theokvclient.ora
file, and so on. - [DEFAULT] and Named Profiles in the okvrestcli.ini File
The[DEFAULT]
and named profile sections of theokvrestcli.ini
file enable you to maintain different sets of configuration parameter settings that can be applied when executing commands in different contexts. - Precedence Order of okvrestcli.ini Parameters
When you execute an Oracle Key Vault RESTful service command, the configuration parameter values are determined on the basis of an order of precedence. - Using an Alternative Configuration File
You can use an alternative parameter configuration file from theokvrestcli.ini
configuration file.
2.2.1.1 About the okvrestcli.ini Configuration File
The okvrestcli.ini
file enables you to configure commonly used settings when you execute Oracle Key Vault RESTful services utility commands.
These are settings such as the user's name or the IP address of an Oracle Key Vault server. The RESTful service utility requires these kinds of configuration parameters in the okvrestcli.ini
file to be set for each command execution. The settings that you set in this file are automatically applied to all Oracle Key Vault RESTful services utility commands without the need for you to manually enter them at the command line each time that you want to execute the command.
The configuration parameters in the okvrestcli.ini
are grouped together in different sections called named profiles. Each section includes the profile name and list of the parameters that are associated with the profile. When you execute the command with a named profile (using the --profile
profile_name
parameter), the configuration parameters listed under the named profile apply for the execution of the command. The configuration parameters listed under the [DEFAULT]
profile represent default parameter settings that apply when either no named profile is specified or the parameter is not listed under the named profile.
By default, the okvrestcli.ini
is in the same location where you downloaded the Oracle Key Vault RESTful services utility, in the OKV_HOME/conf
directory of the endpoint.
Related Topics
Parent topic: okvrestcli.ini Configuration File
2.2.1.2 okvrestcli.ini Configuration Parameters
The okvrestcli.ini
parameters cover settings such as the name and password of a user, the location of the okvclient.ora
file, and so on.
The okvrestcli.ini
parameters are as follows:
-
server
: Determines the target Oracle Key Vault server where command is sent for execution. Enter the IP address of this server. Server information can also be obtained from theokvclient.ora
file when you set theokv_client_config
parameter.In a multi-master deployment of an Oracle Key Vault cluster, Oracle Key Vault dynamically updates the server information in the endpoint's configuration file
okvclient.ora
based on the endpoint's cluster subgroup setting, as well as any changes to the cluster topology or the state of the Oracle Key Vault cluster nodes. Using the server information from endpoint'sokvclient.ora
enables Oracle Key Vault to automatically select the best Oracle Key Vault node to execute the REST commands without you having to constantly update theSERVER
parameter inokvrestcli.ini
. -
okv_client_config
: Specifies the full path of theokvclient.ora
file for an endpoint. By default, this file is located in the$OKV_HOME/conf
directory. This parameter is mandatory if you want to execute managed-object RESTful services utility commands, which must always be executed with the identity of an endpoint. The Oracle Key Vault RESTful services utility uses only the following information from theokvclient.ora
file:- server information: IP address or host name of Oracle Key Vault server(s).
SSL_WALLET_LOC
: location of the wallet that the endpoint uses.
This is a string value and is required.
-
user
: Specifies the Oracle Key Vault user who is executing the RESTful services command. The user must have appropriate privileges to execute the command.Oracle Key Vault does not use the
user
parameter when the RESTful services utility commands for the managed-object category are executed. These commands are always executed with the identity of an endpoint that is set with theokv_client_config
parameter. -
client_wallet
: Specifies the absolute path to a wallet which contains user credentials. This wallet can be used to log into the Oracle Key Vault server without having to manually specify the user’s password. The user information is obtained from theuser
parameter. Theclient_wallet
parameter enables implementation and use of automation scripts that need to run in an unattended mode.Oracle Key Vault does not use the
client_wallet
parameter when the RESTful services utility commands for the managed-object category are executed. These commands are always executed with the identity of an endpoint that is set with theokv_client_config
parameter. -
password
: Specifies the password of the user executing the RESTful services utility commands. Ifclient_wallet
is specified, then thepassword
parameter is not required. If bothclient_wallet
andpassword
parameters are specified, then thepassword
parameter takes precedence overclient_wallet
.Oracle Key Vault does not use the
password
parameter when the RESTful services utility commands for the managed-object category are executed. These commands are always executed with the identity of an endpoint that is set with theokv_client_config
parameter. -
log_property
: Specifies the full path of the Java logging property file. If this parameter is not set, then when you execute a RESTful command, Oracle Key Vault generates a log file with the default name in the current directory with theINFO
level along with the message in a log file sayinglog_property
is not configured. The default log property file is a part of the downloadedokvrestclipackage.zip
file. This file enables you to customize the log file and its format. This is a string value and it is optional.
Parent topic: okvrestcli.ini Configuration File
2.2.1.3 [DEFAULT] and Named Profiles in the okvrestcli.ini File
The [DEFAULT]
and named profile sections of the okvrestcli.ini
file enable you to maintain different sets of configuration parameter settings that can be applied when executing commands in different contexts.
The okvrestcli.ini
file is organized as one or more named profile sections. A named profile section represents a collection of configuration parameter settings that are logically group together. A named profile section includes:
- Named profile section header denoted as
[profile_name]
- Listing of configuration parameters under the name profile header
You apply the configuration parameter settings listed under a named profile by specifying the profile name in the command line with parameter --profile
profile_name
.
The [DEFAULT]
profile lists the default values of the okvrestcli.ini
parameters. The parameter settings under the [DEFAULT]
profile apply when either no named profile is specified during command execution or the parameter is not listed under the named profile, and assuming you do not specify the parameter in the command line.
The following example shows the use of profiles that is suitable for connecting to Oracle Key Vault using identities of different endpoints. This is useful in an environment where you have isolated PDB endpoints configured on the same host. This okvrestcli.ini
file has a named profile for each PDB endpoint that points to respective okvclient.ora
file.
[DEFAULT]
log_property=/usr/local/okv/logging.property
server = 192.0.2.191
[HR_PDB]
okv_client_config=/usr/local/okv/hr_ep/okvclient.ora
[FIN_PDB]
okv_client_config=/usr/local/okv/finance_ep/okvclient.ora
[SALES_PDB]
okv_client_config=/usr/local/okv/sales_ep/okvclient.ora
To create a key using HR_DB
endpoint, you use the [HR_DB]
profile:
okv managed-object key create --profile HR_DB --algorithm AES --length 256 --mask "ENCRYPT,DECRYPT" --wallet hr_wallet
This command uses the okv_client_config
parameter from [HR_DB]
profile. Other configuration parameters (for example, log_property
and server
) are applied from the [DEFAULT]
profile.
This example shows the use case of using profiles in a multi-master cluster environment where you create a profile for each node in the cluster to use settings that are specific to that node. The following example contains profiles for three nodes in a cluster:
[DEFAULT]
log_property=/usr/local/okv/logging.property
user=okvadmin
server=192.0.2.191
[NODE1]
server=192.0.2.191
[NODE2]
server=192.0.2.192
[NODE3]
server=192.0.2.193
To execute a command on NODE2
, you use the [NODE2]
profile:
okv server status get --profile NODE2
This command uses the server entry from [NODE2]
profile. The other configuration parameter settings are used from the [DEFAULT]
profile.
Before you work with [DEFAULT]
settings and profiles, ensure that you understand the precedence order of the okvrestcli.ini
parameters.
Related Topics
Parent topic: okvrestcli.ini Configuration File
2.2.1.4 Precedence Order of okvrestcli.ini Parameters
When you execute an Oracle Key Vault RESTful service command, the configuration parameter values are determined on the basis of an order of precedence.
Parameter Precedence Order
The order of precedence for okvrestcli.ini
configuration file parameters (except for the server
entry) is as follows:
- Parameter value is specified by the user in the command line.
- Parameter value is specified in the profile section. User includes the
--profile
parameter in the command line. - Parameter value is specified in the
[DEFAULT]
profile. User makes no reference in the command line.
Examples of How Parameter Precedence Works
The following examples show how parameter precedence works for the following okvrestcli.ini
file, which contains different settings for the user
parameter under the [DEFAULT]
and [HR]
profiles.
[DEFAULT]
user= psmith
[HR]
user=jgreenberg
- Example 1: To specify the default user,
psmith
, simply omit any reference to this user from the command line.okv manage-access endpoint-group add-endpoint --endpoint-group epg_1 --endpoint ep_1
- Example 2: To override the default user and specify user
jgreenberg
, who is in theHR
profile, specify theHR
profile in the command line.okv manage-access endpoint-group add-endpoint --profile HR --endpoint-group epg_1 --endpoint ep_1
- Example 3: To override all the
user
settings inokvrestcli.ini
, include the--user
setting in the command line.okv manage-access endpoint-group add-endpoint --user kjones --endpoint-group epg_1 --endpoint ep_1
server Parameter Precedence Order
The server
parameter has a slightly different precedence behavior from the other okvrestcli.ini
parameter settings, because in addition to the okvrestcli.ini
file, its setting can come the okvclient.ora
file. The location of the okvclient.ora
file is specified with the okv_client_config
parameter in okvrestcli.ini
. The server
entry that is specified directly takes precedence over the server
entry from the okv_client_config
parameter.
The order of precedence for the server
entry is as follows:
server
parameter value is specified by the user in the command line.- Server information is obtained from the
okvclient.ora
file. User specifies this file by including theokv_client_config
parameter in the command line. -
server
parameter value is specified in the profile section. User includes the--profile
parameter in the command line. - Server information is obtained from the
okvclient.ora
file, which is set by theokv_client_config
parameter from a profile section. User specifies this profile by using the--profile
parameter in the command line. server
parameter value is specified in the[DEFAULT]
profile. User makes no reference in the command line.- Server information is obtained from the
okvclient.ora
file that is specified withokv_client_config
parameter in the[DEFAULT]
section. User makes no reference in the command line.
Examples of How the server Parameter Precedence Order Works
The following examples show how the server
parameter precedence works based on various ways that this parameter can be set:
- Example 1: Assume that the
okvrestcli.ini
configuration file has the following setting:[DEFAULT] server=192.0.2.190
To use this default setting (that is, to use IP address 192.0.2.190), omit any reference to it from the command line.
okv manage-access endpoint-group add-endpoint --endpoint-group epg_1 --endpoint ep_1
- Example 2: Assume that the
okvrestcli.ini
configuration file has the following setting:[DEFAULT] okv_client_config=/usr/local/okv/okvclient/okvclient.ora
The
okv_client_config
parameter points to anokvclient.ora
file that contains theserver
setting that you want to use. Becauseokv_client_config
is in the[DEFAULT]
section, to use thisokvclient.ora
, omit the reference to it from the command line.okv manage-access endpoint-group add-endpoint --endpoint-group epg_1 --endpoint ep_1
- Example 3: Assume that the
okvrestcli.ini
configuration file has the following settings for the default and for a profile called[NODE_1]
:[DEFAULT] okv_client_config=/usr/local/okv/okvclient/okvclient.ora [NODE_1] server=192.0.2.191
To override the default server setting from
okv_client_config
with the[NODE_1]
profile setting of 192.0.2.191, include the--profile
parameter in the command line.okv manage-access endpoint-group add-endpoint --profile node_1 --endpoint-group epg_1 --endpoint ep_1
- Example 4: Assume that the
okvrestcli.ini
configuration file has the following settings:[DEFAULT] server = 192.0.2.191 [HR] okv_client_config=/usr/local/okv/hr_ep/okvclient.ora
To override the default and use the server setting in the
okvclient.ora
file, as with Example 3, include the--profile
parameter in the command.okv manage-access endpoint-group add-endpoint --profile hr --endpoint-group epg_1 --endpoint ep_1
- Example: 5: Assume that the
okvrestcli.ini
configuration file is as follows:[DEFAULT] server = 192.0.2.191 [HR] okv_client_config=/usr/local/okv/hr_ep/okvclient.ora
To override all of these settings, directly specify the appropriate server IP address setting in the command line.
okv manage-access endpoint-group add-endpoint --server 192.0.2.192 --endpoint-group epg_1 --endpoint ep_1
This works with the
okv_client_config
parameter setting as well.okv manage-access endpoint-group add-endpoint --okv_client_config /usr/local/okv/okvclient/okvclient.ora --endpoint-group epg_1 --endpoint ep_1
The following example uses both a named profile (
HR
) and the--server
parameter. The--server
parameter overrides theserver
information from theokvclient.ora
file specified in the[HR]
profile.okv managed-object key create --profile HR --server 192.0.2.192 --algorithm AES --length 256 --mask "ENCRYPT,DECRYPT" --wallet hr_wallet
Parent topic: okvrestcli.ini Configuration File
2.2.1.5 Using an Alternative Configuration File
You can use an alternative parameter configuration file from the okvrestcli.ini
configuration file.
okvrestcli.ini
configuration file to control commonly used settings for the Oracle Key Vault RESTful services utility commands. You can create your own version of this configuration file and specify it in the command line execution.
2.2.2 okvrestcli_logging.properties Log File Parameter Settings
The okvrestcli_logging.properties
log file determines how logging is handled for Oracle Key Vault RESTful services activities.
Modifying the okvrestcli_logging.properties
is optional. If you do not configure it, then Oracle Key Vault creates and updates a default logging file when you execute the RESTful services utility commands.
By default, the okvrestcli_logging.properties
file is in the location you downloaded the Oracle Key Vault RESTful services utility, in the OKV_HOME/conf
directory of the endpoint.
The parameter settings for okvrestcli_logging.properties
are as follows:
java.util.logging.FileHandler.pattern
specifies one of the following patterns for generating the output file name. The default is%h/java%u.log
./
is the local path name separator.%h
is the value of theuser.home
system property.%g
is the generation number to distinguish rotated logs.%u
is a unique number to resolve conflicts.%%
translates to a single percent sign%
.
java.util.logging.FileHandler.limit
specifies an approximate maximum amount to write (in bytes) to any one file. If this is zero, then there is no limit. The default is 200000.java.util.logging.FileHandler.count
specifies how many output files to cycle through. The defaults is 5.java.util.logging.FileHandler.formatter
specifies the name of aFormatter
class to use. The default isjava.util.logging.XMLFormatter
.java.util.logging.ConsoleHandler.level
specifies the default level for the handler. The default toINFO
.The available logging levels are
ALL
,TRACE
,FINEST
,FINER
,FINE
,CONFIG
,INFO
,WARNING
,SEVERE
, andOFF
.Any logging at
INFO
and above provides complete details. If you set the logging level toSEVERE
, then you will only see messages with theSEVERE
logging level, which generally correspond to serious problems. To diagnose the issue, you may need more details and that can be obtained with levels that produce more information, not just the occurrences of the serious issues.
An example of these settings is as follows:
handlers= java.util.logging.FileHandler
# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = ./okvrest.log
java.util.logging.FileHandler.limit = 200000
java.util.logging.FileHandler.count = 1
#java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.FileHandler.formatter = com.oracle.okv.rest.log.OkvFormatter
# Limit the message that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = FINER
#java.util.logging.ConsoleHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.ConsoleHandler.formatter = com.oracle.okv.rest.log.OkvFormatter
2.3 Executing Oracle Key Vault RESTful Services Utility Commands
Oracle Key Vault provides a variety of ways to execute RESTful services utility commands.
- RESTful Services Utility Command Syntax
The RESTful services utility command syntax operates using theokv
command. - Ways of Executing RESTful Services Utility Commands
You can execute the Oracle Key Vault RESTful services utility commands either by directly specifying command-specific parameters in the command line, or by using the JSON syntax. - 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.
Parent topic: Getting Started with Oracle Key Vault RESTful Services
2.3.1 RESTful Services Utility Command Syntax
The RESTful services utility command syntax operates using the okv
command.
The syntax used for RESTful services utility commands is as follows:
okv category resource action rest-cli-configuration-parameters command-parameters
In this specification:
category
refers to the type of command you are executing, such asmanaged-object
,admin
,cluster
, orbackup
commands.resource
is a type of resource on which you are executing the command, such asendpoint
,wallet
, orcertificate
.action
is the action to perform on the resource, such ascreate
,add
,locate
, ordelete
.rest-cli-configuration-parameters
include parameters such as--user
,--client_wallet
, and so on, that you specify in the REST CLI configuration file. These parameters apply to all commands.command-parameters
are parameters that a command may need, such as the--description
or--email
parameters when you create an endpoint
In this guide, commands are identified using okv
followed by category
, resource
, action
, and if the command requires them, rest-cli-configuration-parameters command-parameters
. For example, to create an endpoint, you would use the okv admin endpoint create
command. This command's full syntax is as follows:
okv admin endpoint create --endpoint endpoint_name --description "description" --email email_address --platform platform --type type --unique TRUE|FALSE
The Oracle Key Vault RESTful services utility commands syntax follows the these rules:
- It requires that you specify the command in this order:
okv category resource action rest-cli-configuration-parameters command-parameters
. You must specify thecategory
,resource
, andaction
in the order shown here. REST CLI configuration parameters must be specified before any command-specific parameters. - It enables the configuration file (
okvrestcli.ini
) to be identified by using theOKV_RESTCLI_CONFIG
environment variable. You set this variable in the Oracle Key Vault wrapper scriptokv
itself. This frees you of the necessity of having to specify this configuration file every time that you execute the command.
Note:
For backward compatibility, the RESTful services utility command line interface that existed before Oracle Key Vault release 21.1 is still supported. You can downloadokvrestclipackage.zip
to use that interface.
Most of the RESTful services utility commands support JSON input. In this guide, the commands that support JSON provide an example of how to use JSON.
2.3.2 Ways of Executing RESTful Services Utility Commands
You can execute the Oracle Key Vault RESTful services utility commands either by directly specifying command-specific parameters in the command line, or by using the JSON syntax.
- Executing RESTful Services Utility Commands Using the Command Line
You execute the RESTful services utility commands from the command line by specifying all command-specific parameters in the command line. - Executing RESTful Services Utility Commands Using the JSON Syntax
The RESTful services utility commands support JSON syntax, and after you have generated the JSON output, you can use it in combination with a command line execution of the command. - Naming Conventions for Parameters Executed at the Command Line and in JSON Files
The command parameters when specified on the command line use a different naming convention from the naming convention that is used in the JSON syntax.
2.3.2.1 Executing RESTful Services Utility Commands Using the Command Line
You execute the RESTful services utility commands from the command line by specifying all command-specific parameters in the command line.
For example, okv manage-access endpoint-group add-endpoint
has the endpoint-group and endpoint parameters:
okv manage-access endpoint-group add-endpoint --endpoint-group endpoint_group_name --endpoint endpoint_member
When specifying REST CLI configuration parameters in the command line, you must specify REST CLI configuration parameters before any command-specific parameters. In the following example, --profile hr
is one of the rest_cli_configuration_parameters
, and it is followed by the command_parameters
for the okv managed-object key create
command.
okv managed-object key create --profile hr --algorithm AES --length 128 --mask "ENCRYPT,DECRYPT,EXPORT"
2.3.2.2 Executing RESTful Services Utility Commands Using the JSON Syntax
The RESTful services utility commands support JSON syntax, and after you have generated the JSON output, you can use it in combination with a command line execution of the command.
To execute the RESTful services command using JSON input, you must first prepare a JSON input file with the command-specific parameter values and then execute the command using parameter --from-json json-input-file.json
.
The recommended process of executing RESTful services utility commands using JSON input is as follows:
-
Generate JSON input designed specifically for the command, by executing the command with the
--generate-json-input
parameter. For example:okv managed-object key create --generate-json-input
The generated JSON input for this command is as follows:
{ "service" : { "category" : "managed-object", "resource" : "key", "action" : "create", "options" : { "algorithm" : "#3DES|AES", "length" : "#112,168(3DES)|128,192,256(AES)", "mask" : "#ENCRYPT,DECRYPT,WRAP_KEY,UNWRAP_KEY|EXPORT,DERIVE_KEY,GENERATE_CRYPTOGRAM,VALIDATE_CRYPTOGRAM,TRANSLATE_ENCRYPT,TRANSLATE_DECRYPT,TRANSLATE_WRAP,TRANSLATE_UNWRAP", "wallet" : "#VALUE" } } }
- Save generated input to a file and then edit it so that you can perform the task. You must modify the values that begin with
#
. For this example, you could call the filecreate_key.json
and then edit it to use the following values:{ "service" : { "category" : "managed-object", "resource" : "key", "action" : "create", "options" : { "algorithm" : "AES", "length" : "256", "mask" : "ENCRYPT,DECRYPT", "wallet" : "hr_wallet" } } }
-
To perform the action, execute the
okv managed-object key create
command with the--from-json
parameter to specify the name of the JSON input file that you just edited.For example, to execute theokv managed-object key create
command by using the default configuration settings:okv managed-object key create --from-json create_key.json
When using JSON input, you can also specify command parameters in the command line. The command parameters specified in the command line have higher precedence over the same parameters specified in the JSON input file.
- Example 1: To create a key but with a different length than what is specified in the JSON file
create_key.json
, specify thelength
parameter in the command line:okv managed-object key create --from-json key_create.json --length 128
Overriding command parameters in the command line allows use of the same JSON file for executing the same command but with different parameters without having to modify the JSON input file.
- Example 2: To apply the same attribute values for multiple managed objects, you specify the attribute settings in the input JSON file and specify the UUID of the object in the command line. Consider the following JSON input file
add_attributes.json
:{ "service" : { "category" : "managed-object", "resource" : "attribute", "action" : "add", "options" : { "attributes" : { "contactInfo" : "pfitch@example.com", "deactivationDate" : "2024-12-31 09:00:00", "name" : "PROD-HRDB-MKEY", "protectStopDate" : "2024-09-30 09:00:00" } } } }
To apply this attribute to an object with UUID
2359E04F-DA61-4F7C-BF9F-913D3369A93A
, you execute:okv managed-object attribute add --from-json add_attributes.json --uuid 2359E04F-DA61-4F7C-BF9F-913D3369A93A
- Example 1: To create a key but with a different length than what is specified in the JSON file
2.3.2.3 Naming Conventions for Parameters Executed at the Command Line and in JSON Files
The command parameters when specified on the command line use a different naming convention from the naming convention that is used in the JSON syntax.
The parameters in the JSON syntax use the camelCase naming convention (for example, walletUser
, clientWallet
). The naming convention for the parameters in the command line use follows these rules in general:
- The parameter name is prefixed by two hyphens (for example,
--user
) - Each word is separated by a hyphen (for example,
--endpoint-group
) - All words are in lowercase (for example,
--endpoint
)
The corresponding command line parameter names for the parameters walletUser
and clientWallet
from the JSON syntax are --wallet-user
and --client-wallet
, respectively.
Parent topic: Ways of Executing RESTful Services Utility Commands
2.3.3 Creating a Script to Automatically Enroll Oracle Databases as Endpoints
You can create a script that database administrators can run to automatically enroll Oracle Database endpoints in Oracle Key Vault.
- Oracle Key Vault RESTful services package
ewallet.p12
andcwallet.sso
wallet filesrun-me.sh
script
The following procedure explains how to create these components.
Related Topics
2.4 Naming Guidelines for Objects
The naming guidelines affect the following Oracle Key Vault objects: users, user groups, endpoints, endpoint groups, and virtual wallets.
The naming conventions for these objects are as follows:
- You can include the following characters in the names of endpoints, endpoint groups, user groups, and virtual wallets: letters (
a
–z
,A
–Z
), numbers (0
-9
), underscores (_
), periods (.
), and hyphens (-
). - You can include the following characters in the names of users: letters (
a
–z
,A
–Z
), numbers (0
-9
), and underscores (_
). - In most environments, the maximum number of bytes allowed for the name length is 120 bytes. If you are in a multi-master cluster environment that has any nodes that have not yet been upgraded to Oracle Key Vault release 18.5 or later, then use a maximum of 24 bytes for the object name.
- The names of users, user groups, endpoints, and endpoint groups are not case sensitive. For example,
pfitch
andPFITCH
are considered the same user in Oracle Key Vault. - The names of virtual wallets are case sensitive. For example,
wallet_hr
andWALLET_HR
are considered two separate wallets in Oracle Key Vault.
Parent topic: Getting Started with Oracle Key Vault RESTful Services
2.5 Using RESTful Services with LDAP Users
Both regular Oracle Key Vault administrators and properly authorized LDAP users can log in to a server to execute Oracle Key Vault RESTful services utility commands.
- When executing a RESTful service command, provide the user name and domain name of the user with the
--user
parameter using the following methods:- The LDAP user name in any of the supported formats (shown below) and the domain name separate by a vertical-bar (
|
).sAMAccountName
|
LDAP_domain_name
Example:
psmith|hr.example.com
NetBiosDomainName
\\
sAMAccountName
|LDAP_domain_name
.Example:
hr\\psmith|hr.example.com
The double backslash (
\\
) interpretshr\\psmith
ashr\psmith
.userPrincipalName
|
LDAP_domain_name
Example:
psmith@hr.example.com|hr.example.com
- The user principal name of the LDAP user.
Example:
psmith@hr.example.com
- The LDAP user name in any of the supported formats (shown below) and the domain name separate by a vertical-bar (
Related Topics
Parent topic: Getting Started with Oracle Key Vault RESTful Services