Use signing keys
Web3Signer supports BLS12-381 or secp256k1 signing keys stored in:
- Raw unencrypted files
- Keystore files
- Vaults:
- Hardware Security Modules (HSMs):
You can configure access to the signing key by:
- Creating a separate key configuration file for each signing key.
-
Using the
eth2
subcommand options to bulk load consensus layer signing keys stored in Azure Key Vault, AWS Secrets Manager, or keystore files.Note
Bulk loading is only available when using the consensus layer platform with keys stored in Azure Key Vault, AWS Secrets Manager, or keystore files, and can be used in combination with key configuration files.
Use key configuration files
For each signing key, configure a separate key configuration file that defines the parameters
to access the key. The configuration files must be YAML-formatted, and can use any naming format,
but must have the .yaml
extension.
Place the key configuration files in a single directory which you specify when starting Web3Signer.
Use the --key-store-path
option
to specify the location of the key configuration files.
Example
web3signer --key-store-path=/Users/me/keyFiles/ eth2
Bulk load consensus layer keys
Azure Key Vault
You can bulk load consensus layer keys that are stored in Azure Key Vault using the Web3Signer
eth2
subcommand options.
Example
web3signer eth2 --azure-vault-enabled=true --azure-client-id=87efaa5b-4029-4b54-98bb2e2e8a11 \
--azure-client-secret=0DgK4V_YA99RPk7.f_1op0-em_a46wSe.Z \
--azure-tenant-id=34255fb0-379b-4a1a-bd47-d211ab86df81 \
--azure-vault-name=AzureKeyVault
AWS Secrets Manager
You can bulk load consensus layer keys that are stored in AWS Secrets Manager using the Web3Signer
eth2
subcommand options.
Example
web3signer eth2 --aws-secrets-enabled=true --aws-secrets-access-key-id=AKIAIOSFODNN7EXAMPLE \
--aws-secrets-secret-access-key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
--aws-secrets-region=us-east-2
Keystore files
You can bulk load consensus layer keys that are stored as keystore files using the Web3Signer
eth2
subcommand options.
Example
web3signer eth2 --keystores-path=/Users/me/keystores \
--keystores-passwords-path=/Users/me/passwds
Use --keystores-password-file
or
--keystores-passwords-path
to
specify keystore passwords.
Reload new keys
If you add new keys to an existing set of validators, reload the keys to ensure Web3Signer registers the new keys.
Use the reload
endpoint to reload the keys in Web3Signer.
Example
curl -X POST http://localhost:9000/reload
200 Call is successful
Manage keys
You can manage your keys using the key manager API endpoints. You can list keys, import keystores, and delete keys.
Enable the key manager API by running Web3Signer with the --key-manager-api-enabled
subcommand.
Caution
The key manager API is an early access feature and is still in development.
List keys
List all validating public keys known to and decrypted by the keystore with the list keys
endpoint.
Example
curl -X GET http://localhost:9000/eth/v1/keystores
{
"data": [
{
"validating_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
"derivation_path": "m/12381/3600/0/0/0",
"readonly": true
}
]
}
Import keystores
Import keystores generated by the consensus layer deposit CLI tooling with the import keystores
endpoint.
Example
curl -X POST http://127.0.0.1:9000/eth/v1/keystores --header "Content-Type: application/json"
--data '{
"keystores": [
"{\"version\":4,\"uuid\":\"9f75a3fa-1e5a-49f9-be3d-f5a19779c6fa\",\"path\":\"m/12381/3600/0/0/0\",\"pubkey\":\"0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a\",\"crypto\":{\"kdf\":{\"function\":\"pbkdf2\",\"params\":{\"dklen\":32,\"c\":262144,\"prf\":\"hmac-sha256\",\"salt\":\"8ff8f22ef522a40f99c6ce07fdcfc1db489d54dfbc6ec35613edf5d836fa1407\"},\"message\":\"\"},\"checksum\":{\"function\":\"sha256\",\"params\":{},\"message\":\"9678a69833d2576e3461dd5fa80f6ac73935ae30d69d07659a709b3cd3eddbe3\"},\"cipher\":{\"function\":\"aes-128-ctr\",\"params\":{\"iv\":\"31b69f0ac97261e44141b26aa0da693f\"},\"message\":\"e8228bafec4fcbaca3b827e586daad381d53339155b034e5eaae676b715ab05e\"}}}"
],
"passwords": [
"ABCDEFGH01234567ABCDEFGH01234567"
],
"slashing_protection": "{\"metadata\":{\"interchange_format_version\":\"5\",\"genesis_validators_root\":\"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2\"},\"data\":[{\"pubkey\":\"0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a\",\"signed_blocks\":[],\"signed_attestations\":[]}]}"
}'
{
"data": [
{
"status": "imported",
"message": "string"
}
]
}
Delete keys
Delete keys with the delete keys
endpoint.
Example
curl -X DELETE http://localhost:9000/eth/v1/keystores --data '{"pubkeys": ["0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"]}'
{
"data": [
{
"status": "deleted",
"message": "string"
}
],
"slashing_protection": "{\"metadata\":{\"interchange_format_version\":\"5\",\"genesis_validators_root\":\"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2\"},\"data\":[{\"pubkey\":\"0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a\",\"signed_blocks\":[],\"signed_attestations\":[]}]}"
}