Create Validation Keys and Signing Keys
At this point, you should have the following items installed and configured:
- Primus HSM
- Securosys Transaction Security Broker
- Securosys Custom Server for Fireblocks
- Fireblocks Key Link Agent
As a last step, you need to create validation keys and signing keys on the Primus HSM, and onboard them to your Fireblocks workspace.
How It Works
The validation key is a single key that is onboarded to the Fireblocks workspace once. This onboarding needs to be approved by a quorum of workspace administrators.
The signing keys are the keys that are linked to a Fireblocks Vault, and hence to the actual wallets. To onboard a signing key to Fireblocks, a certificate that is signed by the validation key must be uploaded to Fireblocks. No further approval by a quorum of workspace administrators is needed.
Additionally, to onboard a signing key, proof of ownership is required. For this, you need to sign a specially formatted message with the signing key. This proves to Fireblocks that you really have control over the signing key. Only then will Fireblocks allow you to add the signing key to a vault and use it to manage funds. This signing can be done interactively or non-interactively.
The validation keys and certificate keys can be generated through any of the Primus HSM APIs, including the REST API (that is exposed by the Securosys TSB). To help you generate the validation certificate and the proof of ownership, the Securosys Custom Server provides some helper endpoints.
The Securosys Custom Server sometimes uses the name asset key for what Fireblocks calls the signing key. This is to better describe the key's purpose, since the validation key is also used for signing.
Step 1: Create a Validation Key
First, create a validation key.
This can be done using the POST /v1/createValidationKey helper endpoint of the Securosys Custom Server:
curl -X 'POST' https://custom-server.example.com/v1/createValidationKey --data ''
The response contains the PEM-encoded public key
(without the -----BEGIN/END PUBLIC KEY----- header/trailer and without line breaks):
{
"publicKeyPem": "<PEM>"
}
This creates a key with label FIREBLOCKS_VALIDATION_KEY on the HSM partition
that the Securosys Custom Server is configured to access.
If needed, you can retrieve the public key later via the TSB:
curl https://tsb.example.com/v1/key/attributes --data '{ "label": "FIREBLOCKS_VALIDATION_KEY" }'
The response contains a large JSON object.
The PEM-encoded public key is in the json.publicKey field.
Step 2: Onboard the Validation Key
Upload the public key of the validation key as a PEM-encoded file to your Fireblocks workspace. This can be done via:
Wait for your workspace administrators to approve the validation key.
Step 3: Create a Signing Key
Create a signing key (asset key) on the HSM.
Fireblocks supports ECDSA and EdDSA keys.
For example, use the POST /v1/key endpoint of the TSB to create an EC key with curve secp256k1:
curl https://tsb.example.com/v1/key \
--data '{ "label": "fireblocks-signing-key-1", "algorithm": "EC", "curveOid": "1.3.132.0.10" }'
The response contains the PEM-encoded public key
(without the -----BEGIN/END PUBLIC KEY----- header/trailer and without line breaks):
{
"xml": "...",
"json": {
"label": "label",
"publicKey": "<PEM>"
},
"xmlSignature": "...",
"attestation": "..."
}
If you want this key to be protected by Smart Key Attributes (SKA), you must attach a policy at key creation time. This policy can initially be empty, and can be filled out later (but it must be set). See this tutorial for how to generate an SKA key.
Step 4: Create Validation Certificate
Create a "validation certificate". This certificate contains the public signing key (asset key) and is signed by the validation key.
This can be done using the POST /v1/createValidations helper endpoint of the Securosys Custom Server:
curl https://custom-server.example.com/v1/createValidations \
--data '{ "assetKeyName": "fireblocks-signing-key-1", "assetKeyAlgorithm": "EC", "isSkaKey": false }'
The response contains the PEM-encoded certificate
(without the -----BEGIN/END CERTIFICATE----- header/trailer and without line breaks):
{
"certificate": "<PEM>"
}
Step 5: Create a Non-Interactive Proof of Ownership
Create a non-interactive proof of ownership. This is a signature by the signing key (asset key) over a specifically formatted message.
This can be done using the POST /v1/proofOfOwnership helper endpoint of the Securosys Custom Server:
curl https://custom-server.example.com/v1/proofOfOwnership \
--data '{ "assetKeyName": "fireblocks-signing-key-1", "assetKeyAlgorithm": "EC", "workspaceDisplayName": "<name>", "sdkApiKey": "<key>" }'
The response contains the proofOfOwnership struct in the format that the
Fireblocks API expects:
{
"proofOfOwnership": {
"message": "string",
"signature": "string"
},
"timestamp": 0
}
For convenience, you can also use the POST /v1/validationAndProofOfOwnership endpoint of the Securosys Custom Server.
It combines creating the validation certificate and the proof of ownership into a single request.
Step 6: Onboard the Signing Key
Add the signing key to your Fireblocks workspace. This can be done via:
When using the Fireblocks API, you can already provide the non-interactive
proof of ownership in the proofOfOwnership field.
If you omit the proofOfOwnership field or if you add the signing key via the Fireblocks Key Management Dashboard,
Fireblocks will trigger an interactive proof of ownership process.
This sends a signing request to the HSM via all the web services that you just deployed
(in other words, using the same flow as signing blockchain transactions later).
Onboard More Signing Keys
To onboard more signing keys to your Fireblocks workspace, simply repeat steps 3 to 6.
Next Steps
You can now start managing your digital assets in Fireblocks, with the keys securely stored in a Primus HSM. Assign the signing key to a Fireblocks Vault to start using it.
To continue, you may be interested in the following advanced features that Securosys offers:
- Explore VaultCode to build automated approval flows for your transactions.
- Explore the air-gapped TSB mode to keep your wallet keys offline in cold storage.