> ## 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.

# Configure SAP ASE and create the HSM key

> Enable the SAP ASE external keystore, store the HSM credential, generate the HSM key on the Excrypt HSM, and protect the master keys with it.

Configure SAP ASE to use the Excrypt HSM as its external keystore, store the HSM credential, and create the HSM key and the master keys that it protects.

Run the SQL on this page in `isql` as an SAP ASE login with `sso_role` and `keycustodian_role`. SAP ASE must be running in threaded kernel mode.

## Enable the external keystore

**1. Set the external keystore**

Set the external keystore to HSM:

```sql title="SQL" theme={null}
sp_configure 'external keystore', 0, 'hsm'
go
```

> [!TIP]
>
> The output shows `external keystore` with run value `hsm`.

**2. Store the HSM credential**

SAP ASE encrypts the stored credential and passes the password to the library every time it logs in to the HSM. Replace `<identity-password>` with the password of the identity that you set in `<CRYPTO-OPR>`:

```sql title="SQL" theme={null}
sp_encryption 'hsm_credential', 'lib=libfxpkcs11.so;pin=<identity-password>;slot=0'
go
```

> [!WARNING]
>
> SAP ASE stores the credential without testing it, so a wrong password shows up only at the next key operation or restart. Enter it carefully. If your shell or `isql` tool records history, clear it afterward, or run the command from a file that only you can read with `isql -i`.

**3. Display the stored credential**

```sql title="SQL" theme={null}
sp_encryption 'hsm_credential'
go
```

> [!TIP]
>
> SAP ASE reports `The current HSM credential setting is: 'lib=libfxpkcs11.so;slot=0'` without the password.

## Create the HSM key

SAP ASE supports one HSM key per server instance. It generates the key on the HSM and records its identifier in the `master` database.

**1. Create the HSM key**

```sql title="SQL" theme={null}
use master
go
create encryption key hsm_key on external keystore
go
```

**2. Display the HSM key**

```sql title="SQL" theme={null}
sp_encryption helpkey, hsm_key
go
```

> [!TIP]
>
> The output lists `hsm_key` as a `symmetric hsm key` of 256 bits, protected by `hsm`. On the HSM, the key table contains an AES-256 key with encrypt and decrypt usage and the PKCS #11 label `SAP ASE instance key`. To list it, run `keytable list` in FXCLI as an administrator.

## Protect the master keys with the HSM key

**1. Create the server-wide master key**

Create the master key in the `master` database, encrypted with the HSM key:

```sql title="SQL" theme={null}
use master
go
create encryption key master with external key
go
```

**2. Create the user database master keys**

Create a master key in each user database whose keys the HSM must protect. Replace `<database>` with the database name:

```sql title="SQL" theme={null}
use <database>
go
create encryption key master with external key
go
```

**3. List the keys**

```sql title="SQL" theme={null}
sp_encryption helpkey
go
```

> [!TIP]
>
> `sybencrmasterkey` appears as a `symmetric master key` protected by `hsm key`.

If a database already has a master key protected by a password, move it to the HSM key instead: `alter encryption key master with passwd '<password>' modify encryption with external key`.

## Encrypt data

Create column encryption keys and database encryption keys as usual. SAP ASE protects them with the master key, which the HSM key protects.

**1. Encrypt a column**

Create a column encryption key in the user database and use it in the column definition:

```sql title="SQL" theme={null}
use <database>
go
create encryption key <column_key> for AES with keylength 256
go
create table <encrypted_table> (id int, ssn varchar(20) encrypt with <column_key>)
go
```

> [!TIP]
>
> `sp_encryption helpkey` in the user database lists `<column_key>` protected by `master key`.

**2. Encrypt a whole database (optional)**

Create a database encryption key in `master` and encrypt the database. Full database encryption runs as background worker tasks, so the server needs worker processes:

```sql title="SQL" theme={null}
use master
go
sp_configure 'number of worker processes', 4
go
create encryption key <database>_dek for database encryption
go
alter database <database> encrypt with <database>_dek
go
```

> [!TIP]
>
> When the background task finishes, `sp_helpdb <database>` shows `encrypted` in the database status.