8 Using Oracle Key Vault Endpoints

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:

About Oracle Key Vault Endpoints

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 Vault

Overview of Endpoint Enrollment and Provisioning

Endpoint 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:

Finalizing Enrollment and Provisioning

An endpoint administrator completes the endpoint enrollment and provisioning, for both endpoint self-enrollment and administrator-initiated enrollment.

Topics:

Task 1: Enroll and Provision the Endpoint

To finalize enrollment and provision the endpoint, you must download the appropriate software to the correct endpoint.

  1. As an endpoint administrator, log in to the endpoint.

  2. Connect to the Oracle Key Vault management console.

    For example:

    https://192.0.2.254

  3. When the Oracle Key Vault management console login page appears, do not log in.

    Description of okv_login_screen.png follows
    Description of the illustration ''okv_login_screen.png''

  4. 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.)

    Description of okv_15.png follows
    Description of the illustration ''okv_15.png''

  5. 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.

  6. Click Enroll to complete the process.

    A processing message appears, followed by downloading the okvclient.jar file for your endpoint.

  7. Save the file to the desired location.

  8. Install the okvclient.jar file on the endpoint as described in "Task 2: Install the Oracle Key Vault Client Software on the Endpoint".

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.

  1. Ensure that you have the necessary privileges to install software on the endpoint.

  2. 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.

  3. Navigate to the directory in which you saved the okvclient.jar file.

  4. 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.

  5. 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.

  6. 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>] ]

See Also:

"Using a TDE Direct Connection with Oracle Key Vault"

Special Notes About Endpoint Provisioning

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

The Oracle Key Vault client software installation process determines the Java home location based on a set of rules.

These rules are as follows:

  1. If a user-defined JAVA_HOME environment variable is present, then the value in this variable is used for the installation process.

  2. 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.

See Also:

"Endpoint okvclient.ora Configuration File"

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:

  1. Extract the ssl directory from the okvclient.jar file, as follows:

    jar xvf okvclient.jar ssl

  2. 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

See Also:

"Task 2: Install the Oracle Key Vault Client Software on the Endpoint"

Transparent Data Encryption Endpoint Management

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.

Endpoint okvclient.ora Configuration File

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.

See Also:

"How the Oracle Key Vault Installation Process Determines the okvclient.ora File Location"

Oracle Key Vault okvutil Endpoint Utility Reference

The Oracle Key Vault okvutil utility enables users to find, upload, and download security objects, such as Oracle wallets or Java keystores.

Topics:

About the okvutil Utility

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.

okvutil Utility Syntax

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.

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.

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

okvutil upload Command

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:

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"

okvutil download Command

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.

Example 8-6 Downloading a Virtual Wallet to a Java Keystore

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

Download succeeded

okvutil changepwd Command

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:

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.

Example 8-7 Changing an Oracle Key Vault Endpoint Password

okvutil changepwd -l ./home/oracle/okvutil/ssl -t WALLET
Enter wallet password: current_Key_Vault_endpoint_password
Enter new wallet password: new_Key_Vault_endpoint_password
Confirm new wallet password: new_Key_Vault_endpoint_password