An endpoint administrator can enroll and provision endpoints, which contain security objects, so that these endpoints can share security objects with one another, using the Oracle Key Vault server as a medium.
Topics:
Endpoints are Oracle Key Vault clients that use Oracle Key Vault to store and retrieve security objects, such as keys, passwords, certificates, and credential files.
These systems can be Oracle database servers, Oracle middleware servers, operating systems, and so on. Endpoints use Oracle Key Vault to store secrets for long-term retention, share them with trusted peers, and retrieve them whenever needed.
Oracle Key Vault provides a library that enables Transparent Data Encryption (TDE) to communicate with Key Vault. You can use Oracle Enterprise Manager to manage database targets (Oracle Key Vault database server endpoints), but be aware that Enterprise Manager does not support TDE integration with Oracle Key Vault.
An endpoint administrator can finalize the endpoint enrollment and provisioning after an Oracle Key Vault System Administrator has configured the endpoint to connect to Oracle Key Vault. The administrator can use an endpoint configuration file and the okvutil
utility, which is used to upload, download, and find security objects.
See Also:
"Adding, Deleting, or Reenrolling Endpoints" for information about the initial process of configuring an endpoint to connect to Oracle Key VaultEndpoint enrollment is the process of adding an endpoint to (registering it with) Oracle Key Vault. After the endpoint is registered, it is provisioned.
The okvclient.jar
file is downloaded from Oracle Key Vault to the endpoint. This file installs the utilities necessary for the endpoint to communicate with Oracle Key Vault.
Endpoints must be enrolled in order to communicate with Oracle Key Vault. In an Oracle Real Application Clusters (Oracle RAC) environment, you must enroll and provision each Oracle RAC node as an endpoint. Endpoint enrollment ensures that only authorized endpoints are allowed to communicate with Oracle Key Vault.
Endpoint enrollment and provisioning involves an Oracle Key Vault administrator with the System Administrator role on the Oracle Key Vault side, and an endpoint administrator on the endpoint side. Essentially, the Key Vault administrator starts the process and the endpoint administrator finishes it.
At the end of the enrollment process, Oracle Key Vault prompts the endpoint administrator to download the okvclient.jar
file, described in Step 6 of "Finalizing Enrollment and Provisioning".
The okvclient.jar
that is downloaded contains those items from the following list that apply to this endpoint:
TLS certificate and private key for the endpoint
TLS certificate for Oracle Key Vault: trust anchor
Endpoint libraries and utilities
Additional information that is used by okvutil
to create the okvclient.ora
configuration file, described in "Task 2: Install the Oracle Key Vault Client Software on the Endpoint".
See Also:
"Adding, Deleting, or Reenrolling Endpoints" for more information about the enrollment process
An endpoint administrator completes the endpoint enrollment and provisioning, for both endpoint self-enrollment and administrator-initiated enrollment.
Topics:
To finalize enrollment and provision the endpoint, you must download the appropriate software to the correct endpoint.
As an endpoint administrator, log in to the endpoint.
Connect to the Oracle Key Vault management console.
For example:
https://192.0.2.254
When the Oracle Key Vault management console login page appears, do not log in.
Under the login area, click the Endpoint Enrollment and Software Download link.
The Enroll Endpoint page appears.
Do not fill in any information for the Download Endpoint Software area. (It is used for downloading the software for an already-enrolled endpoint. You can use this area when you update the endpoint software.)
Under Enroll Endpoint, do one of the following:
If the enrollment type was administrator-initiated: Enter the enrollment token that was supplied by the Oracle Key Vault user with the System Administrator role and press Submit Token. If the token is invalid, an error message appears near the Submit Token button. You do not need to perform this action for self-enrolled endpoints. See "Types of Endpoint Enrollment" for more information about the types of enrollment.
If the enrollment type was self-enrollment: Fill in or correct Type, Platform, and Email fields as necessary. For self-enrollment, there is no token.
Type: Oracle Database, Oracle Non-database, or Other. If you are using TDE, enter Oracle Database.
Platform: Select Linux, Solaris SPARC, or Solaris x64.
Administrator Email: Optionally, enter the email address of the endpoint administrator.
Click Enroll to complete the process.
A processing message appears, followed by downloading the okvclient.jar
file for your endpoint.
Save the file to the desired location.
Install the okvclient.jar
file on the endpoint as described in "Task 2: Install the Oracle Key Vault Client Software on the Endpoint".
After you download the Oracle Key Vault client software, you are ready to install the it on the endpoint.
Ensure that you have the necessary privileges to install software on the endpoint.
Ensure that you have JDK 1.4 or later installed and that the PATH
environment variable includes the java
executable (which is in the JAVA_HOME/bin
directory).
Oracle Key Vault supports JDK versions 1.4, 1.5, 1.6, and 7.
Navigate to the directory in which you saved the okvclient.jar
file.
Run the java
command to install the okvclient.jar
file.
For example:
java -jar okvclient.jar -d /home/oracle/okvutil -v
In this specification:
The -d
argument specifies the directory location for the Oracle Key Vault software and configuration files, in this case, the $OKV_HOME
directory.
The -v
argument writes the installation logs to the $OKV_HOME/log/okvutil.deploy.log
file in the server endpoint.
See "How the Oracle Key Vault Client Installation Process Determines the Java Home Location" for information about how the installation process finds the Java home directory.
When prompted, do one of the following to store the credentials for accessing Oracle Key Vault in an Oracle wallet file:
For a password-protected wallet, enter a password between 8 and 30 characters, and then press Enter. This password will be required when the endpoint connects to Oracle Key Vault. (If necessary, you can change this password later on by using the okvutil changepwd
command.)
For an auto-login wallet, do not enter a password. Press Enter only. No password is required when the endpoint connects to Oracle Key Vault.
Enter new Key Vault endpoint password (<enter> for auto-login): Key_Vault_endpoint_password Confirm new Key Vault endpoint password: Key_Vault_endpoint_password
Where the extraction process installs the okvclient.ora
file depends on how you have set the Oracle environment variables. See "How the Oracle Key Vault Installation Process Determines the okvclient.ora File Location" for more information.
The directory structure contains the following directories:
bin
: Contains the okvutil
program, the root.sh
script, and other binary files
conf
: Contains configuration files
jlib
: Contains Java library files
lib
: Contains the file liborapkcs.so
log
: Contains log files
ssl
: Contains TLS-related files and wallets to connect to Oracle Key Vault. After the extraction process completes, the file ewallet.p12
is added to this directory for a password-based wallet, or the file cwallet.sso
is added for an auto-login wallet.
After the extraction process is complete, the following message should appear:
Oracle Key Vault endpoint software installed successfully.
If you are planning to use a TDE direct connection, then run root.sh
to copy the liborapkcs.so
file (located in the lib
directory) to the following directory:
/opt/oracle/extapi/64/hsm/oracle/1.0.0
The liborapkcs.so
file contains the library that the Oracle database uses to communicate with Oracle Key Vault.
Log in as the root user and run the root.sh
script to copy the liborapkcs.so
file.
For example:
$ sudo ./$OKV_HOME/bin/root.sh
Or:
$ su - # bin/root.sh
Note:
If the endpoint does not use the Oracle Key Vault client software, then you must manually set the TLS authentication. See "If the Endpoint Does Not Use the Oracle Key Vault Client Software" for more information.
You can find help information for the okvclient.jar
file as follows:
java -jar okvclient.jar -h
The output is similar to the following:
Oracle Key Vault Release 12.1.0.0.0 (2014-03-12 15:36:49.839 PDT) Production on Wed Mar 12 19:55:31 PDT 2014 Copyright (c) 1996, 2014 Oracle. All Rights Reserved. Usage: java -jar okvclient.jar [-h | -help] [[-v | -verbose] [-d <destination directory>] ]
When you provision endpoints, you should be aware of how the installation process determines the Java home location and the okvclient.ora
file location. You should also be aware of what happens if the endpoint does not use the Oracle Key Vault client software.
Topics:
How the Oracle Key Vault Client Installation Process Determines the Java Home Location
How the Oracle Key Vault Installation Process Determines the okvclient.ora File Location
If the Endpoint Does Not Use the Oracle Key Vault Client Software
How the Oracle Key Vault Client Installation Process Determines the Java Home Location
The Oracle Key Vault client software installation process determines the Java home location based on a set of rules.
These rules are as follows:
If a user-defined JAVA_HOME
environment variable is present, then the value in this variable is used for the installation process.
If the JAVA_HOME
environment variable has not been set, then the installation process tries to infer the JAVA_HOME
from the java.home
system property of the Java Virtual Machine (JVM).
After the installation is complete, the installer adds the determined JAVA_HOME
path into the conf/okvclient.ora
configuration file for future use. Afterward, the okvutil
command tries to use the JAVA_HOME
setting that is found in the okvclient.ora
file. You can force okvutil
to use a different JAVA_HOME
setting by using one of the following methods:
Set the JAVA_HOME
environment variable in the shell where you run okvutil
.
For example:
setenv JAVA_HOME path_to_Java_home
Or:
export JAVA_HOME = path_to_Java_home
Set the JAVA_HOME
property in the okvlient.ora
configuration file.
For example:
JAVA_HOME = path_to_Java_home
How the Oracle Key Vault Installation Process Determines the okvclient.ora File Location
The okvclient.ora
file is a configuration file for the Oracle Key Vault endpoint software.
Where you install this file depends on the following factors:
The default location for the okvclient.ora
file is the $OKV_HOME/conf
directory. The $OKV_HOME
directory is the destination directory, specified with the -d option, when you install the endpoint software. After you install the endpoint software, you must set the environment variable OKV_HOME
to point to the Oracle Key Vault home directory, in order to execute utilities such as Oracle Recovery Manager (RMAN) that access Oracle Key Vault for keys, because installing does not set it automatically. You must set OKV_HOME
in all environments where you will run utilities, like RMAN. For example, if you spawn a new xterm, you will need to set OKV_HOME
in this environment before running RMAN.
If the $ORACLE_BASE
variable is set, then the installation process creates a symbolic link in the $ORACLE_BASE/okv/$ORACLE_SID
location to point to the okvclient.ora
configuration file in the $OKV_HOME/conf
directory. If the okvclient.ora
file already exists in the $ORACLE_BASE/okv/$ORACLE_SID
location, then the installation process does not try to create the soft link, and accepts this location as a valid location.
If the $ORACLE_BASE/okv/$ORACLE_SID
directory is not set, then the installation process tries to create it.
If the $ORACLE_HOME
variable is set and the $ORACLE_BASE
variable is not set, then the installation process creates a symbolic link for the $ORACLE_HOME/okv/$ORACLE_SID
location to point to the configuration file in the $OKV_HOME/conf
directory.
Using Environment Variables in sqlnet.ora
You must consider the following points while using the srvctl
utility:
If you are using the srvctl
utility, and if you want to include environment variables in the sqlnet.ora configuration file, then you must set these environment variables in both the operating system and the srvctl
environment.
The operating system (OS) and Server Control (srvctl
) should have $ORACLE_SID
, $ORACLE_HOME
and $ORACLE_BASE
set to the same values.
If the Endpoint Does Not Use the Oracle Key Vault Client Software
After you install the Oracle Key Vault client software on the endpoint, there are some cases where the endpoint does not use the Key Vault client software (okvutil
and liborapkcs.so
).
If this is the case, then follow these steps:
Extract the ssl
directory from the okvclient.jar
file, as follows:
jar xvf okvclient.jar ssl
Use the following files to set up the TLS authentication:
ssl/key.pem
: endpoint private key
ssl/cert.pem
: endpoint certificate
ssl/cert_req.pem
: certificate request corresponding to cert.pem
ssl/CA.pem
: trust anchor for verifying the Oracle Key Vault server certificate
TDE has supported storing TDE master encryption keys in Oracle wallets, beginning with Oracle Database 10g Release 2, and in hardware security modules (HSMs), beginning with Oracle Database 11g Release 1.
Oracle Key Vault can manage TDE keys by using the same PKCS#11 library interface that TDE uses to communicate with HSMs. Therefore, you do not need to patch the database to use Key Vault for storing and retrieving TDE master keys. Oracle Key Vault supplies the PKCS#11 library, which is used by TDE just as any HSM PKCS#11 library and used by the database to communicate with Oracle Key Vault.
Oracle Key Vault improves upon TDE key management. For example, the keys in the wallet can be uploaded directly to Key Vault for long-term retention and to share with other database endpoints within the same endpoint group. Therefore, you do not need to store to the wallet indefinitely after migration. You can continue to use the wallet and upload wallet copies to Key Vault as part of every TDE key administration SQL operation involving a WITH BACKUP
SQL clause. (However, be aware that though the WITH BACKUP
clause is required for the ADMINISTER KEY MANAGEMENT
statement, TDE ignores it in an Oracle Key Vault environment.)
Example 8-1 shows examples of setting an encryption key.
Example 8-1 Setting an Encryption Key
ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY secret_passphrase -- For Oracle Database 11g Release 2 ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY secret_passphrase WITH BACKUP; -- For Oracle Database 12c
Note:
Migration, in the context of Oracle Key Vault, means that a database is configured as a wallet backup scenario and the administrator intends to migrate to a TDE direct connection. See "Using a TDE Direct Connection with Oracle Key Vault" for more information.Oracle Database and thus TDE are endpoints for Oracle Key Vault. Endpoint enrollment and installation ensure that the PKCS#11 library is installed in the correct location for TDE to pick up and use. When the PKCS#11 library is installed, all other configurations and operations are in effect.
Information necessary to use Oracle Key Vault is stored in a configuration file called okvclient.ora
, which Oracle Key Vault endpoint libraries and endpoint utilities use.
The okvclient.ora
file consists of key-value pairs separated by an equal sign (=
). The following parameters, showing sample data, can be set in the endpoint configuration file:
SERVER = 192.0.2.254:5696
This parameter specifies the IP address and port number, separated by a colon. If the port number is not specified, then it defaults to the standard KMIP port 5696
.
STANDBY_SERVER = 192.0.2.114:5696
This is the standby server. If high availability is configured, then this parameter shows the standby IP address. Otherwise, it shows the IP address as 127.0.0.1
.
SSL_WALLET_LOC=/
home/oracle/okvutil/ssl/
This parameter specifies the location of the wallet containing TLS credentials for the endpoint.
The Oracle Key Vault okvutil
utility enables users to find, upload, and download security objects, such as Oracle wallets or Java keystores.
Topics:
If you are managing endpoints, then you can use the Oracle Key Vault okvutil
command-line utility to manage the storage and retrieval of security objects in Oracle Key Vault.
The okvutil
utility uses the TLS credentials provisioned for the endpoint to authenticate to Oracle Key Vault.
The okvutil
utility syntax enables you to list, download, upload, and change passwords for security objects. It provides long and short options for specifying commands.
The syntax for the okvutil
utility is as follows:
okvutil command arguments [-v verbosity_level]
In this specification:
command
refers to any of the following commands, which are described in the subsequent sections: list
, upload
, and download
.
arguments
refers to the arguments that you pass for the accompanying command.
-v, --verbose
prints more details about the actions of the okvutil
command. For example, it reports the location of the configuration file that was used and the IP addresses of the servers. Valid values are as follows:
-v 0
disables verbose mode.
-v 1
includes debug messages.
-v 2
includes more detailed debug messages.
-h
, --help
shows help information.
Short and Long Forms of Specifying Options
You can specify the options in either a short form or a long form.
Short form: Only use one hyphen and the single-letter option name. For example:
-l /home/username
-t wallet
Long form: Provide two hyphens and the full option name. For example:
--location /home/username
--type wallet
The examples in this guide use the short form.
How Password Prompts for okvutil Work
The okvutil
commands prompt for passwords based on specific situations.
These situations are as follows:
If you specified a password for accessing Oracle Key Vault during the endpoint installation, then okvutil
prompts for the Key Vault password when it executes any command that accesses Key Vault.
If you specify the -l
parameter, then the okvutil
command applies to files that are on the current endpoint and hence makes no connection to Oracle Key Vault. When you specify an Oracle wallet file or Java keystore using the -l
option, okvutil
prompts you to provide the password for the wallet or keystore if it has one.
The okvutil
list
command lists the available security objects that are uploaded. When used without options or with the -g
group
option, it displays the unique ID, object type, and a descriptor for each item it lists from Oracle Key Vault.
The full syntax for okvutil list
is as follows. For the short format:
okvutil list [-l location -t type | -g group] [-v verbosity_level]
Or, for the long format:
okvutil list [--location location --type type | --group group] [--verbose verbosity_level]
In this specification:
-l
, --location
specifies the location of an Oracle wallet file or a Java keystore. For an Oracle wallet, the location is the directory that contains the .p12
or .sso
files. For all other types, the location is the path name of the file itself. If you omit the -l
, --location
option, then the default location is Oracle Key Vault. In this case, the okvutil list
command lists all the available keys in the server. If you use this setting, then you must also include the -t
, --type
setting, described next.
-t
, --type
specifies one of the following types:
WALLET
for an Oracle wallet
JKS
for the Java keystore
JCEKS
for the Java Cryptography Extension keystore (JCEKS)
The WALLET
, JKS
, and JCEKS
types contain multiple objects; Oracle Key Vault lists each of these objects individually. The SSH
, KERBEROS
, and OTHER
, being opaque objects, are listed as single files.
This setting is not case-sensitive.
-g
, --group
lists the content from a single virtual wallet. This option only applies when you omit the -l
, --location
option to list objects stored in Oracle Key Vault.
-v
, --verbose
: See "okvutil Utility Syntax"
Password prompts: See "How Password Prompts for okvutil Work".
Example: Listing Security Objects for the Current Endpoint
The okvutil list
command enables you to list security objects for the current endpoint.
Example 8-2 lists all the authorized security objects for the current endpoint. In the last three lines, the DB Connect Password
entries refer to the password that was used to log in to the instance (for example, the password for user psmith
on the database instance inst01
).
Example 8-2 Listing Security Objects for the Current Endpoint
okvutil list
Enter Oracle Key Vault endpoint password: password
Unique ID Type Identifier
F63E3F4A-C8FB-5560-E043-7A6BF00AA4A6 Symmetric Key TDE Master Key: 062C4F5BAC53E84F2DBF95B96CE577B525
F63E3F4A-C8FC-5560-E043-7A6BF00AA4A6 Symmetric Key TDE Master Key: 069A5253CF9A384F61BFDD9CC07D8A6B07
F63E3F4A-C8FD-5560-E043-7A6BF00AA4A6 Opaque Object -
F63E3F4A-C8FE-5560-E043-7A6BF00AA4A6 Symmetric Key TDE Master Key: 06A66967E70DB24FE6BFD75447F518525E
F63E3F4A-C8FF-5560-E043-7A6BF00AA4A6 Symmetric Key TDE Master Key: 0636D18F2E3FF64F7ABF80900843F37456
F63E3F4A-C900-5560-E043-7A6BF00AA4A6 Opaque Object -
F63E3F4A-C901-5560-E043-7A6BF00AA4A6 Symmetric Key TDE Master Key: 0611E6ABD666954F2FBF8359DE172BA787
F63E3F4A-C902-5560-E043-7A6BF00AA4A6 Symmetric Key TDE Master Key: 0657F27D64D1C04FAEBFE00B5105B3CBAD
F63E3F4A-C91B-5560-E043-7A6BF00AA4A6 Opaque Object Certificate Request
F63E3F4A-C91C-5560-E043-7A6BF00AA4A6 Certificate X509 DN:OU=Class 1 Public Primary Certification Authority,O=VeriSign\, Inc.,C=US
F63E3F4A-C903-5560-E043-7A6BF00AA4A6 Secret Data DB Connect Password: psmith@inst01
F63E3F4A-C904-5560-E043-7A6BF00AA4A6 Secret Data DB Connect Password: jdaley@inst02
F63E3F4A-C905-5560-E043-7A6BF00AA4A6 Secret Data DB Connect Password: tjones@inst03
Example: Listing the Contents of an Oracle Wallet File
The okvutil list
command enables you to list the contents of an Oracle wallet file.
Example 8-3 lists the contents of an Oracle wallet file.
Example 8-3 Listing the Contents of an Oracle Wallet File
okvutil list -t WALLET -l /home/oracle/wallets
Enter target wallet password: Oracle_wallet_password
Dumping secret store of wallet:
ORACLE.SECURITY.DB.ENCRYPTION.MASTERKEY
ORACLE.SECURITY.DB.ENCRYPTION.Aa4JEUaCeE8qv0Dsmmwe5S4AAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.ID.ENCRYPTION.
ORACLE.SECURITY.KB.ENCRYPTION.
ORACLE.SECURITY.TS.ENCRYPTION.BZuIPES7+k/tv0ZwOlDeIp4CAwAAAAAAAAAAAAAAAAAAAAAAAAAA
Dumping cert store of wallet:
There are 1 Certificate Requests in the list
Certificate request:
DN: CN=oracle
Type: NZDST_CERT_REQ
PUB key size: 2048
There are 0 Certificates in the list
There are 0 TPs in the list
The okvutil upload
command uploads the contents of the common key storage files such as Oracle wallets and Java keystores, and credential files such as files with SSH keys and Kerberos keytab.
You can upload Oracle wallets from all currently supported releases of Oracle Database that support TDE Oracle wallets. The okvutil upload
command opens the wallet or Java keystore and uploads each item found as an individual security object into Oracle Key Vault. If you are uploading credential files, then Key Vault uploads them as opaque objects.
After you complete the upload operation, you can selectively add the security objects to another virtual wallet.
The full syntax for the okvutil upload
command is as follows. For the short format:
okvutil upload [-o] -l location -t type [-g group] [-d description] [-v verbosity_level]
Or, for the long format:
okvutil upload [--overwrite] --location location --type type [--group group] [--description description] [--verbose verbosity_level]
In this specification:
-o
, --overwrite
: If there are conflicts with the existing data in the Oracle Key Vault virtual wallet, then Key Vault replaces the existing data with new data that is sent by the endpoint. If there are no conflicts, then the overwrite operation is not necessary and is not performed. Use care if you plan to specify this option.
-l
, --location
specifies the location of an Oracle wallet file or a Java keystore. For an Oracle wallet, the location is the directory that contains the .p12
or .sso
files. If you are uploading a credential file as an opaque object, then ensure that this file is no larger than 120 kilobytes (KB).
-t
, --type
specifies the data type of the object being uploaded to Oracle Key Vault. It must be a value from the following list:
WALLET
for an Oracle wallet
JKS
for a Java keystore
JCEKS
for a Java Cryptography Extension keystore (JCEKS)
SSH
for an SSH key file, to be uploaded as an opaque object. The maximum size is 120 KB.
KERBEROS
for a Kerberos keytab, to be uploaded as an opaque object. The maximum size is 120 KB.
OTHER
for opaque objects, which are other files that store secrets. The maximum size is 120 KB.
The WALLET
, JKS
, and JCEKS
types contain multiple objects. Oracle Key Vault uploads each of these objects individually. The SSH
, KERBEROS
, and OTHER
types, being opaque objects, are uploaded as single files.
This setting is not case-sensitive.
-g
, --group
is the name of a Key Vault virtual wallet to which the certificate store or secret store (or both) are added. This name is case-sensitive. The virtual wallet must already exist, and the user must have authorization to access it. (To find existing virtual wallets, see "Viewing Virtual Wallets".) If you omit this setting, then the default group, if there is one, is used. If there is no default group and you omit the -g
, --group
option, then the data uploaded will not be placed in a group.
-d
, --description
enables you to add a description, up to 2000 bytes. It is valid only if the -t
type
, --
type
parameter is set to SSH
, KERBEROS
, or OTHER
. Optional.
-v
, --verbose
: See "okvutil Utility Syntax" for more information.
Password prompts: See "How Password Prompts for okvutil Work".
See Also:
Oracle Database Security Guide for detailed information about the orapki
utility
Example: Uploading a Java Keystore Using the -v2 Option
The okvutil upload
command enables you to upload a Java keystore.
Example 8-4 shows how to use okvutil upload
to upload a Java keystore. The -v 2
option enables the command to list the items that are uploaded.
Example 8-4 Uploading a Java Keystore Using the -v 2 Option
okvutil upload -l ./fin_jceks.jck -t JCEKS -g fin_wal -v 2 okvutil version 12.1.0.0.0 Configuration file: /tmp/fin_okv/conf/okvclient.ora Server: 192.0.2.254:5696 Standby Server: 127.0.0.1:5696 Uploading from /tmp/fin_okv/keystores/jks/keystore.jks Enter source Java keystore password: Uploading private key Uploading trust point Uploading trust point Uploading private key Uploading private key Uploaded 3 private keys Uploaded 0 secret keys Uploaded 2 trust points Upload succeeded
The okvutil
command prompts if necessary for passwords to connect to Oracle Key Vault and to open the Oracle wallet file.
Example: Uploading a Password-Protected Wallet File
The okvutil upload
command enables you to upload a password-protected wallet file.
Example 8-5 shows how to upload a password-protected wallet file when there is no password for the endpoint to connect to Oracle Key Vault.
Example 8-5 Uploading a Password-Protected Wallet File
okvutil upload -l . -t WALLET -g FinanceWallet
Enter source wallet password: password
Upload succeeded
See Also:
"Uploading Oracle Wallets"The okvutil download
command takes items (Oracle wallets, Java keystores, SSH key files, Kerberos key tabs, and so on) from Oracle Key Vault.
If you download the contents of a virtual wallet, then you must download it into a keystore (that is, a container such as an Oracle wallet or a JCEKS keystore that can hold multiple security objects), and not into a credential file.
Be aware that some keystores only support the storage of certain types of security objects. If you upload a security object (for example a DSA key from a Java keystore), to Oracle Key Vault and then try to download this security object to a keystore of different type (for example, an Oracle wallet), then an error occurs to tell you that the object cannot be stored in this type of container.
To find the names of virtual wallets that are currently registered with Oracle Key Vault, see "Viewing Virtual Wallets".
The full syntax for the okvutil download
command is as follows. For the short format:
okvutil download -l location -t type [-g group | -i object_id] [-o] [-v verbosity_level]
Or, for the long format:
okvutil download --location location --type type [--group group | --item object_id] [--overwrite] [--verbose verbosity_level]
In this specification:
-l
, --location
specifies the directory location to store the items that you want to download. Ensure that you have permission to create wallets in this directory. Ensure that the file you download is no more than 120 KB. This setting is mandatory.
-t
, --type
specifies the data type of the object being downloaded to Oracle Key Vault. It must be a value from the following list:
WALLET
for an Oracle wallet
JKS
for a Java keystore
JCEKS
for a Java Cryptography Extension keystore (JCEKS)
SSH
for an SSH key file, to be downloaded as an opaque object.
KERBEROS
for a Kerberos keytab, to be downloaded as an opaque object.
OTHER
for opaque objects, which are other files that store secrets.
The WALLET
, JKS
, and JCEKS
types contain multiple objects. Oracle Key Vault downloads each of these objects individually. The SSH
, KERBEROS
, and OTHER
types, being opaque objects, are downloaded as single files.
This setting is not case-sensitive. This setting is mandatory.
-g
, --group
is the name of a virtual wallet from which you download an item for the WALLET
, JKS
, and JCEKS
types. The virtual wallet must already exist, and the user must have authorization to access it. The okvutil
utility downloads the entire virtual wallet specified by the -g
option, and stores it in a new wallet. (To find existing virtual wallets, see "Viewing Virtual Wallets".) There must be no existing wallet at the specified location. The okvutil
utility will create one. okvutil
prompts you to create and enter a password for the new wallet. Record that password for the future. Remember that the group name is case-sensitive.
If the type is WALLET
, JKS
, or JCEKS
, then you can either include or omit the group
setting. If the type is SSH
, KERBEROS
, or OTHER
, then you must include the object_id
option, but not include the group
setting.
-i
, --item
refers to the unique ID of the object that you want to download, such as secrets (for example, -i oracle.security.client.password1
for the first secure external password store (SEPS) entry inside a wallet). You can find the available object IDs by running the okvutil list
command, described in "okvutil list Command".
-o
, --overwrite
downloads data into an existing WALLET
, JKS
, or JCEKS
file specified by -l
, which must exist. If a conflict arises between the data to download and the data that already exists in the container, then the new data overwrites the old data. The -o
, --overwrite
option does not apply to the other types (SSH
, KERBEROS
, and OTHER
). Use care if you plan to specify this option.
If you omit the o
or overwrite
option when you download wallets that already exist in the current directory, then the original wallet file is renamed to either ewallet.p12.
timestamp
.bak
or owallet.sso.
timestamp
.bak
before the new wallet file is downloaded. For files that are not wallets (such as Java keystore files), an error appears, and you will need to rename the file or move it to a new location before performing the download.
-v
, --verbose
: See "okvutil Utility Syntax" for more information.
Password prompts: See "How Password Prompts for okvutil Work".
See Also:
"Downloading Oracle Wallets"Example: Downloading a Virtual Wallet to a Java Keystore
The okvutil download
command enables you to download a virtual wallet to a Java keystore.
Example 8-6 downloads the Key Vault virtual wallet FinanceWallet
to a Java keystore.
The okvutil changepwd
command enables you to change the Oracle Key Vault endpoint password. Use this command if you chose to use a password-protected wallet to store the Oracle Key Vault endpoint user credentials.
The full syntax for the okvutil changepwd
command is as follows. For the short format:
okvutil changepwd -l location -t type [-v verbosity_level]
Or, for the long format:
okvutil changepwd --location location --type type [--verbose verbosity_level]
In this specification:
-l
, --location
specifies the directory location of the wallet whose password you want to change.
-t
, --type
specifies the data type. Enter WALLET
.
-v
, --verbose
: See "okvutil Utility Syntax" for more information.
Password prompts: See "How Password Prompts for okvutil Work".
Example: Changing an Oracle Key Vault Endpoint Password
the okvutil changepwd
enables you to change the password of a Key Vault endpoint.
Example 8-7 shows how to change the Oracle Key Vault endpoint password. When you are prompted to create the new password, enter a password that is between 8 and 30 characters.