> ## Documentation Index
> Fetch the complete documentation index at: https://docs.futurex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate a TDE Master Encryption Key on the Excrypt HSM

> Procedural steps to generate a TDE Master Encryption Key on the Excrypt HSM.

To configure Oracle Database 12c TDE with an HSM, we recommend that you refer to the following Oracle knowledge base article:

* Oracle Database 12c: [**https://docs.oracle.com/database/121/ASOAG/configuring-transparent-dataencryption.htm**](https://docs.oracle.com/database/121/ASOAG/configuring-transparent-data-encryption.htm)

This section provides a basic example of configuring Oracle TDE with an HSM using PKCS #11. However, there are many nuances in an Oracle Database environment, so the following steps might not apply directly to certain situations and implementations. Use this section only as a general guide and thoroughly consult the preceding Oracle documentation link before implementing Oracle TDE with an HSM in your environment.

To use HSM-based encryption, you must generate a Master Encryption Key (MEK) and store it on the Excrypt HSM. TDE uses it for encrypting and decrypting the Oracle Table Keys.

Select one of the following Oracle Database implementation methods and follow the instructions:

* A standard implementation of Oracle Database running on a server or desktop
* An Oracle Database implementation running in a Docker container.

## Standard implementation

Perform the following steps to implement Oracle Database with the standard method:

**Step 1**

Set the Oracle environment by using the following commands:

```shell expandable lines wrap title="Shell" theme={null}
$ su oracle

$ cd ~

$ . /usr/local/bin/oraenv
ORACLE_SID = [oracle] ? orcl
```

**Step 2**

Connect to the database:

```shell expandable lines wrap title="Shell" theme={null}
$ sqlplus / as sysdba
```

**Step 3**

Start the Oracle instance:

```sql expandable lines wrap title="Sql" theme={null}
SQL> startup
```

**Step 4**

Open the hardware keystore by using the password of the identity created on the Excrypt HSM:

```sql expandable lines wrap title="Sql" theme={null}
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "Identity_Password";
```

**Step 5**

Perform one of the following options for the TDE Master Encryption Key:

* Migrate a previously configured TDE Master Encryption Key by referring to this article: [**docs.oracle.com/database/121/ASOAG/managing-keystore-and-tde-master-encryption-key.htm#GUID-4335220F-49FF-40BC-9EB0-21442608F436.**](https://docs.oracle.com/database/121/ASOAG/managing-keystore-and-tde-master-encryption-key.htm#GUID-4335220F-49FF-40BC-9EB0-21442608F436)
* Create the TDE Master Encryption Key by using the password of the identity that was created on the Excrypt HSM, by running the following command:

```sql expandable lines wrap title="Sql" theme={null}
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "Identity_Password";
```

> [!TIP]
>
> If the Master Encryption Key creation succeeds, you see the following message:
>
> ```none expandable lines wrap title="None" theme={null}
> System altered.
> ```

> [!NOTE]
>
> If the database contains columns encrypted with a public key, the columns are decrypted and reencrypted with the Oracle table key, which is encrypted and decrypted with the AES symmetric key generated by HSM-based transparent data encryption.

## Docker container implementation

Perform the following steps to implement Oracle Database in a Docker container:

> [!NOTE]
>
> The steps outlined in this section describe how to configure the Futurex PKCS #11 (FXPKCS11) library to work with an Oracle Database Docker container. For instructions on how to build and run Oracle Database in a Docker container, refer to the Oracle documentation.

**Step 1**

On the host computer that runs the Oracle Database container, go to the location of the Oracle Database private key file, `tls_skey.pem`.

**Step 2**

Open a terminal and run the following command to make the Oracle Database private key readable and executable for all users:

```shell expandable lines wrap title="Shell" theme={null}
chmod 555 tls_skey.pem
```

**Step 3**

Set the OpenSSL version to match your container in the **OPENSSL\_VERSION** environment variable.

Depending on your database version, run one of the following commands:

* If you use Oracle Database 19c and the official Oracle Database container images repository on GitHub ([**https://github.com/oracle/docker-images/blob/main/OracleDatabase**](https://github.com/oracle/docker-images/blob/main/OracleDatabase)), the container is based on Oracle Linux 7, which is OpenSSL 1.0-based. In that case, you need to run the following command:

```shell expandable lines wrap title="Shell" theme={null}
OPENSSL_VERSION=OpenSSL-1.0.x
```

* If you use Oracle Database running in a container that is OpenSSL 1.1-based, you need to run the following command:

```shell expandable lines wrap title="Shell" theme={null}
OPENSSL_VERSION=OpenSSL-1.1.x
```

**Step 4**

Download the Futurex PKCS #11 (**FXPKCS11**) library from the Futurex Portal, depending on your OpenSSL version:

* If your container is OpenSSL 1.0-based, download the `fxpkcs11-redhat-4.xx-xxxx.tar` file.
* If your container is OpenSSL 1.1-based, download the `fxpkcs11-redhat8-4.xx-xxxx.tar` file.

**Step 5**

Extract the **FXPKCS11** library and save the version in the **PKCS\_VERSION** environment variable.

```shell expandable lines wrap title="Shell" theme={null}
tar -xvf fxpkcs11*.tar

PKCS_VERSION=$(grep -r --include=*info* Version: | awk 'NR==2{print $2}')
```

**Step 6**

Open the **FXPKCS11** configuration file, `fxpkcs11.cfg`, in a text editor and modify the connection details in the `<HSM>` section to enable the **FXPKCS11** library to connect to the Excrypt HSM. The following configuration example shows part of the `fxpkcs11.cfg` file:

```none expandable lines wrap title="None" theme={null}
<HSM>
    # Which PKCS11 slot
    <SLOT>                  0                       </SLOT>
    <LABEL>                 Futurex                 </LABEL>

    # HSM crypto operator user name
    <CRYPTO-OPR>            [identity_name]                </CRYPTO-OPR>
    # Automatically login on session open
    #<CRYPTO-OPR-PASS>       [identity_password]             </CRYPTO-OPR-PASS>

    # Connection information
    <ADDRESS>               [hsm_ip_address]        </ADDRESS>
    <PROD-PORT>             9100                    </PROD-PORT>
    <PROD-TLS-ENABLED>      YES                     </PROD-TLS-ENABLED>
    <PROD-TLS-ANONYMOUS>    NO                      </PROD-TLS-ANONYMOUS>
#    <PROD-TLS-CA>           /home/user/tls/root.pem        </PROD-TLS-CA>
#    <PROD-TLS-CA>           /home/user/tls/sub1.pem     </PROD-TLS-CA>
#    <PROD-TLS-CA>           /home/user/tls/sub2.pem     </PROD-TLS-CA>
    <PROD-TLS-KEY>          /home/user/tls/PKI.p12       </PROD-TLS-KEY>
    <PROD-TLS-KEY-PASS>     safest                  </PROD-TLS-KEY-PASS>

    # YES = This is communicating through a Guardian
    <FX-LOAD-BALANCE>       NO                      </FX-LOAD-BALANCE>
</HSM>
```

<table>
  <thead>
    <tr>
      <th>***Field***</th>
      <th>***Description***</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`<SLOT>`</td>
      <td>Leave it set to the default value of `0`.</td>
    </tr>

    <tr>
      <td>`<LABEL>`</td>
      <td>Leave it set to the default value of **Futurex**.</td>
    </tr>

    <tr>
      <td>`<CRYPTO-OPR>`</td>
      <td>Specify the name of the\*\* identity\*\* created for the application partition.</td>
    </tr>

    <tr>
      <td>`<CRYPTO-OPR-PASS>`</td>
      <td>Specify the password of the identity configured in the `<CRYPTO-OPR>` field. You can use this to log the application into the HSM automatically if necessary.</td>
    </tr>

    <tr>
      <td>`<ADDRESS>`</td>
      <td>Specify the **IP address** of the HSM to which the PKCS #11 library should connect.</td>
    </tr>

    <tr>
      <td>`<PROD-PORT>`</td>
      <td>Set the port number of the HSM that the **FXPKCS11** library should connect to.</td>
    </tr>

    <tr>
      <td>`<PROD-TLS-ENABLED>`</td>
      <td>Set the field to **YES**. </td>
    </tr>

    <tr>
      <td>`<PROD-TLS-ANONYMOUS>`</td>
      <td>Defines whether the **FXPKCS11** library authenticates to the server.</td>
    </tr>

    <tr>
      <td>`<PROD-TLS-KEY>`</td>
      <td>Set the location of the client private key. Supported formats for the TLS private key include the following values:<ul><li>**PKCS #1** clear private keys</li><li>**PKCS #8** encrypted private keys</li><li>A **PKCS #12** file containing the private key and certificates encrypted under a password.</li></ul>\[!NOTE] Because the `<PROD-TLS-KEY>` field in this example defines the PKCS #12 file, you don't need to define the signed client cert with the `<PROD-TLS-CERT>` tag, nor the CA certificates with one or more instances of the `<PROD-TLS-CA>` tag.\\</td>
    </tr>

    <tr>
      <td>`<PROD-TLS-KEY-PASS>`</td>
      <td>Set the password of the PKCS #12 file, if necessary.</td>
    </tr>

    <tr>
      <td>`<FX-LOAD-BALANCE>`</td>
      <td>If you use a Guardian to manage HSM devices in a cluster, set this field to **YES**. \
      If you don't use a Guardian, set it to **NO**</td>
    </tr>
  </tbody>
</table>

**Step 7**

Run the following command to start the Oracle Database container and bind-mount all of the **FXPKCS11** files needed for **FXPKCS11** to connect to the Excrypt HSM.

> [!NOTE]
>
> You must run this command from the same directory that stores the extracted `fxpkcs11` directory.

> [!NOTE]
>
> If the TLS certificates for authentication with the Excrypt HSM are not stored in the `/home/oracle/pki` directory on your system, modify the third -v flag in your command to reflect the location.

```shell expandable lines wrap title="Shell" theme={null}
docker run -d \
    -v $(pwd)/fxpkcs11.cfg:/etc/fxpkcs11.cfg \
    -v $(pwd)/fxpkcs11/x64/${OPENSSL_VERSION}/libfxpkcs11.so:/opt/oracle/extapi/64/hsm/futurex/${PKCS_VERSION}/libfxpkcs11.so \
    -v /home/oracle/pki:/pki \ 
    -p 1521:1521 \
    -p 5500:5500 \
    -e ORACLE_SID=test \
    -e ORACLE_PWD=Password123 \
    -v data:/opt/oracle/oradata \
    --name TDE \
    oracle/database:19.3.0-ee
```

> [!NOTE]
>
> The preceding command takes 10 to 20 minutes to complete, depending on your system resources.

**Step 8**

After the Oracle Database container is up and running, run the following command to connect to the container file system:

```shell expandable lines wrap title="Shell" theme={null}
docker exec -it TDE /bin/bash
```

**Step 9**

Modify the `/opt/oracle/product/19c/dbhome_1/network/admin/sqlnet.ora` file to the following and save it:

```shell expandable lines wrap title="Shell" theme={null}
NAME.DIRECTORY_PATH= (TNSNAMES, EZCONNECT, HOSTNAME)
WALLET_LOCATION=(SOURCE=(METHOD=HSM)(METHOD_DATA=(DIRECTORY=/opt/oracle/admin/wallet)))
ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=HSM)(METHOD_DATA=(DIRECTORY=/opt/oracle/admin/wallet)))
WALLET_ROOT=/opt/oracle/admin/wallet
```

**Step 10**

Connect to the database.

```shell expandable lines wrap title="Shell" theme={null}
sqlplus sys/Password123@test as sysdba
```

**Step 11**

Create the Master Encryption Key for TDE.

```sql expandable lines wrap title="Sql" theme={null}
SQL > ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "safest";
```

> [!TIP]
>
> If the operation succeeds, you see the following response:
>
> ```sql expandable lines wrap title="Sql" theme={null}
> System altered.
> ```
