Before you start working with the Key Management for Oracle DBMS_CRYPTO Integration Accelerator, ensure that you meet these prerequisites.

Ensure that you prepare the Oracle Database environment with the necessary permissions to run the Key Management for Oracle DBMS_CRYPTO Integration Accelerator.

1. Ensure that the JAVA_HOME environment variable points to the Java Development Toolkit (JDK) location.
2. Set the CLASSPATH to contain the Oracle Key Vault Java SDK jar $OKV_HOME/jsdk/lib/okvjsdk.jar.
   Set the CLASSPATH in Bash UNIX:

   $ export CLASSPATH=$CLASSPATH:$OKV_HOME/jsdk/lib/okvjsdk.jar

3. Ensure that the current directory '.' is also part of CLASSPATH. If not, then add the current directory at the beginning of CLASSPATH.

   In Bash UNIX shell, set as follows:

   $ export CLASSPATH=.:$CLASSPATH

4. Compile the KeyManager.java file.
   Set the current directory to the directory where you extracted the okv_key_management_dbms_crypto.zip file.

   Compile the KeyManager.java in Bash UNIX:

   $ cd folder_path
   $ javac KeyManager.java

5. Log in to Oracle Database as the sys user and set up the database user.
   Determine the default table space default_tablespace of the database user db_username using the following query:

   SQL> select default_tablespace from dba_users where username = db_username;

   Note:

   Ensure db_username is in upper case.
   Grant the following permissions to db_username:

   SQL> grant execute on sys.dbms_crypto to db_username;
   SQL> grant create session to db_username;
   SQL> grant create procedure, create table to db_username;
   SQL> alter user db_username quota 100M on default_tablespace;
   SQL> commit;
   SQL> exit;

6. Ensure that you add the $ORACLE_HOME/bin directory to the PATH environment variable.
7. Load the Java class file KeyManager.class and the dependent JAR file okvjsdk.jar to Oracle Database as the database user db_username, database user password db_pswd, and database name db_name.

   $ loadjava -user db_username/db_pswd@db_name -verbose $OKV_HOME/jsdk/lib/okvjsdk.jar
   $ cd folder_path
   $ loadjava -user db_username/db_pswd@db_name -verbose KeyManager.class

8. Log in to the database as the sys user and run the following SQL file by passing the database user db_username and actual value of OKV_HOME as arguments.

    SQL> @folder_path/setup_java_permissions.sql db_username OKV_HOME;

9. Log in to the database as the sys user and grant permissions required to allow the database user db_username to establish a secure socket connection with Oracle Key Vault:

   SQL> exec dbms_java.grant_permission( db_username, 'SYS:java.net.SocketPermission', 'Oracle Key Vault IP Address:Port#', 'connect,resolve' );
   SQL> commit;
   SQL> exit;

   Note:

   In a multi-master cluster deployment, grant the permission for each cluster node using the IP address and port-number. Ensure that the input db_username is in upper case for these commands.

   The IP address and port-number information is available in the $OKV_HOME/conf/okvclient.ora file.

   For example, the endpoint configuration file $OKV_HOME/conf/okvclient.ora for a 3-node Oracle Key Vault cluster with IP addresses 100.100.100.101, 100.100.100.102 and 100.100.100.103 for the respective nodes is similar to the following:

   SERVER=100.100.100.101:5696/CN=server_cert,OU=Key_Vault,O=Oracle,L=Redwood_City,ST=California,C=us,100.100.100.102:5696/CN=node_2_cert,OU=Key_Vault,O=Oracle,L=Redwood_City,ST=California,C=us
   READ_SERVER=100.100.100.103:5696/CN=node_3_cert,OU=Key_Vault,O=Oracle,L=Redwood_City,ST=California,C=us
   

   Extract the IP address and port details from the previous configuration file and run SQL commands as the sys user for the previous example cluster as follows:

   SQL> exec dbms_java.grant_permission( db_username, 'SYS:java.net.SocketPermission', '100.100.100.101:5696', 'connect,resolve' );
   SQL> exec dbms_java.grant_permission( db_username, 'SYS:java.net.SocketPermission', '100.100.100.102:5696', 'connect,resolve' );
   SQL> exec dbms_java.grant_permission( db_username, 'SYS:java.net.SocketPermission', '100.100.100.103:5696', 'connect,resolve' );
   SQL> commit;
   SQL> exit;

   Ensure that you change these permissions whenever there are changes to the Oracle Key Vault cluster node configuration, such as adding or deleting cluster nodes.

   For example, when a new cluster node 100.100.100.104 is added:

   SQL> exec dbms_java.grant_permission( db_username,'SYS:java.net.SocketPermission', '100.100.100.104:5696', 'connect,resolve' ); 
   SQL> commit; 
   SQL> exit; 

   When the cluster node 100.100.100.103 is removed:

   SQL> exec dbms_java.revoke_permission( db_username, 'SYS:java.net.SocketPermission','100.100.100.103:5696', 'connect,resolve' );
   SQL> commit;
   SQL> exit;

10. Log in to the database with your database user name and password and grant the following permissions to the database user db_username to enable the database user to load the endpoint wallet under $OKV_HOME/ssl file when establishing a secure connection with Oracle Key Vault.

    SQL> exec dbms_java.grant_policy_permission( db_username, db_username, 'oracle.security.pki.OracleWalletPermission', 'load' );
    SQL> exec dbms_java.grant_permission( db_username, 'db_username:oracle.security.pki.OracleWalletPermission', 'load', '' );
    SQL> commit;
    SQL> exit;

    Note:

    Ensure that the input db_username is in upper case for these commands.
11. Connect to the database with your database user name and password and load the package okv_key_mgmt.pkb.

    SQL> @folder_path/okv_key_mgmt.pkb;
    SQL> exit;
    

You can now use the PL/SQL package okv_key_mgmt supplied by the integration accelerator in your PL/SQL applications.

1. Log in to database with your user name and password to the configured database.
2. Run the dbms_crypto_using_okv_keymgmt.sql file using the following command:

   SQL> @folder_path/dbms_crypto_using_okv_keymgmt.sql;

   Note:

   • This SQL script works only for auto-login wallet of the installed Oracle Key Vault endpoint software. If your endpoint is password-protected, then enter the password of your endpoint in 'endpt_pswd' variable present in this SQL file.
   • If you want to give a name for the key created in Oracle Key Vault, then enter the key name value in 'key_name' variable present in this SQL file.

You can extend functionality of the Key Management for Oracle DBMS_CRYPTO Integration Accelerator to suite your application needs.

1. Add the function locateKey() for locating the key using Oracle Key Vault Java SDK APIs in KeyManager.java:

   public static String locateKey(String epPswd, String nameAttrValue) 
                                                     throws OKVException {
   
           /* Create a connection to Oracle Key Vault */
           char[] endpointPswd = null;
   
           if ((epPswd != null) && !(epPswd.trim().isEmpty())) {
               endpointPswd = epPswd.toCharArray();
           }
           OKVService service = setupOKVConnection(endpointPswd);
   
           /* Locate the key */
           System.out.println("\nLocate a key on Oracle Key Vault");
   
           /* Create the attribute list for locate operation */
           OKVTTLV attrList = OKVTTLV.okvEnvGetOpRequestObj();
           OKVTTLV nameAttr = attrList.okvAddAttributeObject(OKVTag.NAME, 0);
           nameAttr.okvAttrAddName(nameAttrValue,
                                OKVTagEnum.NAME_TYPE_UNINTERPRETED_TEXT_STRING);
           OKVTTLV stateAttr = attrList.okvAddAttributeObject(OKVTag.STATE, 0);
           stateAttr.okvAttrAddState(OKVTagEnum.STATE_ACTIVE);
   
           OKVUidListResponse result = service.okvLocate(null, 0, null, 
                                                         attrList);
   
           /* Verify if the key is located */
           int count = result.getUidCnt();
           String uniqueId = null;
           if (count == 1) {
               uniqueId = result.getUids().get(0);
               System.out.println("\tSuccessfully located the key. " + 
                                  "Unique ID of the key: " + uniqueId);
           }
           else {
               System.out.println("\tUnable to locate the key, " + 
                                  "number of unique ID's got: " + count);
           }
   
           /* Release the connection from Oracle Key Vault */
           releaseOKVConnection(service);
   
           return uniqueId;
      }
2. Add the wrapper function locate_key() in okv_key_mgmt.pkb:
   1. Declaration:

      function locate_key(ep_pswd varchar2, key_name varchar2) return varchar2;

   2. Definition:

      function locate_key(ep_pswd varchar2, key_name varchar2) return varchar2 as language java name 'KeyManager.locateKey (java.lang.String,java.lang.String) return java.lang.String';

3. Add the call to okv_key_mgmt.locate_key() before calling okv_key_mgmt.fetch_key() in dbms_crypto_using_okv_keymgmt.sql similar to the following:

   key_id := okv_key_mgmt.locate_key(endpt_pswd, key_name);
   key_value := okv_key_mgmt.fetch_key(endpt_pswd, trim(key_id));
   

   Note:

   Ensure that 'key_name' is not an empty string or null in the dbms_crypto_using_okv_keymgmt.sql file.
4. Recompile modified KeyManager.java:

   $ cd folder_path        
   $ javac KeyManager.java
   

5. Reload KeyManager.class to Oracle Database to include the new changes:

   $ cd folder_path
   $ loadjava -user db_username/db_pswd@db_name -verbose KeyManager.class
   

6. Connect to the database with your user name and password and reload okv_key_mgmt.pkb to include the new locate_key() functionality:

   SQL> @folder_path/okv_key_mgmt.pkb;
   SQL> exit;
   

7. To verify the newly included Locate operation, connect to the database with your user name and password and run the dbms_crypto_using_okv_keymgmt.sql file using the following command:

   SQL> @folder_path/dbms_crypto_using_okv_keymgmt.sql;