BLS12-381 v4 Keystore converter

Converts BLS12-381 v4 keystore's kdf function parameters.

---

Warning

The kdf function parameters should not be lower for production keys. The OWASP recommend minimum SCRYPT n parameter should be 2^17=131072. The defaults for v4 keystores are 2^18=262144. Use this program at your own risk!

---

About

This program decrypts v4 (BLS) keystores and re-encrypt them again with supplied kdf function parameters. The v4 keystore generated by other tools is typically using SCRYPT with cpu cost parameter n=262144 which makes it very secure but very expensive to compute, which makes start up time of validators very long. By decreasing n parameter in SCRYPT or c parameter in PBKDF2, the decryption time can be decreased drastically. The lower the value, the faster the decryption.

The encryption/decryption code is based on Teku

Usage:

To use this program, either build it from source or download the pre-built binaries from the releases pages. This program requires Java 21 or higher to build and run. The gradle build will attempt to download and use appropriate Java version if required.

Build from source:

git clone https://github.com/usmansaleem/v4keystore_converter.git
cd v4keystore_converter
./gradlew installDist
cd ./converter/build/install/converter/bin

Download pre-built binaries:

Download pre-built binaries from the assets on the releases

tar -xvzf ./converter-<version>.tar.gz
cd ./converter-<version>/bin

Usage:

This program uses WEB3SIGNER and NIMBUS mode to expect the keystore and their password files naming patterns.

WEB3SIGNER mode:

In this mode, the keystore files are stored in a directory as <public-key>.json and password files are stored in a different directory as <public-key>.txt. This is the default mode.

NIMBUS mode:

In this mode, the keystore files are stored in a directory as <public-key>/keystore.json where <public-key> is a subdirectory; while the password files are stored in a different directory as <public-key>, a regular file, without any extension.

Following is the minimal usage of the program, defaulting to WEB3SIGNER mode, change the paths as per your requirements:

./converter --src=<path>/keys/ \
 --password-src=<path>/secrets \
 --dest=<path>/converted

To get complete list of options, run the program with --help flag:

./converter --help
Usage: converter [-hV] --src=<PATH> --dest=<PATH> --password-src=<PATH>
                 [--mode=<MODE>] [--kdf-function=<KDF>] [-c=<INTEGER>]
                 [-n=<INTEGER>] [-p=<INTEGER>] [-r=<INTEGER>]
Convert KDF function parameters of EIP-2335 v4 keystores
      --src=<PATH>           Source directory containing v4 keystores
      --dest=<PATH>          Destination directory where converted v4 keystores
                               will be placed.
      --password-src=<PATH>  Path to directory containing passwords files.
      --mode=<MODE>          Keystores Bulk-loading mode. WEB3SIGNER mode
                               expects [<pk>.json | <pk>.txt] while NIMBUS mode
                               expects [<pk>/keystore.json | <pk>] as
                               keystore/password file pair. Valid Values:
                               WEB3SIGNER, NIMBUS. Defaults to: WEB3SIGNER
      --kdf-function=<KDF>   Kdf Function to convert to. Valid values: PBKDF2,
                               SCRYPT. Defaults to: PBKDF2
  -h, --help                 Show this help message and exit.
  -V, --version              Print version information and exit.
PBKDF2 Options
  -c=<INTEGER>               Iterative count parameter. Required for PBKDF2 kdf
                               function. Defaults to 1.
SCRYPT Options
  -n=<INTEGER>               CPU/memory cost parameter. Required for SCRYPT kdf
                               function. Defaults to 2.
  -p=<INTEGER>               Parallelization parameter. Required for SCRYPT kdf
                               function. Defaults to 1.
  -r=<INTEGER>               Block size parameter. Required for SCRYPT kdf
                               function. Defaults to 8.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option. SPDX-License-Identifier: (Apache-2.0 OR MIT)

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.