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
Theokvutil
utility is a command-line utility that you can use to manage security objects. - okvutil Command Syntax
Theokvutil
utility syntax provides short and long options for specifying commands. - okvutil changepwd Command
Theokvutil changepwd
command changes the password associated with the credentials used to connect to Oracle Key Vault. - okvutil diagnostics Command
Theokvutil diagnostics
command collects diagnostic and environmental information on an endpoint to troubleshoot deployment issues. - okvutil download Command
Theokvutil download
command downloads security objects from Oracle Key Vault to the endpoint. - okvutil list Command
Theokvutil
list
command lists the available security objects that are uploaded. - okvutil upload Command
Theokvutil upload
command uploads security objects to Oracle Key Vault. - okvutil sign Command
Theokvutil sign
command generates a digital signature for a message or message digest by using the private key stored on the Oracle Key Vault server. - okvutil sign-verify Command
Theokvutil sign-verify
command verifies digital signature of a message or message digest using the public key or certificate stored on Oracle Key Vault Server. - okvutil Common Errors
Theokvutil
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.
Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference
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: |
arguments |
Refers to the arguments that you pass for the accompanying command. |
|
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:
|
|
Use option to get help with any 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 thatokvutil
is trying to upload to Oracle Key Vault.
Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference
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 |
---|---|
|
Specifies the directory location of the wallet whose password you want to change. |
|
Specifies the data type. Enter |
|
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
Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference
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 |
---|---|
|
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
Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference
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 |
---|---|
|
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. |
|
Specifies the data type of the object being downloaded from Oracle Key Vault. It must be a value from the following list:
The This setting is not case-sensitive. This setting is mandatory. |
|
Is the name of a virtual wallet from which you download an item for the If the type is In a multi-master cluster, only the default wallet assigned to the endpoint can be specified when the name status is |
|
Refers to the unique ID of the object that you want to download, such as secrets (for example, |
|
Downloads data into an existing If you omit the |
|
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
Related Topics
Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference
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 [-llocation
-ttype
| -g group] [-v verbosity_level]
Long format:
okvutil list [--locationlocation
--typetype
| --group group] [--verbose verbosity_level]
Parameters
Table B-5 okvutil list Command Options
Parameter | Description |
---|---|
|
Specifies the location of an Oracle wallet file or a Java keystore. For an Oracle wallet, the location is the directory that contains the |
|
Specifies one of the following types:
The This setting is not case-sensitive. |
|
Lists the content from a single virtual wallet. This option only applies when you omit the |
|
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
Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference
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 |
---|---|
|
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. |
|
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 |
|
Specifies the data type of the object being uploaded to Oracle Key Vault. It must be a value from the following list:
The This setting is not case-sensitive. |
|
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 |
|
Enables you to add a description, up to 2000 bytes. It is valid only if the Enclose this description in double quotation marks. If there are spaces within this description, then include escape characters with the quotation marks. For example: |
|
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 sign Command
The okvutil sign
command generates a digital signature for a message or message digest by using the private
key stored on the Oracle Key Vault server.
The okvutil
utility can sign a message of length up to
32768 when provided on CLI. The okvutil
can also sign a data of any
size when provided in the form of a file. In addition to the signing message or the
file in raw format it can also sign a message digest.
Syntax
Short format:
okvutil sign [-l | -m] [-M ] [-D ] [-i | -n ]
Long format:
okvutil sign [-l <location> | -m <message>] [-M <message-type>] [-D <digital-signature-algorithm>] [-i <object-id> | -n <name>]
Parameters
Table B-7 okvutil sign Command Options
Parameter | Description |
---|---|
|
Specifies the file location containing the data. |
|
Specifies message to be signed. |
|
Specifies whether the message provided with the -m
option is raw or digest (already hashed). The default value is
RAW . The allowed values are:
|
|
Specifies the digital signature algorithm. The
default values is
|
|
Specifies the KMIP ID (UUID) of the private key used
for signing. This KMIP ID (UUID) cannot be used with option
|
|
Specifies the user-supplied name to locate private
key that is used for signing. This cannot be used with option
|
Example 2
The following example shows how to use the okvutil sign
command.
okvutil sign -l ./lib/liborapkcs.so -i 78916DFB-CC03-4FDB-BFF8-F25C1D846EF6 Enter Oracle Key Vault endpoint password: 79A013DE36E7DBDCD718C37A5510C760429FDE782224F4A7D1442D5C34 64A03C04C6A75676985510D05F225C3E3C2D1484F9ADFE4D59AE8D984F 6C059491FE9D856DC7018C77128EF5EBDE54A0F678C10B33C2C6357BF7 E67895FE235D90F2343AEA5A925DA0D266E27BC5F261C94F2AA3A180C5 26D730BB3540D88967695047070CEB41D325F9E618BF628698710586BC5 C7D1C635E35E5B1B28DA10CD3D1575FA66E2C4BBD5B6DAC0B7AAD83D 69C390491BA4F7763BC6880FD214B07394970322A115C368CB0901FA36B 4131ACF53B635661DED63018BECB18E28BE3D33B7217092DEFA54437DD 46E6FA72891B3B157183CD51920BEF9D154243AACEC9379B
Example 3
The following example shows how to use the okvutil sign
command.
okvutil sign -m \"a152b1752be70662511cd615d4a2e8a9503f7a19ce6f8415ddee8024e56001ec\" -M DIGEST -D RSASSA_PKCS1_v1_5_SHA256 -n private_key Enter Oracle Key Vault endpoint password: 79A013DE36E7DBDCD718C37A5510C760429FDE782224F4A7D1442D5C34 64A03C04C6A75676985510D05F225C3E3C2D1484F9ADFE4D59AE8D984F 6C059491FE9D856DC7018C77128EF5EBDE54A0F678C10B33C2C6357BF7 E67895FE235D90F2343AEA5A925DA0D266E27BC5F261C94F2AA3A180C5 26D730BB3540D88967695047070CEB41D325F9E618BF628698710586BC5 C7D1C635E35E5B1B28DA10CD3D1575FA66E2C4BBD5B6DAC0B7AAD83D 69C390491BA4F7763BC6880FD214B07394970322A115C368CB0901FA36B 4131ACF53B635661DED63018BECB18E28BE3D33B7217092DEFA54437DD 46E6FA72891B3B157183CD51920BEF9D154243AACEC9379B
Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference
B.9 okvutil sign-verify Command
The okvutil sign-verify
command
verifies digital signature of a message or message digest using the public key or
certificate stored on Oracle Key Vault Server.
The okvutil utility
can verify digital signature of a message of
length up to 32768 when provided on CLI and data of any size when provided in the
form of a file. In addition to verifying digital signature of message or data in raw
format okvutil utility
can also verify digital signature of a
message digest.
Syntax
Short format:
okvutil sign-verify [-l | -m ] [-M ] [-D ] -S [-i | -n ]
Long format:
okvutil sign-verify [-l <location> | -m <message>] [-M <message-type>] [-D <digital-signature-algorithm>] -S <signature> [-i <object-id> | -n <name>]
Parameters
Table B-8 okvutil sign-verify Command Options
Parameter | Description |
---|---|
|
Specifies the file location containing the data. |
|
Specifies the message for which to verify the signature. |
|
Specifies whether the message provided with the -m
option is raw or digest (already hashed). The default value is
RAW . The allowed values are:
|
|
Specifies the digital signature algorithm. The
default values is
|
|
Specifies the file containing signature or the signature itself. If the value is a path to a valid file then the signature is read from the file otherwise the value is treated as signature itself. |
|
Specifies the KMIP ID (UUID) of the private key used
for signing the file. This KMIP ID (UUID) cannot be used with
option |
|
Specifies the user-supplied name to locate private
key that is used for signing the file. This cannot be used with
option |
Example 1
The following example shows how to use the okvutil
sign-verify
command.
okvutil sign-verify -l ./lib/liborapkcs.so -n public_key -S 79A013DE36E7DBDCD718C37A5510C760429FDE782224F4A7D1442D5C34 64A03C04C6A75676985510D05F225C3E3C2D1484F9ADFE4D59AE8D984F 6C059491FE9D856DC7018C77128EF5EBDE54A0F678C10B33C2C6357BF7 E67895FE235D90F2343AEA5A925DA0D266E27BC5F261C94F2AA3A180C5 26D730BB3540D88967695047070CEB41D325F9E618BF628698710586BC5 C7D1C635E35E5B1B28DA10CD3D1575FA66E2C4BBD5B6DAC0B7AAD83D 69C390491BA4F7763BC6880FD214B07394970322A115C368CB0901FA36B 4131ACF53B635661DED63018BECB18E28BE3D33B7217092DEFA54437DD 46E6FA72891B3B157183CD51920BEF9D154243AACEC9379B Enter Oracle Key Vault endpoint password: Signature Validity:Valid
Example 2
The following example shows how to use the okvutil
sign-verify
command.
okvutil sign-verify -m \"a152b1752be70662511cd615d4a2e8a9503f7a19ce6f8415ddee8024e56001ec\" -M DIGEST -D RSASSA_PKCS1_v1_5_SHA256 -i 5AFBC939-73D2-4F57-BF9E-8D253AEDCD8B -S ./digital_signature_file Enter Oracle Key Vault endpoint password: Signature Validity:Valid
Example 3
okvutil sign
command.
- openssl does not support verification of signatures in HEX
format. As the signature generated by
okvutil sign
command is in HEX format therefore the signature can be converted into binary format using xxd or some other utility.xxd -r -p ./digital_signature_file > ./digital_signature_file.bin
- Verify signature in binary format using openssl and public key stored in
file
key.pub.
openssl dgst -sha256 -verify key.pub -signature ./digital_signature_file.bin ./lib/liborapkcs.so Verified OK
Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference
B.10 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-9 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. |
Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference