B Oracle Key Vault okvutil Endpoint Utility Reference

The okvutil utility enables you to perform tasks uploading and downloading security objects.

• About the okvutil Utility
  The okvutil utility is a command-line utility that you can use to manage security objects.
• okvutil Command Syntax
  The okvutil utility syntax provides short and long options for specifying commands.
• okvutil changepwd Command
  The okvutil changepwd command changes the password associated with the credentials used to connect to Oracle Key Vault.
• okvutil diagnostics Command
  The okvutil diagnostics command collects diagnostic and environmental information on an endpoint to troubleshoot deployment issues.
• okvutil download Command
  The okvutil download command downloads security objects from Oracle Key Vault to the endpoint.
• okvutil list Command
  The okvutil list command lists the available security objects that are uploaded.
• okvutil upload Command
  The okvutil upload command uploads security objects to Oracle Key Vault.
• okvutil Common Errors
  The okvutil common errors describes the error conditions and the reason for their occurrence.

B.1 About the okvutil Utility

The okvutil utility is a command-line utility that you can use to manage security objects.

The okvutil command-line utility enables you to locate, upload, and download security objects to and from Oracle Key Vault. You can also use okvutil to change the wallet password and collect system diagnostics.

The okvutil utility uses the Transport Layer Security (TLS) credentials provisioned for the endpoint to authenticate to Oracle Key Vault.

B.2 okvutil Command Syntax

The okvutil utility syntax provides short and long options for specifying commands.

Syntax

okvutil command arguments [-v verbosity_level]

Parameters

Table B-1 okvutil Command Syntax

Parameter	Description
command	Refers to any of the following commands: upload, list, download, changepwd, diagnostics
arguments	Refers to the arguments that you pass for the accompanying command.
-v, --verbose	Refers to verbosity level. Possible values are 0,1, and 2. Verbosity level 2 provides the highest the level of detail that is printed to standard output during command execution. The meaning of verbosity values are as follows: -v 0 disables verbose mode. -v 1 includes debug messages. -v 2 includes more detailed debug messages.
-h, --help	Use option to get help with any okvutil command. For example: okvutil command --help

Short and Long Forms of Specifying Options

You can specify the options in either a short form or a long form.

Note:

Endpoint platforms AIX and HP-UX (IA) support only short form options currently

• 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 in the following situations:

• If you created a password-protected wallet during endpoint installation to access Oracle Key Vault.

• If you specify an Oracle wallet file or Java keystore file using the -l option, okvutil prompts you to provide the password for the wallet or keystore that okvutil is trying to upload to Oracle Key Vault.

B.3 okvutil changepwd Command

The okvutil changepwd command changes the password associated with the credentials used to connect to Oracle Key Vault.

Use this command if you used a password-protected wallet to store the Oracle Key Vault endpoint user credentials. The new password does not need to be the same password for the JCKS or wallet file when it was uploaded.

Syntax

Short format:

okvutil changepwd -l location [-t type] [-v verbosity_level ]

Long format:

okvutil changepwd 
--location location
[--type type]
[--verbose verbosity_level]

Parameters

Table B-2 okvutil changepwd Command Options

Parameter	Description
-l, --location	Specifies the directory location of the wallet whose password you want to change.
-t, --type	Specifies the data type. Enter WALLET. If you omit the -t, --type option, then the default type is WALLET.
-v, --verbose	Refers to the verbosity level from 0 (none), 1 (debug), 2 (detailed debug).

Example: Changing an Oracle Key Vault Endpoint Password

The following example shows how to use the okvutil changepwd command change the endpoint password. When you are prompted to create the new password, enter a password that is between 8 and 30 characters.

$ okvutil changepwd -l ./home/oracle/okvutil/ssl -t WALLET
Enter wallet password: current_endpoint_password
Enter new wallet password: new_endpoint_password
Confirm new wallet password: new_endpoint_password

B.4 okvutil diagnostics Command

The okvutil diagnostics command collects diagnostic and environmental information on an endpoint to troubleshoot deployment issues.

The information is placed in a diagnostics.zip file, which can be given to Oracle support for further analysis and debugging.

The information gathered includes information on the following:

• The shell environment variables: OKV_HOME, ORACLE_HOME, ORACLE_BASE, ORACLE_SID, PATH, CLASSPATH

• Configuration and IP address of the Oracle Key Vault server from okvclient.ora

• Directory listing of OKV_HOME and its sub-directories

• Oracle Key Vault log files from the endpoint

• Listing of symbolic links created by the Oracle Key Vault endpoint installer

• Network settings and ping results

The okvutil diagnostics command does not collect sensitive information such as user credentials or security objects.

Syntax

Short format:

okvutil diagnostics [-v verbosity_level]

Long format:

okvutil diagnostics  [--verbose verbosity_level]

Parameters

Table B-3 okvutil diagnostics Command Options

Parameter	Description
-v, --verbose	Refers to the verbosity level from 0 (none), 1 (debug), 2 (detailed debug)

Example: Collecting System Diagnostics

The following example shows how to execute the okvutil diagnostics command. After you execute the command, when the Diagnostics complete message appears, then the diagnostics.zip file will be available in the current directory.

$ okvutil diagnostics 
Diagnostics collection complete.
ls
diagnostics.zip

B.5 okvutil download Command

The okvutil download command downloads security objects from Oracle Key Vault to the endpoint.

These security objects include Oracle wallets including auto-login wallets, Java keystores, credential files, and other types of key storage files.

You can only download the contents of a virtual wallet into a keystore (a container such as an Oracle wallet or a JCEKS keystore that can hold multiple security objects), and not into a credential file.

Some keystores only support the storage of certain types of security objects. An error occurs if you upload a DSA key from a Java keystore or later try to download it to a different type of keystore like an Oracle wallet.

Syntax

Short format:

okvutil download -l location -t type [-g group | -i object_id] [-o] [-v verbosity_level]

Long format:

okvutil download --location location --type type [--group group | --item object_id] [--overwrite] [--verbose verbosity_level]

Parameters

Table B-4 okvutil download Command Options

Parameter	Description
-l, --location	Specifies the file location to store the items that you want to download. Ensure that you have permission to create wallets in this location. 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 from 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. 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 this 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. In a multi-master cluster, only the default wallet assigned to the endpoint can be specified when the name status is PENDING.
-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).
-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	Refers to the verbosity level from 0 (none), 1 (debug), 2 (detailed debug).

Example: Downloading a Virtual Wallet to a Java Keystore

The following example shows how to use the okvutil download command to download the Oracle Key Vault virtual wallet FinanceWallet to a Java keystore. This is useful if you are sharing the same Java key store across multiple application servers and want to use the same wallet.

$ okvutil download -l ./fin/okv/work -t JCEKS -g FinanceWallet

The command will prompt for a new password for the Java Keystore as below:

Enter new Java keystore password:
Confirm new Java keystore password:
Download succeeded

B.6 okvutil list Command

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.

Syntax

Short format:

okvutil list [-l location -t type | -g group] [-v verbosity_level]

Long format:

okvutil list [--location location --type type | --group group] [--verbose verbosity_level]

Parameters

Table B-5 okvutil list Command Options

Parameter	Description
-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) OKV_PERSISTENT_CACHE for the persistent cache of Oracle Key Vault (Note that this setting becomes unavailable if EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN has been set for a given endpoint database.) The WALLET, JKS, and JCEKS types are containers for security objects which Oracle Key Vault lists individually. The SSH, KERBEROS, and OTHER are opaque objects, and 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 the objects stored in Oracle Key Vault. Only the default wallet assigned to the endpoint can be specified when the name status is PENDING.
-v, --verbose:	Refers to the verbosity level from 0 (none), 1 (debug), 2 (detailed debug).

Example: Listing Security Objects for the Current Endpoint

The following example shows how to use the okvutil list command to list 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).

$ 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

This example shows 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

B.7 okvutil upload Command

The okvutil upload command uploads security objects to Oracle Key Vault.

These security objects can be Oracle wallets including auto-login wallets, Java keystores, credential files, user-defined keys, and other types of key storage files.

You can upload Oracle wallets from all currently supported releases of Oracle Database and other Oracle software products that use 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 Oracle Key Vault uploads them as whole files called opaque objects.

Syntax

Short format:

okvutil upload [-o] -l location -t type [-g group] [-d description] [-v verbosity_level]

Long format:

okvutil upload [--overwrite] --location location --type type [--group group] [--description description] [--verbose verbosity_level]

Parameters

Table B-6 okvutil upload Command Options

Parameter	Description
-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, Java keystore, or a text file containing user-defined and hex-encoded TDE master encryption identifier and key. 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. TDE_KEY_BYTES for a user-defined key to be used as a TDE master encryption key. 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, TDE_KEY_BYTES, 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. 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. Only the default wallet assigned to the endpoint can be specified when the name status is PENDING.
-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, TDE_KEY_BYTES, or OTHER. Optional. Enclose this description in double quotation marks. If there are spaces within this description, then include escape characters with the quotation marks. For example: -d \"text with spaces\"
-v, --verbose	Refers to the verbosity level from 0 (none), 1 (debug), 2 (detailed debug).

Example: Uploading a Java Keystore Using the -v 2 Option

The following example shows how to use the okvutil upload command to upload a Java keystore. The -v 2 option enables the command to list the items that are uploaded. The okvutil command prompts if necessary for passwords to connect to Oracle Key Vault and to open the Oracle wallet file.

$ okvutil upload -l ./fin_jceks.jck -t JCEKS -g fin_wal -v 2

okvutil version 21.5.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

Example: Uploading a Password-Protected Wallet File

The following example shows how to use the okvutil upload command to upload a password-protected wallet file when there is no password for the endpoint to connect to Oracle Key Vault.

$ okvutil upload -l . -t WALLET -g FinanceWallet 
Enter source wallet password: password

Upload succeeded

Example: Uploading a User-Defined Key to Use as a TDE Master Encryption Key

The following example shows how to upload a user-defined key.

$ okvutil upload -l /tmp/tde_key_bytes.txt -t TDE_KEY_BYTES -g "FIN_DATABASE_VIRTUAL_WALLET" -d \"This key was created for Financial database use on 1st April 2020\"

B.8 okvutil Common Errors

The okvutil common errors describes the error conditions and the reason for their occurrence.

The okvutil utility displays a message when an error condition is established.

Errors

Table B-7 okvutil Common Errors

Error Code	Description
10115	Displayed when the server is down or the port in the okvclient.ora configuration file is incorrect.
28759	Displayed when the SSL wallet location is incorrect.
28791	Displayed when the certificate cannot be verified due to certification error.
29106	Displayed when the password is incorrect.