Configure auto-login for the HSM key store

By default, the HSM key store is closed after each database restart, and an administrator must open it. Until the key store is open, the database cannot read encrypted data. Auto-login removes this manual step. Oracle Database stores the CryptoHub endpoint PIN as a secret in a small software key store. At startup, Oracle Database reads the PIN from the software key store and opens the HSM key store. The master encryption key stays on CryptoHub. The software key store holds only the PIN.

Anyone who can read the auto-login key store file (cwallet.sso) can open the HSM key store on this server. Keep the wallet directory owned by the Oracle software owner with mode 700, and include the file in your host security controls. If your security policy requires a person to open the key store, skip this page and open the key store manually after each restart.

In the commands on this page:

Replace CRYPTOHUB_ENDPOINT_PIN with the CryptoHub endpoint PIN.
Replace SOFTWARE_KEYSTORE_PASSWORD with a new password for the software key store. Store this password securely.

Create the software key store directory

Oracle Database looks for the software key store in the tde subdirectory of WALLET_ROOT. As the Oracle software owner, create the directory:

mkdir -p /u01/app/oracle/admin/ORCL/wallet/tde
chmod 700 /u01/app/oracle/admin/ORCL/wallet/tde

Run these steps in sqlplus / as sysdba.

Set the key store type to a software key store, so that the next commands create and open the software key store:

ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE" SCOPE=BOTH;

Create the software key store:

ADMINISTER KEY MANAGEMENT CREATE KEYSTORE IDENTIFIED BY "SOFTWARE_KEYSTORE_PASSWORD";

Oracle Database returns keystore altered., and the file ewallet.p12 appears in /u01/app/oracle/admin/ORCL/wallet/tde.

Open the software key store:

ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "SOFTWARE_KEYSTORE_PASSWORD";

The software key store must be open before you add the secret. If it is closed, the next step fails with ORA-28417: password-based keystore is not open.

Add the CryptoHub endpoint PIN as the HSM password secret. HSM_PASSWORD is the client name that Oracle Database reads for the HSM key store PIN. Put both values in single quotes:

ADMINISTER KEY MANAGEMENT ADD SECRET 'CRYPTOHUB_ENDPOINT_PIN' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY "SOFTWARE_KEYSTORE_PASSWORD" WITH BACKUP;

Create the auto-login key store from the software key store:

ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE IDENTIFIED BY "SOFTWARE_KEYSTORE_PASSWORD";

The file cwallet.sso appears in /u01/app/oracle/admin/ORCL/wallet/tde.

Set the key store type to use the HSM key store with the software key store:

ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE" SCOPE=BOTH;

Restart the database:

SHUTDOWN IMMEDIATE;
STARTUP;

Confirm that both key stores opened without a manual command:

SELECT WRL_TYPE, WRL_PARAMETER, STATUS, WALLET_TYPE FROM v$encryption_wallet;

The output shows these rows. The software key store has no master key because the master encryption key is on CryptoHub, so OPEN_NO_MASTER_KEY is the expected status for the FILE row.

WRL_TYPE  WRL_PARAMETER                               STATUS              WALLET_TYPE
--------  ------------------------------------------  ------------------  -----------
FILE      /u01/app/oracle/admin/ORCL/wallet/tde/      OPEN_NO_MASTER_KEY  AUTOLOGIN
HSM                                                   OPEN                HSM

Continue to Verify the integration.

​Create the software key store directory

​Store the PIN in an auto-login key store

Create the software key store directory

Store the PIN in an auto-login key store