Skip to main content

Manage validator signing keys

You can manage the signing keys of validators using the key manager API endpoints. You can list keys, import keystores, and delete keys with the API.

Enable validator client API​

To use the key manager API endpoints, enable the validator client API using the --validator-api-enabled option. You must also create a keystore to enable access.

Create a keystore​

When enabling the validator client API, you must create a keystore.

  1. Use a tool such as keytool or openSSL to generate a keystore. Note that the CN value must be set to the domain name or IP used to access the validator API. Keytool sets this based on the answer to What is your first and last name?.

    keytool -genkeypair -keystore <keystore> -storetype PKCS12 -storepass <password>

  2. Create a plain text file (for example validator_keystore_pass.txt) that stores the password you defined in the keystore.

  3. Start Teku using --validator-api-keystore-file to define the keystore file and --validator-api-keystore-password-file to define the password file.

    Example
    teku --validator-api-enabled --validator-api-keystore-file=validator_keystore.p12 --validator-api-keystore-password-file=validator_keystore_pass.txt

Supporting Multiple Domains and IPs​

When the key manager API is accessible via different domain names or IP addresses, each domain or IP needs to be listed in the SSL certificate to be accepted as valid. Multiple addresses can be specified when using openSSL to generate the certificate.

  1. Create a file named openssl.cnf containing the configuration required for the certificate.

    openssl.cnf
    [req]
    distinguished_name = req_distinguished_name
    x509_extensions = v3_req
    prompt = no

    [req_distinguished_name]
    countryName = US
    stateOrProvinceName = CA
    localityName = San Francisco
    organizationName = My Organization Name
    organizationalUnitName = My Department Name

    [v3_req]
    subjectKeyIdentifier = hash
    authorityKeyIdentifier = keyid,issuer
    basicConstraints = CA:TRUE
    subjectAltName = @alt_names

    [alt_names]
    DNS.1 = mydomain.com
    DNS.2 = localhost
    IP.1 = 127.0.0.1
    IP.2 = 10.0.0.6

    You should adjust the req_distinguised_name and alt_names sections to match your needs.

  2. Create a plain text file (for example, validator_keystore_pass.txt) that stores the password you defined in the keystore.

  3. Generate an x509 certificate from the configuration and convert it to PKCS12 format:

    openssl req -x509 -nodes -days <expiry> -newkey rsa:2048 -config openssl.cnf | openssl pkcs12 -export -out <keystore> -passout file:<password-file>

Authentication​

Authentication verifies user access to requested validator client methods.

Upon startup of the validator client, Teku creates an API token at the path /opt/teku/data/validator/key-manager. When calling an endpoint that requires authorization, you must send the generated token in the Authorization request header field with the Bearer authentication scheme.

Example
curl -H "Authorization: Bearer <TOKEN>" -X GET https://localhost:5052/eth/v1/keystores