# Initialize a Thales Luna HSM

The Thales Luna HSM is FIPS 140-2 Level 3 certified and supports both SLIP10 and BIP32 derivation schemes (although SLIP10 is preferred). You can use the HSM to create blockchain keys with deterministic derivation from a seed.

## Prerequisites

Ripple Custody supports on-premise Thales Luna Network HSM 7 deployments, with the following specifications:

- For SLIP10 derivation (for all new implementations):
  - HSM Firmware 7.8.7 or higher
  - Application software 7.8.5-300
  - Ripple Custody version 1.16 or higher
- For BIP32 derivation (minimum — use only for legacy implementations):
  - HSM Firmware 7.7.1 or higher
- PKCS #11 (Public-Key Cryptography Standard)
- The following HSM policy settings enabled:
  - **6**: Enable masking
  - **12**: Enable non-FIPS algorithms
- The following partition policies enabled:
  - **22**: Allow activation
  - **23**: Allow auto-activation
  - **41**: Partition version
  - **43**: Allow non-FIPS algorithms


You cannot upgrade vaults that were registered with a version of Thales Luna earlier than 7.8.7 to perform SLIP10 derivation. To use SLIP10 derivation, deploy a new vault.

For more information, see the Thales Luna Network HSM 7 documentation.

**Warning**
You must ensure all policies listed above are enabled before you begin to use your Thales Luna HSM. Some of these policies are destructive and **will destroy existing data when enabled**. 

## Implementation

The Luna HSM is deployed to a client with the following:

- Scalable Key Storage (SKS)
- A user with **Limited Crypto Officer** role
- HSM policy **12**, required for vault operations
- HSM policy **6**, required for SKS


The vault needs to be deployed to a separate server, since Luna only provides the HSM functionality. We recommend a server with a secure enclave for confidential computing, such as AMD EPYC. You can deploy the other parts of the Ripple Custody stack to general computing nodes, or consume them as part of the Ripple Cloud offering.

You are fully in control of your keys. You can implement a connected hot vault or a disconnected cold vault.

### Key generation

After the HSM is initialized, every new account that's created generates a new set of private keys using either a deterministic key derivation strategy or a random key generation strategy. These private keys are then encrypted using the HSM master key and safely stored in the Ripple Custody database.

If you specify a deterministic key derivation strategy during account creation, key derivation is performed using the derivation scheme specified in your HSM configuration.

For more information about key-derivation strategies, see [Key derivation](/products/custody/v1.26/overview/blockchain/accounts/key-derivation).

#### SLIP10 derivation

HSM Firmware 7.8.7 or higher is recommended for all new implementations as this supports the SLIP10 derivation scheme, which supports both Ed25519 and secp256k1 elliptic curves for key derivation. This lets you create accounts on any blockchain that uses either of these two elliptic curves to derive keys upon account creation.

#### BIP32 derivation

HSM Firmware versions earlier than 7.8.7 support only the BIP32 scheme. Using this scheme, you can only create accounts on chains that use the secp256k1 elliptic curve — namely, Bitcoin, Ethereum, Tron, and XRPL. You can also create accounts on chains that are of the same type and support the BIP32 scheme, such as Litecoin and Polygon.

Alternatively, you can create accounts with a *random* key generation strategy on any chain supported by the HSM. However, see the caveats in [Key derivation](/products/custody/v1.26/overview/blockchain/accounts/key-derivation#random-key-generation) about the backup implications of using random key generation. Deterministic *hard* key derivation is preferred whenever available.

### Backups

For SKS partitions, you only need to back up the SKS master key (SMK) to a backup HSM.

For more information, see the Thales Luna Partition Administration Guide.

## Initialize a Thales Luna HSM

Initialization of a Thales Luna HSM consists of the following tasks:

1. Configure the HSM.
2. Configure Scalable Key Storage (SKS) partitions on the HSM client.
3. Configure high availability (HA) groups for client access to the HSM.
4. Enable access to the HSM.


For setups that generate greater numbers of keys than can be stored within an HSM, but also demand greater security of externally stored keys than is provided by Key Export mode, Scalable Key Storage (SKS) is available in Luna HSM Firmware 7.7.0 and newer.

Using this method, SKS blobs, containing the key material and the associated objects, are encrypted with a symmetric key (SMK) that is cloned when managed within a High Availability (HA) group. The blobs are sent to Ripple Custody for persistent storage.

Since the SMK is replicated by cloning, the SMK never exists outside the HSM, so a high level of security for all keys and objects encrypted by that SMK is assured, without the storage limitations of the HSM.

### Configure the HSM

To initialize a Thales Luna HSM, you need:

- A Thales Luna Network HSM 7 instance deployed according to the vendor instructions, with the following specifications:
  - Firmware 7.8.7 or higher (to support SLIP10 derivation)
  - Enable the following HSM policies (see HSM Capabilities and Policies):
    - HSM policy **6**: Enable masking
    - HSM policy **12**: Enable non-FIPS algorithms
Make sure policies **6** and **12** are enabled before you begin to use your Thales Luna HSM, as these policies are destructive, that is, they will destroy any existing data.
For more information, see the Thales Luna Network HSM 7 documentation.
- A Linux client machine configured with the minimum requirements.
For more information, see Luna Minimal Client Install for Linux.


### Configure Scalable Key Storage (SKS) partitions

SKS partitions share the load of key management for the HSM.

For detailed guidance on configuration of SKS partitions, see the Thales Luna Partition Administration Guide.

To configure your SKS partitions:

1. On your Luna HSM client, open LunaCM.
2. Create the required number of partitions. The partitions must be of type **V1**.
3. Enable the following policies on your partitions:
  - Partition policy **22**: Allow activation
  - Partition policy **23**: Allow auto-activation
  - Partition policy **41**: Partition version
  - Partition policy **43**: Allow non-FIPS algorithms
4. Configure NTLS connections between your partitions.
5. Assign the **Limited Crypto Officer** credential to the SKS partitions.


### Configure High Availability (HA) groups

HA groups allow your client application to access cryptographic services as long as one member HSM is functional and connected to the network. You can configure HA groups on a per-application basis, depending on your own requirements.

For detailed guidance on configuration of HA groups, see High-Availability Groups.

Connection to a third-party or in-house HA solution is also possible but out of scope for this documentation. For guidance on how to configure third party HA, see the Thales documentation on High-Availability indirect login.

To configure your HA groups:

1. On your Luna HSM client, open LunaCM.
2. Create HA groups from the partitions you created in the previous task.


LunaCM saves your HA settings to `Chrystoki.conf` on the client host, as in the following example:


```sh
VirtualToken = {
VirtualToken00Label = haGroup1; // The label of the HA group.
VirtualToken00SN = 11234840370164; // The pseudo serial number of the HA group.
VirtualToken00Members = 1234840370164, 1234924189183; // The serial number of the members.
VirtualTokenActiveRecovery = activeEnhanced; // The recovery mode.
}
HASynchronize = {
haGroup1 = 1; // Enable automatic synchronization of objects.
}
HAConfiguration = {
HAOnly = 1; // Enable listing HA groups only via PKCS#11 library.
haLogPath = /tmp/halog; // Base path of the HA log file; i.e., “/tmp/halog/haErrorLog.txt”.
haLogStatus = enabled; // Enable HA log.
logLen = 100000000; // Maximum size of HA log file in bytes.
failover_on_deactivation = 1; // if a partition becomes deactivated then the client will immediately 
                              // failover and resume its operation on the other HA partitions. This 
                              // is currently an alpha feature
reconnAtt = 120; // Number of recovery attempts.
}
HARecovery = {
haGroup1 = 1; // Deprecated in this release as auto recovery will cover the use case. When cryptoki 
              // loads into memory it reads the number and if the number changes (gets incremented) 
              // then cryptoki interprets this as a manual recovery attempt.
}
```

### Enable access to the HSM

To enable access to the HSM, update the network access-control list (ACL) to allow the HSM client access to the HSM IP addresses and port number.

### Check network connectivity

To check network connectivity is established successfully, run the `nc` and `vtl verify` commands on the client host. For more information, see the [Thales Luna HSM documentation](https://thalesdocs.com/gphsm/luna/7/docs/network/Content/Home_Luna.htm).

If this basic connectivity check is successful, you can proceed to [deploy the vault](/products/custody/v1.26/get-started/deployment/deploy-kms/on-prem/luna/connect).