Skip to content

Commit

Permalink
docs: add new tutorial page on seed generation and fixes (#561)
Browse files Browse the repository at this point in the history
* docs: address documentation feedback

* docs: add create seed tut

* docs: refine seed gen doc

* docs: empty [skip ci]

* Update docs/docusaurus/secrets/seed-generation.md

Co-authored-by: Yurii Shynbuiev - IOHK <[email protected]>

---------

Co-authored-by: Yurii Shynbuiev - IOHK <[email protected]>
  • Loading branch information
patlo-iog and yshyn-iohk authored Jun 21, 2023
1 parent 7ce5c99 commit 3d7696b
Show file tree
Hide file tree
Showing 3 changed files with 62 additions and 5 deletions.
9 changes: 5 additions & 4 deletions docs/docusaurus/secrets/operation.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,16 @@

## Introduction

PRISM agent is a cloud-based agent within the SSI ecosystem that offers user
DID (Decentralized Identifier) management. To generate a DID key material,
the software relies on a seed, following the BIP32 / BIP39 standards.
PRISM agent offers a DID (Decentralized Identifier) management solution
which involves creating, storing and using key materials.
To generate a DID key material, the software relies on a seed, following the BIP32 / BIP39 standards.
The system operators have the option to either provide their own seed or
allow the software to generate one automatically. However, in a production environment,
it is crucial for the system operators to explicitly supply the seed to the agent.
This ensures full control over the DID key material and guarantees secure management of user identities.

The PRISM agent has a default configuration of starting in non-development mode.
The PRISM agent includes a development mode that conveniently bypasses certain checks during development or integration.
By default, the agent does not start in the development mode.
This behavior can be modified using the `DEV_MODE` environment variable,
which accepts the value `true` or `false`.
In development mode, the agent can start with or without a user-provided seed.
Expand Down
55 changes: 55 additions & 0 deletions docs/docusaurus/secrets/seed-generation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Creating a PRISM agent wallet seed

## Introduction

PRISM agent utilizes a hierarchical-deterministic key derivation algorithm for managing PRISM DIDs,
which follows the BIP32 standard. In order to generate the required keys,
BIP32 uses a master binary seed serving as the root of the derivation tree,
and all other keys are derived from this seed.
Given that the PRISM agent employs BIP32, it expects a 64-byte binary seed as input.
Various methods exist for generating a byte sequence, each serving different purposes.

PRISM agent does not have any opinion on how the seed should be generated as long as a valid hex string is provided.
However, it is strongly recommended to use high entropy for generating the master seed.
PRISM agent allows customizing the wallet seed by using the environment variable `WALLET_SEED`.
The variable must contain a 64-byte value encoded in hexadecimal format.

### 1. Static seed

PRISM agent expects any valid 64-byte input for a wallet seed.
Any static 128-character hexadecimal string can be used to simplify the testing.

For example

```sh
# Any of these are valid
WALLET_SEED=00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
WALLET_SEED=11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111
WALLET_SEED=0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a
```
__Note: Do not use method this in production.__

### 2. Simple dynamic seed

Users have the option to create a random hexadecimal string of a desired length using scripting languages
like Bash or Python. An example of a Bash script is shown below.

```bash
WALLET_SEED=$(tr -dc a-f0-9 </dev/urandom | head -c 128 ; echo '')
```
This approach is suitable for basic testing scenarios requiring dynamically generated seeds.
However, for production use, it is advisable to employ a reputable implementation of BIP39
with a high level of entropy. (Refer to the details below for further information.)


### 3. Use BIP39 implementation to generate a seed (recommended)

The [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki#user-content-From_mnemonic_to_seed)
protocol can be utilized to generate a BIP32 master seed, offering a human-friendly approach to seed management.
Instead of noting down a seemingly random hexadecimal string,
users can write down their mnemonic phrase, making it more convenient to keep track of them.

By using BIP39, users have options to choose a mnemonic phrase length as well as a passphrase.
There are many tools for generating a BIP39 seed including but not limited to:
- <https://iancoleman.io/bip39/> (use the BIP39 seed field which provides a 128-chars hex string)
- [BIP39 - implementations section](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki#other-implementations) also provides a list of implementations
3 changes: 2 additions & 1 deletion docs/docusaurus/sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,8 @@ const sidebars = {
description: 'Secret Management'
},
items: [
'secrets/operation'
'secrets/operation',
'secrets/seed-generation'
]
}
]
Expand Down

0 comments on commit 3d7696b

Please sign in to comment.