4 Managing the Keystore and the Master Encryption Key
You can modify settings for the keystore and TDE master encryption key, and store Oracle Database and store Oracle GoldenGate secrets in a keystore.
- Managing the Keystore
You can perform maintenance activities on keystores such as changing passwords, and backing up, merging, and moving keystores. - Managing the TDE Master Encryption Key
You can manage the TDE master encryption key in several ways. - Storing Oracle Database Secrets
Secrets are data that support internal Oracle Database features that integrate external clients such as Oracle GoldenGate into the database. - Storing Oracle GoldenGate Secrets in a Keystore
You can store Oracle GoldenGate secrets in Transparent Data Encryption keystores.
Parent topic: Using Transparent Data Encryption
4.1 Managing the Keystore
You can perform maintenance activities on keystores such as changing passwords, and backing up, merging, and moving keystores.
- Performing Operations That Require a Keystore Password
ManyADMINISTER KEY MANAGEMENT
operations require access to a keystore password, for both software and external keystores. - Changing the Password of a Software Keystore
Oracle Database enables you to easily change password-protected software keystore passwords. - Changing the Oracle Key Vault Password
To change the password of Oracle Key Vault, you useokvutil
, which is part of the Oracle Key Vault endpoint software on the database host. - Configuring an External Store for a Keystore Password
An external store for a keystore password stores the keystore password in a centrally accessed and managed location. - Backing Up Password-Protected Software Keystores
When you back up a password-protected software keystore, you can create a backup identifier string to describe the backup type. - How the V$ENCRYPTION_WALLET View Interprets Backup Operations
TheBACKUP
column of theV$ENCRYPTION_WALLET
view indicates a how a copy of the keystore was created. - Backups of the External Keystore
You cannot use Oracle Database to back up external keystores. - Merging Software Keystores
You can merge software keystores in a variety of ways. - Moving a Software Keystore to a New Location
You move a software keystore to a new location after you have updated theWALLET_ROOT
parameter. - Moving a Software Keystore Out of Automatic Storage Management
You can use theADMINISTER KEY MANAGEMENT
statement to move a software keystore out Automatic Storage Management. - Migrating Between a Software Password Keystore and an External Keystore
You can migrate between password-protected software keystores and external keystores. - Migration of Keystores to and from Oracle Key Vault
You can use Oracle Key Vault to migrate both software and external keystores to and from Oracle Key Vault. - Closing a Keystore
You can manually close software and external keystores. - Using a Software Keystore That Resides on ASM Volumes
You can store a software keystore on an Automatic Storage Management (ASM) disk group. - Backup and Recovery of Encrypted Data
For software keystores, you cannot access encrypted data without the TDE master encryption key. - Dangers of Deleting Keystores
Oracle strongly recommends that you do not delete keystores. - Features That Are Affected by Deleted Keystores
Some features can be adversely affected if a keystore is deleted and a TDE master encryption key residing in that keystore is later needed.
Parent topic: Managing the Keystore and the Master Encryption Key
4.1.1 Performing Operations That Require a Keystore Password
Many ADMINISTER KEY MANAGEMENT
operations require access to a keystore password, for both software and external keystores.
In some cases, a software keystore depends on an auto-login keystore before the operation can succeed. Auto-login keystores open automatically when they are configured and a key is requested. They are generally used for operations where the keystore could be closed but a database operation needs a key (for example, after the database is restarted). Because the auto-login keystore opens automatically, it can be retrieved to perform a database operation without manual intervention. However, some keystore operations that require the keystore password cannot be performed when the auto-login keystore is open. The auto-login keystore must be closed and the password-protected keystore must be opened for the keystore operations that require a password.
In a multitenant environment, the re-opening of keystores affects other PDBs. For example, an auto-login keystore in the root must be accessible by the PDBs in the CDB for this root.
You can temporarily open the keystore by including the FORCE KEYSTORE
clause in the ADMINISTER KEY MANAGEMENT
statement when you perform the following operations: rotating a keystore password; creating, using, rekeying, tagging, importing, exporting, migrating, or reverse migrating encryption keys; opening or backing up keystores; adding, updating, or deleting secret keystores. In a multitenant environment, if no keystore is open in the root, then FORCE KEYSTORE
opens the password-protected keystore in the root.
Parent topic: Managing the Keystore
4.1.2 Changing the Password of a Software Keystore
Oracle Database enables you to easily change password-protected software keystore passwords.
- About Changing the Password of a Password-Protected Software Keystore
You can only change the password for protected-protected software keystores. - Changing the Password-Protected Software Keystore Password
To change the password of a password-protected software keystore, you must use theADMINISTER KEY MANAGEMENT
statement.
Parent topic: Managing the Keystore
4.1.2.1 About Changing the Password of a Password-Protected Software Keystore
You can only change the password for protected-protected software keystores.
You can change this password at any time, as per the security policies, compliance guidelines, and other security requirements of your site. As part of the command to change the password, you will be forced to specify the WITH BACKUP
clause, and thus forced to make a backup of the current keystore. During the password change operation, Transparent Data Encryption operations such as encryption and decryption will continue to work normally.
You can change this password at any time. You may want to change this password if you think it was compromised.
Parent topic: Changing the Password of a Software Keystore
4.1.2.2 Changing the Password-Protected Software Keystore Password
To change the password of a password-protected software keystore, you must use the ADMINISTER KEY MANAGEMENT
statement.
-
Log in to the database instance as a user who has been granted the
ADMINISTER KEY MANAGEMENT
orSYSKM
privilege.For example:
sqlplus sec_admin as syskm Enter password: password Connected.
-
Change the password of the password-protected software keystore by using the following syntax:
ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD [FORCE KEYSTORE] IDENTIFIED BY old_password SET new_password [WITH BACKUP [USING 'backup_identifier']];
In this specification:
-
FORCE KEYSTORE
temporarily opens the password-protected keystore for this operation. You must open the keystore for this operation. -
old_password
is the current keystore password that you want to change. -
new_password
is the new password that you will set for the keystore. -
WITH BACKUP
creates a backup of the current keystore before the password is changed. You must include this clause. -
backup_identifier
specifies an optional identifier string for the backup that is created. Thebackup_identifier
is added to the name of the backup file. Enclosebackup_identifier
in single quotation marks (' '). This identifier is appended to the named keystore file (for example,ewallet_
time_stamp
_emp_key_pwd_change.p12
).
The following example backs up the current keystore and then changes the password for the keystore:
ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD FORCE KEYSTORE IDENTIFIED BY old_password SET new_password WITH BACKUP USING 'pwd_change'; keystore altered.
-
Parent topic: Changing the Password of a Software Keystore
4.1.3 Changing the Oracle Key Vault Password
To change the password of Oracle Key Vault, you use okvutil
, which is part of the Oracle Key Vault endpoint software on the database host.
Related Topics
Parent topic: Managing the Keystore
4.1.4 Configuring an External Store for a Keystore Password
An external store for a keystore password stores the keystore password in a centrally accessed and managed location.
- About Configuring an External Store for a Keystore Password
An external store for a keystore password stores the keystore password in a centrally accessed and managed location. - Configuring the External Keystore Password Store with WALLET_ROOT
When you configure TDE by using theWALLET_ROOT
parameter, the external keystore password store is auto-discovered in theWALLET_ROOT/tde_seps
directory. - When to Use the EXTERNAL STORE Clause After Configuration
After you configure the external store for a keystore password, you can use theEXTERNAL_STORE
clause in theADMINISTER KEY MANAGEMENT
statement.
Parent topic: Managing the Keystore
4.1.4.1 About Configuring an External Store for a Keystore Password
An external store for a keystore password stores the keystore password in a centrally accessed and managed location.
An external store for a TDE password is useful if you want to hide the keystore password wallet, Oracle Key Vault, or Oracle Cloud Infrastructure (OCI) key management service (KMS)) from the database administrator. It is also useful for situations in which you use automated tools to perform Transparent Data Encryption operations that require a password, when the scripts that run the automated tools include hard-coded password. To avoid hard-coding the password in a script, you can store this password in an external store on the database server. In a multitenant environment, different PDBs can make use of the external store.
Related Topics
Parent topic: Configuring an External Store for a Keystore Password
4.1.4.2 Configuring the External Keystore Password Store with WALLET_ROOT
When you configure TDE by using the WALLET_ROOT
parameter, the external keystore password store is auto-discovered in the WALLET_ROOT/tde_seps
directory.
Related Topics
Parent topic: Configuring an External Store for a Keystore Password
4.1.4.3 When to Use the EXTERNAL STORE Clause After Configuration
After you configure the external store for a keystore password, you can use the EXTERNAL_STORE
clause in the ADMINISTER KEY MANAGEMENT
statement.
You must use the EXTERNAL STORE
clause in the ADMINISTER KEY MANAGEMENT
statement for the following operations: opening, closing, backing up the keystore; adding, updating, or deleting a secret keystore; creating, using, rekeying, tagging, importing, exporting encryption keys.
For example:
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY EXTERNAL STORE;
You can change or delete external keystore passwords by using the ADMINISTER KEY MANAGEMENT UPDATE CLIENT SECRET
statement or the ADMINISTER KEY MANAGEMENT DELETE CLIENT SECRET
statement.
Parent topic: Configuring an External Store for a Keystore Password
4.1.5 Backing Up Password-Protected Software Keystores
When you back up a password-protected software keystore, you can create a backup identifier string to describe the backup type.
- About Backing Up Password-Protected Software Keystores
You must back up password-protected software keystores, as per the security policy and requirements of your site. - Creating a Backup Identifier String for the Backup Keystore
The backup file name of a software password keystore is derived from the name of the password-protected software keystore. - Backing Up a Password-Protected Software Keystore
TheBACKUP KEYSTORE
clause of theADMINISTER KEY MANAGEMENT
statement backs up a password-protected software keystore.
Parent topic: Managing the Keystore
4.1.5.1 About Backing Up Password-Protected Software Keystores
You must back up password-protected software keystores, as per the security policy and requirements of your site.
A backup of the keystore contains all of the keys contained in the original keystore. Oracle Database prefixes the backup keystore with the creation time stamp (UTC). If you provide an identifier string, then this string is inserted between the time stamp and keystore name.
After you complete the backup operation, the keys in the original keystore are marked as "backed up". You can check the status of keys querying the V$ENCRYPTION_WALLET
data dictionary view.
You cannot back up auto-login or local auto-login software keystores. No new keys can be added to them directly through the ADMINISTER KEY MANAGEMENT
statement operations. The information in these keystores is only read and hence there is no need for a backup.
You must include the WITH BACKUP
clause in any ADMINISTER KEY MANAGEMENT
statement that changes the wallet (for example, changing the wallet password or setting the master encryption key).
Parent topic: Backing Up Password-Protected Software Keystores
4.1.5.2 Creating a Backup Identifier String for the Backup Keystore
The backup file name of a software password keystore is derived from the name of the password-protected software keystore.
Parent topic: Backing Up Password-Protected Software Keystores
4.1.5.3 Backing Up a Password-Protected Software Keystore
The BACKUP KEYSTORE
clause of the ADMINISTER KEY MANAGEMENT
statement backs up a password-protected software keystore.
Parent topic: Backing Up Password-Protected Software Keystores
4.1.6 How the V$ENCRYPTION_WALLET View Interprets Backup Operations
The BACKUP
column of the V$ENCRYPTION_WALLET
view indicates a how a copy of the keystore was created.
The column indicates if a copy of the keystore had been created with the WITH BACKUP
clause of the ADMINISTER KEY MANAGEMENT
statement or the ADMINISTER KEY MANAGEMENT BACKUP KEYSTORE
statement.
When you modify a key or a secret, the modifications that you make do not exist in the previously backed-up copy, because you make a copy and then modify the key itself. Because there is no copy of the modification in the previous keystores, the BACKUP
column is set to NO
, even if the BACKUP
had been set to YES
previously. Hence, if the BACKUP
column is YES
, then after you perform an operation that requires a backup, such as adding a custom attribute tag, the BACKUP
column value changes to NO
.
Parent topic: Managing the Keystore
4.1.7 Backups of the External Keystore
You cannot use Oracle Database to back up external keystores.
Uploading TDE wallets into Oracle Key Vault is another way of backing up the wallet and having it available immediately if the need arises (for example after accidental deletion of the wallet, or file corruption). If the database is not migrated to online key management with Oracle Key Vault, then it keeps relying on the TDE wallet, even if the wallet has been uploaded into Oracle Key Vault.
You can use the Oracle Key Vault okvutil upload
and okvutil download
commands to upload and download TDE wallets to and from Oracle Key Vault.
For example, to upload a TDE wallet to Oracle Key Vault:
$ okvutil upload -l "/etc/oracle/wallets" -t wallet -g "HRWallet"
Enter wallet password (<enter> for auto-login): password
Enter Oracle Key Vault endpoint password: Key_Vault_endpoint_password
This example shows how to download a TDE wallet from Oracle Key Vault:
$ okvutil download -l "/etc/oracle/wallets/orcl/" -t WALLET -g HRWallet
Enter new wallet password(<enter> for auto-login): Oracle_wallet_password
Confirm new wallet password: Oracle_wallet_password
Enter Oracle Key Vault endpoint password: Key_Vault_endpoint_password
Related Topics
Parent topic: Managing the Keystore
4.1.8 Merging Software Keystores
You can merge software keystores in a variety of ways.
- About Merging Software Keystores
You can merge any combination of software keystores, but the merged keystore must be password-protected. It can have a password that is different from the constituent keystores. - Merging One Software Keystore into an Existing Software Keystore
You can use theADMINISTER KEY MANAGEMENT
statement with theMERGE KEYSTORE
clause to merge one software keystore into another existing software keystore. - Merging Two Software Keystores into a Third New Keystore
You can merge two software keystores into a third new keystore. The two existing source keystores are not changed. - Merging an Auto-Login Software Keystore into an Existing Password-Protected Software Keystore
You can merge an auto-login software keystore into an existing password-protected software keystore. - Reversing a Software Keystore Merge Operation
You cannot directly reverse a keystore merge operation.
Parent topic: Managing the Keystore
4.1.8.1 About Merging Software Keystores
You can merge any combination of software keystores, but the merged keystore must be password-protected. It can have a password that is different from the constituent keystores.
To use the merged keystore, you must explicitly open the merged keystore after you create it, even if one of the constituent keystores was already open before the merge.
Whether a common key from two source keystores is added or overwritten to a merged keystore depends on how you write the ADMINISTER KEY MANAGEMENT
merge statement. For example, if you merge Keystore 1 and Keystore 2 to create Keystore 3, then the key in Keystore 1 is added to Keystore 3. If you merge Keystore 1 into Keystore 2, then the common key in Keystore 2 is not overwritten.
The ADMINISTER KEY MANAGEMENT
merge statement has no bearing on the configured keystore that is in use. However, the merged keystore can be used as the new configured database keystore if you want. Remember that you must reopen the keystore if you are using the newly created keystore as the keystore for the database at the location configured by the WALLET_ROOT
parameter.
4.1.8.2 Merging One Software Keystore into an Existing Software Keystore
You can use the ADMINISTER KEY MANAGEMENT
statement with the MERGE KEYSTORE
clause to merge one software keystore into another existing software keystore.
-
To perform this type of merge, follow the steps in Merging Two Software Keystores into a Third New Keystore but use the following SQL statement:
ADMINISTER KEY MANAGEMENT MERGE KEYSTORE 'keystore1_location' [IDENTIFIED BY software_keystore1_password] INTO EXISTING KEYSTORE 'keystore2_location' IDENTIFIED BY software_keystore2_password [WITH BACKUP [USING 'backup_identifier]];
In this specification:
-
keystore1_location
is the directory location of the first keystore, which will be left unchanged after the merge. Enclose this path in single quotation marks (' '). -
The
IDENTIFIED BY
clause is required for the first keystore if it is a password-protected keystore.software_keystore1_password
is the password for the first keystore. -
keystore2_location
is the directory location of the second keystore into which the first keystore is to be merged. Enclose this path in single quotation marks (' '). -
software_keystore2_password
is the password for the second keystore. -
WITH BACKUP
creates a backup of the software keystore. Optionally, you can use theUSING
clause to add a brief description of the backup. Enclose this description in single quotation marks (' '). This identifier is appended to the named keystore file (for example,ewallet_
time-stamp
_emp_key_backup
.p12
, withemp_key_backup
being the backup identifier). Follow the file naming conventions that your operating system uses.
-
The resultant keystore after the merge operation is always a password-protected keystore.
Parent topic: Merging Software Keystores
4.1.8.3 Merging Two Software Keystores into a Third New Keystore
You can merge two software keystores into a third new keystore. The two existing source keystores are not changed.
Parent topic: Merging Software Keystores
4.1.8.4 Merging an Auto-Login Software Keystore into an Existing Password-Protected Software Keystore
You can merge an auto-login software keystore into an existing password-protected software keystore.
-
Use the
ADMINISTER KEY MANAGEMENT MERGE KEYSTORE
SQL statement to merge an auto-login software keystore into an existing password-protected software keystore.
Example 4-1 shows how to merge an auto-login software keystore into a password-protected software keystore. It also creates a backup of the second keystore before creating the merged keystore.
Example 4-1 Merging a Software Auto-Login Keystore into a Password Keystore
ADMINISTER KEY MANAGEMENT MERGE KEYSTORE '/etc/ORACLE/KEYSTORE/DB1'
INTO EXISTING KEYSTORE '/etc/ORACLE/KEYSTORE/DB2'
IDENTIFIED BY keystore_password WITH BACKUP;
In this specification:
-
MERGE KEYSTORE
must specify the auto-login keystore. -
EXISTING KEYSTORE
refers to the password keystore.
Parent topic: Merging Software Keystores
4.1.8.5 Reversing a Software Keystore Merge Operation
You cannot directly reverse a keystore merge operation.
When you merge a keystore into an existing keystore (rather than creating a new one), you must include the WITH BACKUP
clause in the ADMINISTER KEY MANAGEMENT
statement to create a backup of this existing keystore. Later on, if you decide that you must reverse the merge, you can replace the merged software keystore with the one that you backed up.
In other words, suppose you want merge Keystore A into Keystore B. By using the WITH BACKUP
clause, you create a backup for Keystore B before the merge operation begins. (The original Keystore A is still intact.) To reverse the merge operation, revert to the backup that you made of Keystore B.
-
Use the
ADMINISTER KEY MANAGEMENT MERGE KEYSTORE
SQL statement to perform merge operations.-
For example, to perform a merge operation into an existing keystore:
ADMINISTER KEY MANAGEMENT MERGE KEYSTORE '/etc/ORACLE/KEYSTORE/DB1' INTO EXISTING KEYSTORE '/etc/ORACLE/KEYSTORE/DB2' IDENTIFIED BY password WITH BACKUP USING "merge1";
Replace the new keystore with the backup keystore, which in this case would be named
ewallet_
time-stamp
_merge1.p12
. -
To merge an auto-login keystore into a password-based keystore, use the
ADMINISTER KEY MANAGEMENT MERGE KEYSTORE
SQL statement.
-
Parent topic: Merging Software Keystores
4.1.9 Moving a Software Keystore to a New Location
You move a software keystore to a new location after you have updated the WALLET_ROOT
parameter.
If you are using Oracle Key Vault, then you can configure a TDE direct connection where Key Vault directly manages the master encryption keys. In this case, you will never need to manually move the keystore to a new location.
-
Log in to the database instance as a user who has been granted the
ADMINISTER KEY MANAGEMENT
orSYSKM
privilege. -
Back up the software keystore.
For example:
ADMINISTER KEY MANAGEMENT BACKUP KEYSTORE USING 'hr.emp_keystore' FORCE KEYSTORE IDENTIFIED BY software_keystore_password TO '/etc/ORACLE/KEYSTORE/DB1/';
-
Close the software keystore.
Examples of ways that you can close the keystore are as follows.
For an auto-login software keystore:
ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE;
For a password-protected software keystore:
ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY software_keystore_password;
For a keystore for which the password is stored externally:
ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY EXTERNAL STORE;
-
Exit the database session.
For example, if you are logged in to SQL*Plus:
EXIT
-
In the
init.ora
file for the database instance, update theWALLET_ROOT
parameter to point to the new location where you want to move the keystore. -
Use the operating system move command (such as
mv
) to move the keystore with all of its keys to the new directory location.
Related Topics
Parent topic: Managing the Keystore
4.1.10 Moving a Software Keystore Out of Automatic Storage Management
You can use the ADMINISTER KEY MANAGEMENT
statement to move a software keystore out Automatic Storage Management.
Parent topic: Managing the Keystore
4.1.11 Migrating Between a Software Password Keystore and an External Keystore
You can migrate between password-protected software keystores and external keystores.
- Migrating from a Password-Protected Software Keystore to an External Keystore
You can migrate from a password-protected software keystore to an external keystore. - Migrating from an External Keystore to a Password-Based Software Keystore
You can migrate an external keystore to a software keystore. - Keystore Order After a Migration
After you perform a migration, keystores can be either primary or secondary in their order.
Parent topic: Managing the Keystore
4.1.11.1 Migrating from a Password-Protected Software Keystore to an External Keystore
You can migrate from a password-protected software keystore to an external keystore.
- Step 1: Convert the Software Keystore to Open with the External Keystore
Some Oracle tools require access to the old software keystore to encrypt or decrypt data that was exported or backed up using the software keystore. - Step 2: Configure the External Keystore Type
You can use theALTER SYSTEM
statement to configure the external keystore type. - Step 3: Perform the External Keystore Migration
You can use theADMINISTER KEY MANAGEMENT
SQL statement to perform an external keystore migration.
4.1.11.1.1 Step 1: Convert the Software Keystore to Open with the External Keystore
Some Oracle tools require access to the old software keystore to encrypt or decrypt data that was exported or backed up using the software keystore.
- Use the
ADMINISTER KEY MANAGEMENT
SQL statement to convert a software keystore to open with an external keystore.- To set the software keystore password as that of the external keystore, use the following syntax:
ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD FORCE KEYSTORE IDENTIFIED BY software_keystore_password SET "external_key_manager_password" WITH BACKUP [USING 'backup_identifier'];
In this specification:
-
software_keystore_password
is the same password that you used when creating the software keystore. -
external_key_manager_password
is the new software keystore password which is the same as the password of the external keystore. -
WITH BACKUP
creates a backup of the software keystore. Optionally, you can use theUSING
clause to add a brief description of the backup. Enclose this description in single quotation marks (' '
). This identifier is appended to the named keystore file (for example,ewallet_
time-stamp
_emp_key_backup
.p12
, withemp_key_backup
being the backup identifier). Follow the file naming conventions that your operating system uses.
-
- To create an auto-login keystore for a software keystore, use the following syntax:
ADMINISTER KEY MANAGEMENT CREATE [LOCAL] AUTO_LOGIN KEYSTORE FROM KEYSTORE 'keystore_location' IDENTIFIED BY software_keystore_password;
In this specification:
-
LOCAL
enables you to create a local auto-login software keystore. Otherwise, omit this clause if you want the keystore to be accessible by other computers. -
keystore_location
is the path to the keystore directory location of the keystore that is configured in thesqlnet.ora
file. -
software_keystore_password
is the existing password of the configured software keystore.
-
- To set the software keystore password as that of the external keystore, use the following syntax:
4.1.11.1.2 Step 2: Configure the External Keystore Type
You can use the ALTER SYSTEM
statement to configure the external keystore type.
4.1.11.1.3 Step 3: Perform the External Keystore Migration
You can use the ADMINISTER KEY MANAGEMENT
SQL statement to perform an external keystore migration.
MIGRATE USING
keystore_password
clause in the ADMINISTER KEY MANAGEMENT SET KEY
SQL statement to decrypt the existing TDE table keys and tablespace encryption keys with the TDE master encryption key in the software keystore and then reencrypt them with the newly created TDE master encryption key in the external keystore. After you complete the migration, you do not need to restart the database, nor do you need to manually re-open the external keystore. The migration process automatically reloads the keystore keys in memory.
4.1.11.2 Migrating from an External Keystore to a Password-Based Software Keystore
You can migrate an external keystore to a software keystore.
- About Migrating Back from an External Keystore
To switch from using an external keystore solution to a software keystore, you can use reverse migration of the keystore. - Step 1: Configure the External Type
You can use theALTER SYSTEM
statement to configure the external keystore type. - Step 2: Configure the Keystore for the Reverse Migration
TheADMINISTER KEY MANAGEMENT
statement with theSET ENCRYPTION KEY
andREVERSE MIGRATE
clauses can be used to reverse the migration of a keystore. - Step 3: Configure the External Keystore to Open with the Software Keystore
After you complete the migration, the migration process automatically reloads the keystore keys in memory.
4.1.11.2.1 About Migrating Back from an External Keystore
To switch from using an external keystore solution to a software keystore, you can use reverse migration of the keystore.
After you complete the switch, keep the external keystore, in case earlier backup files rely on the TDE master encryption keys in the external key manager.
If you had originally migrated from the software keystore to the external keystore and reconfigured the software keystore, then you already have an existing keystore with the same password as the external keystore password. Reverse migration configures this keystore to act as the new software keystore with a new password. If your existing keystore is an auto-login software keystore and you have the password-based software keystore for this auto-login keystore, then use the password-based keystore. If the password-based keystore is not available, then merge the auto-login keystore into a newly created empty password-based keystore, and use the newly created password-based keystore.
If you do not have an existing keystore, then you must specify a keystore location using the WALLET_ROOT
parameter in the init.ora
file. When you perform the reverse migration, migrate to the previous keystore so that you do not lose the keys.
4.1.11.2.2 Step 1: Configure the External Type
You can use the ALTER SYSTEM
statement to configure the external keystore type.
4.1.11.2.3 Step 2: Configure the Keystore for the Reverse Migration
The ADMINISTER KEY MANAGEMENT
statement with the SET ENCRYPTION KEY
and REVERSE MIGRATE
clauses can be used to reverse the migration of a keystore.
-
Log in to the database instance as a user who has been granted the
ADMINISTER KEY MANAGEMENT
orSYSKM
privilege.For example:
sqlplus sec_admin as syskm Enter password: password Connected.
-
Reverse migrate the keystore by using the following syntax:
ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY software_keystore_password REVERSE MIGRATE USING "external_key_manager_password" [WITH BACKUP [USING 'backup_identifier']];
In this specification:
-
software_keystore_password
is the password for the existing keystore or the new keystore. -
external_key_manager_password
is the password that was created when you first created the external keystore. If the pre-external software keystore is the new keystore, then you must ensure that it has the same password as theexternal_key_manager_password
before issuing the reverse migration command. Enclose this setting in double quotation marks (" "
). -
WITH BACKUP
creates a backup of the software keystore. Optionally, you can include theUSING
clause to add a brief description of the backup. Enclose this description in single quotation marks (' '
). This identifier is appended to the named keystore file (for example,ewallet_
time-stamp
_
emp_key_backup
.p12
, withemp_key_backup
being the backup identifier). Follow the file naming conventions that your operating system uses.
For example:
ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY password REVERSE MIGRATE USING "external_key_manager_password" WITH BACKUP; keystore altered.
-
-
Optionally, change the keystore password.
For example:
ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD IDENTIFIED BY old_password SET new_password WITH BACKUP USING 'new_password';
Related Topics
4.1.11.2.4 Step 3: Configure the External Keystore to Open with the Software Keystore
After you complete the migration, the migration process automatically reloads the keystore keys in memory.
You do not need to restart the database, nor do you need to manually re-open the software keystore.
The external keystore may still be required after reverse migration because the old keys are likely to have been used for encrypted backups or by tools such as Oracle Data Pump and Oracle Recovery Manager. You should cache the external keystore credentials in the keystore so that the HSM can be opened with the software keystore.
4.1.11.3 Keystore Order After a Migration
After you perform a migration, keystores can be either primary or secondary in their order.
The WALLET_ORDER
column of the V$ENCRYPTION_WALLET
dynamic view describes whether a keystore is primary (that is, it holds the current TDE master encryption key) or if it is secondary (it holds the previous TDE master encryption key). The WRL_TYPE
column describes the type of locator for the keystore (for example, FILE
for the sqlnet.ora
file). The WALLET_ORDER
column shows SINGLE
if two keystores are not configured together and no migration was ever performed previously.
Table 4-1 describes how the keystore order works after you perform a migration.
Table 4-1 Keystore Order After a Migration
Type of Migration Done | WRL_TYPE | WALLET_ORDER | Description |
---|---|---|---|
Migration of software keystore to external keystore |
|
|
Both the external and software keystore are configured. The TDE master encryption key can be either in Oracle Key Vault or the software keystore. The TDE master encryption key is first searched in Oracle Key Vault. If the TDE master encryption key is not in the primary keystore (Oracle Key Vault), then it will be searched for in the software keystore. All of the new TDE master encryption keys will be created in the primary keystore (in this case, Oracle Key Vault). |
Reverse migration from HSM to software keystore |
|
|
Both the external and software keystore are configured. The TDE master encryption key can be either in the external keystore or the software keystore. The TDE master encryption key is first searched for in the software keystore. If the TDE master encryption key is not present in the primary (that is, software) keystore, then it will be searched for in the HSM's external keystore. All of the new TDE master encryption keys will be created in the primary keystore (in this case, the software keystore). |
4.1.12 Migration of Keystores to and from Oracle Key Vault
You can use Oracle Key Vault to migrate both software and external keystores to and from Oracle Key Vault.
This enables you to manage the keystores centrally, and then share the keystores as necessary with other TDE-enabled databases in your enterprise.
Oracle Key Vault enables you to upload a keystore to a container called a virtual wallet, and then create a new virtual wallet from the contents of previously uploaded Oracle keystores. For example, suppose you previously uploaded a keystore that contains 5 keys. You can create a new virtual wallet that consists of only 3 of these keys. You then can download this keystore to another TDE-enabled database. This process does not modify the original keystore.
In addition to Oracle keystores, Oracle Key Vault enables you to securely share other security objects, such as credential files and Java keystores, across the enterprise. It prevents the loss of keys and keystores due to forgotten passwords or accidentally deleted keystores. You can use Oracle Key Vault with products other than TDE: Oracle Real Application Security, Oracle Active Data Guard, and Oracle GoldenGate. Oracle Key Vault facilitates the movement of encrypted data using Oracle Data Pump and Oracle Transportable Tablespaces.
Related Topics
Parent topic: Managing the Keystore
4.1.13 Closing a Keystore
You can manually close software and external keystores.
- About Closing Keystores
After you open a keystore, it remains open until you shut down the database instance. - Closing a Software Keystore
You can manually close password-based software keystores, auto-login software keystores, and local auto-login software keystores. - Closing an External Keystore
To close an external keystore, you must use theADMINISTER KEY MANAGEMENT
statement with theSET KEYSTORE CLOSE
clause.
Parent topic: Managing the Keystore
4.1.13.1 About Closing Keystores
After you open a keystore, it remains open until you shut down the database instance.
When you restart the database instance, then auto-login and local auto-login software keystores automatically open when required (that is, when the TDE master encryption key must be accessed). However, software password-based and external keystores do not automatically open. You must manually open them again before you can use them.
When you close a software or an external keystore, you disable all of the encryption and decryption operations on the database. Hence, a database user or application cannot perform any operation involving encrypted data until the keystore is reopened.
When you re-open a keystore after closing it, the keystore contents are reloaded back into the database. Thus, if the contents had been modified (such as during a migration), the database will have the latest keystore contents.
You can check if a keystore is closed by querying the STATUS
column of the V$ENCRYPTION_WALLET
view.
The following data operations will fail if the keystore is not accessible:
-
SELECT
data from an encrypted column -
INSERT
data into on an encrypted column -
CREATE
a table with encrypted columns -
CREATE
an encrypted tablespace
Parent topic: Closing a Keystore
4.1.13.2 Closing a Software Keystore
You can manually close password-based software keystores, auto-login software keystores, and local auto-login software keystores.
In the case of an auto-login keystore, which opens automatically when it is accessed, manually close it if you moved it to a new location. You do this if you are changing your configuration from an auto-login keystore to a password-based keystore: you move out the auto-login keystore, and then close the auto-login keystore.
-
Log in to the database instance as a user who has been granted the
ADMINISTER KEY MANAGEMENT
orSYSKM
privilege.For example:
sqlplus sec_admin as syskm Enter password: password Connected.
-
Run the
ADMINISTER KEY MANAGEMENT
SQL statement.-
For a password-based software keystore, use the following syntax:
ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE [IDENTIFIED BY [EXTERNAL STORE | software_keystore_password]];
In this specification:
-
IDENTIFIED BY
can be one of the following:-
EXTERNAL STORE
uses the keystore password stored in the external store to perform the keystore operation. -
software_keystore_password
is the password of the user who created the keystore.
-
-
-
For an auto-login or local auto-login software keystore, use the following SQL statement:
ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE;
You do not need to specify a password for this statement.
-
Closing a keystore disables all of the encryption and decryption operations. Any attempt to encrypt or decrypt data or access encrypted data results in an error.
Parent topic: Closing a Keystore
4.1.13.3 Closing an External Keystore
To close an external keystore, you must use the ADMINISTER KEY MANAGEMENT
statement with the SET KEYSTORE CLOSE
clause.
Parent topic: Closing a Keystore
4.1.14 Using a Software Keystore That Resides on ASM Volumes
You can store a software keystore on an Automatic Storage Management (ASM) disk group.
-
Edit the
WALLET_ROOT
parameter of theinit.ora
file to use the location of an ASM disk group specified using the ASM file naming convention that was used in previous releases when you configured theDIRECTORY
setting in theENCRYPTION_WALLET_LOCATION
setting. That is, you must use the plus sign (+
) notation for the ASM file name.
For example:
WALLET_ROOT=+disk1/mydb/wallet
If you must move or merge software keystores between a regular file system and an ASM file system, then you can use the same keystore merge statements that are used to merge software keystores.
To manage keystores in an ASM environment, you can use the ASMCMD
utility.
4.1.15 Backup and Recovery of Encrypted Data
For software keystores, you cannot access encrypted data without the TDE master encryption key.
Because the TDE master encryption key is stored in the keystore, you should periodically back up the software keystore in a secure location. You must back up a copy of the keystore whenever you set a new TDE master encryption key or perform any operation that writes to the keystore.
Do not back up the software keystore in the same location as the encrypted data. Back up the software keystore separately. This is especially true when you use the auto-login keystore, which does not require a password to open. In case the backup tape is lost, a malicious user should not be able to get both the encrypted data and the keystore.
Oracle Recovery Manager (Oracle RMAN) does not back up the software keystore as part of the database backup. When using a media manager such as Oracle Secure Backup with Oracle RMAN, Oracle Secure Backup automatically excludes auto-open keystores (the cwallet.sso
files). However, it does not automatically exclude encryption keystores (the ewallet.p12
files). It is a good practice to add the following exclude
data set statement to your Oracle Secure Backup configuration:
exclude name *.p12
This setting instructs Oracle Secure Backup to exclude the encryption keystore from the backup set.
If you lose the software keystore that stores the TDE master encryption key, then you can restore access to encrypted data by copying the backed-up version of the keystore to the appropriate location. If you archived the restored keystore after the last time that you reset the TDE master encryption key, then you do not need to take any additional action.
If the restored software keystore does not contain the most recent TDE master encryption key, then you can recover old data up to the point when the TDE master encryption key was reset by rolling back the state of the database to that point in time. All of the modifications to encrypted columns after the TDE master encryption key was reset are lost.
Related Topics
Parent topic: Managing the Keystore
4.1.16 Dangers of Deleting Keystores
Oracle strongly recommends that you do not delete keystores.
If a keystore becomes overly full, any TDE master encryption key other than the currently active TDE master encryption key can be moved to a new keystore to reduce the overall size of the keystore, but it is important to keep a backup of the old and new keystores because even though the keys have been moved out of the currently active keystore, they may still be needed by other Oracle features, such as Oracle Recovery Manager backup operations. (See Related Topics at the end of this topic for a listing of features that are affected by deleted keystores.)
Deleting a keystore that still contains keys is particularly dangerous if you have configured Transparent Data Encryption and the keystore is in use. You can find if a keystore is in use by querying the STATUS
column of the V$ENCRYPTION_WALLET
view after you open the keystore. How you should proceed depends on whether you are using united mode or isolated mode.
- In isolated mode, if the
STATUS
column of theV$ENCRYPTION_WALLET
isOPEN_NO_MASTER_KEY
, then it is safe to archive and later delete the this keystore, because there are no keys in it. - In united mode, you must execute the query of
V$ENCRYPTION_WALLET
from theCDB$ROOT
, not the PDB. If you execute the query in a PDB that does not yet have a key set, then theSTATUS
isOPEN_NO_MASTER_KEY
. However, this can be misleading, because a key could have been set in theCDB$ROOT
. After you execute the query in the root and if theSTATUS
isOPEN_NO_MASTER_KEY
, then you can safely archive and later delete the keystore.
The reason that you should be cautious when moving keys out of the currently-active TDE keystore is that this keystore may contain keys that are still needed by the database (even though the TDE master encryption key has been rekeyed). Deleting the keystore deletes these keys, and could result in the loss of encrypted data. Even if you decrypted all of the data in your database, you still should not delete the keystore, because doing so could still hamper the normal functioning of the Oracle database. This is because a TDE master encryption key in the keystore can also be required for other Oracle Database features. (See Related Topics at the end of this topic for a listing of features that are affected by deleted keystores.)
Even after you performed TDE keystore migration (which rekeys in such a way that the location of your currently-active TDE master encryption key changes place between your software keystore and your external keystore), you still should not delete your original keystore. The keys in the original keystore may be needed at a later time (for example, when you must recover an offline encrypted tablespace). Even if all online tablespaces are not encrypted, the key may still be in use.
The exception is in the case of software auto-login (or local auto-login) keystores. If you do not want to use this type of keystore, then ideally you should move it to a secure directory. Only delete an auto-login keystore if you are sure that it was created from a specific password-based keystore because an auto-login keystore is always based on an ordinary software keystore. The keystore should be available and known.
If you must delete a keystore, then do so with great caution. You must first move the keys within the keystore to a new keystore by using the ADMINISTER KEY MANAGEMENT MOVE KEYS TO NEW KEYSTORE
statement.
4.1.17 Features That Are Affected by Deleted Keystores
Some features can be adversely affected if a keystore is deleted and a TDE master encryption key residing in that keystore is later needed.
Before you delete a keystore, consider the impact that the deletion will have in the event that you need the any TDE master encryption key in the TDE keystore at a later time. The following features and activities are affected:
- Offlined tablespace operations
- Oracle Secure Backup operations
- Media recovery and block media recovery operations
- Point-in-time recovery operations
- Physical and logical Oracle Data Guard standby operations
- Golden Gate operations
- Oracle Streams operations
- Oracle Recovery Manager operations, including restoring Oracle Recovery Manager backups
- Applying archived redo logs to a database during database crash recovery operations
- Database online block recovery. (Online block recovery implies that the database is still open. Deleting a wallet in an open database with encrypted tablespaces will cause additional problems other than those associated with online block recovery.) These problems can include the following:
- Encrypted online data in encrypted tablespaces would no longer be decrypted. Encrypted metadata in the
SYSTEM
,UNDO
, andTEMP
tablespaces would no longer be decrypted. You will no longer have control over what metadata is encrypted or where that metadata can reside. - Buffered data or metadata needs to be encrypted before it can be written back to the disk, but if the wallet is deleted, then the buffered data or metadata would no longer be encrypted. This could cause redo generation to fail, and the DBWR background process would not be able to write the data, which would possibly lead to a database instance hang or crash.
- After a database instance crash, the database instance recovery and database crash recovery would fail, leading to the database not being able to be restarted.
- Encrypted online data in encrypted tablespaces would no longer be decrypted. Encrypted metadata in the
Related Topics
Parent topic: Managing the Keystore
4.2 Managing the TDE Master Encryption Key
You can manage the TDE master encryption key in several ways.
- Creating User-Defined TDE Master Encryption Keys
You can create a user-defined TDE master encryption key outside the database by generating a TDE master encryption key ID. - Creating TDE Master Encryption Keys for Later Use
You can create a TDE master encryption key that can be activated at a later date. - Activating TDE Master Encryption Keys
After you activate a TDE master encryption key, it can be used. - TDE Master Encryption Key Attribute Management
TDE master encryption key attributes store information about the TDE master encryption key. - Creating Custom TDE Master Encryption Key Attributes for Reports
Custom TDE master encryption key attributes enable you to defined attributes that are specific to your needs. - Setting or Rekeying the TDE Master Encryption Key in the Keystore
You can set or rekey the TDE master encryption key for both software keystores and external keystores. - Exporting and Importing the TDE Master Encryption Key
You can export and import the TDE master encryption key in different ways. - Moving TDE Master Encryption Keys into a New Keystore
You can move an existing TDE master encryption key into a new keystore from an existing password-protected keystore. - Management of TDE Master Encryption Keys Using Oracle Key Vault
You can use Oracle Key Vault to manage and share TDE master encryption keys across an enterprise.
Parent topic: Managing the Keystore and the Master Encryption Key
4.2.1 Creating User-Defined TDE Master Encryption Keys
You can create a user-defined TDE master encryption key outside the database by generating a TDE master encryption key ID.
- About User-Defined TDE Master Encryption Keys
A TDE master encryption key that is outside the database has its own user-generated ID, which tracks the use of the TDE master encryption key. - Creating a User-Defined TDE Master Encryption Key
To create a user-defined TDE master encryption key, use theADMINISTER KEY MANAGEMENT
statement with theSET | CREATE [ENCRYPTION] KEY
clause.
Parent topic: Managing the TDE Master Encryption Key
4.2.1.1 About User-Defined TDE Master Encryption Keys
A TDE master encryption key that is outside the database has its own user-generated ID, which tracks the use of the TDE master encryption key.
You can use the ADMINISTER KEY MANAGEMENT
to create and set user-defined TDE master encryption key IDs. After you generate the TDE master encryption key, you can bring this key into the database. Optionally, you can specify the TDE master encryption key ID in various ADMINISTER KEY MANAGEMENT
statements.
This type of configuration benefits Oracle Fusion SaaS Cloud environments in that it enables you to generate a TDE master encryption key this complies with your site’s requirements. This key that you generate supports the current encryption algorithms and can be used for software keystores.
After you generate the TDE master encryption key ID, you can encrypt your data as you normally would.
The TDE master encryption key and its corresponding ID will not be captured by any auditing logs.
Parent topic: Creating User-Defined TDE Master Encryption Keys
4.2.1.2 Creating a User-Defined TDE Master Encryption Key
To create a user-defined TDE master encryption key, use the ADMINISTER KEY MANAGEMENT
statement with the SET | CREATE [ENCRYPTION] KEY
clause.
Related Topics
Parent topic: Creating User-Defined TDE Master Encryption Keys
4.2.2 Creating TDE Master Encryption Keys for Later Use
You can create a TDE master encryption key that can be activated at a later date.
- About Creating a TDE Master Encryption Key for Later Use
TheCREATE KEY
clause of theADMINISTER KEY MANAGEMENT
statement can create a TDE master encryption key to be activated at a later date. - Creating a TDE Master Encryption Key for Later Use
A keystore must be opened before you can create a TDE master encryption key for use later on. - Example: Creating a TDE Master Encryption Key in a Single Database
You can use theADMINISTER KEY MANAGEMENT CREATE KEY USING TAG
statement to create a TDE master encryption key in a single database.
Parent topic: Managing the TDE Master Encryption Key
4.2.2.1 About Creating a TDE Master Encryption Key for Later Use
The CREATE KEY
clause of the ADMINISTER KEY MANAGEMENT
statement can create a TDE master encryption key to be activated at a later date.
You then can activate this key on the same database or export it to another database and activate it there.
This method of TDE master encryption key creation is useful in a multitenant environment when you must re-create the TDE master encryption keys. The CREATE KEY
clause enables you to use a single SQL statement to generate a new TDE master encryption key for all of the PDBs within a multitenant environment. The creation time of the new TDE master encryption key is later than the activation of the TDE master encryption key that is currently in use. Hence, the creation time can serve as a reminder to all of the PDBs to activate the most recently created TDE master encryption key as soon as possible.
Parent topic: Creating TDE Master Encryption Keys for Later Use
4.2.2.2 Creating a TDE Master Encryption Key for Later Use
A keystore must be opened before you can create a TDE master encryption key for use later on.
-
Log in to the database instance as a user who has been granted the
ADMINISTER KEY MANAGEMENT
orSYSKM
privilege.For example:
sqlplus sec_admin as syskm Enter password: password Connected.
-
Create the TDE master encryption key by using this syntax:
ADMINISTER KEY MANAGEMENT CREATE KEY [USING TAG 'tag'] [FORCE KEYSTORE] IDENTIFIED BY [EXTERNAL STORE | keystore_password] [WITH BACKUP [USING 'backup_identifier']];
In this specification:
-
tag
is the associated attribute and information that you define. Enclose this setting in single quotation marks (' '). -
FORCE KEYSTORE
temporarily opens the password-protected keystore for this operation. You must open the keystore for this operation. -
IDENTIFIED BY
can be one of the following settings:-
EXTERNAL STORE
uses the keystore password stored in the external store to perform the keystore operation. -
keystore_password
is the mandatory keystore password that you used when you created the original keystore. It is case sensitive.
-
-
WITH BACKUP
backs up the TDE master encryption key in the same location as the key, as identified by theWRL_PARAMETER
column of theV$ENCRYPTION_WALLET
view. To find the key locations for all of the database instances, query theGV$ENCRYPTION_WALLET
view.You must back up password-based software keystores. You do not need to back up auto-login or local auto-login software keystores. Optionally, include the
USING
backup_identifier
clause to add a description of the backup. Enclosebackup_identifier
in single quotation marks (' '
).
-
-
If necessary, activate the TDE master encryption key.
-
Fin the key ID.
SELECT KEY_ID FROM V$ENCRYPTION_KEYS; KEY_ID ---------------------------------------------------- AWsHwVYC2U+Nv3RVphn/yAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
-
Use this key ID to activate the key.
ADMINISTER KEY MANAGEMENT USE KEY 'AWsHwVYC2U+Nv3RVphn/yAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' USING TAG 'quarter:second;description:Activate Key on standby' IDENTIFIED BY password WITH BACKUP;
-
4.2.2.3 Example: Creating a TDE Master Encryption Key in a Single Database
You can use the ADMINISTER KEY MANAGEMENT CREATE KEY USING TAG
statement to create a TDE master encryption key in a single database.
Example 4-2 shows how to create a TDE master encryption key in a single database. After you run this statement, a TDE master encryption key with the tag definition is created in the keystore for that database. You can query the TAG
column of the V$ENCRYPTION_KEYS
view for the identifier of the newly created key. You can query the CREATION_TIME
column to find the most recently created key, which would be the key that you created from this statement. You can export this key to another database if you want or activate it locally later on, as described in Activating TDE Master Encryption Keys.
Example 4-2 Creating a TDE Master Encryption Key in a Single Database
ADMINISTER KEY MANAGEMENT CREATE KEY USING TAG
'source:admin@source;target:db1@target'
IDENTIFIED BY password WITH BACKUP;
keystore altered.
Parent topic: Creating TDE Master Encryption Keys for Later Use
4.2.3 Activating TDE Master Encryption Keys
After you activate a TDE master encryption key, it can be used.
- About Activating TDE Master Encryption Keys
You can activate a previously created or imported TDE master encryption key by using theUSE KEY
clause ofADMINISTER KEY MANAGEMENT
. - Activating a TDE Master Encryption Key
To activate a TDE master encryption key, you must open the keystore and useADMINISTER KEY MANAGEMENT
with theUSE KEY
clause. - Example: Activating a TDE Master Encryption Key
You can use the ADMINISTER KEY MANAGEMENT SQL statement to activate a TDE master encryption key.
Parent topic: Managing the TDE Master Encryption Key
4.2.3.1 About Activating TDE Master Encryption Keys
You can activate a previously created or imported TDE master encryption key by using the USE KEY
clause of ADMINISTER KEY MANAGEMENT
.
After you activate the master encryption key, it is used to encrypt all data encryption keys in your database. The key will be used to protect all of the column keys and all of the tablespace encryption keys. If you have deployed a logical standby database, then you must export the TDE master encryption keys after recreating them, and then import them into the standby database. You can have the TDE master encryption key in use on both the primary and the standby databases. To do so, you must activate the TDE master encryption key after you import it to the logical standby database.
Parent topic: Activating TDE Master Encryption Keys
4.2.3.2 Activating a TDE Master Encryption Key
To activate a TDE master encryption key, you must open the keystore and use ADMINISTER KEY MANAGEMENT
with the USE KEY
clause.
-
Log in to the database instance as a user who has been granted the
ADMINISTER KEY MANAGEMENT
orSYSKM
privilege.For example:
sqlplus sec_admin as syskm Enter password: password Connected.
-
Query the
KEY_ID
column of theV$ENCRYPTION_KEYS
view to find the key identifier.For example:
SELECT KEY_ID FROM V$ENCRYPTION_KEYS; KEY_ID ---------------------------------------------------- ARaHD762tUkkvyLgPzAi6hMAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
-
Use this key identifier to activate the TDE master encryption key by using the following syntax:
ADMINISTER KEY MANAGEMENT USE KEY 'key_identifier_from_V$ENCRYPTION_KEYS' [USING TAG 'tag'] [FORCE KEYSTORE] IDENTIFIED BY [EXTERNAL STORE | keystore_password] [WITH BACKUP [USING 'backup_identifier']];
In this specification:
-
key_identifier_from_V$ENCRYPTION_KEYS
is the key identifie. Enclose this setting in single quotation marks (' '
). -
tag
is the associated attributes and information that you define. Enclose this setting in single quotation marks (' '
). -
FORCE KEYSTORE
temporarily opens the password-protected keystore for this operation. You must open the keystore for this operation. -
IDENTIFIED BY
can be one of the following settings:-
EXTERNAL STORE
uses the keystore password stored in the external store to perform the keystore operation. -
keystore_password
is the mandatory keystore password that you used when you created the original keystore.
-
-
WITH BACKUP
backs up the TDE master encryption key in the same location as the key, as identified by theWRL_PARAMETER
column of theV$ENCRYPTION_WALLET
view. To find the key locations for all of the database instances, query theGV$ENCRYPTION_WALLET
view.You must back up password-based software keystores. You do not need to back up auto-login or local auto-login software keystores. Optionally, include the
USING
backup_identifier
clause to add a description of the backup. Enclosebackup_identifier
in single quotation marks (' '
).
-
Related Topics
Parent topic: Activating TDE Master Encryption Keys
4.2.3.3 Example: Activating a TDE Master Encryption Key
You can use the ADMINISTER KEY MANAGEMENT SQL statement to activate a TDE master encryption key.
Example 4-3 shows how to activate a previously imported TDE master encryption key and then update its tag. This key is activated with the current database time stamp and time zone.
Example 4-3 Activating a TDE Master Encryption Key
ADMINISTER KEY MANAGEMENT USE KEY
'ARaHD762tUkkvyLgPzAi6hMAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'
USING TAG 'quarter:second;description:Activate Key on standby'
IDENTIFIED BY password WITH BACKUP;
keystore altered.
In this version of the same operation, the FORCE KEYSTORE
clause is added in the event that the auto-login keystore is in use, or if the keystore is closed. The password of the keystore is stored externally, so the EXTERNAL STORE
setting is used for the IDENTIFIED BY
clause.
ADMINISTER KEY MANAGEMENT USE KEY 'ARaHD762tUkkvyLgPzAi6hMAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' USING TAG 'quarter:second;description:Activate Key on standby' FORCE KEYSTORE IDENTIFIED BY EXTERNAL STORE WITH BACKUP; keystore altered.
Parent topic: Activating TDE Master Encryption Keys
4.2.4 TDE Master Encryption Key Attribute Management
TDE master encryption key attributes store information about the TDE master encryption key.
- TDE Master Encryption Key Attributes
TDE master encryption key attributes include detailed information about the TDE master encryption key. - Finding the TDE Master Encryption Key That Is in Use
A TDE master encryption key that is in use is the encryption key that was activated most recently for the database.
Parent topic: Managing the TDE Master Encryption Key
4.2.4.1 TDE Master Encryption Key Attributes
TDE master encryption key attributes include detailed information about the TDE master encryption key.
The information contains the following types:
-
Key time stamp information: Internal security policies and compliance policies usually determine the key rekeying frequency. You should expire keys when they reach the end of their lifetimes and then generate new keys. Time stamp attributes such as key creation time and activation time help you to determine the key age accurately, and automate key generation.
The
V$ENCRYPTION_KEYS
view includes columns such asCREATION_TIME
andACTIVATION_TIME.
See Oracle Database Reference for a complete description of theV$ENCRYPTION_KEYS
view. -
Key owner information: Key owner attributes help you to determine the user who created or activated the key. These attributes can be important for security, auditing, and tracking purposes. Key owner attributes also include key use information, such as whether the key is used for standalone TDE operations or used in a multitenant environment.
The
V$ENCRYPTION_KEYS
view includes columns such asCREATOR, CREATOR_ID, USER, USER_ID,
andKEY_USE.
-
Key source information: Keys often must be moved between databases for operations such as import-export operations and Data Guard-related operations. Key source attributes enable you to track the origin of each key. You can track whether a key was created locally or imported, and the database name and instance number of the database that created the key. In a multitenant environment, you can track the PDB where the key was created.
The
V$ENCRYPTION_KEYS
view includes columns such asCREATOR_DBNAME, CREATOR_DBID, CREATOR_INSTANCE_NAME, CREATOR_INSTANCE_NUMBER, CREATOR_PDBNAME,
and so on. -
Key usage information: Key usage information determines the database or PDB where the key is being used. It also helps determine whether a key is in active use or not.
The
V$ENCRYPTION_KEYS
view includes columns such asACTIVATING_DBNAME, ACTIVATING_DBID, ACTIVATING_INSTANCE_NAME, ACTIVATING_PDBNAME,
and so on. -
User-defined information and other information: When creating a key, you can tag it with information using the
TAG
option. Each key contains important information such as whether or not it has been backed up.The
V$ENCRYPTION_KEYS
view includes columns such asKEY_ID, TAG,
and other miscellaneous columns, for exampleBACKED_UP
.
Note:
TDE Master Key Attributes and Tag are only supported with a hardware security module that has PKCS#11 data object support.Parent topic: TDE Master Encryption Key Attribute Management
4.2.4.2 Finding the TDE Master Encryption Key That Is in Use
A TDE master encryption key that is in use is the encryption key that was activated most recently for the database.
Parent topic: TDE Master Encryption Key Attribute Management
4.2.5 Creating Custom TDE Master Encryption Key Attributes for Reports
Custom TDE master encryption key attributes enable you to defined attributes that are specific to your needs.
- About Creating Custom Attribute Tags
Attribute tags enable you to monitor specific activities users perform, such as accessing a particular terminal ID. - Creating a Custom Attribute Tag
To create a custom attribute tag, you must use theSET TAG
clause of theADMINISTER KEY MANAGEMENT
statement.
Parent topic: Managing the TDE Master Encryption Key
4.2.5.1 About Creating Custom Attribute Tags
Attribute tags enable you to monitor specific activities users perform, such as accessing a particular terminal ID.
By default, Oracle Database defines a set of attributes that describe various characteristics of the TDE master encryption keys that you create, such as the creation time, database in which the TDE master encryption key is used, and so on. These attributes are captured by the V$ENCRYPTION_KEY
dynamic view.
You can create custom attributes that can be captured by the TAG
column of the V$ENCRYPTION_KEYS
dynamic view. This enables you to define behaviors that you may want to monitor, such as users who perform activities on encryption keys. The tag can encompass multiple attributes, such as session IDs from a specific terminal.
After you create the tag for a TDE master encryption key, its name should appear in the TAG
column of the V$ENCRYPTION_KEYS
view for that TDE master encryption key. If you create a tag for the secret, then the tag appears in the SECRET_TAG
column of the V$CLIENT_SECRETS
view. If you create a secret with a tag, then the tag appears in the SECRET_TAG
column of the V$CLIENT_SECRETS
view.
4.2.5.2 Creating a Custom Attribute Tag
To create a custom attribute tag, you must use the SET TAG
clause of the ADMINISTER KEY MANAGEMENT
statement.
-
Log in to the database instance as a user who has been granted the
ADMINISTER KEY MANAGEMENT
orSYSKM
privilege.For example:
sqlplus sec_admin as syskm Enter password: password Connected.
-
If necessary, query the
TAG
column of theV$ENCRYPTION_KEY
dynamic view to find a listing of existing tags for the TDE master encryption keys.When you create a new tag for a TDE master encryption key, it overwrites the existing tag for that TDE master encryption key.
-
Create the custom attribute tag by using the following syntax:
ADMINISTER KEY MANAGEMENT SET TAG 'tag' FOR 'master_key_identifier' [FORCE KEYSTORE] IDENTIFIED BY [EXTERNAL STORE | keystore_password] [WITH BACKUP [USING 'backup_identifier']];
In this specification
-
tag
is the associated attributes or information that you define. Enclose this information in single quotation marks (' '). -
master_key_identifier
identifies the TDE master encryption key for which thetag
is set. To find a list of TDE master encryption key identifiers, query theKEY_ID
column of theV$ENCRYPTION_KEYS
dynamic view. -
FORCE KEYSTORE
temporarily opens the password-protected keystore for this operation. You must open the keystore for this operation. -
IDENTIFIED BY
can be one of the following settings:-
EXTERNAL STORE
uses the keystore password stored in the external store to perform the keystore operation. -
keystore_password
is the password that was used to create the keystore.
-
-
backup_identifier
defines the tag values. Enclose this setting in single quotation marks (' '
) and separate each value with a colon.
For example, to create a tag that uses two values, one to capture a specific session ID and the second to capture a specific terminal ID:
ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY USING TAG 'sessionid=3205062574:terminal=xcvt' IDENTIFIED BY keystore_password WITH BACKUP; keystore altered.
Both the session ID (
3205062574
) and terminal ID (xcvt
) can derive their values by using either theSYS_CONTEXT
function with theUSERENV
namespace, or by using theUSERENV
function. -
4.2.6 Setting or Rekeying the TDE Master Encryption Key in the Keystore
You can set or rekey the TDE master encryption key for both software keystores and external keystores.
- About Setting or Rekeying the TDE Master Encryption Key in the Keystore
You can set or rekey the TDE master encryption key for both software password-based and external keystores. - Creating, Tagging, and Backing Up a TDE Master Encryption Key
TheADMINISTER KEY MANAGEMENT
statement enables you to create, tag, and back up a TDE master encryption key. - About Rekeying the TDE Master Encryption Key
Oracle Database uses a unified TDE Master Encryption Key for both TDE column encryption and TDE tablespace encryption. - Rekeying the TDE Master Encryption Key
You can use theADMINISTER KEY MANAGEMENT
statement to rekey a TDE master encryption key. - Rekeying the TDE Master Encryption Key for a Tablespace
You can use theREKEY
clause of theALTER TABLESPACE
statement to rekey a TDE master encryption key for an encrypted tablespace.
Parent topic: Managing the TDE Master Encryption Key
4.2.6.1 About Setting or Rekeying the TDE Master Encryption Key in the Keystore
You can set or rekey the TDE master encryption key for both software password-based and external keystores.
The TDE master encryption key is stored in an external security module (keystore), and it is used to protect the TDE table keys and tablespace encryption keys. By default, the TDE master encryption key is a system-generated random value created by Transparent Data Encryption (TDE).
Use the ADMINISTER KEY MANAGEMENT
statement to set or reset (REKEY
) the TDE master encryption key. When the master encryption key is set, then TDE is considered enabled and cannot be disabled.
Before you can encrypt or decrypt database columns or tablespaces, you must generate a TDE master encryption key. Oracle Database uses the same TDE master encryption key for both TDE column encryption and TDE tablespace encryption. The instructions for setting a software or hardware TDE master encryption key explain how to generate a tDE master encryption key.
4.2.6.2 Creating, Tagging, and Backing Up a TDE Master Encryption Key
The ADMINISTER KEY MANAGEMENT
statement enables you to create, tag, and back up a TDE master encryption key.
WALLET_ROOT
parameter in the initialization parameter file to store the TDE master encryption key.
4.2.6.3 About Rekeying the TDE Master Encryption Key
Oracle Database uses a unified TDE Master Encryption Key for both TDE column encryption and TDE tablespace encryption.
When you rekey the TDE master encryption key for TDE column encryption, the TDE Master Encryption Key for TDE tablespace encryption also is rekeyed. Rekey the TDE Master Encryption Key only if it was compromised or as per the security policies of the organization. This process deactivates the previous TDE master encryption key.
For better security and to meet compliance regulations, periodically rekey the TDE master encryption key. This process deactivates the previous TDE master encryption key, creates a new TDE master encryption key, and then activates it. You can check the keys that were created recently by querying the CREATION_TIME
column in the V$ENCRYPTION_KEYS
view. To find the keys that were activated recently, query the ACTIVATION_TIME
column in the V$ENCRYPTION_KEYS
view.
You cannot change the TDE master encryption key or rekey a TDE master encryption key for an auto-login keystore. Because auto-login keystores do not have a password, an administrator or a privileged user can change the keys without the knowledge of the security officer. However, if both the auto-login and the password-based keystores are present in the configured location (as set in the sqlnet.ora
file), then when you rekey the TDE master encryption key, a TDE master encryption key is added to both the auto-login and password-based keystores. If the auto-login keystore is in use in a location that is different from that of the password-based keystore, then you must re-create the auto-login keystore.
Do not perform a rekey operation of the master key concurrently with an online tablespace rekey operation. You can find if an online tablespace is in the process of being TDE Master Encryption Keyed by issuing the following query:
SELECT TS#,ENCRYPTIONALG,STATUS FROM V$ENCRYPTED_TABLESPACES;
A status of REKEYING
means that the corresponding tablespace is still being rekeyed.
Note:
You cannot add new information to auto-login keystores separately.
4.2.6.4 Rekeying the TDE Master Encryption Key
You can use the ADMINISTER KEY MANAGEMENT
statement to rekey a TDE master encryption key.
4.2.7 Exporting and Importing the TDE Master Encryption Key
You can export and import the TDE master encryption key in different ways.
- About Exporting and Importing the TDE Master Encryption Key
Oracle Database features such as transportable tablespaces and Oracle Data Pump move data that is possibly encrypted between databases. - About Exporting TDE Master Encryption Keys
You can useADMINISTER KEY MANAGEMENT EXPORT
to export TDE master encryption keys from a keystore, and then import them into another keystore. - Exporting a TDE Master Encryption Key
TheADMINISTER KEY MANAGEMENT
statement with theEXPORT [ENCRYPTION] KEYS WITH SECRET
clause exports a TDE master encryption key. - Example: Exporting a TDE Master Encryption Key by Using a Subquery
TheADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS
statement can export a TDE master encryption key by using a subquery. - Example: Exporting a List of TDE Master Encryption Key Identifiers to a File
TheADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS WITH SECRET
statement can export a list of TDE master encryption key identifiers to a file. - Example: Exporting All TDE Master Encryption Keys of the Database
TheADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS
SQL statement can export all TDE master encryption keys of a database. - About Importing TDE Master Encryption Keys
TheADMINISTER KEY MANAGEMENT IMPORT
statement can import exported TDE master encryption keys from a key export file into a target keystore. - Importing a TDE Master Encryption Key
TheADMINISTER KEY MANAGEMENT
statement with theIMPORT [ENCRYPTION] KEYS WITH SECRET
clause can import a TDE master encryption key. - Example: Importing a TDE Master Encryption Key
You can use the ADMINISTER KEY MANAGEMENT IMPORT KEYS SQL statement to import a TDE master encryption key. - How Keystore Merge Differs from TDE Master Encryption Key Export or Import
The keystore merge operation differs from the TDE master encryption key export and import operations.
Parent topic: Managing the TDE Master Encryption Key
4.2.7.1 About Exporting and Importing the TDE Master Encryption Key
Oracle Database features such as transportable tablespaces and Oracle Data Pump move data that is possibly encrypted between databases.
These are some common scenarios in which you can choose to export and import TDE master encryption keys to move them between source and target keystores. For Data Guard (Logical Standby), you must copy the keystore that is in the primary database to the standby database. Instead of merging the primary database keystore with the standby database, you can export the TDE master encryption key that is in use and then import it to the standby database. Moving transportable tablespaces that are encrypted between databases requires that you export the TDE master encryption key at the source database and then import it into the target database.
Parent topic: Exporting and Importing the TDE Master Encryption Key
4.2.7.2 About Exporting TDE Master Encryption Keys
You can use ADMINISTER KEY MANAGEMENT EXPORT
to export TDE master encryption keys from a keystore, and then import them into another keystore.
A TDE master encryption key is exported together with its key identifier and key attributes. The exported keys are protected with a password (secret) in the export file.
You can specify the TDE master encryption keys to be exported by using the WITH IDENTIFIER
clause of the ADMINSITER KEY MANAGENT EXPORT
statement. To export the TDE master encryption keys, you can either specify their key identifiers as a comma-separated list, or you can specify a query that enumerates their key identifiers. Be aware that Oracle Database executes the query determining the key identifiers within the current user's rights and not with definer's rights.
If you omit the WITH IDENTIFER
clause, then all of the TDE master encryption keys of the database are exported.
4.2.7.3 Exporting a TDE Master Encryption Key
The ADMINISTER KEY MANAGEMENT
statement with the EXPORT [ENCRYPTION] KEYS WITH SECRET
clause exports a TDE master encryption key.
-
Log in to the database instance as a user who has been granted the
ADMINISTER KEY MANAGEMENT
orSYSKM
privilege.For example:
sqlplus sec_admin as syskm Enter password: password Connected.
-
Export the TDE master encryption keys by using the following syntax:
ADMINISTER KEY MANAGEMENT EXPORT [ENCRYPTION] KEYS WITH SECRET "export_secret" TO 'file_path' [FORCE KEYSTORE] IDENTIFIED BY [EXTERNAL STORE | keystore_password] [WITH IDENTIFIER IN 'key_id1', 'key_id2', 'key_idn' | (SQL_query)];
In this specification:
-
export_secret
is a password that you can specify to encrypt the export the file that contains the exported keys. Enclose this secret in double quotation marks (" "), or you can omit the quotation marks if the secret has no spaces. -
file_path
is the complete path and name of the file to which the keys must be exported. Enclose this path in single quotation marks (' ')
. You can export to regular file systems only. -
FORCE KEYSTORE
temporarily opens the password-protected keystore for this operation. You must open the keystore for this operation. -
IDENTIFIED BY
can be one of the following settings:-
EXTERNAL STORE
uses the keystore password stored in the external store to perform the keystore operation. -
software_keystore_password
is the password of the keystore containing the keys.
-
-
key_id1
,key_id2
,key_idn
is a string of one or more TDE master encryption key identifiers for the TDE master encryption key being exported. Separate each key identifier with a comma and enclose each of these key identifiers in single quotation marks (' '
). To find a list of TDE master encryption key identifiers, query theKEY_ID
column of theV$ENCRYPTION_KEYS
dynamic view. -
SQL_query
is a query that fetches a list of the TDE master encryption key identifiers. It should return only one column which contains the TDE master encryption key identifiers. This query is executed with current user rights.
-
Related Topics
Parent topic: Exporting and Importing the TDE Master Encryption Key
4.2.7.4 Example: Exporting a TDE Master Encryption Key by Using a Subquery
The ADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS
statement can export a TDE master encryption key by using a subquery.
Example 4-5 shows how to export TDE master encryption keys whose identifiers are fetched by a query to a file called export.exp
. The TDE master encryption keys in the file are encrypted using the secret my_secret
. The SELECT
statement finds the identifiers for the TDE master encryption keys to be exported.
Example 4-4 Exporting a List of TDE Master Encryption Key Identifiers to a File
ADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS
WITH SECRET "my_secret"
TO '/TDE/export.exp'
FORCE KEYSTORE
IDENTIFIED BY password
WITH IDENTIFIER IN 'AdoxnJ0uH08cv7xkz83ovwsAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
'AW5z3CoyKE/yv3cNT5CWCXUAAAAAAAAAAAAAAAAAAAAAAAAAAAAA';
keystore altered.
Parent topic: Exporting and Importing the TDE Master Encryption Key
4.2.7.5 Example: Exporting a List of TDE Master Encryption Key Identifiers to a File
The ADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS WITH SECRET
statement can export a list of TDE master encryption key identifiers to a file.
Example 4-4 shows how to export TDE master encryption keys by specifying their identifiers as a list, to a file called export.exp
. TDE master encryption keys in the file are encrypted using the secret my_secret
. The identifiers of the TDE master encryption key to be exported are provided as a comma-separated list.
Example 4-5 Exporting TDE Master Encryption Key Identifiers by Using a Subquery
ADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS
WITH SECRET "my_secret" TO '/etc/TDE/export.exp'
FORCE KEYSTORE
IDENTIFIED BY password
WITH IDENTIFIER IN (SELECT KEY_ID FROM V$ENCRYPTION_KEYS WHERE ROWNUM <3);
keystore altered.
Parent topic: Exporting and Importing the TDE Master Encryption Key
4.2.7.6 Example: Exporting All TDE Master Encryption Keys of the Database
The ADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS
SQL statement can export all TDE master encryption keys of a database.
Example 4-6 shows how to export all of the TDE master encryption keys of the database to a file called export.exp
. The TDE master encryption keys in the file are encrypted using the secret my_secret
.
Example 4-6 Exporting All of the TDE Master Encryption Keys of the Database
ADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS WITH SECRET "my_secret" TO '/etc/TDE/export.exp' FORCE KEYSTORE IDENTIFIED BY password; keystore altered.
Parent topic: Exporting and Importing the TDE Master Encryption Key
4.2.7.7 About Importing TDE Master Encryption Keys
The ADMINISTER KEY MANAGEMENT IMPORT
statement can import exported TDE master encryption keys from a key export file into a target keystore.
You cannot re-import TDE master encryption keys that have already been imported.
4.2.7.8 Importing a TDE Master Encryption Key
The ADMINISTER KEY MANAGEMENT
statement with the IMPORT [ENCRYPTION] KEYS WITH SECRET
clause can import a TDE master encryption key.
-
Log in to the database instance as a user who has been granted the
ADMINISTER KEY MANAGEMENT
orSYSKM
privilege.sqlplus sec_admin as syskm Enter password: password Connected.
-
Run the following SQL statement:
ADMINISTER KEY MANAGEMENT IMPORT [ENCRYPTION] KEYS WITH SECRET "import_secret" FROM 'file_name' [FORCE KEYSTORE] IDENTIFIED BY [EXTERNAL STORE | keystore_password] [WITH BACKUP [USING 'backup_identifier']];
In this specification:
-
import_secret
is the same password that was used to encrypt the keys during the export operation. Enclose this secret in double quotation marks (" "), or you can omit the quotation marks if the secret has no spaces. -
file_name
is the complete path and name of the file from which the keys need to be imported. Enclose this setting in single quotation marks (' '
). -
FORCE KEYSTORE
temporarily opens the password-protected keystore for this operation. You must open the keystore for this operation. -
IDENTIFIED BY
can be one of the following settings:-
EXTERNAL STORE
uses the keystore password stored in the external store to perform the keystore operation. -
software_keystore_password
is the password of the software keystore where the keys are being imported.
-
-
WITH BACKUP
must be used in case the target keystore was not backed up before the import operation.backup_identifier
is an optional string that you can provide to identify the keystore backup. Enclose this setting in single quotation marks (' '
).
-
Related Topics
Parent topic: Exporting and Importing the TDE Master Encryption Key
4.2.7.9 Example: Importing a TDE Master Encryption Key
You can use the ADMINISTER KEY MANAGEMENT IMPORT KEYS SQL statement to import a TDE master encryption key.
Example 4-7 shows how to import the TDE master encryption key identifiers that are stored in the file export.exp
and encrypted with the secret my_secret
.
Example 4-7 Importing TDE Master Encryption Key Identifiers from an Export File
ADMINISTER KEY MANAGEMENT IMPORT KEYS
WITH SECRET "my_secret"
FROM '/etc/TDE/export.exp'
FORCE KEYSTORE
IDENTIFIED BY password WITH BACKUP;
keystore altered.
Parent topic: Exporting and Importing the TDE Master Encryption Key
4.2.7.10 How Keystore Merge Differs from TDE Master Encryption Key Export or Import
The keystore merge operation differs from the TDE master encryption key export and import operations.
Even though both the ADMINISTER KEY MANAGEMENT MERGE
statement and the ADMINISTER KEY MANAGEMENT EXPORT
and IMPORT
statements eventually move the TDE master encryption keys from one keystore to the next, there are differences in how these two statements function.
-
The
MERGE
statement merges two keystores whereas theEXPORT
andIMPORT
statements export the keys to a file or import the keys from a file. The keystore is different from the export file, and the two cannot be used interchangeably. The export file is not a keystore and cannot be configured to be used with a database as a keystore. Similarly, theIMPORT
statement cannot extract the TDE master encryption keys from the keystore. -
The
MERGE
statement merges all of the TDE master encryption keys of the specified keystores where as theEXPORT
andIMPORT
statements can be selective. -
The
EXPORT
andIMPORT
statements require the user to provide both a location (filepath
) and the file name of the export file, whereas theMERGE
statement only takes in the location of the keystores. -
The file name of the keystores is fixed and is determined by the
MERGE
operation and can be eitherewallet.p12
orcwallet.sso
. The file names for the export files used in theEXPORT
theIMPORT
statements are specified by the user. -
The keystores on Automatic Storage Management (ASM) disk groups or regular file systems can be merged with
MERGE
statements. The export files used in theEXPORT
and theIMPORT
statements can only be a regular operating system file and cannot be located on an ASM disk group. -
The keystores merged using the
MERGE
statement do not need to be configured or in use with the database. TheEXPORT
statement can only export the keys from a keystore that is configured and in use with the database and is also open when the export is done. TheIMPORT
statement can only import the keys into a keystore that is open, configured, and in use with the database. -
The
MERGE
statement never modifies the metadata associated with the TDE master encryption keys. TheEXPORT
andIMPORT
operations can modify the metadata of the TDE master encryption keys when required, such as during a PDB plug operation.
Parent topic: Exporting and Importing the TDE Master Encryption Key
4.2.8 Moving TDE Master Encryption Keys into a New Keystore
You can move an existing TDE master encryption key into a new keystore from an existing password-protected keystore.
- About Moving TDE Master Encryption Keys into a New Keystore
You can move an unused (and safely archived) TDE master encryption key into a new keystore. - Moving a TDE Master Encryption Key into a New Keystore
TheADMINISTER KEY MANAGEMENT MOVE KEYS
moves an existing TDE master encryption key into a new keystore from an existing keystore.
Parent topic: Managing the TDE Master Encryption Key
4.2.8.1 About Moving TDE Master Encryption Keys into a New Keystore
You can move an unused (and safely archived) TDE master encryption key into a new keystore.
Use great caution when you decide to execute ADMINISTER KEY MANAGEMENT MOVE KEYS
. Even though this statement will not move an active master encryption key, it can still affect keys that are necessary for a range of database features. If you have deleted a key, then the data that was encrypted by that key is rendered permanently inaccessible (equivalent to deleting the data) for these features to be used. See Related Topics at the end of this topic for more information about features that are affected by deleted keystores.
Therefore, before you move the keystore, it is very important that you safely archive it. Delete the keystore only after a period of time has passed, to ensure that the keystore is no longer really useful.
To move a TDE master encryption key into a new keystore, you use the ADMINISTER KEY MANAGEMENT MOVE KEYS
statement. This statement does not move the active TDE master encryption key (that is, the key that is currently in use at the time that ADMINISTER KEY MANAGEMENT MOVE KEYS
is issued) because the database is currently using it.
If you mistakenly use the ADMINISTER KEY MANAGEMENT MOVE KEYS
statement instead of ADMINISTER KEY MANAGEMENT MERGE KEYSTORE
when you are configuring a new TDE keystore (for example, when you are changing the TDE keystore configuration from one where the software keystore is located in the operating system's file system to one where the software keystore is located in Oracle Automatic Storage Management (Oracle ASM)), then the following symptoms may help you to identify the TDE misconfiguration that was introduced by the use of the wrong key management command:
- When you open the TDE keystore that was the target of the earlier
ADMINISTER KEY MANAGEMENT MOVE KEYS
operation, anORA-28374: typed master key not found in wallet
error is seen, because the active TDE master encryption key was not moved to that keystore. - The value shown in the
STATUS
column of theV$ENCRYPTION_WALLET
view isOPEN_NO_MASTER_KEY
after you open the new keystore. TheOPEN_NO_MASTER_KEY
status is expected, because the new TDE keystore that was mistakenly populated by means of theADMINISTER KEY MANAGEMENT MOVE KEYS
statement does not contain the active TDE master encryption key.
4.2.8.2 Moving a TDE Master Encryption Key into a New Keystore
The ADMINISTER KEY MANAGEMENT MOVE KEYS
moves an existing TDE master encryption key into a new keystore from an existing keystore.
4.2.9 Management of TDE Master Encryption Keys Using Oracle Key Vault
You can use Oracle Key Vault to manage and share TDE master encryption keys across an enterprise.
Oracle Key Vault securely stores the keys in a central repository, along with other security objects such as credential files and Java keystores, and enables you to share these objects with other TDE-enabled databases.
4.3 Storing Oracle Database Secrets
Secrets are data that support internal Oracle Database features that integrate external clients such as Oracle GoldenGate into the database.
- About Storing Oracle Database Secrets in a Keystore
Keystores can store secrets that support internal Oracle Database features and integrate external clients such as Oracle GoldenGate. - Storage of Oracle Database Secrets in a Software Keystore
TheADMINISTER KEY MANAGEMENT ADD SECRET|UPDATE SECRET|DELETE SECRET
statements can add secrets, update secrets, and delete secrets from a keystore. - Example: Adding an Oracle Key Vault Password to a Software Keystore
TheADMINISTER KEY MANAGEMENT ADD SECRET
statement can add an Oracle Key Vault password to a software keystore. - Example: Changing an Oracle Key Vault Password Stored as a Secret in a Software Keystore
TheADMINISTER KEY MANAGEMENT UPDATE SECRET
statement can change an Oracle Key Vault password that is stored as a secret in a software keystore. - Example: Deleting an Oracle Key Vault Password Stored as a Secret in a Software Keystore
TheADMINISTER KEY MANAGEMENT DELETE SECRET
statement can delete Oracle Key Vault passwords that are stored as secrets in a software keystore. - Storage of Oracle Database Secrets in an External Keystore
TheADMINISTER KEY MANAGEMENT ADD SECRET|UPDATE SECRET|DELETE SECRET
statements can add, update, and delete secrets. - Example: Adding an Oracle Database Secret to an External Keystore
TheADMINISTER KEY MANAGEMENT ADD SECRET
statement can add an Oracle Database secret to an external keystore. - Example: Changing an Oracle Database Secret in an External Keystore
TheADMINISTER KEY MANAGEMENT MANAGEMENT UPDATE SECRET
statement can change an Oracle Database secret in an external keystore. - Example: Deleting an Oracle Database Secret in an External Keystore
TheADMINISTER KEY MANAGEMENT DELETE SECRET FOR CLIENT
statement can delete an Oracle Database secret that is in an external keystore. - Configuring Auto-Open Connections into External Key Managers
An external key manager can be configured to use the auto-login capability.
Parent topic: Managing the Keystore and the Master Encryption Key
4.3.1 About Storing Oracle Database Secrets in a Keystore
Keystores can store secrets that support internal Oracle Database features and integrate external clients such as Oracle GoldenGate.
The secret key must be a string adhering to Oracle identifier rules. You can add, update, or delete a client secret in an existing keystore. The Oracle GoldenGate Extract process must have data encryption keys to decrypt the data that is in data files and in REDO
or UNDO
logs. Keys are encrypted with shared secrets when you share the keys between an Oracle database and an Oracle GoldenGate client. The software keystore stores the shared secrets.
Depending on your site's requirements, you may require automated open keystore operations even when an external keystore is configured. For this reason, the external key manager password can be stored in a software auto-login keystore, which enables the auto-login capability for the external keystore. The Oracle Database side can also store the credentials for the database to log in to an external storage server in the software keystore.
You can store Oracle Database secrets in both software keystores and external keystores:
-
Software keystores: You can store secrets in software password-based, auto-login, and local auto-login software keystores. If you want to store secrets in an auto-login (or auto-login local) keystore, then note the following:
-
If the software auto-login keystore is in the same location as its corresponding password-based software keystore, then the secrets are added automatically.
-
If the software auto-login keystore is in a different location from its corresponding password-based software keystore, then you must create the auto-login keystore again from the password-based keystore, and keep the two keystores in synchronization.
-
-
External keystores: You can store secrets in standard external key managers.
4.3.2 Storage of Oracle Database Secrets in a Software Keystore
The ADMINISTER KEY MANAGEMENT ADD SECRET|UPDATE SECRET|DELETE SECRET
statements can add secrets, update secrets, and delete secrets from a keystore.
As with all of the ADMINISTER KEY MANAGEMENT
statements, you must have the ADMINISTER KEY MANAGEMENT
or the SYSKM
administrative privilege. To find information about existing secrets, you can query the V$CLIENT_SECRETS
dynamic view.
-
Adding a secret: Use the following syntax:
ADMINISTER KEY MANAGEMENT ADD SECRET 'secret' FOR CLIENT 'client_identifier' [USING TAG 'tag'] [TO [[LOCAL] AUTO_LOGIN] KEYSTORE keystore_location [FORCE KEYSTORE] IDENTIFIED BY [EXTERNAL STORE | keystore_password] [WITH BACKUP [USING backup_id];
-
Updating a secret: Use the following syntax:
ADMINISTER KEY MANAGEMENT UPDATE SECRET 'secret' FOR CLIENT 'client_identifier' [USING TAG 'tag'] [TO [[LOCAL] AUTO_LOGIN] KEYSTORE keystore_location [FORCE KEYSTORE] IDENTIFIED BY [EXTERNAL STORE | keystore_password] [WITH BACKUP [USING backup_id];
-
Deleting a secret: Use the following syntax:
ADMINISTER KEY MANAGEMENT DELETE SECRET FOR CLIENT 'client_identifier' [FROM [[LOCAL] AUTO_LOGIN] KEYSTORE keystore_location [FORCE KEYSTORE] IDENTIFIED BY [EXTERNAL STORE | keystore_password] [WITH BACKUP [USING backup_id];
In all of these statements, the specification is as follows:
-
secret
is the client secret key to be stored, updated, or deleted. Enclose this setting in single quotation marks (' '
) or omit the quotation marks if the secret has no spaces. To find information about existing secrets and their client identifiers, query theV$CLIENT_SECRETS
dynamic view. -
client_identifier
is an alphanumeric string used to identify the secret key.client_identifier
does not have a default value. Enclose this setting in single quotation marks (' '
). -
TO [[LOCAL] AUTO_LOGIN] KEYSTORE
refers to the location of an auto-login keystore, which is specified in thesqlnet.ora
file. -
tag
is an optional, user-defined description for the secret key to be stored. You can usetag
with theADD
andUPDATE
operations. Enclose this setting in single quotation marks (' '
). This tag appears in theSECRET_TAG
column of theV$CLIENT_SECRETS
view.WITH BACKUP
is required in case the keystore was not backed up before theADD
,UPDATE
, orDELETE
operation.backup_identifier
is an optional user-defined description for the backup. Enclosebackup_identifier
in single quotation marks (' '
). -
[TO | FROM [[LOCAL] AUTOLLOGIN] KEYSTORE
specifies the location of the auto-login or password keystore, which is set in the sqlnet.ora
file. -
FORCE KEYSTORE
temporarily opens the password-protected keystore for this operation if an auto-login keystore is open (and in use) or if the keystore is closed. -
IDENTIFIED BY
can be one of the following settings:-
EXTERNAL STORE
uses the keystore password stored in the external store to perform the keystore operation. -
keystore_password
is the password for the keystore.
-
Parent topic: Storing Oracle Database Secrets
4.3.3 Example: Adding an Oracle Key Vault Password to a Software Keystore
The ADMINISTER KEY MANAGEMENT ADD SECRET
statement can add an Oracle Key Vault password to a software keystore.
Example 4-8 shows how to add an Oracle Key Vault password as a secret into an existing software keystore (for example, after migrating to Oracle Key Vault, the Oracle Key Vault password can be added to the old TDE software keystore to set up an auto-open connection into Oracle Key Vault.
Example 4-8 Adding an Oracle Database Secret to a Software Keystore
ADMINISTER KEY MANAGEMENT ADD SECRET 'external_key_manager_password' FOR CLIENT 'OKV_PASSWORD' IDENTIFIED BY software_keystore_password WITH BACKUP;
Before migrating from a software keystore to Oracle Key Vault, you can upload the software keystore into the virtual wallet of that endpoint in Oracle Key Vault. After migrating, you now can delete the old TDE wallet, because its key is in Oracle Key Vault. In order to configure auto-open Oracle Key Vault without a wallet being already present, execute the following statement:
ADMINISTER KEY MANAGEMENT ADD SECRET 'external_keystore_password' FOR CLIENT 'OKV_PASSWORD' INTO [LOCAL] AUTO_LOGIN KEYSTORE 'WALLET_ROOT/tde';
Note that the setting TDE_CONFIGURATION='KEYSTORE_CONFIGUARTION=OKV'
is for a password-protected connection into Oracle Key Vault. After the Oracle Key Vault password has been inserted into an existing or newly created wallet, change the TDE_CONFIGURATION
setting to 'KEYSTORE_CONFIGURATION=OKV|FILE'
.
Parent topic: Storing Oracle Database Secrets
4.3.4 Example: Changing an Oracle Key Vault Password Stored as a Secret in a Software Keystore
The ADMINISTER KEY MANAGEMENT UPDATE SECRET
statement can change an Oracle Key Vault password that is stored as a secret in a software keystore.
Example 4-9 shows how to change an Oracle Key Vault password that is stored as a secret in a software keystore.
Example 4-9 Changing an Oracle Key Vault Password Secret to a Software Keystore
ADMINISTER KEY MANAGEMENT UPDATE SECRET admin_password FOR CLIENT 'admin@myhost' USING TAG 'new_host_credentials' FORCE KEYSTORE IDENTIFIED BY software_keytore_password;
In this version, the password for the keystore is in an external store:
DMINISTER KEY MANAGEMENT UPDATE SECRET admin_password FOR CLIENT 'admin@myhost' USING TAG 'new_host_credentials' FORCE KEYSTORE IDENTIFIED BY EXTERNAL STORE;
Parent topic: Storing Oracle Database Secrets
4.3.5 Example: Deleting an Oracle Key Vault Password Stored as a Secret in a Software Keystore
The ADMINISTER KEY MANAGEMENT DELETE SECRET
statement can delete Oracle Key Vault passwords that are stored as secrets in a software keystore.
Example 4-10 shows how to delete an Oracle Key Vault password that is stored as a secret in the software keystore.
Example 4-10 Deleting an Oracle Key Vault Password Secret in a Software Keystore
ADMINISTER KEY MANAGEMENT
DELETE SECRET FOR CLIENT 'OKV_PASSWORD'
FORCE KEYSTORE
IDENTIFIED BY password WITH BACKUP;
In this version, the password for the keystore is in an external store:
ADMINISTER KEY MANAGEMENT DELETE SECRET FOR CLIENT 'OKV_PASSWORD' FORCE KEYSTORE IDENTIFIED BY EXTERNAL STORE WITH BACKUP;
Parent topic: Storing Oracle Database Secrets
4.3.6 Storage of Oracle Database Secrets in an External Keystore
The ADMINISTER KEY MANAGEMENT ADD SECRET|UPDATE SECRET|DELETE SECRET
statements can add, update, and delete secrets.
As with all ADMINISTER KEY MANAGEMENT
statements, you must have the ADMINISTER KEY MANAGEMENT
or the SYSKM
administrative privilege. When you add, update, or delete secrets from a keystore that is in use or presently open, then you must run ADMINISTER KEY MANAGEMENT
in the root.
You can store Oracle Database secrets in both HSM and Oracle Key Vault external keystores, but be aware that automatic logins do not work if you store the HSM_PASSWORD
in a Key Vault keystore.
-
Adding a secret: Use the following syntax:
ADMINISTER KEY MANAGEMENT ADD SECRET 'secret' FOR CLIENT 'client_identifier' [USING TAG 'tag'] [TO [[LOCAL] AUTO_LOGIN] KEYSTORE keystore_location [FORCE KEYSTORE] IDENTIFIED BY "external_key_manager_password" [WITH BACKUP [USING backup_id]];
-
Updating a secret: Use the following syntax:
ADMINISTER KEY MANAGEMENT UPDATE SECRET 'secret' FOR CLIENT 'client_identifier' [USING TAG 'tag'] [TO [[LOCAL] AUTO_LOGIN] KEYSTORE keystore_location [FORCE KEYSTORE] IDENTIFIED BY "external_key_manager_password" [WITH BACKUP [USING backup_id]];
-
Deleting a secret: Use the following syntax:
ADMINISTER KEY MANAGEMENT DELETE SECRET FOR CLIENT 'client_identifier' [FROM [[LOCAL] AUTO_LOGIN] KEYSTORE keystore_location [FORCE KEYSTORE] IDENTIFIED BY "external_key_manager_password" [WITH BACKUP [USING backup_id]];
In all of these statements, the specification as follows:
-
secret
is the client secret key to be stored, updated, or deleted. Enclose this setting in double quotation marks (' '
) or omit the quotation marks if the secret has no spaces. To find information about existing secrets and their client identifiers, query theV$CLIENT_SECRETS
dynamic view. -
client_identifier
is an alphanumeric string used to identify the secret key.client_identifier
does not have a default value. Enclose this setting in single quotation marks (' '). -
tag
is an optional, user-defined description for the secret key to be stored. You can usetag
with theADD
andUPDATE
operations. Enclose this setting in single quotation marks (' '
). This tag appears in theSECRET_TAG
column of theV$CLIENT_SECRETS
view. -
[TO | FROM [[LOCAL] AUTO_LOGIN] KEYSTORE
specifies the location of the keystore used for the external keystore. -
external_key_manager_password
is for an external keystore manager, which can be Oracle Key Vault or OCI Vault - Key Management. Enclose this password in double quotation marks. For Oracle Key Vault, enter the password that was given during the Oracle Key Vault client installation. If at that time no password was given, then the password in theADMINISTER KEY MANAGEMENT
statement becomesNULL
.
Parent topic: Storing Oracle Database Secrets
4.3.7 Example: Adding an Oracle Database Secret to an External Keystore
The ADMINISTER KEY MANAGEMENT ADD SECRET
statement can add an Oracle Database secret to an external keystore.
Example 4-11 shows how to add a password for a user to an external keystore.
Example 4-11 Adding an Oracle Database Secret to an External Keystore
ADMINISTER KEY MANAGEMENT ADD SECRET 'password' FOR CLIENT 'admin@myhost' USING TAG 'myhost admin credentials' IDENTIFIED BY "external_key_manager_password";
In this version, the keystore password is in an external store, so the EXTERNAL STORE
setting is used for IDENTIFIED BY
:
ADMINISTER KEY MANAGEMENT ADD SECRET 'password'
FOR CLIENT 'admin@myhost' USING TAG 'myhost admin credentials'
IDENTIFIED BY EXTERNAL STORE;
Parent topic: Storing Oracle Database Secrets
4.3.8 Example: Changing an Oracle Database Secret in an External Keystore
The ADMINISTER KEY MANAGEMENT MANAGEMENT UPDATE SECRET
statement can change an Oracle Database secret in an external keystore.
Example 4-12 shows how to change a password that is stored as a secret in a external keystore.
Example 4-12 Changing an Oracle Database Secret in an External Keystore
ADMINISTER KEY MANAGEMENT MANAGEMENT UPDATE SECRET 'password2' FOR CLIENT 'admin@myhost' USING TAG 'New host credentials' IDENTIFIED BY "external_key_manager_password";
In this version, the password for the keystore is in an external store:
ADMINISTER KEY MANAGEMENT MANAGEMENT UPDATE SECRET 'password2'
FOR CLIENT 'admin@myhost' USING TAG 'New host credentials'
IDENTIFIED BY EXTERNAL STORE;
Parent topic: Storing Oracle Database Secrets
4.3.9 Example: Deleting an Oracle Database Secret in an External Keystore
The ADMINISTER KEY MANAGEMENT DELETE SECRET FOR CLIENT
statement can delete an Oracle Database secret that is in an external keystore.
Example 4-13 shows how to delete an external key manager password that is stored as a secret in the external keystore.
Example 4-13 Deleting an Oracle Database Secret in an External Keystore
ADMINISTER KEY MANAGEMENT DELETE SECRET FOR CLIENT 'admin@myhost'
IDENTIFIED BY "external_key_manager_password";
In this version, the password for the keystore is in an external store:
ADMINISTER KEY MANAGEMENT DELETE SECRET FOR CLIENT 'admin@myhost' IDENTIFIED BY EXTERNAL STORE;
Parent topic: Storing Oracle Database Secrets
4.3.10 Configuring Auto-Open Connections into External Key Managers
An external key manager can be configured to use the auto-login capability.
- About Auto-Open Connections into External Key Managers
An auto-open connection into an external key manager stores the external keystore credentials in an auto-login keystore. - Configuring an Auto-Open Connection into an External Key Manager
To configure the auto-open connection, you must use theADMINISTER KEY MANAGEMENT
statement to add or update a client secret that to authenticate to the external key manager.
Parent topic: Storing Oracle Database Secrets
4.3.10.1 About Auto-Open Connections into External Key Managers
An auto-open connection into an external key manager stores the external keystore credentials in an auto-login keystore.
You can configure a connection to an external key manager so that the database can open the keystore without prompting for the keystore password. This configuration is essential in Oracle Real Application Clusters (Oracle RAC) environments, and is highly recommended for Oracle Data Guard standby databases. Be aware that this configuration reduces the security of the system as a whole. However, this configuration does support unmanned or automated operations, and is useful in deployments where TDE-enabled databases that are enrolled into an external keystore for key management can start automatically.
Be aware that executing the query SELECT * FROM V$ENCRYPTION_WALLET
will automatically open an auto-login external keystore. For example, suppose you have an auto-login external keystore configured. If you close the keystore and query the V$ENCRYPTION_WALLET
view, then the output will indicate that a keystore is open. This is because V$ENCRYPTION_WALLET
opened up the auto-login external keystore and then displayed the status of the auto-login keystore.
To enable the auto-login capability for an external keystore, you must store the external keystore's credentials in an auto-login wallet.
When you use the ADMINISTER KEY MANAGEMENT
statement, there are conceptually two sets of commands that act on client secrets:
ADMINISTER KEY MANAGEMENT
commands that act on the wallet that is currently in use (in other words, a wallet that contains an active TDE master encryption key).ADMINISTER KEY MANAGEMENT
commands that act on a wallet that is not currently being used to hold the active TDE master encryption key. Oracle recommends that you use this approach when you configure an auto-login external keystore.
4.3.10.2 Configuring an Auto-Open Connection into an External Key Manager
To configure the auto-open connection, you must use the ADMINISTER KEY MANAGEMENT
statement to add or update a client secret that to authenticate to the external key manager.
V$ENCRYPTION_WALLET
dynamic view for this wallet, the STATUS
column shows OPEN_NO_MASTER_KEY
rather than OPEN
, because the wallet only contains the client secret.
-
Reconfigure the
WALLET_ROOT
parameter in theinit.ora
file to include the keystore location of the software keystore, if it is not already present.The software keystore location may already be present if the you have previously migrated to using an external keystore.
For example:
WALLET_ROOT=/etc/ORACLE/WALLETS/orcl
-
Add or update the secret in the software keystore.
The secret is the external key manager password and the client is the
HSM_PASSWORD
.HSM_PASSWORD
is an Oracle-defined client name that is used to represent the external key manager password as a secret in the software keystore.For example:
ADMINISTER KEY MANAGEMENT ADD SECRET 'external_key_manager_password' FOR CLIENT 'HSM_PASSWORD' TO LOCAL AUTO_LOGIN KEYSTORE software_keystore_location WITH BACKUP;
In this example:
software_keystore_location
is the location of the software keystore within theWALLET_ROOT
location that you just defined in Step 1.LOCAL
creates a local auto-login wallet file,cwallet.sso
, to hold the credentials for the HSM. This wallet is tied to the host on which it was created.For an Oracle Real Application Clusters environment, omit the
LOCAL
keyword, because each Oracle RAC node has a different host name, yet they all use the same external key manager. If you configure a local auto-login wallet for the Oracle RAC instance, then only the first Oracle RAC node, where thecwallet.sso
file was created, would be able to access the external key manager credentials. If you try to open the keystore from another node instead of from that first node, there would be a problem auto-openingcwallet.sso
, and so it would result in a failure to auto-open the auto-login external keystore. This restriction applies if you are using a shared location to hold thecwallet.sso
file for the Oracle RAC cluster, because usingLOCAL
only works if you have a separatecwallet.sso
file (containing the same credentials) on each node of the Oracle RAC environment.
At this stage, the next time that a TDE operation executes, the external key manager auto-login keystore opens automatically.
4.4 Storing Oracle GoldenGate Secrets in a Keystore
You can store Oracle GoldenGate secrets in Transparent Data Encryption keystores.
- About Storing Oracle GoldenGate Secrets in Keystores
You can use a keystore to store secret keys for tools and external clients such as Oracle GoldenGate. - Oracle GoldenGate Extract Classic Capture Mode TDE Requirements
Ensure that you meet the requirements for Oracle GoldenGate Extract to support Transparent Data Encryption capture. - Configuring Keystore Support for Oracle GoldenGate
You can configure Transparent Data Encryption keystore support for Oracle GoldenGate by using a shared secret for the keystore.
Parent topic: Managing the Keystore and the Master Encryption Key
4.4.1 About Storing Oracle GoldenGate Secrets in Keystores
You can use a keystore to store secret keys for tools and external clients such as Oracle GoldenGate.
The secret key must be a string adhering to Oracle identifier rules. You can add, update, or delete a client secret in an existing keystore. This section describes how to capture Transparent Data Encryption encrypted data in the Oracle GoldenGate Extract (Extract) process using classic capture mode.
TDE support when Extract is in classic capture mode requires the exchange of the following keys:
-
TDE support for Oracle GoldenGate in the classic capture mode of the Extract process requires that an Oracle database and the Extract process share the secret to encrypt sensitive information being exchanged. The shared secret is stored securely in the Oracle database and Oracle GoldenGate domains. The shared secret is stored in the software keystore or the external keystore as the database secret.
-
The decryption key is a password known as the shared secret that is stored securely in the Oracle database and Oracle GoldenGate domains. Only a party that has possession of the shared secret can decrypt the table and redo log keys.
After you configure the shared secret, Oracle GoldenGate Extract uses the shared secret to decrypt the data. Oracle GoldenGate Extract does not handle the TDE master encryption key itself, nor is it aware of the keystore password. The TDE master encryption key and password remain within the Oracle database configuration.
Oracle GoldenGate Extract only writes the decrypted data to the Oracle GoldenGate trail file, which Oracle GoldenGate persists during transit. You can protect this file using your site's operating system standard security protocols, as well as the Oracle GoldenGate AES encryption options. Oracle GoldenGate does not write the encrypted data to a discard file (specified with the DISCARDFILE
parameter). The word ENCRYPTED
will be written to any discard file that is in use.
Oracle GoldenGate does require that the keystore be open when processing encrypted data. There is no performance effect of Oracle GoldenGate feature on the TDE operations.
Parent topic: Storing Oracle GoldenGate Secrets in a Keystore
4.4.2 Oracle GoldenGate Extract Classic Capture Mode TDE Requirements
Ensure that you meet the requirements for Oracle GoldenGate Extract to support Transparent Data Encryption capture.
The requirements are as follows:
-
To maintain high security standards, ensure that the Oracle GoldenGate Extract process runs as part of the Oracle user (the user that runs the Oracle database). That way, the keys are protected in memory by the same privileges as the Oracle user.
-
Run the Oracle GoldenGate Extract process on the same computer as the Oracle database installation.
Parent topic: Storing Oracle GoldenGate Secrets in a Keystore
4.4.3 Configuring Keystore Support for Oracle GoldenGate
You can configure Transparent Data Encryption keystore support for Oracle GoldenGate by using a shared secret for the keystore.
- Step 1: Decide on a Shared Secret for the Keystore
A shared secret for a keystore is a password. - Step 2: Configure Oracle Database for TDE Support for Oracle GoldenGate
TheDBMS_INTERNAL_CLKM
PL/SQL package enables you to configure TDE support for Oracle GoldenGate. - Step 3: Store the TDE GoldenGate Shared Secret in the Keystore
TheADMINISTER KEY MANAGEMENT
statement can store a TDE GoldenGate shared secret in a keystore. - Step 4: Set the TDE Oracle GoldenGate Shared Secret in the Extract Process
The GoldenGate Software Command Interface (GGSCI) utility sets the TDE Oracle GoldenGate shared secret in the extract process.
Parent topic: Storing Oracle GoldenGate Secrets in a Keystore
4.4.3.1 Step 1: Decide on a Shared Secret for the Keystore
A shared secret for a keystore is a password.
-
Decide on a shared secret that meets or exceeds Oracle Database password standards.
Do not share this password with any user other than trusted administrators who are responsible for configuring Transparent Data Encryption to work with Oracle GoldenGate Extract.
Related Topics
Parent topic: Configuring Keystore Support for Oracle GoldenGate
4.4.3.2 Step 2: Configure Oracle Database for TDE Support for Oracle GoldenGate
The DBMS_INTERNAL_CLKM
PL/SQL package enables you to configure TDE support for Oracle GoldenGate.
-
Log in to the database instance as user
SYS
with theSYSDBA
administrative privilege.For example
sqlplus sys as sysdba Enter password: password Connected.
-
Load the Oracle Database-supplied
DBMS_INTERNAL_CLKM
PL/SQL package.For example:
@?/app/oracle/product/12.2/rdbms/admin/prvtclkm.plb
The
prvtclkm.plb
file also enables Oracle GoldenGate to extract encrypted data from an Oracle database. -
Grant the
EXECUTE
privilege on theDBMS_INTERNAL_CLKM
PL/SQL package to the Oracle GoldenGate Extract database user.For example:
GRANT EXECUTE ON DBMS_INTERNAL_CLKM TO psmith;
This procedure enables the Oracle database and Oracle GoldenGate Extract to exchange information.
-
Exit SQL*Plus.
Parent topic: Configuring Keystore Support for Oracle GoldenGate
4.4.3.3 Step 3: Store the TDE GoldenGate Shared Secret in the Keystore
The ADMINISTER KEY MANAGEMENT
statement can store a TDE GoldenGate shared secret in a keystore.
-
Set the Oracle GoldenGate-TDE key in the keystore by using the following syntax.
ADMINISTER KEY MANAGEMENT ADD|UPDATE|DELETE SECRET 'secret' FOR CLIENT 'secret_identifier' [USING TAG 'tag'] IDENTIFIED BY keystore_password [WITH BACKUP [USING 'backup_identifier']];
In this specification:
-
secret
is the client secret key to be stored, updated, or deleted. Enclose this setting in single quotation marks (' '
). -
secret_identifier
is an alphanumeric string used to identify the secret key.secret_identifier
does not have a default value. Enclose this setting in single quotation marks (' '
). -
tag
is an optional, user-defined description for the secret key to be stored.tag
can be used with theADD
andUPDATE
operations. Enclose this setting in single quotation marks (' '
). This tag appears in theSECRET_TAG
column of theV$CLIENT_SECRETS
view. Creating Custom TDE Master Encryption Key Attributes for Reports -
keystore_password
is the password for the keystore that is configured. -
WITH BACKUP
is required in case the keystore was not backed up before theADD
,UPDATE
orDELETE
operation.backup_identifier
is an optional user-defined description for the backup. Enclosebackup_identifier
in single quotation marks (' '
).
The following example adds a secret key to the keystore and creates a backup in the same directory as the keystore:
ADMINISTER KEY MANAGEMENT ADD SECRET 'some_secret' FOR CLIENT 'ORACLE_GG' USING TAG 'GoldenGate Secret' IDENTIFIED BY password WITH BACKUP USING 'GG backup';
-
-
Verify the entry that you just created.
For example:
SELECT CLIENT, SECRET_TAG FROM V$CLIENT_SECRETS WHERE CLIENT = 'ORACLEGG'; CLIENT SECRET_TAG -------- ------------------------------------------ ORACLEGG some_secret
-
Switch the log files.
CONNECT / AS SYSDBA ALTER SYSTEM SWITCH LOGFILE;
See Also:
-
Creating Custom TDE Master Encryption Key Attributes for Reports for more information about tags
-
Oracle Database Administrator’s Guide for more information about switching log files
-
How Transparent Data Encryption Works with Oracle Real Application Clusters if you are having problems using this procedure in an Oracle Real Application Clusters environment
Parent topic: Configuring Keystore Support for Oracle GoldenGate
4.4.3.4 Step 4: Set the TDE Oracle GoldenGate Shared Secret in the Extract Process
The GoldenGate Software Command Interface (GGSCI) utility sets the TDE Oracle GoldenGate shared secret in the extract process.
-
Start the GGSCI utility.
For example:
ggsci
-
In the GGSCI utility, run the
ENCRYPT PASSWORD
command to encrypt the shared secret within the Oracle GoldenGate Extract parameter file.ENCRYPT PASSWORD shared_secret algorithm ENCRYPTKEY keyname
In this specification:
-
shared_secret
is the clear-text shared secret that you created when you decided on a shared secret for the keystore. This setting is case sensitive. -
algorithm
is one of the following values to specify AES encryption:-
AES128
-
AES192
-
AES256
-
-
keyname
is the logical name of the encryption key in theENCKEYS
lookup file. Oracle GoldenGate uses this name to look up the actual key in theENCKEYS
file.
For example:
ENCRYPT PASSWORD password AES256 ENCRYPTKEY mykey1
-
-
In the Oracle GoldenGate Extract parameter file, set the
DBOPTIONS
parameter with theDECRYPTPASSWORD
option.As input, supply the encrypted shared secret and the Oracle GoldenGate-generated or user-defined decryption key.
DBOPTIONS DECRYPTPASSWORD shared_secret algorithm ENCRYPTKEY keyname
In this specification:
-
shared_secret
is the clear-text shared secret that you created when you decided on a shared secret for the keystore. This setting is case sensitive. -
algorithm
is one of the following values to specify AES encryption:-
AES128
-
AES192
-
AES256
-
-
keyname
is the logical name of the encryption key in theENCKEYS
lookup file.For example:
DBOPTIONS DECRYPTPASSWORD AACAAAAAAAAAAAIALCKDZIRHOJBHOJUH AES256 ENCRYPTKEY mykey1
-
Related Topics
Parent topic: Configuring Keystore Support for Oracle GoldenGate