Skip to main content

Use signing keys

Web3Signer supports BLS12-381 or secp256k1 signing keys stored in:

You can configure access to the signing key by:

note

Bulk loading is only available when using 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, define the parameters to access the key in a key configuration file. You can create a separate configuration file for each key, or specify multiple configurations in a single file by adding a triple-dash separator (---) between configurations.

The configuration file must be YAML-formatted, and can use any naming format, but must have the .yaml extension.

Place one or more 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.

web3signer --key-store-path=/Users/me/keyFiles/ eth2

Bulk load keys​

Azure Key Vault​

You can bulk load keys that are stored in Azure Key Vault using the Web3Signer eth1 subcommand options or eth2 subcommand options.

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.

The AWS bulk load mode supports loading multiple consensus layer keys from the same secret, if keys are stored with a line terminating character such as \n. This saves cost when dealing with a large number of keys. Up to 200 keys can be stored under a secret name.

web3signer eth2 --aws-secrets-enabled=true --aws-secrets-access-key-id=AKIA...EXAMPLE \
--aws-secrets-secret-access-key=sk...EXAMPLE \
--aws-secrets-region=us-east-2

Keystore files​

You can bulk load consensus layer or execution layer keys that are stored as keystore files using the Web3Signer eth1 subcommand options or eth2 subcommand options.

web3signer eth2 --keystores-path=/Users/me/keystores \
--keystores-passwords-path=/Users/me/passwds

Use the eth1 or eth2 --keystores-password-file or --keystores-passwords-path command line option to specify keystore passwords.

Reload new keys​

If you add new keys to an existing set of validators, or modify the key configuration files, reload the keys to ensure Web3Signer registers the new or modified keys. Use the reload endpoint to reload the keys in Web3Signer.

curl -X POST http://localhost:9000/reload

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 using the --key-manager-api-enabled subcommand option.

warning

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 using the list keys endpoint.

curl -X GET http://localhost:9000/eth/v1/keystores

Import keystores​

Import keystores generated by the consensus layer deposit CLI tooling using the import keystores endpoint.

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\":[]}]}"
  }'

Delete keys​

Delete keys using the delete keys endpoint.

curl -X DELETE http://localhost:9000/eth/v1/keystores --data '{"pubkeys": ["0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"]}'