This article deals with identifying the necessary information in order to configure Vault enterprise to auto-unseal with an HSM where the HSM is configured for HSM high availability as per the HSM vendor's configuration. For support and assistance with the configuration of the HSM kindly contact your HSM provider.
This article does not deal with configuring Vault seal high availability that was introduced in Vault 1.16 enterprise. For Vault seal high availability please refer to:
Vault Documentation: Vault Seal High Availability
Vault Documentation: Vault Seal HA Configuration
For the purposes of this article, Thales Luna HSM HA documentation was referenced:
Thales: High Availability Options for Luna HSMs
All examples and references to the Luna client (LunaCM Commands) are based on version 7.7.0 (current version at the time of the publication of this article).
From a Vault operator's perspective it is assumed that the HSM operator has successfully configured the Luna HSM to have High Availability and on the Vault server the necessary Luna HSM client has been installed.
The following steps are all done on each Vault server in the Vault cluster to confirm the configuration of the Luna HSM Client. It is critically important that the configuration both of the Vault PKCS11 unseal stanza and the Luna HSM client is identical on ALL nodes in the Vault cluster. Mismatched configurations could result in the loss of data.
[external to Vault] Confirm that HAOnly mode is enabled for the Luna HSM client.
Example:
lunacm:> hagroup haonly -show
This system is configured to show only HA slots. (HA Only is enabled)
Command Result : No Error
[external to Vault] If HAOnly mode on the Luna HSM client is not enabled, it must be enabled:
Example:
lunacm:> hagroup haonly -enable
"HA Only" has been enabled.
Command Result : No Error
[external to Vault] Using the Luna HSM Client, list the available slots that the Luna HSM Client itself is aware of:
Example:
lunacm:> slot list
Slot 0 (0x0): Net Token Slot
token label : vaultsandbox1
token manufacturer : Safenet, Inc.
token model : LunaSA 7.7.0
token flags : login required, PIN pad present, rng, token initialized, PIN initialized, other flags=0x20
hardware version : 118.68
firmware version : 7.3
serial num : 1459712821234
pin min/max : 16/255
Slot 1 (0x1): Net Token Slot
token label : vaultsandbox2
token manufacturer : Safenet, Inc.
token model : LunaSA 7.7.0
token flags : login required, PIN pad present, rng, token initialized, PIN initialized, other flags=0x20
hardware version : 118.68
firmware version : 7.3
serial num : 1459787326567
pin min/max : 16/255
Slot 8 (0x8): HA Virtual Card Slot
token label : vault
token manufacturer : Safenet, Inc.
token model : LunaVirtual
token flags : login required, rng, token initialized, PIN initialized, other flags=0x20
hardware version : 0.0
firmware version : 7.3
serial num : 11459712821234
pin min/max : 16/255
Current Slot ID: 0
Command Result : No Error
In the above example listing of slots take note that both the physical slots and the virtual slot are listed. However, going back to the output of checking the HAOnly mode, this message was displayed:
This system is configured to show only HA slots. (HA Only is enabled)
Therefore, it is necessary to determine what HSM HA slot and information are in fact being presented to the consumer of the HSM because, as the message above states, the system is configured to show only the HA slots.
Vault leverages the PKCS11 library to interface with the Luna HSM client. A basic way to understand this is that Vault interfaces with the PKCS11 library which in turn interfaces with the Luna HSM client. Therefore, it needs to be determined what slots are being presented to the PKCS11 library in order to know what information to use when configuring the Vault PKCS11 seal stanza. For this purpose the pkcs11-tool is used. The pkcs11-tool is part of the OpenSC project.
[external to Vault] Example command to install OpenSC:
sudo apt install opensc
[external to Vault] Using the pkcs11-tool list the slots that the Luna HSM Client is presenting for consumption/use.
Example:
pkcs11-tool --module /usr/safenet/lunaclient/lib/libCryptoki2_64.so -L
Available slots:
Slot 0 (0x0): HA Virtual Card Slot
token label : vault
token manufacturer : Safenet, Inc.
token model : LunaVirtual
token flags : login required, rng, token initialized, PIN initialized, other flags=0x20
hardware version : 0.0
firmware version : 7.3
serial num : 11459712821234
pin min/max : 16/255
Note that only the HSM HA Slot is presented by the Luna HSM Client to the PKCS11 Library to consume/use. At this point you may wish to cross check the token label and serial number with the output that was presented by the Luna HSM Client. Take note, however, that in this example the slot number presented from the Luna HSM Client to the PKCS11 library is listed as 0, whereas in the Luna HSM Client itself, in this example, it was listing the HSM HA slot as 8. This is a key piece of information.
[specific to Vault] This is the information that you require in order to configure the PKCS11 seal stanza in Vault. Based on the above output an example of the Vault PKCS11 seal stanza is as follows:
seal "pkcs11" {
lib = "/usr/safenet/lunaclient/lib/libCryptoki2_64.so"
slot = "0"
key_label = "AES_2024-11-08_001"
hmac_key_label = "HMAC_2024-11-08_001"
pin = "AAAA-BBBB-CCCC-DDDD"
}
[specific to Vault] Alternatively, if using token_label instead of slot, an example Vault PKCS11 stanza will be as follows:
seal "pkcs11" {
lib = "/usr/safenet/lunaclient/lib/libCryptoki2_64.so"
token_label = "vault"
key_label = "AES_2024-11-08_001"
hmac_key_label = "HMAC_2024-11-08_001"
pin = "AAAA-BBBB-CCCC-DDDD"
}
Having done the above, Vault, via the PKCS11 library, will interface only with the Luna HSM HA slot. Keep in mind that the actual high availability functionality here is being handled by the Luna HSM itself.
Cautionary Note: If, at Vault key creation, for example Vault Initialisation, generate_key was set to true in the Vault PKCS11 stanza then it is highly recommended to disable this flag post key creation to prevent any unintended key creation in future.
Additional Information
Vault Documentation: Vault Seal High Availability
Vault Documentation: Vault Seal HA Configuration
Vault Documentation: PKCS11 seal stanza
Vault Documentation: generate_key
Thales Documentation: High Availability Options for Luna HSMs
Thales Documentation: LunaCM Commands
GitHub OpenSC Project: OpenSC project