Transparent Data Encryption (TDE) Management

This section encompasses the management of Transparent Data Encryption (TDE) for securing database data. It includes commands for handling encryption keys and keystores, such as dbaascli tde addSecondaryHsmKey to add secondary HSM keys, dbaascli tde rotateMasterKey to rotate the master key, and dbaascli tde encryptTablespacesInPDB to encrypt tablespaces within a pluggable database. You can also convert between FILE and HSM-based TDE (dbaascli tde fileToHsm, dbaascli tde hsmToFile), manage key versions, and retrieve key details with various commands. These tools ensure effective encryption management and data security.

dbaascli tde addSecondaryHsmKey

To add a secondary HSM (KMS) key to the existing HSM (KMS) configuration, use the dbaascli tde addSecondaryHsmKey command.

Prerequisites:

Run the command as the root user.

Syntax:

dbaascli tde addSecondaryHsmKey --dbname <value> --secondaryKmsKeyOCID <value>
[--executePrereqs]

Parameters:

Parameter Description
--secondaryKmsKeyOCID specifies the secondary KMS key to add to the existing HSM (KMS) configuration
--dbname specifies the name of the database
--executePrereqs execute the prerequisites checks and report the results.

Frequently Asked Questions:

Q: What does the dbaascli tde addSecondaryHsmKey command do?

A: The dbaascli tde addSecondaryHsmKey command adds a secondary HSM (KMS) key to the existing HSM (KMS) configuration for an Oracle Base Database Cloud@Customer database.

Q: Who should run the dbaascli tde addSecondaryHsmKey command?

A: The command must be run as the root user.

Q: On which machine should I run the dbaascli tde addSecondaryHsmKey command?

A: You need to connect to an Oracle Base Database Cloud@Customer virtual machine using SSH to run this command.

Q: Where can I find more details about connecting to a virtual machine to run this command?

A: You can refer to the guide Connecting to a Virtual Machine with SSH for instructions on how to connect.

Q: What does the –secondaryKmsKeyOCID option specify?

A: The --secondaryKmsKeyOCID option specifies the OCID (Oracle Cloud Identifier) of the secondary KMS key to be added to the existing HSM (KMS) configuration.

Q: What does the –dbname option do?

A: The --dbname option allows you to specify the name of the database for which the secondary KMS key should be added. It is optional.

Q: What does the –precheckOnly option do?

A: The --precheckOnly option, when set to yes, runs a precheck of the operation without making any actual changes. The valid values are yes or no.

Q: Can I run the precheck only without making changes?

A: Yes, you can use the --precheckOnly yes option to run just the precheck without making changes.

Q: Can you give an example of how to run this command to add a secondary HSM key?

A: Here’s an example:

dbaascli tde addSecondaryHsmKey --secondaryKmsKeyOCID ocid1.kms.key.oc1..example

Q: How do I run the command for a specific database?

A: You can specify the database name like this:

dbaascli tde addSecondaryHsmKey --secondaryKmsKeyOCID ocid1.kms.key.oc1..example --dbname mydatabase

Q: How do I run the command with a precheck only?

A: To run the precheck, use the following syntax:

dbaascli tde addSecondaryHsmKey --secondaryKmsKeyOCID ocid1.kms.key.oc1..example --precheckOnly yes

Q: What should I do if the command fails?

A: Ensure that you are running the command as the root user and that you have connected to the correct Oracle Base Database Cloud@Customer virtual machine. Also, verify the OCID of the KMS key and check if the required permissions are granted.

Q: How can I check if I have the correct OCID for the secondary KMS key?

A: You can retrieve the OCID of the KMS key from the Oracle Cloud Infrastructure console, under the Key Management Service (KMS) section.

Q: What permissions are required to add a secondary KMS key?

A: You need appropriate permissions in Oracle Cloud Infrastructure for KMS operations, including the ability to manage KMS keys for the relevant compartment.

Q: Can I use the dbaascli tde addSecondaryHsmKey command without specifying the –dbname option?

A: Yes, the --dbname option is optional. If omitted, the command applies to all databases using the existing HSM (KMS) configuration.

Q: What happens if I add a secondary KMS key?

A: The secondary KMS key will be added to the existing configuration, providing an additional layer of encryption key management redundancy.

Q: Can I remove a secondary KMS key once it is added?

A: No, once a secondary KMS key is added, it cannot be removed. You can only rotate or update keys in the future.

Example: dbaascli tde addSecondaryHsmKey

dbaascli tde addSecondaryHsmKey --dbname dbname --secondaryKmsKeyOCID ocid1.key.oc1.eu-frankfurt-1.bjqnwclvaafak.abtheljsgfxa2xe5prvlzdxtygoiqpm2pu2afgta54krxwllk5uxainvvxza
dbaascli tde addSecondaryHsmKey --dbname dbname --secondaryKmsKeyOCID ocid1.key.oc1.eu-frankfurt-1.bjqnwclvaafak.abtheljsgfxa2xe5prvlzdxtygoiqpm2pu2afgta54krxwllk5uxainvvxza --precheckOnly yes

dbaascli tde changePassword

To change TDE keystore password as well as DB wallet password for the alias tde_ks_passwd, use the dbaascli tde changePassword command.

Prerequisites:

Run the command as the root user.

Syntax:

dbaascli tde changePassword [--dbname <value>]
  {            [--prepareStandbyBlob <value> [--blobLocation <value>]]
               | [--standbyBlobFromPrimary <value>]
  }
  [--resume [--sessionID <value>]]

Parameters:

Parameter Description
--dbname specifies the name of the database
--prepareStandbyBlob specify true to generate a blob file containing the artifacts needed to perform the operation in a DG environment.
--blobLocation custom path where the standby blob file will be generated in a DG environment.
--standbyBlobFromPrimary specify the location of the standby blob file which is prepared from the primary database. This is required only for standby operations.
--resume to resume the previous execution
--sessionID to resume a specific session id.

Frequently Asked Questions:

Q: What does the dbaascli tde changePassword command do?

A: The dbaascli tde changePassword command changes the Transparent Data Encryption (TDE) keystore password as well as the database wallet password for the alias tde_ks_passwd.

Q: Who should run the dbaascli tde changePassword command?

A: The command must be run as the root user.

Q: When should I use the dbaascli tde changePassword command?

A: Use this command when you need to change the TDE keystore password or the DB wallet password for an Oracle Base Database Cloud@Customer database.

Q: What does the –dbname option do?

A: The --dbname option specifies the name of the database for which you want to change the TDE keystore password.

Q: What does the –pdbName option do?

A: The --pdbName option specifies the name of the pluggable database (PDB) for which the TDE keystore password needs to be changed. This option is used for multitenant databases.

Q: Can you give an example of how to run this command for a specific database?

A: Here’s an example to change the TDE keystore password for a specific database:

dbaascli tde changePassword --dbname mydatabase

Q: How do I run the command for a specific PDB within a multitenant database?

A: You can specify the PDB name using this syntax:

dbaascli tde changePassword --dbname mydatabase --pdbName mypdb

Q: What are the prerequisites for running the dbaascli tde changePassword command?

A: You must run the command as the root user and have access to the Oracle Base Database Cloud@Customer virtual machine where the database is running.

Q: Do I need to stop the database to change the TDE keystore password?

A: No, the database does not need to be stopped to change the TDE keystore password.

Q: What should I do if the command fails?

A: Ensure that you are running the command as the root user and that the database name (--dbname) and PDB name (--pdbName, if applicable) are correct.

Q: What if I get an “invalid password” error when changing the TDE keystore password?

A: Make sure the new password meets your system’s password complexity requirements, and that you are entering the correct old password if prompted.

Q: How do I check if the TDE keystore password has been changed successfully?

A: You can check the database logs or use the Oracle AI Database Vault and Key Management views to verify that the TDE keystore password change was successful.

Q: Can I change the TDE keystore password for a multitenant database and all PDBs at once?

A: No, the dbaascli tde changePassword command needs to be run for each PDB individually if you need to change the password for multiple PDBs.

Q: What happens if I forget the new TDE keystore password?

A: If the new password is forgotten, you may need to restore the keystore from a backup or follow Oracle’s recovery process to reset it, depending on your setup.

Q: Can I automate the process of changing the TDE keystore password?

A: While the dbaascli tde changePassword command itself is not designed for automation, you can script it as part of your regular database maintenance procedures if needed.

Q: How often should I change the TDE keystore password?

A: Oracle recommends periodically changing your TDE keystore password based on your organization’s security policies. Best practices typically involve rotating encryption keys and keystore passwords regularly.

To change the TDE password in a non-Data Guard environment

dbaascli tde changepassword --dbname
      <dbname>

To change the TDE password in a Data Guard environment

  1. Change the TDE password in primary database.

    dbaascli tde changepassword --dbname
      <dbname> --prepareStandbyBlob true --blobLocation
      <Location where blob file has to be generated>

  2. Copy the created standby blob to standby database environment.

  3. Change the TDE password in standby database

    dbaascli tde changepassword --dbname
     <dbname> --standbyBlobFromPrimary <Location of blob generated from
    primary>

dbaascli tde enableWalletRoot

To enable wallet_root spfile parameter for the existing database, use the dbaascli tde enableWalletRoot command.

Prerequisites:

Run the command as the root user.

Syntax:

dbaascli tde enableWalletRoot --dbname <value>
[--dbRestart <value>]
[--executePrereqs]
[--resume [--sessionID <value>]]

Parameters:

Parameter Description
--dbname specifies the name of the Oracle AI Database.
--dbrestart specifies the database restart option. Valid values are: rolling or full. Default value: rolling. If you do not pass the dbrestart argument, then the database restarts in a rolling manner.
--precheckOnly runs only the precheck for this operation. Valid values are: yes or no
--resume to resume the previous execution
--sessionID to resume a specific session id.

Frequently Asked Questions:

Q: What does the dbaascli tde enableWalletRoot command do?

A: The dbaascli tde enableWalletRoot command enables the wallet_root parameter in the spfile for an existing Oracle AI Database on Oracle Base Database Cloud@Customer.

Q: Who should run the dbaascli tde enableWalletRoot command?

A: The command must be run as the root user.

Q: On which machine should I run the dbaascli tde enableWalletRoot command?

A: You must connect to an Oracle Base Database Cloud@Customer virtual machine using SSH to run this command.

Q: Where can I find instructions to connect to the virtual machine?

A: You can refer to the guide Connecting to a Virtual Machine with SSH for instructions on connecting.

Q: What does the –dbRestart option do?

A: The --dbRestart option specifies how the database should be restarted after enabling wallet_root. The valid values are:

Q: What does the –dbname option do?

A: The --dbname option allows you to specify the name of the Oracle AI Database for which the wallet_root parameter should be enabled.

Q: What does the –precheckOnly option do?

A: The --precheckOnly option runs a precheck of the operation without making actual changes. The valid values are yes or no.

Q: What happens if I do not specify the –dbRestart option?

A: If you do not specify the --dbRestart option, the database will restart in a rolling manner by default.

Q: Can you give an example of how to enable wallet_root for a specific database?

A: Here’s an example to enable wallet_root for a database named mydatabase:

dbaascli tde enableWalletRoot --dbname mydatabase

Q: How do I enable wallet_root and specify a full database restart?

A: You can enable wallet_root with a full database restart using the following command:

dbaascli tde enableWalletRoot --dbname mydatabase --dbRestart full

Q: How do I run the command with a precheck only?

A: To perform a precheck without making changes, use the following syntax:

dbaascli tde enableWalletRoot --dbname mydatabase --precheckOnly yes

Q: What are the prerequisites for running the dbaascli tde enableWalletRoot command?

A: You must run the command as the root user and be connected to the correct Oracle Base Database Cloud@Customer virtual machine.

Q: Do I need to restart the database to enable wallet_root?

A: Yes, the database will need to restart either in a rolling manner (default) or fully, depending on the option you choose.

Q: What should I do if the command fails?

A: Ensure that you are running the command as the root user, and verify that the database name (--dbname) is correct. Check for any precheck errors if you are running with --precheckOnly.

Q: What if the database fails to restart after running the command?

A: Verify that the correct restart option was used (rolling or full) and check the database logs for any errors. You may need to manually restart the database if the automatic restart fails.

Q: How can I check if wallet_root was enabled successfully?

A: You can verify the change by checking the database’s spfile or using Oracle SQL queries to confirm that the wallet_root parameter is enabled.

Q: Can I enable wallet_root without restarting the database?

A: No, the database needs to restart for the change to take effect. You can choose between a rolling restart or a full restart.

Q: What is the difference between a rolling and full database restart?

A: A rolling restart restarts the database one instance at a time, allowing the database to remain partially available during the operation. A full restart shuts down and restarts the entire database, causing a complete downtime.

Q: Can I run this command for multiple databases simultaneously?

A: You need to run the dbaascli tde enableWalletRoot command separately for each database you wish to enable wallet_root on.

Q: How does enabling wallet_root affect the existing TDE keystore configuration?

A: Enabling wallet_root updates the TDE keystore location to the new wallet root directory, making it easier to manage multiple keystores and wallets in Oracle AI Databases.

Example: dbaascli tde enableWalletRoot

dbaascli tde enableWalletRoot --dbname db name --dbrestart rolling|full
dbaascli tde enableWalletRoot --dbname orcl
dbaascli tde enableWalletRoot --dbname orcl--dbrestart full

dbaascli tde encryptTablespacesInPDB

To encrypt all the tablespaces in the specified PDB, use the dbaascli tde encryptTablespacesInPDB command.

Prerequisites:

Run the command as the root user.

Syntax:

dbaascli tde encryptTablespacesInPDB --dbname <value> --pdbName <value>
[--executePrereqs]

Parameters:

Parameter Description
--pdbName specifies the name of the PDB to encrypt all the tablespaces.
--dbname specifies the name of the Oracle AI Database.
--executePrereqs execute the prerequisites checks and report the results.

Frequently Asked Questions:

Q: What does the dbaascli tde encryptTablespacesInPDB command do?

A: The dbaascli tde encryptTablespacesInPDB command encrypts all the tablespaces in the specified pluggable database (PDB) for an Oracle AI Database on Oracle Base Database Cloud@Customer.

Q: Who should run the dbaascli tde encryptTablespacesInPDB command?

A: The command must be run as the root user.

Q: On which machine should I run the dbaascli tde encryptTablespacesInPDB command?

A: You need to connect to an Oracle Base Database Cloud@Customer virtual machine using SSH to run this command.

Q: Where can I find instructions for connecting to the virtual machine?

A: Refer to the guide Connecting to a Virtual Machine with SSH for connection instructions.

Q: What does the –pdbName option specify?

A: The --pdbName option specifies the name of the pluggable database (PDB) whose tablespaces need to be encrypted.

Q: What does the –dbname option do?

A: The --dbname option allows you to specify the name of the Oracle AI Database to which the PDB belongs.

Q: What does the –precheckOnly option do?

A: The --precheckOnly option runs a precheck of the encryption operation without making any actual changes. Valid values are yes or no.

Q: What does the –useSysdbaCredential option do?

A: The --useSysdbaCredential option specifies whether SYSDBA credentials should be used for the operation. Valid values are true or false.

Q: Can you give an example of how to encrypt tablespaces in a specific PDB?

A: Here’s an example to encrypt all tablespaces in a PDB named mypdb:

dbaascli tde encryptTablespacesInPDB --pdbName mypdb

Q: How do I encrypt tablespaces in a specific PDB within a database?

A: Use the following command to specify both the PDB and the database:

dbaascli tde encryptTablespacesInPDB --pdbName mypdb --dbname mydatabase

Q: How do I run a precheck without performing the encryption?

A: You can run a precheck only using this syntax:

dbaascli tde encryptTablespacesInPDB --pdbName mypdb --precheckOnly yes

Q: How do I use SYSDBA credentials to encrypt the tablespaces?

A: You can use the SYSDBA credentials by adding the --useSysdbaCredential true option:

dbaascli tde encryptTablespacesInPDB --pdbName mypdb --useSysdbaCredential true

Q: What are the prerequisites for running the dbaascli tde encryptTablespacesInPDB command?

A: You must run the command as the root user and have access to the Oracle Base Database Cloud@Customer virtual machine.

Q: Do I need to restart the database to encrypt the tablespaces?

A: No, the command does not require a database restart. The encryption is performed while the database is online.

Q: Do I need SYSDBA credentials to encrypt tablespaces?

A: You may need SYSDBA credentials for this operation if specified using the --useSysdbaCredential option.

Q: What should I do if the command fails?

A: Ensure you are running the command as the root user, and verify that the PDB name (--pdbName) and database name (--dbname) are correct. You can also run the command with --precheckOnly yes to check for issues before running the full encryption.

Q: What should I do if encryption of the tablespaces fails?

A: Check the database logs and ensure that you have the necessary privileges and resources to perform the encryption. You may also need to verify that there is enough space to handle the encryption process.

Q: How can I check if the tablespaces in a PDB are encrypted?

A: You can query the database views related to encryption, such as V$ENCRYPTED_TABLESPACES, to verify if the tablespaces have been successfully encrypted.

Q: How do I verify if the precheck was successful?

A: If you ran the command with --precheckOnly yes, you can check the output for any warnings or errors indicating potential issues with the encryption process.

Q: Can I encrypt the tablespaces for multiple PDBs simultaneously?

A: No, you need to run the dbaascli tde encryptTablespacesInPDB command separately for each PDB.

Q: Can I partially encrypt some tablespaces in a PDB?

A: No, this command encrypts all tablespaces within the specified PDB. For partial encryption, you would need to use different database management commands.

Q: Does encrypting tablespaces impact database performance?

A: Encrypting tablespaces can have a temporary performance impact during the encryption process. However, the impact should be minimal once the encryption is complete.

Q: Can I undo the encryption of tablespaces?

A: No, once the tablespaces are encrypted, the encryption cannot be undone. You can only rotate or re-encrypt the keys as needed.

Q: What happens if the operation is interrupted during the encryption process?

A: If the operation is interrupted, you may need to rerun the command. The system will resume encryption from where it left off, and you can verify the status using database views.

Example: dbaascli tde encryptTablespacesInPDB

dbaascli tde encryptTablespacesInPDB --dbname dbname --pdbName pdb
dbaascli tde encryptTablespacesInPDB --dbname dbname --pdbName pdb --executePrereqs

dbaascli tde fileToHsm

To convert FILE based TDE to HSM (KMS/OKV) based TDE, use the dbaascli tde fileToHsm command.

Prerequisites:

Run the command as the root user.

Syntax:

dbaascli tde fileToHsm --kmsKeyOCID <value> --dbname <value>
[--skipPatchCheck <value>]
[--executePrereqs ]
[--primarySuc <value>]
{
    [--resume [--sessionID <value>]] | [--revert [--sessionID <value>]]
}
[--waitForCompletion <value>]

Parameters:

Parameter Description
--kmsKeyOCID specifies the KMS key OCID to use for TDE. This is applicable only if KMS is selected for TDE
--dbname specifies the name of the database
--skipPatchCheck skips validation check for required patches if the value passed for this argument is true. Valid values: true or false
--executePrereqs execute the prerequisites checks and report the results.
--primarySuc specify this property in the standby database of the Data Guard environment once the command is successfully run on the primary database
--resume specifies to resume the previous run
--sessionID specifies to resume a specific session ID
--revert specifies to rollback the previous run
--sessionID specifies to rollback a specific session ID
--waitForCompletion specify false to run the operation in background. Valid values: true or false.

Frequently Asked Questions:

Q: What is the purpose of the dbaascli tde fileToHsm command?

A: The dbaascli tde fileToHsm command is used to convert a FILE-based Transparent Data Encryption (TDE) to Hardware Security Module (HSM)-based TDE, such as KMS or OKV, in an Oracle AI Database Cloud Service environment.

Q: Who can run the dbaascli tde fileToHsm command?

A: The command must be run as the root user.

Q: What is the purpose of the –kmsKeyOCID parameter?

A: The --kmsKeyOCID parameter specifies the KMS key OCID that will be used for TDE encryption when transitioning from file-based to HSM-based TDE.

Q: What does the –dbname parameter do?

A: The --dbname parameter specifies the name of the database for which you are converting the TDE from file-based to HSM-based.

Q: Can I skip the patch validation check while converting TDE?

A: Yes, by using the --skipPatchCheck parameter with the value true, you can skip the validation check for required patches.

Q: What is the –executePrereqs parameter used for?

A: The --executePrereqs parameter allows you to run only the prechecks for the TDE conversion process without performing the actual conversion. Valid values are yes or no.

Q: What does the –primarySuc parameter do in a Data Guard setup?

A: The --primarySuc parameter is used in a Data Guard environment to indicate that the command has been successfully run on the primary database. It should be specified on the standby database after the primary conversion is complete.

Q: How do I resume a previous TDE conversion?

A: You can resume a previously incomplete TDE conversion by using the --resume parameter. Optionally, you can specify a specific session ID with --sessionID.

Q: How do I revert a TDE conversion?

A: To revert a previous TDE conversion, use the --revert parameter. You can also provide the specific session ID you want to revert using --sessionID.

Q: How do I specify a session ID when resuming or reverting a TDE conversion?

A: You can use the --sessionID parameter to specify the ID of the session you want to resume or revert. Example: --resume --sessionID <ID> or --revert --sessionID <ID>.

Q: What happens if I set –waitForCompletion to false?

A: If you set --waitForCompletion to false, the TDE conversion process will run in the background, and the command prompt will return immediately. If set to true, the command will wait for the process to finish before returning control to the user.

Q: What are the valid values for the –waitForCompletion parameter?

A: Valid values are true or false. Setting it to true makes the command wait until the process is complete; setting it to false runs the process in the background.

Q: Can I run dbaascli tde fileToHsm without converting the TDE immediately?

A: Yes, you can use the --executePrereqs yes parameter to perform only the prechecks for the conversion, without making any changes to the TDE.

Q: In a Data Guard environment, how do I handle the standby database after converting TDE on the primary?

A: After successfully running the conversion on the primary database, you need to specify --primarySuc when running the command on the standby database.

Q: What should I do if the TDE conversion process fails?

A: If the process fails, you can use the --resume parameter to try resuming from where it left off. If necessary, you can use the --revert parameter to roll back the changes made during the failed session.

Example: dbaascli tde fileToHsm –kmsKeyOCID

dbaascli tde fileToHSM --dbname dbname --kmsKeyOCID ocid1.key.oc1.eu-frankfurt-.bjqnwclvaafak.abtheljsgfxa2xe5prvlzdxtygoiqpm2pu2afgta54krxwllk5uxainvvxza
dbaascli tde fileToHSM --dbname dbname --kmsKeyOCID ocid1.key.oc1.eu-frankfurt-.bjqnwclvaafak.abtheljsgfxa2xe5prvlzdxtygoiqpm2pu2afgta54krxwllk5uxainvvxza --executePrereqs
dbaascli tde fileToHSM --dbname dbname --kmsKeyOCID ocid1.key.oc1.eu-frankfurt-.bjqnwclvaafak.abtheljsgfxa2xe5prvlzdxtygoiqpm2pu2afgta54krxwllk5uxainvvxza --resume

dbaascli tde getHsmKeys

To get TDE active key details, use the dbaascli tde getHsmKeys command.

Prerequisites:

Run the command as the root user.

Syntax:

dbaascli tde getHsmKeys
[--dbname]
[--infoFile]

Parameters:

Parameter Description
--dbname specifies the name of the database
--infoFile specifies the file path where the list of OCIDs will be saved. The output is in JSON format

Frequently Asked Questions:

Q: What does the dbaascli tde getHsmKeys command do?

A: The dbaascli tde getHsmKeys command retrieves details of active Transparent Data Encryption (TDE) keys from the Hardware Security Module (HSM) for a specified database.

Q: Who should run the dbaascli tde getHsmKeys command?

A: The command must be run as the root user.

Q: On which machine should I run the dbaascli tde getHsmKeys command?

A: You must connect to an Oracle Base Database Cloud@Customer virtual machine using SSH to run this command.

Q: Where can I find instructions for connecting to the virtual machine?

A: Refer to the guide Connecting to a Virtual Machine with SSH for instructions on connecting.

Q: What does the –dbname option do?

A: The --dbname option allows you to specify the name of the Oracle AI Database for which you want to retrieve TDE key details.

Q: What does the –infoFile option do?

A: The --infoFile option specifies the file path where the list of key OCIDs (Oracle Cloud Identifiers) will be saved. The output is in JSON format.

Q: Can you give an example of how to retrieve TDE key details for a specific database?

A: Here’s an example to get the TDE key details for a database named mydatabase:

dbaascli tde getHsmKeys --dbname mydatabase

Q: How do I save the TDE key details to a file?

A: You can specify a file path using the --infoFile option to save the output in JSON format:

dbaascli tde getHsmKeys --dbname mydatabase --infoFile /path/to/output.json

Q: What are the prerequisites for running the dbaascli tde getHsmKeys command?

A: You must run the command as the root user and be connected to the Oracle Base Database Cloud@Customer virtual machine.

Q: Do I need SYSDBA credentials to retrieve TDE key details?

A: No, SYSDBA credentials are not required to run the dbaascli tde getHsmKeys command.

Q: In what format is the TDE key information saved when using the –infoFile option?

A: The output is saved in JSON format.

Q: What information is included in the TDE key details?

A: The details include key OCIDs and other metadata about the active encryption keys stored in the HSM for the specified database.

Q: What should I do if the command fails to retrieve the key details?

A: Ensure that you are running the command as the root user and that the database name (--dbname) is correct. Check your connection to the Oracle Base Database Cloud@Customer virtual machine.

Q: How do I check if the output file was created successfully?

A: You can check the specified file path for the output JSON file. If the file is missing, verify that the file path is correct and that you have write permissions to the directory.

Q: What should I do if the output file is empty?

A: Ensure that the database specified contains active TDE keys and that the --dbname parameter is correct. You may also need to check if there are any errors in the database logs.

Q: Can I retrieve TDE key details for multiple databases at once?

A: No, you must run the dbaascli tde getHsmKeys command separately for each database.

Q: How can I use the output file from the –infoFile option in other operations?

A: Since the output is in JSON format, you can parse the file programmatically or use it as input for other database or encryption management tasks.

Q: Can I get historical TDE key details using this command?

A: No, the command only retrieves details about the currently active keys in the HSM.

Q: How do I verify that the keys retrieved are correct?

A: You can verify the keys by cross-referencing them with the Oracle Cloud Infrastructure (OCI) console or using database views related to encryption management.

Example: dbaascli tde getHsmKeys

dbaascli tde getHsmkeys --dbname dbname
dbaascli tde getHsmkeys --dbname dbname --infoFile infoFilePath

dbaascli tde getMkidForKeyVersionOCID

To get Master Key ID associated with the KMS key version OCID, use the dbaascli tde getMkidForKeyVersionOCID command.

Prerequisites:

Run the command as the root user.

Syntax:

dbaascli tde getMkidForKeyVersionOCID --kmsKeyVersionOCID <value>
[--dbname <value>]
[--waitForCompletion <value>]

Parameters:

Parameter Description
--kmsKeyVersionOCID specifies the KMS key version OCID to set
--dbname specifies the name of the database
--waitForCompletion specify false to run the operation in background. Valid values : true or false.

Frequently Asked Questions:

Q: What is the purpose of the dbaascli tde getMkidForKeyVersionOCID command?

A: The dbaascli tde getMkidForKeyVersionOCID command retrieves the Master Key ID (MKID) associated with a specific KMS key version OCID in Oracle AI Database Cloud Service environments.

Q: What are the prerequisites for running the dbaascli tde getMkidForKeyVersionOCID command?

A: You must:

Q: Who can run the dbaascli tde getMkidForKeyVersionOCID command?

A: Only the root user can run this command.

Q: What does the –kmsKeyVersionOCID parameter specify?

A: The --kmsKeyVersionOCID parameter specifies the KMS key version OCID for which you want to retrieve the associated Master Key ID (MKID).

Q: What does the –dbname parameter specify?

A: The --dbname parameter specifies the name of the database for which the KMS key version OCID is being queried.

Q: Is the –dbname parameter mandatory?

A: No, the --dbname parameter is optional. If you don’t specify a database name, the command will retrieve the MKID for the default database on the system.

Q: What should I do if I don’t know the KMS key version OCID?

A: You must retrieve the KMS key version OCID from your KMS management console or service provider before using this command. Without it, the command cannot retrieve the Master Key ID (MKID).

Q: Can I run this command on a non-Oracle Base Database Cloud@Customer environment?

A: No, this command is specifically for use in an Oracle Base Database Cloud@Customer environment, and you need to connect to a virtual machine using SSH to execute it.

Q: What happens if I run the command without specifying a database name using –dbname?

A: If the --dbname parameter is not provided, the command will attempt to retrieve the MKID for the default database configured on the system.

Q: What should I do if I encounter an error while retrieving the MKID?

A: Ensure that:

Q: How do I connect to the Oracle Base Database Cloud@Customer virtual machine?

A: You can connect to the virtual machine via SSH. Refer to the Oracle Base Database Cloud@Customer documentation for steps on how to securely connect.

Example: dbaascli tde getMkidForKeyVersionOCID

dbaascli tde getMkidForKeyVersionOCID --dbname dbname --kmsKeyVersionOCID ocid1.keyversion.oc1.eu-frankfurt-1.bjqnwclvaafak.bc4hmd3olgaaa.abtheljsyxtgn4vzi2bbpcej6a7abcwvylkd2lx56lu2s6iwnxwgigu23nha

dbaascli tde getPrimaryHsmKey

To get primary HSM (KMS) key from the existing HSM (KMS) configuration, use the dbaascli tde getPrimaryHsmKey command.

Prerequisites:

Run the command as the root user.

Syntax:

dbaascli tde getPrimaryHsmKey
[--dbname]

Parameters:

Parameter Description
--dbname specifies the name of the database

Frequently Asked Questions:

Q: What is the purpose of the dbaascli tde getPrimaryHsmKey command?

A: The dbaascli tde getPrimaryHsmKey command retrieves the primary Hardware Security Module (HSM) key from the existing HSM (KMS) configuration in an Oracle AI Database environment.

Q: What are the prerequisites for running the dbaascli tde getPrimaryHsmKey command?

A: You must:

Q: Who can execute the dbaascli tde getPrimaryHsmKey command?

A: Only the root user can execute this command.

Q: What does the –dbname parameter specify in this command?

A: The --dbname parameter specifies the name of the database for which you want to retrieve the primary HSM key.

Q: Is the –dbname parameter mandatory?

A: No, the --dbname parameter is optional. If not provided, the command will retrieve the primary HSM key for the default database on the system.

Q: What should I do if I don’t specify a database name with –dbname?

A: If the --dbname parameter is not specified, the command will attempt to retrieve the primary HSM key for the default database configured on the system.

Q: Can I run this command on a non-Oracle Base Database Cloud@Customer environment?

A: No, this command is designed specifically for use in an Oracle Base Database Cloud@Customer environment, and you must be connected to the virtual machine using SSH to run it.

Q: How do I connect to the Oracle Base Database Cloud@Customer virtual machine to run the command?

A: You can connect to the virtual machine via SSH. Refer to the Oracle Base Database Cloud@Customer documentation for instructions on how to securely connect.

Q: What should I check if I encounter an error while retrieving the primary HSM key?

A: If you encounter an error, ensure that:

Q: Do I need to stop the database to run the dbaascli tde getPrimaryHsmKey command?

A: No, the database does not need to be stopped to run this command. You can execute it while the database is running.

Q: What is the purpose of retrieving the primary HSM key?

A: Retrieving the primary HSM key allows you to identify the current HSM key that is being used for encryption in the database’s existing HSM (KMS) configuration.

Example: dbaascli tde getPrimaryHsmKey

dbaascli tde getPrimaryHsmKey --dbname dbname

dbaascli tde hsmToFile

To convert HSM (KMS/OKV) based TDE to FILE based TDE, use the dbaascli tde hsmToFile command.

Run the command as the root user.

Syntax:

dbaascli tde hsmToFile
[--dbname <value>]
{
    [--prepareStandbyBlob <value> [--blobLocation <value>]
   | [--standbyBlobFromPrimary <value>]
}
]
[--skipPatchCheck <value>]
[--executePrereqs ]
[--primarySuc <value>]
{
     [--resume [--sessionID <value>]] |
     [--revert [--sessionID <value>]]
}
[--waitForCompletion <value>]

Parameters:

Parameter Description
--dbname specifies the name of the database
--prepareStandbyBlob specify true to generate a blob file containing the artifacts needed to perform the operation in a DG environment.
--blobLocation custom directory location where the standby blob file will be generated in a DG environment.
--standbyBlobFromPrimary specify the location of the standby blob file which is prepared from the primary database. This is required only for standby operations. ]
--skipPatchCheck skips validation check for required patches if the value passed for this argument is true. Valid values: true or false
--executePrereqs execute the prerequisites checks and report the results.
--primarySuc specify this property in the standby database of the Data Guard environment once the command is successfully run on the primary database
--resume resumes the previous run
--sessionID specifies to resume a specific session ID
--revert specifies to roll back the previous run
--sessionID specifies to rollback a specific session ID
--waitForCompletion specifies false to run the operation in background. Valid values: true or false

Frequently Asked Questions:

Q: What is the purpose of the dbaascli tde hsmToFile command?

A: The dbaascli tde hsmToFile command is used to convert a Hardware Security Module (HSM)-based Transparent Data Encryption (TDE) to a file-based TDE in Oracle AI Database Cloud Service environments.

Q: What are the prerequisites for running the dbaascli tde hsmToFile command?

A: You must:

Q: What does the –dbname parameter specify?

A: The --dbname parameter specifies the name of the database for which you are converting TDE from HSM-based to file-based.

Q: When is the –primaryDBWalletTar parameter required?

A: The --primaryDBWalletTar parameter is required only when performing the hsmToFile conversion on a standby database. It specifies the tar file of the primary database’s wallet.

Q: What is the purpose of the –skipPatchCheck parameter?

A: The --skipPatchCheck parameter allows you to skip the validation check for required patches. Set this to true to skip the check or false to enforce it.

Q: How do I run only prechecks for the conversion process without performing the actual conversion?

A: You can use the --executePrereqs parameter and set it to yes to run only the prechecks. Set it to no to perform the full conversion.

Q: What does the –primarySuc parameter do in a Data Guard environment?

A: The --primarySuc parameter is used in a Data Guard setup to indicate that the conversion has successfully run on the primary database. It should be used when running the conversion on the standby database.

Q: How can I resume a previous hsmToFile conversion?

A: You can resume a previous conversion by using the --resume parameter. Optionally, you can specify the session ID of the previous run with --sessionID.

Q: What is the purpose of the –revert parameter?

A: The --revert parameter is used to roll back a previously initiated conversion process in case of failure or if you need to undo the operation.

Q: What happens if I set –waitForCompletion to false?

A: If you set --waitForCompletion to false, the operation will run in the background, allowing you to continue other tasks. If set to true, the command will wait for the process to complete before returning control to the user.

Q: What should I do if I need to convert the TDE in a standby database in a Data Guard setup?

A: In a Data Guard setup, after converting TDE on the primary database, you must run the command on the standby database using the --primaryDBWalletTar parameter, specifying the wallet tar file from the primary database, and include --primarySuc.

Q: What should I do if I want to skip checking for required patches during the conversion?

A: You can skip the patch check by using the --skipPatchCheck parameter and setting it to true.

Q: How do I check if the system is ready for the hsmToFile conversion without making changes?

A: You can perform only the prechecks by using the --executePrereqs parameter and setting it to yes.

Q: What should I do if the conversion process is interrupted?

A: You can use the --resume parameter to restart the process from where it left off. Optionally, you can specify a particular session ID with --sessionID.

Q: What should I do if the conversion process fails?

A: If the conversion fails, you can roll back the process using the --revert parameter. Additionally, review any error messages and check system logs for more details.

Q: Can I run the dbaascli tde hsmToFile command on a non-Base Database environment?

A: This command is designed for use in Oracle Base Database Cloud@Customer environments. If you are not using Base Database, ensure that you are in a supported environment for the command to work properly.

Example: dbaascli tde hsmToFile

dbaascli tde hsmToFile --dbname dbname
dbaascli tde hsmToFile --dbname dbname --executePrereqs
dbaascli tde hsmToFile --dbname dbname --resume

dbaascli tde listKeys

To list TDE master keys, use the dbaascli tde listKeys command.

Prerequisites:

Run the command as the root user.

Syntax:

dbaascli tde listKeys
[--dbname <value>]
[--infoFilePath <value>]

Parameters:

Parameter Description
--dbname specifies the name of the database
--infoFilePath specify the absolute path of the file where the results will be saved.

Frequently Asked Questions:

Q: What is the purpose of the dbaascli tde listKeys command?

A: The dbaascli tde listKeys command is used to list all the Transparent Data Encryption (TDE) master keys for a specified database in an Oracle AI Database environment.

Q: What are the prerequisites for running the dbaascli tde listKeys command?

A: You must:

Q: What does the –file parameter do in the dbaascli tde listKeys command?

A: The --file parameter specifies the file path where the list of TDE master keys should be saved. If this parameter is not provided, the results will be displayed directly in the terminal.

Q: What does the –dbname parameter specify?

A: The --dbname parameter specifies the name of the database for which you want to list the TDE master keys.

Q: Is the –file parameter mandatory?

A: No, the --file parameter is optional. If not provided, the list of TDE keys will be shown in the terminal output instead of being saved to a file.

Q: Is the –dbname parameter mandatory?

A: No, the --dbname parameter is optional. If not specified, the command will list the TDE master keys for the default database configured on the system.

Q: What should I do if I want to save the list of keys to a file?

A: You should provide the --file parameter along with the desired file path. For example:

dbaascli tde listKeys --file /path/to/output.txt

Q: What happens if I don’t provide a database name with –dbname?

A: If the --dbname parameter is not provided, the command will list the TDE master keys for the default database on the system.

Q: Can I use this command in environments other than Oracle Base Database Cloud@Customer?

A: This command is designed specifically for Oracle Base Database Cloud@Customer environments. Ensure you are connected to the appropriate virtual machine to run it.

Q: What should I do if the command fails to list keys?

A: Ensure that:

Q: Can I run the dbaascli tde listKeys command while the database is running?

A: Yes, the command can be executed while the database is running. It simply lists the TDE master keys and does not alter the state of the database.

Q: Do I need special permissions to run this command?

A: You must run this command as the root user. Without root permissions, you will not be able to execute the command.

Q: What is the purpose of listing TDE master keys?

A: Listing TDE master keys allows you to review the encryption keys being used for protecting your database’s data. It is essential for monitoring and managing encryption settings.

Q: How do I connect to the Oracle Base Database Cloud@Customer virtual machine to run the command?

A: You can connect to the virtual machine using SSH. Refer to the Oracle Base Database Cloud@Customer documentation for instructions on how to establish a secure connection.

Example: dbaascli tde listKeys

dbaascli tde listKeys --dbname dbname
dbaascli tde listKeys --dbname dbname --infoFilePath infoFilePath

dbaascli tde removeSecondaryHsmKey

To remove secondary HSM (KMS) key from the existing HSM (KMS) configuration, use the dbaascli tde removeSecondaryHsmKey command.

Prerequisites:

Run the command as the root user.

Syntax:

dbaascli tde removeSecondaryHsmKey --dbname <value>
[--confirmDeletion]
[--secondaryKmsKeyOCID]
[--executePrereqs]

Parameters:

Parameter Description
--dbname specifies the name of the database
--confirmDeletion if not specified the user will be prompted while deleting all existing HSM(KMS) keys.
--secondaryKmsKeyOCID secondary KMS key to be removed from existing HSM(KMS) configuration. If not specified all secondary KMS keys will be removed.
--executePrereqs execute the prerequisites checks and report the results.

Frequently Asked Questions:

Q: What is the purpose of the dbaascli tde removeSecondaryHsmKey command?

A: The dbaascli tde removeSecondaryHsmKey command is used to remove a secondary Hardware Security Module (HSM) key from the existing HSM (KMS) configuration in an Oracle AI Database environment.

Q: What are the prerequisites for running the dbaascli tde removeSecondaryHsmKey command?

A: You must:

Q: What does the –force parameter do in the dbaascli tde removeSecondaryHsmKey command?

A: The --force parameter allows the removal of the secondary HSM key without prompting the user for confirmation. If not specified, the command will prompt the user before deleting any keys.

Q: What does the –secondaryKmsKeyOCID parameter specify?

A: The --secondaryKmsKeyOCID parameter specifies the OCID (Oracle Cloud Identifier) of the secondary KMS key you want to remove from the existing HSM configuration.

Q: What does the –dbname parameter do?

A: The --dbname parameter specifies the name of the database for which the secondary HSM key is being removed.

Q: What is the purpose of the –precheckOnly parameter?

A: The --precheckOnly parameter, if set to yes, will only run the prechecks to validate the readiness for the removal operation without actually removing the secondary HSM key. If set to no, the full removal operation is performed.

Q: Is the –force parameter mandatory?

A: No, the --force parameter is optional. If it’s not specified, the system will prompt the user for confirmation before proceeding with the key removal.

Q: Is the –secondaryKmsKeyOCID parameter mandatory?

A: Yes, you must provide the --secondaryKmsKeyOCID to identify the specific secondary HSM key that you want to remove from the configuration.

Q: Is the –dbname parameter mandatory?

A: No, the --dbname parameter is optional. If not specified, the command will attempt to remove the secondary HSM key from the default database on the system.

Q: What should I do if I want to remove the secondary HSM key without any user prompts?

A: You should use the --force parameter to bypass the confirmation prompt and remove the secondary HSM key directly:

dbaascli tde removeSecondaryHsmKey --force --secondaryKmsKeyOCID <value>

Q: How can I test whether the system is ready to remove the secondary HSM key without actually removing it?

A: You can use the --precheckOnly parameter set to yes to perform a precheck:

dbaascli tde removeSecondaryHsmKey --precheckOnly yes --secondaryKmsKeyOCID <value>

Q: What happens if I don’t provide a database name with –dbname?

A: If the --dbname parameter is not specified, the command will attempt to remove the secondary HSM key from the default database configured on the system.

Q: What should I check if the command fails to remove the secondary HSM key?

A: Ensure that:

Q: What should I do if the removal operation fails partway through?

A: If the operation fails, review the error logs and try running the command with --precheckOnly to ensure the system is ready for the operation. If necessary, correct any issues before retrying.

Q: Can I run the dbaascli tde removeSecondaryHsmKey command while the database is running?

A: Yes, the command can be executed while the database is running, as it does not require the database to be stopped.

Q: What is the purpose of removing a secondary HSM key?

A: Removing a secondary HSM key is typically done when the key is no longer needed or when you want to manage the encryption keys used in your TDE (Transparent Data Encryption) configuration.

Q: How do I connect to the Oracle Base Database Cloud@Customer virtual machine to run the command?

A: You can connect to the virtual machine using SSH. Refer to the Oracle Base Database Cloud@Customer documentation for instructions on establishing a secure connection.

Example: dbaascli tde removeSecondaryHsmKey

dbaascli tde removeSecondaryHsmKey --dbname dbname
dbaascli tde removeSecondaryHsmKey --dbname dbname --secondaryKmsKeyOCID ocid1.key.oc1.eu-frankfurt-1.bjqnwclvaafak.abtheljsgfxa2xe5prvlzdxtygoiqpm2pu2afgta54krxwllk5uxainvvxza
dbaascli tde removeSecondaryHsmKey --dbname dbname --secondaryKmsKeyOCID ocid1.key.oc1.eu-frankfurt-1.bjqnwclvaafak.abtheljsgfxa2xe5prvlzdxtygoiqpm2pu2afgta54krxwllk5uxainvvxza --executePrereqs

dbaascli tde rotateMasterKey

To rotate the master key for database encryption, use the dbaascli tde rotateMasterKey command.

Prerequisites:

Run the command as the root user.

Syntax:

dbaascli tde rotateMasterKey --dbname <value>
[--rotateMasterKeyOnAllPDBs]
[--pdbName <value>]
[--executePrereqs]
[--resume [--sessionID <value>]]
{
     [--prepareStandbyBlob <value> [--blobLocation <value>]]
     | [--standbyBlobFromPrimary <value>]
 }

Parameters:

Parameter Description
--dbname specifies the name of the Oracle AI Database
--rotateMasterKeyOnAllPDBs specifies true to rotate master key of all PDBs in CDB. Valid values: true or false
--pdbName specifies the name of the PDB
--executePrereqs runs the prerequisites checks and report the results
--resume specifies to resume the previous execution
--sessionID specifies to resume a specific session ID
--prepareStandbyBlob specifies true to generate a BLOB file containing the artifacts needed to perform the operation in a Data Guard environment
--blobLocation specifies the location of the custom directory where the standby BLOB file will be generated in a Data Guard environment
--standbyBlobFromPrimary specifies the location of the standby BLOB file, which is prepared from the primary database. This is required only for standby operations.

Frequently Asked Questions:

Q: What is the purpose of the dbaascli tde rotateMasterKey command?

A: The dbaascli tde rotateMasterKey command is used to rotate the master key used for Transparent Data Encryption (TDE) in an Oracle AI Database. This process ensures the encryption keys are updated for better security.

Q: What are the prerequisites for running the dbaascli tde rotateMasterKey command?

A: You must:

Q: What does the –dbname parameter specify?

A: The --dbname parameter specifies the name of the Oracle AI Database for which you want to rotate the master encryption key.

Q: What is the purpose of the –rotateMasterKeyOnAllPDBs parameter?

A: The --rotateMasterKeyOnAllPDBs parameter specifies whether to rotate the master key for all Pluggable Databases (PDBs) in a Container Database (CDB). Valid values are true or false.

Q: What does the –pdbName parameter do?

A: The --pdbName parameter specifies the name of a particular Pluggable Database (PDB) if you want to rotate the master key for a specific PDB rather than all PDBs.

Q: What does the –executePrereqs parameter do?

A: The --executePrereqs parameter runs prerequisite checks to validate whether the environment is ready for the master key rotation without performing the actual rotation.

Q: What does the –resume parameter specify?

A: The --resume parameter is used to resume a previously started operation. You can also provide a specific session ID using --sessionID to resume a particular session.

Q: What is the purpose of the –prepareStandbyBlob parameter?

A: The --prepareStandbyBlob parameter, if set to true, generates a BLOB file containing the necessary artifacts to perform master key rotation in a Data Guard environment.

Q: What does the –blobLocation parameter do?

A: The --blobLocation parameter specifies a custom directory path where the standby BLOB file will be generated. This is applicable when --prepareStandbyBlob is set to true.

Q: What does the –standbyBlobFromPrimary parameter specify?

A: The --standbyBlobFromPrimary parameter specifies the location of the standby BLOB file that was generated from the primary database. This parameter is used when performing the master key rotation on a standby database in a Data Guard environment.

Q: Is the –rotateMasterKeyOnAllPDBs parameter mandatory?

A: No, the --rotateMasterKeyOnAllPDBs parameter is optional. If it is not specified, the master key will only be rotated for the database (or specific PDB) provided in the --dbname or --pdbName parameters.

Q: Is the –pdbName parameter required if I’m rotating keys for a CDB?

A: No, the --pdbName parameter is only required if you want to rotate the master key for a specific Pluggable Database (PDB). It is optional when rotating the key for the entire CDB.

Q: Do I need to use the –prepareStandbyBlob and –standbyBlobFromPrimary parameters for standalone databases?

A: No, these parameters are only relevant in a Data Guard environment where a standby database is involved.

Q: How can I rotate the master key for all PDBs in a CDB?

A: You should use the --rotateMasterKeyOnAllPDBs parameter set to true to rotate the master key for all PDBs in the CDB. For example:

dbaascli tde rotateMasterKey --dbname CDB_NAME --rotateMasterKeyOnAllPDBs true

Q: How do I run a check to validate that the system is ready for master key rotation without performing the actual operation?

A: You can use the --executePrereqs parameter to run the prerequisite checks. This will report any issues that might prevent the master key rotation:

dbaascli tde rotateMasterKey --dbname DB_NAME --executePrereqs

Q: What should I do if the operation was interrupted, and I want to resume it?

A: You can use the --resume parameter to resume the previously interrupted operation. If you have a session ID, provide it with the --sessionID parameter:

dbaascli tde rotateMasterKey --dbname DB_NAME --resume --sessionID <value>

Q: How can I prepare for key rotation in a Data Guard environment?

A: You should use the --prepareStandbyBlob parameter to generate a BLOB file that contains the required artifacts for rotating the master key in a standby environment:

dbaascli tde rotateMasterKey --dbname DB_NAME --prepareStandbyBlob true --blobLocation /path/to/blob

Q: How do I apply the standby BLOB file from the primary database when rotating keys on a standby database?

A: Use the --standbyBlobFromPrimary parameter to specify the location of the BLOB file that was prepared on the primary database:

dbaascli tde rotateMasterKey --dbname DB_NAME --standbyBlobFromPrimary /path/to/blob

Q: What should I check if the master key rotation fails?

A: Ensure that:

Q: What should I do if the operation does not complete successfully in a Data Guard environment?

A: Ensure that the BLOB file from the primary database was prepared correctly using --prepareStandbyBlob, and then use --standbyBlobFromPrimary to apply it on the standby database.

Q: Can I run the dbaascli tde rotateMasterKey command while the database is running?

A: Yes, the command can be executed while the database is running. However, it is recommended to run prerequisite checks beforehand using the --executePrereqs option.

Q: Why is rotating the master key important?

A: Rotating the master key improves database security by ensuring that the encryption keys used for data protection are periodically updated, reducing the risk of key compromise.

Q: Do I need to restart the database after rotating the master key?

A: No, restarting the database is not required after rotating the master key. The key rotation will take effect immediately without any service disruption.

dbaascli tde setKeyVersion

To set the version of the primary key to be used in DB/CDB or PDB, use the dbaascli tde setKeyVersion command.

Run the command as the root user.

Syntax:

dbaascli tde setKeyVersion --kmsKeyVersionOCID <value> --dbname <value>
[--pdbName <value>]
[--masterKeyID <value>]
[--standbySuc]
[--executePrereqs]
[--waitForCompletion <value>]

Parameters:

Parameter Description
--kmsKeyVersionOCID specifies the KMS key version OCID to set.
--dbname specifies the name of the database.
--pdbName name of the PDB to use the key version OCID.
--masterKeyID specifies the master key ID of the given key version OCID. This is applicable to the Data Guard environment.
--standbySuc specify this property in the primary database of the Data Guard environment once the command is successfully run on the standby database
--executePrereqs execute the prerequisites checks and report the results.
--waitForCompletion specify false to run the operation in background. Valid values: true or false

Frequently Asked Questions:

Q: What is the purpose of the dbaascli tde setKeyVersion command?

A: The dbaascli tde setKeyVersion command is used to set the version of the primary encryption key that should be used for Transparent Data Encryption (TDE) in a database or Pluggable Database (PDB). This allows for the specific version of a KMS key to be assigned to the database.

Q: What are the prerequisites for using the dbaascli tde setKeyVersion command?

A: You must run the command as the root user and ensure that you are connected to an Oracle Base Database Cloud@Customer virtual machine.

Q: What does the –kmsKeyVersionOCID parameter specify?

A: The --kmsKeyVersionOCID parameter specifies the KMS key version OCID (Oracle Cloud Identifier) that you want to set for the database or PDB.

Q: What does the –dbname parameter specify?

A: The --dbname parameter specifies the name of the Oracle AI Database for which the key version will be set.

Q: What is the purpose of the –pdbName parameter?

A: The --pdbName parameter specifies the name of the Pluggable Database (PDB) within a Container Database (CDB) where you want to set the specific KMS key version.

Q: What is the –masterKeyID parameter used for?

A: The --masterKeyID parameter specifies the master key ID that is associated with the given KMS key version OCID. This is particularly important in a Data Guard environment.

Q: What is the role of the –standbySuc parameter?

A: The --standbySuc parameter is used in a Data Guard environment. It specifies that this property should be set on the primary database after successfully running the command on the standby database.

Q: What does the –executePrereqs parameter do?

A: The --executePrereqs parameter specifies whether to run prerequisite checks before executing the operation. Valid values are yes or no.

Q: What does the –waitForCompletion parameter control?

A: The --waitForCompletion parameter determines whether the operation will run synchronously (waiting for completion) or asynchronously (in the background). Valid values are true or false.

Q: Is the –pdbName parameter required if setting the key version for a CDB?

A: No, the --pdbName parameter is only required if you are setting the key version for a specific Pluggable Database (PDB). It is optional if you are setting the key version for the entire Container Database (CDB).

Q: Is the –masterKeyID parameter necessary for non-Data Guard environments?

A: No, the --masterKeyID parameter is typically only used in Data Guard environments. For standalone databases, this parameter is not required.

Q: How do I set the key version for a database?

A: You can set the key version for a database by running:

dbaascli tde setKeyVersion --kmsKeyVersionOCID <value> --dbname <DB_NAME>

Q: How do I set the key version for a specific PDB?

A: To set the key version for a specific Pluggable Database (PDB), use the --pdbName parameter along with the database name:

dbaascli tde setKeyVersion --kmsKeyVersionOCID <value> --dbname <DB_NAME> --pdbName <PDB_NAME>

Q: How can I ensure that all prerequisites are met before setting the key version?

A: You can run the prerequisite checks by using the --executePrereqs parameter:

dbaascli tde setKeyVersion --kmsKeyVersionOCID <value> --executePrereqs yes

Q: How do I set the key version in a Data Guard environment?

A: In a Data Guard environment, you should:

Q: How can I run the operation in the background without waiting for it to complete?

A: You can run the operation asynchronously by setting --waitForCompletion to false:

dbaascli tde setKeyVersion --kmsKeyVersionOCID <value> --waitForCompletion false

Q: What should I do if the key version fails to set?

A: Ensure that:

Q: What should I check if the operation doesn’t complete successfully in a Data Guard environment?

A: Ensure that the --masterKeyID parameter is correctly specified when running the command on the standby database. Once completed on the standby, the --standbySuc parameter should be used when running the command on the primary database.

Q: Can I run the dbaascli tde setKeyVersion command while the database is running?

A: Yes, the command can be executed while the database is running. However, running the prerequisite checks beforehand using --executePrereqs is recommended.

Q: Why is it important to set the correct KMS key version for a database?

A: Setting the correct KMS key version ensures that the database is using the appropriate encryption key version for TDE, which helps maintain data security and compliance with organizational policies.

Q: What happens if I use the wrong KMS key version OCID?

A: If an incorrect KMS key version OCID is used, the encryption may fail, and the database will not be able to use the incorrect key for encryption operations. You should ensure that the correct key version OCID is provided.

Q: Do I need to restart the database after setting the key version?

A: No, restarting the database is not necessary after setting the key version. The new key version will take effect immediately without requiring a restart.

Example: dbaascli tde setKeyVersion

dbaascli tde setKeyVersion --dbname dbname --kmsKeyVersionOCID ocid1.keyversion.oc1.eu-frankfurt-1.bjqnwclvaafak.bc4hmd3olgaaa.abtheljsyxtgn4vzi2bbpcej6a7abcwvylkd2lx56lu2s6iwnxwgigu23nha
dbaascli tde setKeyVersion --dbname dbname --kmsKeyVersionOCID ocid1.keyversion.oc1.eu-frankfurt-1.bjqnwclvaafak.bc4hmd3olgaaa.abtheljsyxtgn4vzi2bbpcej6a7abcwvylkd2lx56lu2s6iwnxwgigu23nha --executePrereqs
dbaascli tde setKeyVersion --dbname dbname --pdbName pdb --kmsKeyVersionOCID ocid1.keyversion.oc1.eu-frankfurt-1.bjqnwclvaafak.bc4hmd3olgaaa.abtheljsyxtgn4vzi2bbpcej6a7abcwvylkd2lx56lu2s6iwnxwgigu23nha

dbaascli tde setPrimaryHsmKey

To change the primary HSM (KMS) key for the existing HSM (KMS) configuration, use the dbaascli tde setPrimaryHsmKey command.

Run the command as the root user.

Syntax:

dbaascli tde setPrimaryHsmKey --primaryKmsKeyOCID <value> --dbname <value>
[--allStandbyPrepared]
[--bounceDatabase]
[--executePrereqs]
[--resume [--sessionID <value>]]

Parameters:

Parameter Description
--primaryKmsKeyOCID specifies the primary KMS key to set
--dbname specifies the name of the database
--allStandbyPrepared specify to confirm that the operation has been successfully run on all the standby databases.
--bounceDatabase specify this flag to do rolling database bounce for this operation
--executePrereqs execute the prerequisites checks and report the results.
--resume to resume the previous execution
--sessionID to resume a specific session id.

Frequently Asked Questions:

Q: What is the purpose of the dbaascli tde setPrimaryHsmKey command?

A: The dbaascli tde setPrimaryHsmKey command is used to change the primary HSM (Hardware Security Module) or KMS (Key Management Service) key in an existing HSM/KMS configuration for Transparent Data Encryption (TDE).

Q: What are the prerequisites for running the dbaascli tde setPrimaryHsmKey command?

A: The command must be executed as the root user, and the environment should be an Oracle Base Database Cloud@Customer virtual machine.

Q: What does the –primaryKmsKeyOCID parameter specify?

A: The --primaryKmsKeyOCID parameter specifies the OCID (Oracle Cloud Identifier) of the primary KMS key to be set for the TDE environment.

Q: What is the function of the –dbname parameter?

A: The --dbname parameter specifies the name of the Oracle AI Database for which the primary HSM/KMS key will be set.

Q: What does the –standbySuc parameter do?

A: The --standbySuc parameter is used in a Data Guard environment. It specifies that the command should be run on the primary database after successfully executing it on the standby database.

Q: What is the purpose of the –precheckOnly parameter?

A: The --precheckOnly parameter allows you to run only the prechecks for this operation. It validates the environment without making any actual changes. Valid values are yes or no.

Q: What does the –bounceDatabase parameter control?

A: The --bounceDatabase parameter specifies whether the database should be bounced (restarted) in a rolling manner as part of the operation. This ensures minimal downtime by restarting parts of the database one by one.

Q: How do I set the primary KMS key for my database?

A: To set the primary KMS key, run the following command:

dbaascli tde setPrimaryHsmKey --primaryKmsKeyOCID <key_OCID> --dbname <DB_NAME>

Q: How do I ensure that the operation can be executed without any issues?

A: Run the operation with the --precheckOnly parameter to verify that all prerequisites are met:

dbaascli tde setPrimaryHsmKey --primaryKmsKeyOCID <key_OCID> --precheckOnly yes

Q: How do I set the primary KMS key in a Data Guard environment?

A: First, run the command on the standby database:

dbaascli tde setPrimaryHsmKey --primaryKmsKeyOCID <key_OCID> --dbname <DB_NAME>

Then, run the command on the primary database with the --standbySuc parameter:

dbaascli tde setPrimaryHsmKey --primaryKmsKeyOCID <key_OCID> --dbname <DB_NAME> --standbySuc yes

Q: How do I minimize downtime while changing the primary KMS key?

A: You can use the --bounceDatabase parameter to perform a rolling restart, minimizing downtime:

dbaascli tde setPrimaryHsmKey --primaryKmsKeyOCID <key_OCID> --bounceDatabase

Q: Is the –dbname parameter required for all databases?

A: Yes, you should specify the --dbname parameter to indicate the target database for which the primary KMS key should be set.

Q: Is it mandatory to use the –standbySuc parameter in a Data Guard environment?

A: Yes, the --standbySuc parameter must be used when running the command on the primary database after successfully executing it on the standby database.

Q: Can I skip the bounce operation for the database?

A: Yes, if you do not specify the --bounceDatabase parameter, the database will not be bounced (restarted) as part of the operation.

Q: What should I do if the command fails during execution?

A: If the command fails, ensure:

Q: What if the operation fails in a Data Guard environment?

A: Ensure that the command has been successfully executed on the standby database before running it on the primary. Check for errors in the logs and rerun the operation with correct parameters.

Q: Can I run the dbaascli tde setPrimaryHsmKey command on a live database?

A: Yes, the command can be run while the database is live. However, using the --bounceDatabase parameter will restart the database in a rolling fashion, which minimizes the impact.

Q: How do I run the command in a rolling manner to avoid complete downtime?

A: Use the --bounceDatabase parameter to perform a rolling restart of the database while changing the primary KMS key:

dbaascli tde setPrimaryHsmKey --primaryKmsKeyOCID <key_OCID> --bounceDatabase

Q: What is the significance of changing the primary KMS key?

A: Changing the primary KMS key ensures that the database uses an updated or different encryption key for Transparent Data Encryption (TDE). This may be required for security or compliance reasons.

Q: How often should the primary KMS key be rotated or changed?

A: While there is no strict rule, organizations may rotate the primary KMS key based on security policies, such as key rotation intervals or compliance requirements.

Q: What happens if the primary KMS key is set incorrectly?

A: If the incorrect key OCID is set, database encryption operations may fail, and you may need to revert to the correct key or rectify the configuration by setting the correct KMS key OCID.

Q: Do I need to restart the database after changing the primary KMS key?

A: No, you do not need to restart the database unless you choose to use the --bounceDatabase parameter, which will automatically restart the database to apply the change.

Example: dbaascli tde setPrimaryHsmKey

dbaascli tde setPrimaryHsmKey --dbname dbname --primaryKmsKeyOCID ocid1.key.oc1.eu-frankfurt-1.bjqnwclvaafak.abtheljsgfxa2xe5prvlzdxtygoiqpm2pu2afgta54krxwllk5uxainvvxza
dbaascli tde setPrimaryHsmKey --dbname dbname --primaryKmsKeyOCID ocid1.key.oc1.eu-frankfurt-1.bjqnwclvaafak.abtheljsgfxa2xe5prvlzdxtygoiqpm2pu2afgta54krxwllk5uxainvvxza --executePrereqs

dbaascli tde status

To display information about the keystore for the specified database, use the dbaascli tde status command.

Prerequisites:

Run the command as the oracle user.

Syntax:

dbaascli tde status --dbname dbname

Parameters:

Parameter Description
--dbname specifies the name of the database that you want to check.

Output from the command includes the type of keystore, and the status of the keystore.

Frequently Asked Questions:

Q: What does the dbaascli tde status command do?

A: The dbaascli tde status command displays information about the keystore for a specified database. This includes details about the type of keystore and its status.

Q: Who should run the dbaascli tde status command?

A: The command must be executed as the oracle user.

Q: Where should the dbaascli tde status command be run?

A: The command should be run on an Oracle Base Database Cloud@Customer virtual machine. You must connect to the virtual machine via SSH to run the utility.

Q: What is the function of the –dbname parameter?

A: The --dbname parameter specifies the name of the database for which the TDE keystore status will be checked.

Q: What information does the dbaascli tde status command return?

A: The output of the command includes the type of keystore (e.g., HSM-based or file-based) and the current status of the keystore, such as whether it is open, closed, or in some other state.

Q: How can I know if the keystore is open or closed using the dbaascli tde status command?

A: The status of the keystore, including whether it is open or closed, is part of the output returned by the dbaascli tde status command.

Q: How do I check the status of the TDE keystore for a specific database?

A: To check the TDE keystore status for a specific database, run:

dbaascli tde status --dbname <DB_NAME>

Q: Can I check the status of the keystore for multiple databases?

A: Yes, but you need to run the command separately for each database, specifying its name using the --dbname parameter.

Q: Can the dbaascli tde status command be run as the root user?

A: No, the command should be executed as the oracle user, not the root user.

Q: Do I need special permissions to run the dbaascli tde status command?

A: Yes, you need to have oracle user privileges and be connected to an Oracle Base Database Cloud@Customer virtual machine to run the command.

Q: What should I do if I get an error when running the dbaascli tde status command?

A: Ensure you are running the command as the oracle user, and verify that you have the necessary permissions and are connected to the correct virtual machine.

Q: How do I know what type of keystore my database is using?

A: The type of keystore, such as whether it is file-based or HSM/KMS-based, is displayed in the output of the dbaascli tde status command.

Q: What should I do if the keystore is closed?

A: If the keystore is closed, you may need to open it manually, depending on the operation you are trying to perform. The exact process will depend on the keystore type and your environment.

Q: Can I view keystore status for a CDB (Container Database) or PDB (Pluggable Database)?

A: Yes, by specifying the appropriate database name using the --dbname parameter, you can view the keystore status for both CDBs and PDBs.

Q: What does it mean if the command returns an error about database connectivity?

A: This could indicate an issue with the connection to the database or a problem with your environment. Ensure that the database is running and accessible, and verify your SSH connection to the Oracle Base Database Cloud@Customer virtual machine.

Q: What happens if the database name is incorrect?

A: If the --dbname parameter specifies an incorrect or non-existent database, the command will fail, and you’ll receive an error message indicating the problem.

Q: How do I troubleshoot if the keystore status indicates an unexpected state?

A: If the keystore status indicates an unexpected state, review the database logs for more details and check the configuration of the keystore to ensure it is properly set up.

Q: Can I automate the check of keystore status for monitoring purposes?

A: Yes, you can script the dbaascli tde status command to check keystore status periodically or integrate it into your database monitoring tools.

Q: How do I verify that Transparent Data Encryption (TDE) is correctly enabled?

A: You can verify TDE is correctly enabled by checking the status of the keystore using the dbaascli tde status command. A valid and open keystore indicates that TDE is properly configured.

Example: dbaascli tde status

dbaascli tde status --dbname dbname