Stronghold Usage Examples

The following examples explain how Stronghold works. There are two sets of examples:

Command-line interface examples: A simple command-line interface for generating secrets, working with the store, and other topics.
REPL example: A read-evaluate-print-loop for interactively working with a Stronghold instance.

Command Line Interface

You should run the examples from within the client crate. The examples shown in this doc were executed on Linux but should work on the other supported platforms. Make sure to adapt paths according to your operating system default. For example, Windows(TM) requires backslashes \ as a delimiter for a path. This could pose a problem, as backslashes are also used to escape characters.

Generate an Ed25519 key pair and print the public key on console

This example will generate a Ed25519 key pair inside an ephemeral vault print the public key into the console.

$ cargo run --example cli generate-key --key-type Ed25519 --vault-path "vault_path" --record-path "record_path"

Executing this command should print something similar:

[2022-03-28T08:21:47Z INFO  cli] Generating keys with type ED25519
[2022-03-28T08:21:47Z INFO  cli] Using output location: vault_path=vault_path, record_path=record_path
[2022-03-28T08:21:47Z INFO  cli] Key generation successful? true
[2022-03-28T08:21:47Z INFO  cli] Creating public key
[2022-03-28T08:21:47Z INFO  cli] Public key is "9IYNQfZJQiHpQJZiHpYG2p6FEy8B9qGcwZ3Le8u1bU0=" (Base64)

Write some value into the store, read it again and print the output on console

A new ephemeral store is being created and a value with an associated key will be written into it.

$ cargo run --example cli store-read-write  --key "key" --value "value"

This should give you following output:

[2022-03-28T08:21:47Z INFO  cli] Insert value into store "value" with key "key"
[2022-03-28T08:21:47Z INFO  cli] Store contains key "key" ? true
[2022-03-28T08:21:47Z INFO  cli] Value for key "key" ? "value"

Generate A BIP39 Seed and Return the Mnemonic Phrase

This will create a new BIP39 seed with the associates mnemonic in the available languages. An optional passphrase can be provided to protect the seed.

$ cargo run --example cli bip39-generate  --passphrase "optional-passphrase" --lang "japanese" --vault-path "vault-path-0" --record-path "record-path-0"

This should give you following output:

[2022-03-28T08:21:47Z INFO  cli] BIP39 Mnemonic: ほんしつ　あんぜん　ざんしょ　ひなまつり　りんご　けわしい　のみもの　ろしゅつ　へらす　せんさい　すずしい　ひんこん　あぶら　けんり　かいつう　しごと　きもの　ほんやく　くたびれる　むらさき　かいてん　たすける　あめりか　るいさい

Generate SLIP10 Master Key

Derives a SLIP10 master key with optional size.

$ cargo run --example cli slip10-generate --size 512 --vault-path "slip10-vault-path" --record-path "slip10-record-path"

This should give you following output:

[2022-03-28T08:24:00Z INFO  cli] SLIP10 seed successfully created? true

Derive SLIP10 Private Public Keypair

This example creates an ephemeral SLIP10 master key and derives a private/public key pair from it. The public key will be returned.

$ cargo run --example cli slip10-derive  --chain "/1234567/1234567" --input-vault-path "input-vault-path" --input-record-path "input-record-path" --output-vault-path "output-vault-path" --output-record-path "output-record-path"

This should give you following output:

[2022-03-28T08:24:38Z INFO  cli] Deriving SLIP10 Child Secret
[2022-03-28T08:24:38Z INFO  cli] Derivation Sucessful? true

Create a Snapshot

This example creates a new snapshot on the file system and generates and stores a new key (Ed25519) inside the desired location.

$ cargo run --example cli create-snapshot --path "/path/to/snapshot.file" --client-path "client-path-0" --vault-path "vault-path" --record-path "record-path" --key "passphrase"

This should give you following output:

[2022-03-28T08:27:35Z INFO  cli] Snapshot created successully true

Read a Snapshot From Filesystem

This example reads a snapshot from the file system and returns the public key from the stored secret key (Ed25519) stored at the given location

$ cargo run --example cli read-snapshot --path "/path/to/snapshot.file" --client-path "client-path-0" --vault-path "vault-path" --record-path "record-path" --key "passphrase"

This should give you following output:

[2022-03-28T08:29:33Z INFO  cli] Loading snapshot
[2022-03-28T08:29:33Z INFO  cli] Creating public key
[2022-03-28T08:29:33Z INFO  cli] Public key is "smsmXBG/Ln/Yjip72OJns4PB4iejVBIzs4MOXO9IkTE=" (Base64)

Recover a BIP39 Seed with a Mnemonic and Optional Passphrase

This example recovers a BIP39 seed with provided mnemonic and optional passphrase. Stronghold will store the recovered seed at the provided location.

$ cargo run --example cli bip39-recover --path "/path/to/snapshot.file" --client-path "client-path-0" --key "passphrase-for-snapshot" --mnemonic "けさき　にんか　せっさたくま　よかん　たいまつばな　ちんもく　そだてる　ふっこく　せっさたくま　しゃおん　そがい　つうはん　まなぶ　りくぐん　さのう" --passphrase "mnemonic-passphrase-if-present" --vault-path "vault-path" --record-path "record-path"

This should give you following output:

[2022-03-28T08:35:13Z INFO  cli] Loading snapshot
[2022-03-28T08:35:13Z INFO  cli] Recovering BIP39
[2022-03-28T08:35:13Z INFO  cli] BIP39 Recovery successful? true

REPL Example

Stronghold features a simple read-evaluate print loop (REPL) to showcase basic operations from an interaction command shell-like environment. The REPL maintains a state of a running Stronghold instance to store secrets or configuration data.

You can start REPL from a terminal inside the root folder of Stronghold by running the following command:

cargo run --example repl

Available Commands

You can use the following commands:

Command	Parameters	Description
help	-	Display a help message.
init	< client_path >	Initializes the underlying Stronghold system.
keygen	< key_type > < vault_path > < record_path >	Generates a "ed25510" or "x25519" key at a location composed of "vault_path" and "record_path".
backup	< path_to_snapshot_location > < passphrase >	Writes the current Stronghold state to "path_to_snapshot_location" (a path) with "passphrase".
restore	< path_to_snapshot_location > < passphrase >	Loads the current Stronghold state from "path_to_snapshot_location" (a path) with "passphrase".
slip10gen	< vault_path > < record_path >
slip10derive	< chain > < vault_path_origin > < record_path_origin > < vault_path_derive > < record_path_derive >	Derives a new key from old location and stores it into the new location. The key will be derived from the provided chain code.
mnemonic	-	Creates a BIP39 mnemonic and generates a seed.
bip39restore	-
quit	-	Exits the REPL.
checkrecord	< vault_path > < record_path >	Checks a record inside the vault. The command will return `yes` if the record exists or `no` if it doesn't.
checkvault	< vault_path >	Checks for the presence of a vault.

Note: Each command will show a short help message, if the entered command or parameters are incorrect.