Use signing keys

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

Raw unencrypted files
Keystore files
Vaults:
Hardware Security Modules (HSMs):
- YubiHSM 2
- USB Armory Mk II

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 request

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

Result

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 request

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

Result

{
  "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 request

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

Result

{
  "data": [
    {
      "status": "imported",
      "message": "string"
    }
  ]
}

Delete keys

Delete keys with the delete keys endpoint.

Example

curl request

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

Result

{
  "data": [
    {
      "status": "deleted",
      "message": "string"
    }
  ],
  "slashing_protection": "{\"metadata\":{\"interchange_format_version\":\"5\",\"genesis_validators_root\":\"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2\"},\"data\":[{\"pubkey\":\"0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a\",\"signed_blocks\":[],\"signed_attestations\":[]}]}"
}