3 Configuring Transparent Data Encryption

You can configure software or hardware keystores, for use on both individual table columns or entire tablespaces.

Configuring a Software Keystore

A software keystore is a container for the TDE master encryption key, and it resides in the software file system.

About Configuring a Software Keystore

A software keystore is a container that stores the Transparent Data Encryption master encryption key.

Before you can configure the keystore, you first must define a location for it in the sqlnet.ora file. There is one keystore per database, and the database locates this keystore by checking the keystore location that you define in the sqlnet.ora file. You can create other keystores, such as copies of the keystore and export files that contain keys, depending on your needs. However, you must never remove or delete the keystore that you configured in the sqlnet.ora location, nor replace it with a different keystore.

After you configure the software keystore location in the sqlnet.ora file, you can log in to the database instance to create and open the keystore, and then set the TDE master encryption key. After you complete these steps, you can begin to encrypt data.

Step 1: Set the Keystore Location in the sqlnet.ora File

The first step you must take to configure a software keystore is to designate a location for it in the sqlnet.ora file.

About the Keystore Location in the sqlnet.ora File

Oracle Database checks the sqlnet.ora file for the directory location of the keystore, whether it is a software keystore, a hardware module security (HSM) keystore, or an Oracle Key Vault keystore.

You must edit the sqlnet.ora file to define a directory location for the keystore that you plan to create. Ensure that this directory exists beforehand. Preferably, this directory should be empty.

Note the following behavior when you must edit the sqlnet.ora file in an Oracle Real Application Clusters (Oracle RAC) or a multitenant environment:

  • In an Oracle RAC environment: If you are using the srvctl utility and if you want to include environment variables in the sqlnet.ora configuration file, then you must set these environment variables in both the operating system and the srvctl environment. Oracle recommends that you place the keystore on a shared file system, such as Oracle Automatic Storage Management (ASM) or NFS.

  • In a multitenant environment: The keystore location is set for the entire multitenant container database (CDB), not for individual pluggable databases (PDBs).

In the sqlnet.ora file, you must set the ENCRYPTION_WALLET_LOCATION parameter to specify the keystore location. When determining which keystore to use, Oracle Database searches for the keystore location in the following places, in this order:

  1. It attempts to use the keystore in the location specified by the parameter ENCRYPTION_WALLET_LOCATION in the sqlnet.ora file.

  2. If the ENCRYPTION_WALLET_LOCATION parameter is not set, then it attempts to use the keystore in the location that is specified by the parameter WALLET_LOCATION.

  3. If the WALLET_LOCATION parameter is also not set, then Oracle Database looks for a keystore at the default database location, which is ORACLE_BASE/admin/DB_UNIQUE_NAME/wallet or ORACLE_HOME/admin/DB_UNIQUE_NAME/wallet. (DB_UNIQUE_NAME is the unique name of the database specified in the initialization parameter file.) When the keystore location is not set in the sqlnet.ora file, then the V$ENCRYPTION_WALLET view displays the default location. You can check the location and status of the keystore in the V$ENCRYPTION_WALLET view.

By default, the sqlnet.ora file is located in the ORACLE_HOMEdbs directory or in the location set by the TNS_ADMIN environment variable. Ensure that you have properly set the TNS_ADMIN environment variable to point to the correct sqlnet.ora file.

See Also:

SQL*Plus User's Guide and Reference for more information and examples of setting the TNS_ADMIN environment variable
Configuring the sqlnet.ora File for a Software Keystore Location

Use the sqlnet.ora file to configure the keystore location for a regular file system, for multiple database access, and for use with Oracle Automatic Storage Management (ASM).

  • To create a software keystore on a regular file system, use the following format when you edit the sqlnet.ora file:

    ENCRYPTION_WALLET_LOCATION=
     (SOURCE=
      (METHOD=FILE)
       (METHOD_DATA=
        (DIRECTORY=path_to_keystore)))
    

If the path_to_keystore will contain an environment variable, then set this variable in the environment where the database instance is started and before you start the database. If you are using the srvctl utility to start the database, then set the environment variable in the srvctl environment as well, using the following command:

srvctl setenv database -db database_name -env "environment_variable_name=environment_variable_value"
Configuring an External Store for a Keystore Password

An external store for a keystore password stores the software keystore password in a centrally accessed and managed location.

An external store for a password is 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 passwords. 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.
You must complete the following steps before you use the IDENTIFIED BY EXTERNAL STORE clause in the ADMINISTER KEY MANAGEMENT statement.
  1. Set the external keystore credential location by using one of the following methods:
    • Run the ALTER SYSTEM statement for the EXTERNAL_KEYSTORE_CREDENTIAL_LOCATION parameter. For example:
      ALTER SYSTEM SET EXTERNAL_KEYSTORE_CREDENTIAL_LOCATION = "/etc/ORACLE/WALLETS/orcl/external_store" SCOPE = SPFILE;
    • Edit the init.ora file for the database instance. For example:
      EXTERNAL_KEYSTORE_CREDENTIAL_LOCATION = "/etc/ORACLE/WALLETS/orcl/external_store"

      By default, the init.ora file is located in the ORACLE_HOME/dbs directory or in the location set by the TNS_ADMIN environment variable.

  2. Log in as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege and who has the ALTER SYSTEM system privilege.

    In a multitenant environment, log in to the root. For example:

    sqlplus c##sec_admin as sysdba
    Enter password: password
    Connected.
  3. Create an auto-login keystore that contains the keystore password, by including the ADD SECRET clause to the ADMINISTER KEY MANAGEMENT statement.

    For example:

    ADMINISTER KEY MANAGEMENT ADD SECRET 'password'  
      FOR CLIENT 'TDE_WALLET' 
          TO LOCAL AUTO_LOGIN KEYSTORE '/etc/ORACLE/WALLETS/orcl/external_store';

    In this example, enter 'TDE_WALLET', in capital letters and enclosed in single quotation marks, for the client_identifier value set by the FOR CLIENT clause. This is a fixed value and must be entered as shown here for this application of the ADD SECRET clause. Otherwise, TDE will be unable to find this secret, and attempts to use the IDENTIFIED BY EXTERNAL STORE setting will generate an ORA-00988: missing or invalid password(s) error message.

  4. Restart the database.

    For example:

    SHUTDOWN IMMEDIATE
    STARTUP

Afterward, 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, to open a keystore in a multitenant environment:

ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY EXTERNAL STORE CONTAINER = ALL;
Example: Configuring a Software Keystore for a Regular File System

You can configure a software keystore for a regular file system.

The following example shows how to configure a software keystore location in the sqlnet.ora file for a regular file system in which the database name is orcl.

ENCRYPTION_WALLET_LOCATION=
  (SOURCE=
   (METHOD=FILE)
    (METHOD_DATA=
     (DIRECTORY=/etc/ORACLE/WALLETS/orcl)))
Example: Configuring a Software Keystore When Multiple Databases Share the sqlnet.ora File

You can configure multiple databases to share the sqlnet.ora file.

The following example shows how to configure a software keystore location when multiple databases share the sqlnet.ora file.

ENCRYPTION_WALLET_LOCATION=
 (SOURCE=
  (METHOD=FILE)
   (METHOD_DATA=
    (DIRECTORY=/etc/ORACLE/WALLETS/$ORACLE_SID/)))
Example: Configuring a Software Keystore for Oracle Automatic Storage Management

You can configure sqlnet.ora for an Automatic Storage Management (ASM) file system

The following example shows how to configure a software keystore location in the sqlnet.ora file for an ASM file system:

ENCRYPTION_WALLET_LOCATION=
 (SOURCE=
  (METHOD=FILE)
   (METHOD_DATA=
    (DIRECTORY=+disk1/mydb/wallet)))
Example: Configuring a Software Keystore for an Oracle Automatic Storage Management Disk Group

You can configure sqlnet.ora for an Oracle Automatic Storage Management (ASM) disk group.

The following format shows how to configure a software keystore if you want to create a software keystore location on an ASM disk group:

ENCRYPTION_WALLET_LOCATION=
 (SOURCE=
  (METHOD=FILE)
   (METHOD_DATA=
    (DIRECTORY=+ASM_file_path_of_the_diskgroup)))

Step 2: Create the Software Keystore

After you have specified a directory location for the software keystore, you can create the keystore.

About Creating Software Keystores

There are three different types of software keystores.

You can create password-based software keystores, auto-login software keystores, and local auto-login software keystores.

Be aware that executing the query SELECT * FROM V$ENCRYPTION_WALLET will automatically open an auto-login software keystore. For example, suppose you have a password-based keystore and an auto-login keystore. If the password-based keystore is open and you close the password-based keystore and then query the V$ENCRYPTION_WALLET view, then the output will indicate that a keystore is open. However, this is because V$ENCRYPTION_WALLET opened up the auto-login software keystore and then displayed the status of the auto-login keystore.

In a multitenant environment, you can create a secure external store for the software keystore. This feature enables you to hide the password from the operating system: it removes the need for storing clear-text keystore passwords in scripts or other tools that can access the database without user intervention, such as overnight batch scripts. The location for this keystore is set by the EXTERNAL_KEYSTORE_CREDENTIAL_LOCATION initialization parameter. In a multitenant environment, different PDBs can access this external store location when you run the ADMINISTER KEY MANAGEMENT statement using the IDENTIFIED BY EXTERNAL STORE clause. This way, you can centrally locate the password and then update it only once in the external store.

Creating a Password-Based Software Keystore

A password-based software keystore requires a user password, which is used to protect the keys and credentials stored in the keystore.

Before you begin this procedure, ensure that you complete the procedure described in Step 1: Set the Keystore Location in the sqlnet.ora File.
  1. Log in to the database instance as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.

    In a multitenant environment, log in to the root. For example:

    sqlplus c##sec_admin as syskm
    Enter password: password
    Connected.
    

    If SQL*Plus is already open and you had modified the sqlnet.ora file during this time, then reconnect to SQL*Plus. The database session must be changed before the sqlnet.ora changes can take effect.

  2. Run the ADMINISTER KEY MANAGEMENT SQL statement to create the keystore.

    The syntax is as follows:

    ADMINISTER KEY MANAGEMENT CREATE KEYSTORE 'keystore_location' IDENTIFIED BY software_keystore_password;
    

    In this specification:

    • keystore_location is the path to the keystore directory location of the password-based keystore for which you want to create the auto-login keystore (for example, /etc/ORACLE/WALLETS/orcl). Enclose the keystore_location setting in single quotation marks (' '). To find this location, you can query the WRL_PARAMETER column of the V$ENCRYPTION_WALLET view. (If the keystore was not created in the default location, then the STATUS column of the V$ENCRYPTION_WALLET view is NOT_AVAILABLE.)

    • software_keystore_password is the password of the keystore that you, the security administrator, creates.

    For example, to create the keystore in the /etc/ORACLE/WALLETS/orcl directory:

    ADMINISTER KEY MANAGEMENT CREATE KEYSTORE '/etc/ORACLE/WALLETS/orcl' IDENTIFIED BY password;
    
    keystore altered.
    

    After you run this statement, the ewallet.p12 file, which is the keystore, appears in the keystore location.

Creating an Auto-Login or a Local Auto-Login Software Keystore

As an alternative to password-based keystores, you can create either an auto-login or local auto-login software keystore.

Both of these keystores have system-generated passwords. They are also PKCS#12-based files. The auto-login software keystore can be opened from different computers from the computer where this keystore resides, but the local auto-login software keystore can only be opened from the computer on which it was created. Both the auto-login and local auto-login keystores are created from the password-based software keystores.

Before you begin this procedure, ensure that you complete the procedure described in Step 1: Set the Keystore Location in the sqlnet.ora File.

  1. Log in to the database instance as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.

    In a multitenant environment, log in to the root. For example:

    sqlplus c##sec_admin as syskm
    Enter password: password
    Connected.
    

    If SQL*Plus is already open and you had modified the sqlnet.ora file during this time, then reconnect to SQL*Plus. The database session must be changed before the sqlnet.ora changes can take effect.

  2. Create a password-based software keystore.

    For example:

    ADMINISTER KEY MANAGEMENT CREATE KEYSTORE '/etc/ORACLE/WALLETS/orcl' IDENTIFIED BY keystore_password;
  3. Run the ADMINISTER KEY MANAGEMENT SQL statement to create the keystore.

    The syntax is as follows:

    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 directory location of the password-based keystore for which you want to create the auto-login keystore (for example, /etc/ORACLE/WALLETS/orcl). Enclose this setting in single quotation marks (' '). To find this location, query the WRL_PARAMETER column of the V$ENCRYPTION_WALLET view.

    • software_keystore_password is the password-based keystore for which you want to create the auto-login keystore.

    For example, to create an auto-login software keystore of the password-based keystore that is located in the/etc/ORACLE/WALLETS/orcl directory:

    ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE '/etc/ORACLE/WALLETS/orcl' IDENTIFIED BY password;
    
    keystore altered.
    

    After you run this statement, the cwallet.sso file appears in the keystore location. The ewallet.p12 file is the password-based wallet.

Note:

Do not remove the PKCS#12 wallet (ewallet.p12 file) after you create the auto login keystore (.sso file). You must have the PKCS#12 wallet to regenerate or rekey the TDE master encryption key in the future. By default, this file is located in the $ORACLE_HOME/admin/ORACLE_SID/wallet directory.

Transparent Data Encryption uses an auto login keystore only if it is available at the correct location (ENCRYPTION_WALLET_LOCATION, WALLET_LOCATION, or the default keystore location), and the SQL statement to open an encrypted keystore has not already been executed. (Note that auto-login keystores are encrypted, because they have system-generated passwords.)

Step 3: Open the Software Keystore

Depending on the type of keystore you create, you must manually open the keystore before you can use it.

About Opening Software Keystores

A password-based software keystore must be open before any TDE master encryption keys can be created or accessed in the keystore.

You can either manually open a software keystore or, when you perform certain ADMINISTER KEY MANAGEMENT operations, have the keystore open temporarily during the course of the operation itself. You do not need to manually open auto-login or local auto-login software keystores. These keystore are automatically opened when it is required, that is, when an encryption operation must access the key. If necessary, you can explicitly close any of these types of keystores. Keystores can be in the following states: open, closed, open but with no master key, open but with an unknown master key, undefined, or not available (that is, not present in the sqlnet.ora location).

You can check the status of whether a keystore is open or not by querying the STATUS column of the V$ENCRYPTION_WALLET view.

After you open a keystore, it remains open until you manually close it. Each time you restart a database instance, you must manually open the password keystore to reenable encryption and decryption operations.

Opening a Software Keystore

To open a software keystore, you must use the ADMINISTER KEY MANAGEMENT statement with the SET KEYSTORE OPEN clause.

  1. Ensure that you complete the procedure described in Step 2: Create the Software Keystore.
  2. Log in to the database instance as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.

    In a multitenant environment, you must open the keystore first in the root before you can open it in a PDB. For example, to log in to the root:

    sqlplus c##sec_admin as syskm
    Enter password: password
    Connected.
    

    To find the available PDBs, query the DBA_PDBS data dictionary view. To check the current PDB, run the show con_name command.

  3. Run the ADMINISTER KEY MANAGEMENT statement.

    Use the following syntax:

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN [FORCE KEYSTORE] 
    IDENTIFIED BY [EXTERNAL STORE] | keystore_password  
    [CONTAINER = ALL | CURRENT];
    

    In this specification:

    • FORCE KEYSTORE enables the keystore operation if the auto-login keystore is in use, or if the keystore is closed.

    • IDENTIFIED BY permits the following authentication methods:

      • EXTERNAL STORE uses the keystore password stored in the external store to perform the keystore operation.

      • keystore_password is the same password that you used to create the software keystore in Step 2: Create the Software Keystore. In a multitenent environment, ensure that you enter the password that is specific to the PDB in which you are logged.

    • CONTAINER is for use in a multitenant environment. Enter ALL to set the keystore in all of the PDBs in this CDB, or CURRENT for the current PDB.

    For example:

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY password;
    keystore altered.
    

    If the auto-login keystore is open or if the password keystore is closed:

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN FORCE KEYSTORE IDENTIFIED BY EXTERNAL STORE;
    
    keystore altered.
    

Note that if the keystore is open but you have not created a TDE master encryption key yet (described next), the STATUS column of the V$ENCRYPTION_WALLET view reminds you with an OPEN_NO_MASTER_KEY status.

Step 4: Set the Software TDE Master Encryption Key

Once the keystore is open, you can set a TDE master encryption key for it.

About Setting the Software TDE Master Encryption Key

The TDE master encryption key is stored in the keystore.

This key protects the TDE table keys and tablespace encryption keys. By default, the TDE master encryption key is a key that Transparent Data Encryption (TDE) generates. You can find if a keystore has no master key set or an unknown master key by querying the STATUS column of the V$ENCRYPTION_WALLET view.

In a multitenant environment, you can create and manage the TDE master encryption key from either the root or the PDB.

You also can create TDE master encryption keys for use later on, and then manually activate them.

Setting the TDE Master Encryption Key in the Software Keystore

To set the TDE master encryption key in a software keystore, use the ADMINISTER KEY MANAGEMENT statement with the SET KEY clause.

  1. For password software keystores, ensure that you complete the procedure described in Step 3: Open the Software Keystore to open the key.

    Auto-login or local auto-login software keys are opened automatically after you create them. Password-based software keystores must be open before you can set the TDE master encryption key. If the auto-login software keystore is open, then you must close it and open the password-based software keystore. If both the password-based keystore and auto-login keystores are present in the configured location and the password-based keystore is open, then the TDE master encryption key is automatically written to the auto-login keystore as well.

  2. Log in to the database instance as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.

    In a multitenant environment, log in to the root or to the PDB. For example, to log in to a PDB:

    sqlplus sec_admin@hrpdb as syskm
    Enter password: password
    Connected.
    

    To find the available PDBs, query the DBA_PDBS data dictionary view. To check the current PDB, run the show con_name command.

  3. Ensure that the database is open in READ WRITE mode.

    You can set the TDE master encryption key if OPEN_MODE is set to READ WRITE. To find the status, for a non-multitenant environment, query the OPEN_MODE column of the V$DATABASE dynamic view. If you are using a multitenant environment, then query the V$PDBS view. (If you cannot access these views, then connect as SYSDBA and try the query again. In order to connect as SYSKM for this type of query, you must create a password file for it.

  4. Connect using the SYSKM administrative privilege and then run the ADMINISTER KEY MANAGEMENT SQL statement to set the software management keystore.

    ADMINISTER KEY MANAGEMENT SET KEY [USING TAG 'tag'] [FORCE KEYSTORE] IDENTIFIED BY [EXTERNAL STORE] | keystore_password [WITH BACKUP [USING 'backup_identifier']] [CONTAINER = ALL | CURRENT];
    

    In this specification:

    • tag is the associated attributes and information that you define. Enclose this setting in single quotation marks (' ').

    • FORCE KEYSTORE enables the keystore operation if the auto-login keystore is in use, or 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 mandatory keystore password that you created when you created the keystore in Step 2: Create the Software Keystore.

    • WITH BACKUP creates a backup of the keystore. You must use this option for password-based keystores. Optionally, you can use the USING 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, with emp_key_backup being the backup identifier). Follow the file naming conventions that your operating system uses.

    • CONTAINER is for use in a multitenant environment. Enter ALL to set the key in all of the PDBs in this CDB, or CURRENT for the current PDB.

    For example, if the password-based keystore is open:

    ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY keystore_password WITH BACKUP USING 'emp_key_backup';
    
    keystore altered.

    If the auto-login keystore is open or if the keystore is closed:

    ADMINISTER KEY MANAGEMENT SET KEY FORCE KEY IDENTIFIED BY keystore_password WITH BACKUP USING 'emp_key_backup';
    
    keystore altered.

Step 5: Encrypt Your Data

After you complete the software keystore configuration, you can begin to encrypt data.

You can encrypt data in individual table columns or in entire tablespaces or databases.

Configuring a Hardware Keystore

A hardware keystore resides in a hardware security module (HSM), which is designed to store encryption keys.

About Configuring a Hardware (External) Keystore

A hardware keystore, also called an external keystore, is a separate server or device that provides security storage for encryption keys.

External keystores are external to an Oracle database. Oracle Database can interface with external keystores but cannot manipulate them outside of the Oracle interface. The Oracle database can request the external keystore to create a key but it cannot define how this key is stored in an external database. (Conversely, for software keystores that are created using TDE, Oracle Database has full control: that is, you can use SQL statements to manipulate this type of keystore.) Examples of external keystores are hardware security modules or Oracle Key Vault keystores. External keystores among multiple databases can be managed centrally, such as with Oracle Key Vault.

To configure a keystore for a hardware security module (hardware keystore), you must first include the keystore type in the sqlnet.ora file, configure and open the hardware keystore, and then set the hardware keystore TDE master encryption key. In short, there is one hardware keystore per database, and the database locates this keystore by checking the keystore type that you define in the sqlnet.ora file.

How you specify the IDENTIFIED BY clause when you run the ADMINISTER KEY MANAGEMENT statement depends on the type of hardware keystore. In most cases, and in the examples throughout this guide, you would use the following syntax for a hardware security module keystore:

IDENTIFIED BY "user_name:password"

However, depending on your site’s configuration of HSMs, the syntax for the credential may be password:user_name.

After you configure the hardware keystore, you are ready to begin encrypting your data.

Step 1: Set the Hardware Keystore Type in the sqlnet.ora File

Before you can configure a hardware keystore, you must modify the sqlnet.ora file.

By default, the sqlnet.ora file is located in the ORACLE_HOMEdbs directory or in the location set by the TNS_ADMIN environment variable.

  • Use the following setting in the sqlnet.ora file to define the hardware keystore type, which is either OKV for Oracle Key Vault or HSM for hardware security module.

    ENCRYPTION_WALLET_LOCATION=
     (SOURCE=
      (METHOD=OKV))

Step 2: Configure the Hardware Security Module

To configure a third-party hardware security module, you must copy the PKCS#11 library to the correct location and follow your vendor's instructions.

If you are using Oracle Key Vault, then you can bypass this section.
  1. Ensure that you complete the procedure described in Step 1: Set the Hardware Keystore Type in the sqlnet.ora File.

  2. Copy the PKCS#11 library to its correct path.

    Your hardware keystore vendor should provide you with an associated PKCS#11 library. Only one PKCS#11 library is supported at a time. If you want to use a hardware keystore from a new vendor, then you must replace the PKCS#11 library from the earlier vendor with the library from the new vendor.

    Copy this library to the appropriate location to ensure that Oracle Database can find this library:

    • UNIX systems: Use the following syntax to copy the library to this directory:

      /opt/oracle/extapi/[32,64]/hsm/{VENDOR}/{VERSION}/libapiname.so
      
    • Windows systems: Use the following syntax to copy the library to this directory:

      %SYSTEM_DRIVE%\oracle\extapi\[32,64]\hsm\{VENDOR}\{VERSION}\libapiname.dll
      

    In this specification:

    • [32,64] specifies whether the supplied binary is 32 bits or 64 bits.

    • VENDOR stands for the name of the vendor supplying the library

    • VERSION refers to the version of the library. This should preferably be in the format, number.number.number

    • apiname requires no special format. However, the apiname must be prefixed with the word lib, as illustrated in the syntax.

  3. Follow your vendor's instructions to set up the hardware keystore.

    Use your hardware keystore management interface and the instructions provided by your HSM vendor to set up the hardware keystore. Create the user account and password that must be used by the database to interact with the hardware keystore. This process creates and configures a hardware keystore that communicates with your Oracle database.

Step 3: Open the Hardware Keystore

After you have configured the hardware security module, you must open the hardware keystore before it can be used.

About Opening Hardware Keystores

You must open the hardware keystore so that it is accessible to the database before you can perform any encryption or decryption.

You can check the status of whether a keystore is open, closed, open but with no TDE master encryption key, or open but with an unknown master encryption key by querying the STATUS column of the V$ENCRYPTION_WALLET view.

You can either manually open a hardware keystore or, when you perform certain ADMINISTER KEY MANAGEMENT operations, have the keystore open temporarily during the course of the operation itself. Keystores can be in the following states: open, closed, open but with no master key, open but with an unknown master key, undefined, or not available (that is, not present in the sqlnet.ora location).

Opening a Hardware Keystore

To open a hardware keystore, use the ADMINISTER KEY MANAGEMENT statement with the SET KEYSTORE OPEN clause.

Before you begin this procedure, ensure that you complete the procedure described in Step 2: Configure the Hardware Security Module.
  1. Log in to the database instance as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.

    In a multitenant environment, you must open the keystore first in the root before you can open it in a PDB. For example, to log in to the root:

    sqlplus sec_admin as syskm
    Enter password: password
    Connected.
    

    To find the available PDBs, query the DBA_PDBS data dictionary view. To check the current PDB, run the show con_name command.

    If SQL*Plus is already open and you had modified the sqlnet.ora file during this time, then reconnect to SQL*Plus. The database session must be changed before the sqlnet.ora changes can take effect.

  2. Run the ADMINISTER KEY MANAGEMENT SQL statement using the following syntax:

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN [FORCE KEYSTORE] IDENTIFIED BY "user_id:password" [CONTAINER = ALL | CURRENT];
    

    In this specification:

    • FORCE KEYSTORE enables the keystore operation 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.

      • user_id:password: user_id is the user ID created for the hardware keystore; password is the password created for the hardware keystore. Enclose the user_id:password string in double quotation marks (" ") and separate user_id and password with a colon (:).

    • CONTAINER is for use in a multitenant environment. Enter ALL to set the keystore in all of the PDBs in this CDB, or CURRENT for the current PDB.

    For example:

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN FORCE KEYSTORE IDENTIFIED BY "psmith:password";
    
    keystore altered.
    

    Or, for a keystore that is stored externally:

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN FORCE KEYSTORE IDENTIFIED BY EXTERNAL STORE;
    
    keystore altered.
    
  3. Repeat this procedure each time you restart the database instance.

Step 4: Set the Hardware Keystore TDE Master Encryption Key

After you have opened the hardware keystore, you are ready to set the hardware keystore TDE master encryption key.

About Setting the Hardware Keystore TDE Master Encryption Key

You must create a TDE master encryption key that is stored inside the hardware keystore.

Oracle Database uses the TDE master encryption key to encrypt or decrypt TDE table keys or tablespace encryption keys inside the hardware security module.

If you have not previously configured a software keystore for Transparent Data Encryption, then you must set the master encryption key. If you have already configured a software keystore for TDE, then you must migrate it to the hardware security module.

Along with the current TDE master key, Oracle wallets maintain historical TDE master keys that are generated after every re-key operation that rotates the TDE master key. These historical TDE master keys help to restore Oracle database backups that were taken previously using one of the historical TDE master keys.

Setting a New TDE Master Encryption Key

You should complete this procedure if you have not previously configured a hardware keystore for Transparent Data Encryption.

In a multitenant environment, you can create and manage the TDE master encryption key from either the root or the PDB.

  1. Ensure that you complete the procedure described in Step 3: Open the Hardware Keystore.

  2. Log in to the database instance as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.

    In a multitenant environment, log in to the root or to the PDB. For example:

    sqlplus sec_admin@hrpdb as syskm
    Enter password: password
    Connected.
    

    To find the available PDBs, query the DBA_PDBS data dictionary view. To check the current PDB, run the show con_name command.

  3. Ensure that the database is open in READ WRITE mode.

    You can set the TDE master encryption key if OPEN_MODE is set to READ WRITE. To find the status, for a non-multitenant environment, query the OPEN_MODE column of the V$DATABASE dynamic view. If you are in a multitenant environment, then query the V$PDBS view. (If you cannot access these views, then connect as SYSDBA and try the query again. In order to connect as SYSKM for this type of query, you must create a password file for it.

  4. Run the following SQL statement:

    ADMINISTER KEY MANAGEMENT SET KEY [USING TAG 'tag'] [FORCE KEYSTORE] IDENTIFIED BY [EXTERNAL STORE | "user_id:password"] [CONTAINER = ALL | CURRENT];
    

    In this specification:

    • tag is the associated attributes and information that you define. Enclose this setting in single quotation marks (' ').

    • FORCE KEYSTORE enables the keystore operation 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.

      • user_id:password: user_id is the user ID created for the hardware keystore; password is the password created for the hardware keystore. Enclose the user_id:password string in double quotation marks (" ") and separate user_id and password with a colon (:).

    • CONTAINER is for use in a multitenant environment. Enter ALL to set the keystore in all of the PDBs in this CDB, or CURRENT for the current PDB.

    For example:

    ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "psmith:password";
    
    keystore altered.
Migration of a Previously Configured TDE Master Encryption Key

You must migrate the previously configured TDE master encryption key if you previously configured a software keystore.

Tools such as Oracle Data Pump and Oracle Recovery Manager require access to the old software keystore to perform decryption and encryption operations on data exported or backed up using the software keystore. You can migrate from the software to the hardware keystore by following the instructions in Migrating Between a Software Password Keystore and a Hardware Keystore.

Along with the current TDE master key, Oracle wallets maintain historical TDE master keys that are generated after every re-key operation that rotates the TDE master key. These historical TDE master keys help to restore Oracle database backups that were taken previously using one of the historical TDE master keys.

Step 5: Encrypt Your Data

After you have completed the configuration for a hardware keystore or for an Oracle Key Vault keystore, you can begin to encrypt data.

Oracle Key Vault Administrator's Guide describes how to configure Oracle Key Vault keystores.

You can encrypt individual columns in a table or entire tablespaces.

Encrypting Columns in Tables

You can use Transparent Data Encryption to encrypt individual columns in database tables.

About Encrypting Columns in Tables

You can encrypt individual columns in tables.

Whether you choose to encrypt individual columns or entire tablespaces depends on the data types that the table has. There are also several features that do not support TDE column encryption.

Data Types That Can Be Encrypted with TDE Column Encryption

Oracle Database supports a specific set of data types that can be used with TDE column encryption.

You can encrypt data columns that use a variety of different data types.

Supported data types are as follows:

  • BINARY_DOUBLE

  • BINARY_FLOAT

  • CHAR

  • DATE

  • INTERVAL DAY TO SECOND

  • INTERVAL YEAR TO MONTH

  • NCHAR

  • NUMBER

  • NVARCHAR2

  • RAW (legacy or extended)

  • TIMESTAMP (includes TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE)

  • VARCHAR2 (legacy or extended)

You cannot encrypt a column if the encrypted column size is greater than the size allowed by the data type of the column.

Table 3-1 shows the maximum allowable sizes for various data types.

Table 3-1 Maximum Allowable Size for Data Types

Data Type Maximum Size

CHAR

1932 bytes

VARCHAR2 (legacy)

3932 bytes

VARCHAR2 (extended)

32,699 bytes

NVARCHAR2 (legacy)

1966 bytes

NVARCHAR2 (extended)

16,315 bytes

NCHAR

966 bytes

RAW (extended)

32,699 bytes

Note:

TDE tablespace encryption does not have these data type restrictions.

Restrictions on Using Transparent Data Encryption Column Encryption

TDE column encryption is performed at the SQL layer. Oracle Database utilities that bypass the SQL layer cannot use TDE column encryption services.

Do not use TDE column encryption with the following database features:

  • Index types other than B-tree

  • Range scan search through an index

  • Synchronous change data capture

  • Transportable tablespaces

  • Columns that have been created as identity columns

In addition, you cannot use TDE column encryption to encrypt columns used in foreign key constraints.

Applications that must use these unsupported features can use the DBMS_CRYPTO PL/SQL package for their encryption needs.

Transparent Data Encryption protects data stored on a disk or other media. It does not protect data in transit. Use the network encryption solutions discussed in Oracle Database Security Guide to encrypt data over the network.

Creating Tables with Encrypted Columns

Oracle Database provides a selection of different algorithms that you can use to define the encryption used in encrypted columns.

About Creating Tables with Encrypted Columns

You can use the CREATE TABLE SQL statement to create a table with an encrypted column.

To create relational tables with encrypted columns, you can specify the SQL ENCRYPT clause when you define database columns with the CREATE TABLE SQL statement.

Creating a Table with an Encrypted Column Using the Default Algorithm

By default, TDE uses the AES encryption algorithm with a 192-bit key length (AES192).

If you encrypt a table column without specifying an algorithm, then the column is encrypted using the AES192 algorithm.

TDE adds salt to plaintext before encrypting it. Adding salt makes it harder for attackers to steal data through a brute force attack. TDE also adds a Message Authentication Code (MAC) to the data for integrity checking. The SHA-1 integrity algorithm is used by default.

  • To create a table that encrypts a column, use the CREATE TABLE SQL statement with the ENCRYPT clause.

    For example, to encrypt a table column using the default algorithm:

    CREATE TABLE employee (
         first_name VARCHAR2(128),
         last_name VARCHAR2(128),
         empID NUMBER,
         salary NUMBER(6) ENCRYPT);

    This example creates a new table with an encrypted column (salary). The column is encrypted using the default encryption algorithm (AES192). Salt and MAC are added by default. This example assumes that the wallet is open and a master key is set.

Note:

If there are multiple encrypted columns in a table, then all of these columns must use the same pair of encryption and integrity algorithms.

Salt is specified at the column level. This means that an encrypted column in a table can choose not to use salt irrespective of whether or not other encrypted columns in the table use salt.

Creating a Table with an Encrypted Column Using No Algorithm or a Non-Default Algorithm

You an use the CREATE TABLE SQL statement to create a table with an encrypted column.

By default, TDE adds salt to plaintext before encrypting it. Adding salt makes it harder for attackers to steal data through a brute force attack. However, if you plan to index the encrypted column, then you must use the NO SALT parameter.

  • To create a table that uses an encrypted column that is a non-default algorithm or no algorithm, run the CREATE TABLE SQL statement as follows:

    • If you do not want to use any algorithm, then include the ENCRYPT NO SALT clause.

    • If you want to use a non-default algorithm, then use the ENCRYPT USING clause, followed by one of the following algorithms enclosed in single quotation marks:

      • 3DES168

      • AES128

      • AES192 (default)

      • AES256

The following example shows how to specify encryption settings for the empID and salary columns.

CREATE TABLE employee (
     first_name VARCHAR2(128),
     last_name VARCHAR2(128),
     empID NUMBER ENCRYPT NO SALT,
     salary NUMBER(6) ENCRYPT USING '3DES168');

In this example:

  • The empID column is encrypted and does not use salt. Both the empID and salary columns will use the 3DES168 encryption algorithm, because all of the encrypted columns in a table must use the same encryption algorithm.

  • The salary column is encrypted using the 3DES168 encryption algorithm. Note that the string that specifies the algorithm must be enclosed in single quotation marks (' '). The salary column uses salt by default.

Using the NOMAC Parameter to Save Disk Space and Improve Performance

You can bypass checks that TDE performs. This can save up to 20 bytes of disk space per encrypted value.

If the number of rows and encrypted columns in the table is large, then bypassing TDE checks can add up to a significant amount of disk space. In addition, this saves processing cycles and reduces the performance overhead associated with TDE.

TDE uses the SHA-1 integrity algorithm by default. All of the encrypted columns in a table must use the same integrity algorithm. If you already have a table column using the SHA-1 algorithm, then you cannot use the NOMAC parameter to encrypt another column in the same table.

  • To bypass the integrity check during encryption and decryption operations, use the NOMAC parameter in the CREATE TABLE and ALTER TABLE statements.

Example: Using the NOMAC Parameter in a CREATE TABLE Statement

You can use the CREATE TABLE SQL statement to encrypt a table column using the NOMAC parameter.

Example 3-1 creates a table with an encrypted column. The empID column is encrypted using the NOMAC parameter.

Example 3-1 Using the NOMAC parameter in a CREATE TABLE statement

CREATE TABLE employee (
     first_name VARCHAR2(128),
     last_name VARCHAR2(128),
     empID NUMBER ENCRYPT 'NOMAC' ,
     salary NUMBER(6));
Example: Changing the Integrity Algorithm for a Table

You can use the ALTER TABLE SQL statement to change the integrity algorithm for a database table.

Example 3-2 shows how to change the integrity algorithm for encrypted columns in a table. The encryption algorithm is set to 3DES168 and the integrity algorithm is set to SHA-1. The second ALTER TABLE statement sets the integrity algorithm to NOMAC.

Example 3-2 Changing the Integrity Algorithm for a Table

ALTER TABLE EMPLOYEE REKEY USING '3DES168' 'SHA-1';

ALTER TABLE EMPLOYEE REKEY USING '3DES168' 'NOMAC';
Creating an Encrypted Column in an External Table

The external table feature enables you to access data in external sources as if the data were in a database table.

External tables can be updated using the ORACLE_DATAPUMP access driver.

  • To encrypt specific columns in an external table, use the ENCRYPT clause when you define those columns:

    A system-generated key encrypts the columns. For example, the following CREATE TABLE SQL statement encrypts the ssn column using the 3DES168 algorithm:

    CREATE TABLE emp_ext (
        first_name,
        ....
        ssn ENCRYPT USING '3DES168',
        ....
    
    

If you plan to move an external table to a new location, then you cannot use a randomly generated key to encrypt the columns. This is because the randomly generated key will not be available at the new location.

For such scenarios, you should specify a password while you encrypt the columns. After you move the data, you can use the same password to regenerate the key required to access the encrypted column data at the new location.

Table partition exchange also requires a password-based TDE table key.

Example 3-3 creates an external table using a password to create the TDE table key.

Example 3-3 Creating a New External Table with a Password-Generated TDE Table Key

CREATE TABLE emp_ext (
     first_name,
     last_name,
     empID,
     salary,
     ssn ENCRYPT IDENTIFIED BY password
)  ORGANIZATION EXTERNAL
   (
    TYPE ORACLE_DATAPUMP
    DEFAULT DIRECTORY "D_DIR"
    LOCATION('emp_ext.dat')
    )
    REJECT LIMIT UNLIMITED
AS SELECT * FROM EMPLOYEE;

Encrypting Columns in Existing Tables

You can encrypt columns in existing tables. As with new tables, you have a choice of different algorithms to use to definite the encryption.

About Encrypting Columns in Existing Tables

The ALTER TABLE SQL statement enables you to encrypt columns in an existing table.

To add an encrypted column to an existing table, or to encrypt or decrypt an existing column, you use the ALTER TABLE SQL statement with the ADD or MODIFY clause.

Adding an Encrypted Column to an Existing Table

You can encrypt columns in existing tables, use a different algorithm, and use NO SALT to index the column.

  • To add an encrypted column to an existing table, use the ALTER TABLE ADD statement, specifying the new column with the ENCRYPT clause.

Example 3-4 adds an encrypted column, ssn, to an existing table, called employee. The ssn column is encrypted with the default AES192 algorithm. Salt and MAC are added by default.

Example 3-4 Adding an Encrypted Column to an Existing Table

ALTER TABLE employee ADD (ssn VARCHAR2(11) ENCRYPT);
Encrypting an Unencrypted Column

You can use the ALTER TABLE MODIFY statement to encrypt an existing unencrypted column.

  • To encrypt an existing unencrypted column, use the ALTER TABLE MODIFY statement, specifying the unencrypted column with the ENCRYPT clause.

The following example encrypts the first_name column in the employee table. The first_name column is encrypted with the default AES192 algorithm. Salt is added to the data, by default. You can encrypt the column using a different algorithm. If you want to index a column, then you must specify NO SALT. You can also bypass integrity checks by using the NOMAC parameter.

ALTER TABLE employee MODIFY (first_name ENCRYPT);

The following example encrypts the first_name column in the employee table using the NOMAC parameter.

ALTER TABLE employee MODIFY (first_name ENCRYPT 'NOMAC');
Disabling Encryption on a Column

You may want to disable encryption for reasons of compatibility or performance.

  • To disable column encryption, use the ALTER TABLE MODIFY command with the DECRYPT clause.

Example 3-5 decrypts the first_name column in the employee table.

Example 3-5 Turning Off Column Encryption

ALTER TABLE employee MODIFY (first_name DECRYPT);

Creating an Index on an Encrypted Column

You can create an index on an encrypted column.

The column being indexed must be encrypted without salt. If the column is encrypted with salt, then the ORA-28338: cannot encrypt indexed column(s) with salt error is raised.

  • To create an index on an encrypted column, use the CREATE INDEX statement with the ENCRYPT NO SALT clause.

Example 3-6 shows how to create an index on a column that has been encrypted without salt.

Example 3-6 Creating Index on a Column Encrypted Without Salt

CREATE TABLE employee (
   first_name VARCHAR2(128),
   last_name VARCHAR2(128),
   empID NUMBER ENCRYPT NO SALT,
   salary NUMBER(6) ENCRYPT USING '3DES168');

CREATE INDEX employee_idx on employee (empID);

Adding Salt to an Encrypted Column

Salt, which is a random string added to data before encryption, is a way to strengthen the security of encrypted data. .

Salt ensures that the same plaintext data does not always translate to the same encrypted text. Salt removes the one common method that intruders use to steal data, namely, matching patterns of encrypted text. Adding salt requires an additional 16 bytes of storage per encrypted data value.

  • To add or remove salt from encrypted columns, use the ALTER TABLE MODIFY SQL statement.

For example, suppose you want to encrypt the first_name column using salt. If the first_name column was encrypted without salt earlier, then the ALTER TABLE MODIFY statement reencrypts it using salt.

ALTER TABLE employee MODIFY (first_name ENCRYPT SALT);

Removing Salt from an Encrypted Column

You can use the ALTER TABLE SQL statement to remove salt from an encrypted column.

  • To remove salt from an encrypted column, use the ENCRYPT NO SALT clause in the ALTER TABLE SQL statement.

For example, suppose you wanted to remove salt from the first_name column. If you must index a column that was encrypted using salt, then you can use this statement to remove the salt before indexing

ALTER TABLE employee MODIFY (first_name ENCRYPT NO SALT);

Changing the Encryption Key or Algorithm for Tables with Encrypted Columns

You can use the ALTER TABLE SQL statement to change the encryption key or algorithm used in encrypted columns.

Each table can have only one TDE table key for its columns. You can regenerate the TDE table key with the ALTER TABLE statement. This process generates a new key, decrypts the data in the table using the previous key, reencrypts the data using the new key, and then updates the table metadata with the new key information. You can also use a different encryption algorithm for the new TDE table key.

  • To change the encryption key or algorithm for tables that contain encrypted columns, use the ALTER TABLE SQL statement with the REKEY or REKEY USING clause.

For example:

ALTER TABLE employee REKEY;

Example 3-7 regenerates the TDE table key for the employee table by using the 3DES168 algorithm.

Example 3-7 Changing an Encrypted Table Column Encryption Key and Algorithm

ALTER TABLE employee REKEY USING '3DES168';

Encryption Conversions for Tablespaces and Databases

You can perform encryption operations on both offline and online tablespaces and databases.

About Encryption Conversions for Tablespaces and Databases

The CREATE TABLESPACE SQL statement can be used to encrypt new tablespaces. ALTER TABLESPACE can encrypt existing tablespaces.

In addition to encrypting new and existing tablespaces, you can encrypt full databases, which entails the encryption of the Oracle-supplied SYS, SYSAUX, TEMP, and UNDO tablespaces. To encrypt a full database, you use the ALTER TABLESPACE statement, not ALTER DATABASE, to encrypt the Oracle-supplied tablespaces.

The following table compares the differences between an offline and an online encryption conversion of tablespaces and databases.

Table 3-2 Offline and Online Tablespace and Database Encryption Conversions

Functionality Offline Conversion Online Conversion

Release with minimum conversion capability

Oracle Database 11g release 1 (11.1)

Oracle Database 12c release 2 (12.2)

What can be backported?

The ability to encrypt or decrypt a data file with the AES128 algorithm (using
ALTER DATABASE DATAFILE data_file ENCRYPT
or DECRYPT) can be used in Oracle Database releases 12.1.0.2 and 11.2.0.4.

No

Algorithms supported

AES128 only

All symmetric encryption algorithm that TDE supports. See About Encryption Conversions for Existing Online Tablespaces for a list of the supported algorithms.

When can the conversion be run?

When the tablespace is offline or the database is in the mount stage.

When the tablespace is online and database is open in read/write mode.

Is auxiliary space required for the conversion?

No

Yes. See Encrypting an Existing Tablespace with Online Conversion for guidelines.

Oracle Data Guard conversion guidelines

Convert both the primary and standby manually. Convert the standby first and then switch over to minimum downtime

After you convert the primary, the standby conversion takes place automatically. You cannot perform an online conversion directly on the standby.

Encrypt the SYSTEM, SYSAUX, and UNDO tablespaces (database conversion)

Oracle Database 12c release 2 (12.2) only. You must set COMPATIBILITY to 12.2.0.0.

Oracle Database 12c release 2 (12.2) only. You must set COMPATIBILITY to 12.2.0.0.

Can an existing TEMP tablespace be converted?

No, but you can create an encrypted TEMP tablespace in Oracle Database 12c release 2 (12.2), make it the default temporary tablespace, and then drop the original TEMP tablespace.

No, but you can create an encrypted TEMP tablespace in Oracle Database 12c release 2 (12.2), make it the default temporary tablespace, and then drop the original TEMP tablespace.

Can an existing tablespace be decrypted?

You only can decrypt a tablespace or data file that was previously encrypted by an offline encrypt operation. Oracle does not recommend that you decrypt the UNDO tablespace once it is encrypted.

Yes, but Oracle does not recommend that you decrypt the UNDO tablespace once it is encrypted.

Can encryption keys be rekeyed or rotated?

No, but after the tablespace is encrypted, you can then use online conversion to rekey in Oracle Database 12c release 2 (12.2) compatibility.

Yes

Can encryption operations be run in parallel?

You can run parallel encryption conversions at the data file level with multiple user sessions running.

You can run parallel encryption conversions at the tablespace level with multiple user sessions running.

What to do if an encryption conversion SQL statement fails to complete?

Re-issue the encryption or decryption SQL statement to ensure that all the data files within the tablespace are consistently either encrypted or decrypted.

Rerun the SQL statement but use the FINISH clause.

Restrictions on Using Transparent Data Encryption Tablespace Encryption

You should be aware of restrictions on using Transparent Data Encryption when you encrypt a tablespace.

Note the following restrictions:

  • Transparent Data Encryption (TDE) tablespace encryption encrypts or decrypts data during read and write operations, as opposed to TDE column encryption, which encrypts and decrypts data at the SQL layer. This means that most restrictions that apply to TDE column encryption, such as data type restrictions and index type restrictions, do not apply to TDE tablespace encryption.

  • To perform import and export operations, use Oracle Data Pump.

  • If you encrypt the SYSTEM, SYSAUX, TEMP, or UNDO tablespace, then never close the keystore manually, even if you later decrypt the tablespace by using the ALTER TABLESPACE SQL statement.

See Also:

Oracle Database Utilities for more information about Oracle Data Pump

Creating an Encrypted New Tablespace

When you create a new tablespace, you can configure its encryption settings during the creation process.

Step 1: Set the COMPATIBLE Initialization Parameter for Tablespace Encryption

You must set the COMPATIBLE initialization parameter before creating an encrypted tablespace.

About Setting the COMPATIBLE Initialization Parameter for Tablespace Encryption

A minimum COMPATIBLE initialization parameter setting of 11.2.0.0 enables the full set of tablespace encryption features.

Setting the compatibility to 11.2.0.0 enables the following functionality:

  • The 11.2.0.0 setting enables the database to use any of the four supported algorithms for data encryption (3DES168, AES128, AES192, and AES256).

  • The 11.2.0.0 setting enables the migration of a key from a software keystore to a hardware keystore (ensure that the TDE master encryption key was configured for the hardware keystore)

  • The 11.2.0.0 setting enables resetting and rotating the TDE master encryption key

Be aware that once you set the COMPATIBLE parameter to 11.2.0.0, the change is irreversible. To use tablespace encryption, ensure that the compatibility setting is at the minimum, which is 11.2.0.0.

See Also:

Setting the COMPATIBLE Initialization Parameter for Tablespace Encryption

To set the COMPATIBLE initialization parameter, you must edit the initialization parameter file for the database instance.

  1. Log in to the database instance.

    In a multitenant environment, log in to the PDB. For example:

    sqlplus sec_admin@hrpdb
    Enter password: password
    Connected.
    

    To find the available PDBs, query the DBA_PDBS data dictionary view. To check the current PDB, run the show con_name command.

  2. Check the current setting of the COMPATIBLE parameter.

    For example:

    SHOW PARAMETER COMPATIBLE
     
    NAME                                 TYPE        VALUE
    ------------------------------------ ----------- ------------------------------
    compatible                           string      11.2.0.0
    noncdbcompatible                     BOOLEAN     FALSE
    
  3. If you must change the COMPATIBLE parameter, then complete the remaining steps in this procedure.

    The value should be 11.2.0.0 or higher.

  4. From the command line, locate the initialization parameter file for the database instance.

    • UNIX systems: This file is in the ORACLE_HOME/dbs directory and is named initORACLE_SID.ora (for example, initmydb.ora).

    • Windows systems: This file is in the ORACLE_HOME\database directory and is named initORACLE_SID.ora (for example, initmydb.ora).

  5. Edit the initialization parameter file to use the new COMPATIBLE setting.

    For example:

    compatible=12.2.0.0.0
  6. In SQL*Plus, connect as a user who has the SYSDBA administrative privilege, and then restart the database.

    For example:

    CONNECT /AS SYSDBA
    SHUTDOWN
    STARTUP
    

    If tablespace encryption is in use, then open the keystore at the database mount. The keystore must be open before you can access data in an encrypted tablespace.

    For example:

    STARTUP MOUNT;
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY keystore_password;
    ALTER DATABASE OPEN;
Step 2: Set the Tablespace TDE Master Encryption Key

You should ensure that you have configured the TDE master encryption key.

Step 3: Create the Encrypted Tablespace

After you have set the COMPATIBLE initialization parameter, you are ready to create the encrypted tablespace.

About Creating Encrypted Tablespaces

To create an encrypted tablespace, you can use the CREATE TABLESPACE SQL statement.

You must have the CREATE TABLESPACE system privilege to create an encrypted tablespace.

You can import data into an encrypted tablespace by using Oracle Data Pump. You can also use a SQL statement such as CREATE TABLE...AS SELECT... or ALTER TABLE...MOVE... to move data into an encrypted tablespace. The CREATE TABLE...AS SELECT... statement creates a table from an existing table. The ALTER TABLE...MOVE... statement moves a table into the encrypted tablespace.

For security reasons, you cannot encrypt a tablespace with the NO SALT option.

You can query the ENCRYPTED column of the DBA_TABLESPACES and USER_TABLESPACES data dictionary views to verify if a tablespace was encrypted.

See Also:

Oracle Database Reference for more information about the DBA_TABLESPACES and USER_TABLESPACES data dictionary views

Creating an Encrypted Tablespace

To create an encrypted tablespace, you must use the CREATE TABLESPACE statement with the ENCRYPTION USING clause.

  1. Log in to the database instance as a user who has been granted the CREATE TABLESPACE system privilege.

    In a multitenant environment, log in to the PDB. For example:

    sqlplus sec_admin@hrpdb as syskm
    Enter password: password
    Connected.
    

    To find the available PDBs, query the DBA_PDBS data dictionary view. To check the current PDB, run the show con_name command.

  2. Run the CREATE TABLESPACE statement, using its encryption clauses.

    For example:

    CREATE TABLESPACE encrypt_ts
      DATAFILE '$ORACLE_HOME/dbs/encrypt_df.dbf' SIZE 1M
      ENCRYPTION USING 'AES256' ENCRYPT;
    

    In this specification:

    • ENCRYPTION USING 'AES256' ENCRYPT specifies the encryption algorithm and the key length for the encryption. The ENCRYPT clause encrypts the tablespace. Enclose this setting in single quotation marks (' '). The key lengths are included in the names of the algorithms. If you do not specify an encryption algorithm, then the default encryption algorithm, AES128, is used.

Example: Creating an Encrypted Tablespace That Uses AES192

You can use the CREATE TABLESPACE SQL statement to create an encrypted tablespace.

Example 3-8 creates a tablespace called securespace_1 that is encrypted using the 3DES algorithm. The key length is 168 bits.

Example 3-8 Creating an Encrypted Tablespace That Uses AES192

CREATE TABLESPACE securespace_1
DATAFILE '/home/user/oradata/secure01.dbf'
SIZE 150M
ENCRYPTION USING 'AES192' ENCRYPT;
Example: Creating an Encrypted Tablespace That Uses the Default Algorithm

You can use the CREATE TABLESPACE SQL statement to create an encrypted tablespace that uses the default algorithm.

Example 3-9 creates a tablespace called securespace_2. Because no encryption algorithm is specified, the default encryption algorithm (AES128) is used. The key length is 128 bits.

You cannot encrypt an existing tablespace.

Example 3-9 Creating an Encrypted Tablespace That Uses the Default Algorithm

CREATE TABLESPACE securespace_2
DATAFILE '/home/user/oradata/secure01.dbf'
SIZE 150M
ENCRYPTION ENCRYPT;

Encrypting Future Tablespaces

You can configure Oracle Database to automatically encrypt future tablespaces that you will create.

About Encrypting Future Tablespaces

The ability to encrypt future tablespaces can help prevent data breaches in Oracle Cloud environments.

The ENCRYPT_NEW_TABLESPACES database initialization parameter controls how future databases are encrypted.

You can create and run an Oracle database completely in Oracle Cloud. Because this configuration hosts the customer’s data in the Cloud, Oracle recommends that you enable encryption as much as possible. A long-term goal is to encrypt all data in Oracle Cloud. Alternatively, you can have the database both in the Cloud and on premises.

In an Oracle Cloud environment, the following scenarios may occur when you create encrypted tablespaces in Oracle Cloud and on-premises environments:

  • You create a test database in Oracle Cloud and the tablespaces were encrypted by using when the ENCRYPT_NEW_TABLESPACE parameter has been set to automatically create the Cloud database as encrypted. However, you may not have the intention or even an Advanced Security Option license to bring the encrypted database back on premises.

  • You create a hybrid definer’s rights environment where the primary database is on premises and the standby database is on Oracle Cloud. If a switchover operation takes place, then the new primary is on Oracle Cloud. If a new tablespace is transparently encrypted, then a similar scenario to the first item in this list may occur. For example, suppose you do not have an Advanced Security Option (ASO) license, and you have an automatically encrypted tablespace in the Oracle Cloud. The standby database on premises is also automatically encrypted. In this case, because you do not have an ASO license, you cannot use the standby database. To remedy this problem, set the ENCRYPT_NEW_TABLESPACES to DDL, which prevents the encryption of the tablespace in Oracle Cloud.

Setting Future Tablespaces to be Encrypted

You can set the ENCRYPT_NEW_TABLESPACES database initialization parameter to automatically encrypt future tablespaces that you create.

  • In SQL*Plus, enter the following ALTER SYSTEM statement:
    ALTER SYSTEM SET ENCRYPT_NEW_TABLESPACES = value;

    In this specification, value can be:

    • CLOUD_ONLY transparently encrypts the tablespace in the Cloud using the AES128 algorithm if you do not specify the ENCRYPTION clause of the CREATE TABLESPACE SQL statement. It applies only to an Oracle Cloud environment. If you create the tablespace on premise, then it will follow the CREATE TABLESPACE statement specification that you enter. For example, if you omit the ENCRYPTION clause, then the tablespace is created unencrypted. If you include this clause and use a different algorithm, then the tablespace will use that algorithm. CLOUD_ONLY is the default.

    • ALWAYS automatically encrypts the tablespace using the AES128 algorithm if you omit the ENCRYPTION clause of CREATE TABLESPACE, for both the Cloud and premises scenarios.

      If you do provide the ENCRYPTION clause, however, the algorithm that you specify takes precedence over AES128.
    • DDL encrypts the tablespace using the specified setting of the ENCRYPTION clause of CREATE TABLESPACE, for both Oracle Cloud and on-premise environments.

Encryption Conversions for Existing Offline Tablespaces

You can perform offline encryption conversions by using the ALTER TABLESPACE SQL statement OFFLINE, ENCRYPT, and DECRYPT clauses.

About Encryption Conversions for Existing Offline Tablespaces

You can encrypt or decrypt an existing data file of a user tablespace when the tablespace is offline or when the database is not open.

Use the offline encryption method if you do not plan to change the compatibility of your databases from Oracle Database 11g release 2 (11.2) or Oracle Database 12c release 1 (12.1) to Release 12.2, which is irreversible. The offline encryption method is also useful if you want to quickly make use of Transparent Data Encryption before you upgrade this database to release 12.2. You can both encrypt and decrypt offline tablespaces.

Note the following:

  • If you want to encrypt the Oracle Database-supplied tablespaces (SYSTEM, SYSAUX, and UNDO) using the offline conversion method, then you must use the method that is described in Encrypting an Existing Database with Offline Conversion.

  • You can use the online method to rekey a tablespace that was previously encrypted with the offline method.

  • If you have configured Oracle Data Guard, you can minimize downtime by encrypting the tablespaces on the standby first, switching over to the primary, and then encrypting the tablespaces on the primary.

  • You cannot specify the encryption algorithm in an offline conversion. In an offline conversion, all data files and tablespaces are encrypted using the AES128 encryption key. You can check the encryption key by querying the ENCRYPTIONALG column in the V$DATABASE_KEY_INFO view.

  • You can convert offline tablespaces in parallel by using multiple foreground sessions to encrypt different data files.

  • If you are using Oracle Data Guard, you can minimize the downtime by encrypting the tablespaces on the standby first, switching over, and then encrypting the tablespaces on the original primary next.

  • For Oracle Database 11g release 2 (11.2.0.4) and Oracle Database 12c release 1 (12.1.0.2), you cannot perform an offline encryption of the SYSTEM and SYSAUX tablespaces. Also, Oracle does not recommend encrypting offline the UNDO tablespace in these releases. Doing so prevents the keystore from being closed, and this prevents the database from functioning. In addition, encrypting the UNDO tablespace while the database is offline is not necessary because all undo records that are associated with any encrypted tablespaces are already automatically encrypted in the UNDO tablespace. If you want to encrypt the TEMP tablespace, you must drop and then recreate it as encrypted.

Encrypting an Existing User-Defined Tablespace with Offline Conversion

To encrypt an existing tablespace with offline conversion, you can use the ALTER TABLESPACE SQL statement with the OFFLINE and ENCRYPT clauses.

The procedure that is described in this section applies to the case where you want to encrypt individual user-created tablespaces within a database. These tablespaces can be encrypted offline. However, the Oracle Database-supplied SYSTEM and UNDO tablespaces cannot be brought offline. If you want to encrypt the tablespaces offline, then you must use the method that is described in Encrypting an Existing Database with Offline Conversion.
  1. Connect as a user who has the SYSDBA administrative privilege.

    For example:

    sqlplus sec_admin as sysdba
    Enter password: password

    You must have the SYSDBA administrative privilege if you plan to encrypt the SYSTEM and SYSAUX tablespaces. Otherwise, connect with the SYSKM administrative privilege.

  2. Bring the tablespace offline.
    ALTER TABLESPACE users OFFLINE NORMAL;
  3. Back up the tablespace.

    The offline conversion method does not use auxiliary disk space or files, and it operates directly in-place to the data files. Therefore, you should perform a full backup of the user tablespace before converting it offline.

  4. As a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege, open the software keystore.
    For example:
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY software_keystore_password; 
  5. Encrypt the tablespace.
    For example, to encrypt an entire tablespace, include its data files:
    ALTER TABLESPACE users ENCRYPTION OFFLINE ENCRYPT; 
    To encrypt individual data files within a tablespace, use the ALTER DATABASE DATAFILE SQL statement. For example, to encrypt the data files user_01.dbf and user_02.dbf:
    ALTER DATABASE DATAFILE 'user_01.dbf' ENCRYPT;
    ALTER DATABASE DATAFILE 'user_02.dbf' ENCRYPT;

    In the same database session, these statements encrypt each of the data files in sequence, one after another. If you execute each statement in its own database session, then they will be executed in parallel.

    If the encryption process is interrupted, then rerun the ALTER TABLESPACE statement. The kinds of errors that you can expect in an interruption are general errors, such as file system or storage file system errors. The data files within the tablespace should be consistently encrypted. For example, suppose you offline a tablespace that has 10 files but for some reason, the encryption only completes for nine of the files, leaving one decrypted. Although it is possible to bring the tablespace back online with such inconsistent encryption if the COMPATIBLE parameter is set to 12.2.0.0 or higher, then it is not recommended to leave the tablespace in this state. If COMPATIBLE is less than 12.2.0.0, then it is not possible to bring the tablespace online if the encryption property is inconsistent across the data files.
  6. Bring the tablespace back online or open the database.
    • To bring the tablespace back online:
      ALTER TABLESPACE users ONLINE;
    • To open a database in a non-multitenant environment:

      ALTER DATABASE OPEN
    • In a multitenant environment, you can encrypt a data file or tablespace with the offline method if the root is open and the PDB is not open. For example, for a PDB named hr_pdb:

      ALTER PLUGGABLE DATABASE hr_pdb OPEN
Decrypting an Existing Tablespace with Offline Conversion

To decrypt an existing tablespace with offline conversion, you can use the ALTER TABLESPACE SQL statement with the OFFLINE and DECRYPT clauses.

  1. Connect as a user who has the SYSDBA administrative privilege.

    For example:

    sqlplus sec_admin as sysdba
    Enter password: password

    You must have the SYSDBA administrative privilege if you plan to decrypt the SYSTEM and SYSAUX tablespaces. Otherwise, connect with the SYSKM administrative privilege.

  2. Bring the tablespace offline.
    ALTER TABLESPACE users OFFLINE NORMAL;
  3. As a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege, open the keystore.
    For example:
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY software_keystore_password; 
  4. Run the ALTER TABLESPACE SQL statement to perform the decryption.
    For example, for a tablespace called users:
    ALTER TABLESPACE users ENCRYPTION OFFLINE DECRYPT; 

    If the decryption process is interrupted, then rerun the ALTER TABLESPACE statement. The kinds of errors that you can expect in an interruption are general errors, such as file system or storage file system errors. The data files within the tablespace should be consistently decrypted. For example, suppose you offline a tablespace that has 10 files but for some reason, the decryption only completes for nine of the files, leaving one encrypted. Although it is possible to bring the tablespace back online with such inconsistent decryption if the COMPATIBLE parameter is set to 12.2.0.0 or higher, then it is not recommended to leave the tablespace in this state. If COMPATIBLE is less than 12.2.0.0, then it is not possible to bring the tablespace online if the encryption property is inconsistent across the data files.

  5. Bring the tablespace online.
    ALTER TABLESPACE users ONLINE;

Encryption Conversions for Existing Online Tablespaces

You can encrypt and decrypt an online existing tablespace by using the ALTER TABLESPACE SQL statement with the OFFLINE and ENCRYPT or DECRYPT clauses.

Encrypting an Existing Tablespace with Online Conversion

To encrypt an existing tablespace with online conversion, use ALTER TABLESPACE with the ONLINE and ENCRYPT clauses.

  1. Connect as a user who has the SYSDBA administrative privilege.

    For example:

    sqlplus sec_admin as sysdba
    Enter password: password

    You must have the SYSDBA administrative privilege if you plan to encrypt the SYSTEM and SYSAUX tablespaces. Otherwise, connect with the SYSKM administrative privilege.

  2. Ensure that the COMPATIBLE initialization parameter is set to 12.2.0.0.

    You can use the SHOW PARAMETER command to check the current setting of a parameter.

  3. Ensure that the database is open in read-write mode.

    You can query the STATUS column of the V$INSTANCE dynamic view to find if a database is open and the OPEN_MODE column of the V$DATABASE view to find if it in read-write mode.

  4. If necessary, open the database in read-write mode.
    ALTER DATABASE OPEN READ WRITE;
  5. Ensure that the auxiliary space is at least the same size as the largest data file of this tablespace.

    This size requirement is because Oracle Database performs the conversion one file at a time. For example, if the largest data file of the tablespace is 32 GB, then ensure that you have 32 GB of auxiliary space. To find the space used by a data file, query the BYTES or BLOCKS column of the V$DATAFILE dynamic performance view.

  6. Create and open a master encryption key.

    For example:

    ADMINISTER KEY MANAGEMENT CREATE KEYSTORE 'keystore_location' IDENTIFIED BY software_keystore_password;
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY software_keystore_password;
    ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY software_keystore_password WITH BACKUP;
  7. Run the ALTER TABLESPACE statement using the ENCRYPTION and ENCRYPT clauses to perform the encryption.

    For example, for a non-Oracle managed files tablespace named users:

    ALTER TABLESPACE users ENCRYPTION ONLINE USING 'AES192' ENCRYPT FILE_NAME_CONVERT = ('users.dbf', 'users_enc.dbf');

    In this example:

    • ENCRYPTION ONLINE USING ‘AES192’ ENCRYPT sets the statement to encrypt the tablespace users while it is online and assigns it the AES192 encryption algorithm. If you omit the USING algorithm clause, then the default algorithm, AES128, is used. For the SYSTEM and UNDO tablespaces, you can use the ENCRYPT clause to encrypt the tablespace, but you cannot specify an encryption algorithm because they must be encrypted with the existing database key the first time. After encrypting the tablespace, use the REKEY clause to specify the algorithm.

    • FILE_NAME_CONVERT specifies one or more pairs of data files that are associated with the tablespace. The first name in the pair is an existing data file, and the second name is for the encrypted version of this data file, which will be created after the ALTER TABLESPACE statement successfully executes. If the tablespace has more than one data file, then you must process them all in this statement. Note the following:

      • Separate each file name with a comma, including multiple pairs of files. For example:

        FILE_NAME_CONVERT = ('users1.dbf', 'users1_enc.dbf', 'users2.dbf', 'users2_enc.dbf')
      • You can specify directory paths in the FILE_NAME_CONVERT clause. For example, the following clause converts and moves the matching files of the tablespace from the dbs directory to the dbs/enc directory:

        FILE_NAME_CONVERT = ('dbs', 'dbs/enc')
      • The FILE_NAME_CONVERT clause recognizes patterns. The following example converts the data files users_1.dbf and users_2.dbf to users_enc1.dbf and users_enc2.dbf:

        FILE_NAME_CONVERT = ('users', 'users_enc')
      • In an Oracle Data Guard environment, include the name of the standby database data file in the FILE_NAME_CONVERT settings.

      • You must use the FILE_NAME_CONVERT clause for non-Oracle managed files. (In an Oracle-managed files configuration, new data files are created automatically.)

      • You can find the data files for a tablespace by querying the V$DATAFILE or V$DATAFILE_HEADER dynamic views.

      By default, data files are in the $ORACLE_HOME/dbs directory. If the data files are located there, then you do not have to specify a path.

After you complete the conversion, you can check the encryption status by querying the STATUS column of the V$ENCRYPTED_TABLESPACES dynamic view. The ENCRYPTIONALG column of this view shows the encryption algorithm that is used. If the conversion process was interrupted, then you can resume it by running ALTER TABLESPACE with the FINISH clause. For example, if the primary data file converts but the standby data file does not, then you can run ALTER TABLESPACE ... FINISH on the standby database for the standby data files.
About Encryption Conversions for Existing Online Tablespaces

You can encrypt, decrypt, or rekey existing user tablespaces, and the SYSTEM, SYSAUX, and UNDO tablespace when they are online.

However, you cannot encrypt, decrypt, or rekey a temporary tablespace online.

An online tablespace can be created by using the ONLINE clause of the CREATE TABLESPACE SQL statement. When you encrypt or rekey a tablespace online, the tablespace will have its own independent encryption keys and algorithms.

Note the following:

  • If an offline tablespace has been encrypted, then you can rekey it online to use a different algorithm.

  • You can encrypt multiple tablespaces online in parallel by using multiple foreground sessions to encrypt different tablespaces. Within each tablespace, the data files are encrypted sequentially.

  • If the conversion is interrupted, then you can resume the process by issuing the FINISH clause of the ALTER TABLESPACE SQL statement.

  • A redo log is generated for each online tablespace conversion.

  • Do not encrypt the SYSTEM and UNDO tablespaces concurrently with other tablespaces.

  • You cannot use the transportable tablespace feature with Oracle Data Pump while you are encrypting a tablespace.

  • You cannot run the ALTER TABLESPACE statement concurrently with the following features:
    • ADMINSTER KEY MANAGEMENT SET KEY SQL statement

    • FLASHBACK DATABASE SQL statement

  • If you are using Oracle-managed files for the data files, then the encryption process rekeys the data files that are associated with the tablespace and then copies or moves them to the default Oracle-managed files location.

  • You can add new files to the tablespace after you have encrypted it. Oracle Database reformats the new file with the new encryption key. Blocks will be encrypted using the new key.

  • Previous operations that took place in the root or the PDB may require the control files to be cross-checked against the data dictionary before you can begin the online conversion process. An ORA-241 operation disallowed: control file is not yet checked against data dictionary error may occur. To resolve this problem, restart the root or PDB, and then try issuing the online conversion commands again.

Rekeying an Existing Tablespace with Online Conversion

To rekey an existing tablespace that is online, you can use the REKEY clause of the ALTER TABLESPACE SQL statement.

Before you perform a rekey operation, be aware of the following:
  • You cannot rekey the TEMP tablespace. If you want to assign a different encryption algorithm to a TEMP tablespace, then drop TEMP and recreate it with the correct encryption algorithm.

  • Do not perform an online tablespace rekey operation with a master key operation concurrently. To find if any tablespaces are currently being rekeyed, issue the following query to find the rekey status of encrypted tablespaces:

    SELECT TS#,ENCRYPTIONALG,STATUS FROM V$ENCRYPTED_TABLESPACES;

    A status of REKEYING means that the corresponding tablespace is still being rekeyed. Do not rekey the master key while this status is in effect.

To rekey an existing tablespace with online conversion:

  1. Connect as a user who has the SYSDBA administrative privilege.

    For example:

    sqlplus sec_admin as sysdba
    Enter password: password

    You must have the SYSDBA administrative privilege if you plan to rekey the SYSTEM and SYSAUX tablespaces. Otherwise, connect with the SYSKM administrative privilege.

  2. Ensure that the following requirements are met:
    • The COMPATIBLE initialization parameter is set to 12.2.0.0.
    • The database is open and in read-write mode.
    • A master encryption key has been created and is open.
  3. Query the KEY_VERSION and STATUS columns of the V$ENCRYPTED_TABLESPACES dynamic view to find the current status of the encryption algorithm used by the master encryption key.
  4. Perform the rekey operation, based on the status returned by the V$ENCRYPTED_TABLESPACES dynamic view:
    • If the key version status of the tablespace is NORMAL, then specify the new algorithm of the online tablespace rekey.

      For example:

      ALTER TABLESPACE users ENCRYPTION USING 'AES192' REKEY FILE_NAME_CONVERT = ('users.dbf', 'users_enc.dbf');
    • If the key version status is ENCRYPTING, DECRYPTING, or REKEYING, then use the FINISH clause.

      For example:

      ALTER TABLESPACE users ENCRYPTION ONLINE FINISH REKEY FILE_NAME_CONVERT = ('users.dbf', 'users_enc.dbf');
  5. If the ORA-00241 operation disallowed: control file inconsistent with data dictionary error appears, then restart the database.
    In a multitenant environment, restart the CDB root database and then retry Step 4.
If the conversion process was interrupted, then you can resume it by running ALTER TABLESPACE with the FINISH clause.
Decrypting an Existing Tablespace with Online Conversion

To decrypt an existing tablespace with online conversion, you can use the ALTER TABLESPACE SQL statement with DECRYPT clause.

  1. Connect as a user who has the SYSDBA administrative privilege.

    For example:

    sqlplus sec_admin as sysdba
    Enter password: password

    You must have the SYSDBA administrative privilege if you plan to decrypt the SYSTEM and SYSAUX tablespaces. Otherwise, connect with the SYSKM administrative privilege.

  2. Ensure that the following requirements are met:
    • The COMPATIBLE initialization parameter is set to 12.2.0.0.
    • The database is open and in read-write mode.
    • A master encryption key has been created and is open.
    • There is enough auxiliary space to complete the decryption.
  3. Run the ALTER TABLESPACE SQL statement with the DECRYPT clause.

    For example:

    ALTER TABLESPACE users ENCRYPTION ONLINE DECRYPT FILE_NAME_CONVERT = ('users_enc.dbf', 'users.dbf');

    In this specification:

    • When you specify the files to decrypt, enter them in the reverse order in which they were originally encrypted. That is, first enter the name of the encrypted file (users_enc.dbf), followed by the data file (users.dbf).

    • Do not provide an algorithm key for the decryption.

If the conversion process was interrupted, then you can resume it by running ALTER TABLESPACE with the FINISH clause.
Finishing an Interrupted Online Encryption Conversion

If an online encryption process is interrupted, then you can complete the conversion by rerunning the ALTER TABLESPACE statement using the FINISH clause.

An interrupted encryption process (encryption, rekey, or decryption) can be, for example, an ORA-28425: missing a valid FILE_NAME_CONVERT clause error in the FILE_NAME_CONVERT clause of the ALTER TABLESPACE SQL statement. Other examples of interrupted processes are if the conversion skips a data file, which can happen if there is an error when an Oracle DataBase WRiter (DBWR) process offlines a data file, or if there is not enough space for the auxiliary file. The tablespace should be operational even if you do not rerun the ALTER TABLESPACE statement with the FINISH clause.
  1. Query the V$ENCRYPTED_TABLESPACES to check the STATUS column for the tablespace.

    If the STATUS column reports ENCRYPTING, DECRYPTING, or REKEYING, then re-run the ALTER TABLESPACE statement with the FINISH clause, as described in this procedure. If the STATUS reports NORMAL, then you can rerun ALTER TABLESPACE without the FINISH clause.

    You can find the tablespace name that matches the TS# and TABLESPACE_NAME columns by querying the V$DATAFILE_HEADER view.

  2. If necessary query the following additional views to find information about the tablespace whose online conversion was interrupted:
    • DBA_TABLESPACES to find if the STATUS of the tablespace indicates if it is online or offline.
    • V$ENCRYPTED_TABLESPACES to find if the STATUS of the tablespace indicates if it is encrypted, and what the KEY_VERSION of the encryption key is.
    • V$DATAFILE and V$DATAFILE_HEADER to find the data files that are associated with a tablespace.
  3. Run the ALTER TABLESPACE statement using the FINISH clause.
    Examples are as follows:
    • For an encryption operation:
      ALTER TABLESPACE users ENCRYPTION ONLINE FINISH ENCRYPT FILE_NAME_CONVERT = ('users.dbf', 'users_enc.dbf');
    • For a decryption operation:
      ALTER TABLESPACE users ENCRYPTION ONLINE FINISH DECRYPT FILE_NAME_CONVERT = ('users_enc.dbf', 'users.dbf');

      Note the order in which the files are specified: first, the name of the encrypted file, and then the name of the data file. (In the encryption operation, the name of the data file is specified first, followed by the name of the encrypted file.)

    • For a rekey operation:
      ALTER TABLESPACE users ENCRYPTION ONLINE FINISH REKEY FILE_NAME_CONVERT = ('users.dbf', 'users_enc.dbf');
      You cannot specify an algorithm when you use the FINISH clause in an ALTER TABLESPACE statement.
  4. To check the conversion, query the STATUS column of the V$ENCRYPTED_TABLESPACES view.
    The status should be NORMAL. In an Oracle Data Guard environment, if the database does not have NORMAL as the STATUS, then run the ALTER TABLESPACE ... FINISH statement on the primary or the standby data file that did not successfully convert.

Encryption Conversions for Existing Databases

You can encrypt both offline and online databases.

About Encryption Conversions for Existing Databases

The encryption conversion of an entire database encrypts all tablespaces, including the Oracle-supplied SYSTEM, SYSAUX, UNDO, and TEMP tablespaces.

Note the following:

  • To perform the encryption, you can use the offline and online functionality of the tablespace encryption conversions.

  • You can encrypt any or all of the Oracle-supplied tablespaces, and in any order. The encryption of the Oracle-supplied tablespaces has no impact on the encryption of user-created tablespaces.

  • When you encrypt the Oracle-supplied tablespaces, Oracle Database prevents the keystore from being closed.

  • You cannot encrypt an existing temporary tablespace, but you can drop the existing temporary tablespace and then recreate it as encrypted.

  • The UNDO and TEMP metadata that is generated from sensitive data in an encrypted tablespace is already automatically encrypted. Therefore, encrypting UNDO and TEMP is optional.

  • Oracle recommends that you encrypt the Oracle-supplied tablespaces by using the default tablespace encryption algorithm, AES128. However, you can rekey any of these tablespaces afterwards to use a different encryption algorithm if you want. (To find the current encryption key for the current database, you can query the V$DATABASE_KEY_INFO dynamic view.)

  • The performance effect of encrypting all the tablespaces in a database depends on the workload and platform. Many modern CPUs provide built-in hardware acceleration, which results in a minimal performance impact.

  • In a multitenant environment, you can encrypt any tablespaces in any pluggable databases (PDBs), including the Oracle-supplied tablespaces. However, the keystore in the CDB root must be open at all times so that a PDB can open its keystore. You can check the status of whether a keystore is open by querying the STATUS column of the V$ENCRYPTION_WALLET view

Encrypting an Existing Database with Offline Conversion

When you encrypt an existing database with offline conversion, you do not specify an encryption algorithm.

  1. Connect as a user who has the SYSDBA administrative privilege.

    For example:

    sqlplus sec_admin as sysdba
    Enter password: password

    You must have the SYSDBA administrative privilege to encrypt the SYSTEM and SYSAUX tablespaces.

  2. Mount the database.
    STARTUP MOUNT
  3. Open the keystore.
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY keystore_password;
  4. Run the ALTER TABLESPACE SQL statement to encrypt the SYSTEM, SYSAUX, and UNDO tablespaces. Do not specify an algorithm, and do not encrypt the SYSTEM tablespace concurrently with the encryption of other tablespaces.

    For example, to encrypt the SYSTEM tablespace:

    ALTER TABLESPACE SYSTEM ENCRYPTION OFFLINE ENCRYPT;
  5. Open the database.
    For example, to open the database in read/write mode:
    ALTER DATABASE OPEN READ WRITE;
  6. For a temporary tablespace, drop it and then recreate it as encrypted. Do not specify an algorithm.

    For example, for a user-created tablespace:

    DROP TABLESPACE temp_01;
    CREATE TEMPORARY TABLESPACE temp_01 
    TEMPFILE 'temp01.dbf' SIZE 5M AUTOEXTEND ON 
    ENCRYPTION ENCRYPT;

    You cannot drop the default TEMP tablespace. You must first create a new tablespace and make it the default before you can drop TEMP.

    For example:

    CREATE TEMPORARY TABLESPACE temp_01 
    TEMPFILE 'temp01.dbf' SIZE 5M AUTOEXTEND ON 
    ENCRYPTION ENCRYPT;
    
    ALTER DATABASE DEFAULT TEMPORARY TABLESPACE temp_01;
    
    DROP TABLESPACE TEMP;
  7. Run the ALTER TABLESPACE SQL statement to encrypt other user tablespaces. Alternatively, you can proceed to the next step and open the database first, and then perform the steps described in Encrypting an Existing User-Defined Tablespace with Offline Conversion.
  8. Open the database.
    ALTER DATABASE OPEN;

See Rotating the TDE Master Encryption Key for a Tablespace if you want to change the encryption algorithm of the tablespace.

Encrypting an Existing Database with Online Conversion

When you encrypt an existing database with online conversion, you do not specify an encryption algorithm.

The reason that you do not need to specify an encryption algorithm the first time you perform the encryption is that the tablespaces that you must use to encrypt the database are automatically encrypted with the database key. If you want to change the algorithm, then you can issue the ALTER TABLESPACE ENCRYPTION REKEY SQL statement after the initial encryption.
  1. Perform the following tasks, which are described in Encrypting an Existing Tablespace with Online Conversion:
    1. Connect as a user who has been granted the SYSDBA administrative privilege.
    2. Ensure that the COMPATIBLE parameter is set to 12.2.0.0.
    3. Ensure that the database is open in read-write mode.
    4. Ensure that you have enough auxiliary space to complete the encryption.
    5. Back up the tablespaces that you must encrypt.
    6. Open the keystore.
  2. Run the ALTER TABLESPACE SQL statement to encrypt the SYSTEM, SYSAUX, and UNDO tablespaces. Do not specify an algorithm, and do not encrypt the SYSTEM tablespace concurrently with the encryption of other tablespaces.

    For example, to encrypt the SYSTEM tablespace:

    ALTER TABLESPACE SYSTEM ENCRYPTION ONLINE ENCRYPT 
    FILE_NAME_CONVERT=('system01.dbf','system01_enc.dbf');
  3. For a temporary tablespace, drop it and then recreate it as encrypted. Do not specify an algorithm.

    For example, for a user-created tablespace:

    DROP TABLESPACE temp_01;
    CREATE TEMPORARY TABLESPACE temp_01 
    TEMPFILE 'temp01.dbf' SIZE 5M AUTOEXTEND ON 
    ENCRYPTION ENCRYPT;

    You cannot drop the default TEMP tablespace. You must first create a new tablespace and make it the default before you can drop TEMP.

    For example:

    CREATE TEMPORARY TABLESPACE temp_01 
    TEMPFILE 'temp01.dbf' SIZE 5M AUTOEXTEND ON 
    ENCRYPTION ENCRYPT;
    
    ALTER DATABASE DEFAULT TEMPORARY TABLESPACE temp_01;
    
    DROP TABLESPACE TEMP;

Transparent Data Encryption Data Dynamic and Data Dictionary Views

You can query a set of dynamic and data dictionary views to find more information about Transparent Data Encryption (TDE) data.

Table 3-3 describes these dynamic and data dictionary views.

Table 3-3 Transparent Data Encryption Related Views

View Description

ALL_ENCRYPTED_COLUMNS

Displays encryption information about encrypted columns in the tables accessible to the current user

DBA_ENCRYPTED_COLUMNS

Displays encryption information for all of the encrypted columns in the database

USER_ENCRYPTED_COLUMNS

Displays encryption information for encrypted table columns in the current user's schema

DBA_TABLESPACE_USAGE_METRICS

Describes tablespace usage metrics for all types of tablespaces, including permanent, temporary, and undo tablespaces

V$CLIENT_SECRETS

Lists the properties of the strings (secrets) that were stored in the keystore for various features (clients).

In a multitenant environment, when you query this view in a PDB, then it displays information about keys that were created or activated for the current PDB. If you query this view in the root, then it displays this information about keys for all of the PDBs.

V$DATABASE_KEY_INFO

Displays information about the default encryption key that is used for the current database. The default is AES128.

V$ENCRYPTED_TABLESPACES

Displays information about the tablespaces that are encrypted

V$ENCRYPTION_KEYS

When used with keys that have been rotated with the ADMINISTER KEY MANAGEMENT statement, displays information about the TDE master encryption keys.

In a multitenant environment, when you query this view in a PDB, it displays information about keys that were created or activated for the current PDB. If you query this view in the root, it displays this information about keys for all of the PDBs.

V$ENCRYPTION_WALLET

Displays information on the status of the keystore and the keystore location for TDE

V$WALLET

Displays metadata information for a PKI certificate, which can be used as a master encryption key for TDE

See Also:

Oracle Database Reference for detailed information about these views