#seed #phrase #generation #generate #numbers #original #validate

bin+lib harpo

The harpo crate provides functionality to secret-share seed phrases

6 releases

0.7.0 Dec 17, 2021
0.6.4 Dec 14, 2021
0.6.2 Nov 30, 2021
0.6.0 Oct 29, 2021

#3 in #phrase

GPL-3.0-or-later

130KB
2K SLoC

harpo

harpo is a tool and library that provides the following functionality:

  • It can generate a seed phrase.
  • It can validate a given seed phrase.
  • Given a valid seed phrase, it can generate any number of secret-shared seed phrases.
  • Given sufficiently many generated seed phrases, it can reconstruct the original seed phrase.

The harpo crate gets its name from Harpocrates, the ancient god of silence, secrecy, and confidentiality.

While harpo is reasonably well tested, use it at your own risk.

Compilation

Make sure that Rust is installed.

After cloning the repository and changing the directory to harpo, run the following command:

cargo build --release

The binary can then be found under target/release (or target/debug when running the command without the --release flag).

Usage

Generation of a Seed Phrase

A seed phrase can be generated by running the following command:

harpo generate --length [L]

The length [L] must be either 12, 15, 18, 21, or 24. The generated seed phrase is written to standard output.

Validation of a Seed Phrase

A seed phrase can be validated, i.e. checked for BIP-0039 compliance, by running the following command:

harpo validate (--file [F]))

The input is provided in one of two ways:

  • By default, the seed phrase is entered on the command line.
  • When using the --file (-f) option, the space-delimited seed phrase is read from the file at path [F].

For example, the content of the file or input provided interactively may be:

cat swing flag economy stadium alone churn speed unique patch report train

Creation of Secret-Shared Seed Phrases

In order to create secret-shared seed phrases, run the following command:

harpo create --num-shares [N] --threshold [T] (--file [F])

The input is again provided in one of two ways, on the command line or using the --file (-f) option, in which case the space-delimited seed phrase is read from the file at path [F].

Note that the input seed phrase must pass validation, otherwise the execution will terminate with an error message.

Apart from specifying the input source, two other parameters are required:

  • --num-shares (-n) [N]: The desired number [N] of secret-shared seed phrases must be provided. Note that the number of shares can be at most 16 unless the option --no-embedding is used (see Additional Parameters).
  • --threshold (-t) [T]: The desired threshold [T], i.e., the minimum number of secret-shared seed phrases required to reconstruct the original seed phrase, must be provided. The threshold must not exceed the number of shares.

The created seed phrases are written to standard output.

Reconstruction of a Secret-Shared Seed Phrase

In order to reconstruct the original seed phrase, run the following command:

harpo reconstruct (--file [F] | --interactive)

Again, the input is provided in one of two ways:

  • By default, the seed phrases are entered on the command line, one after the other.
  • When using the --file (-f) option, the space-delimited seed phrases are read from the file at path [F], one seed phrase per line.

The reconstructed seed phrase is written to standard output. If at least [T] secret-shared seed phrases are provided, the output will match the original seed phrase. Otherwise, the output is indistinguishable from a random seed phrase.

Additional Parameters

The following additional parameters can be specified (before entering the subcommand):

  • --verbose (-v): Add this flag in order to activate verbose output.
  • --word-list (-w) [W]: A different word list (other than the standard English word list) can be provided. It has to be a list of 2048 distinct words, with one word per line.

There is one optional parameter for the create subcommand:

  • --no-embedding (-N): By default, the secret-shared seed phrases are not BIP-0039 compliant because they encode an index that is required for the reconstruction. In order to obtain BIP-0039 compliant seed phrases, the embedding can be turned off using this flag. In this case, the indices must be provided explicitly when using the reconstruct command. The format is [INDEX]: [SEED PHRASE].

All available parameters can be printed using the --help (-h) flag for each subcommand.

Dependencies

~3MB
~56K SLoC