hcseedbundle

SeedBundle parsing and generation library.

Links

• Git Repo - https://github.com/holochain/lair
• API Documentation - https://docs.rs/hcseedbundle
• Javascript Implementation - https://holochain.github.io/hcSeedBundle/

Rationale

• Applications like Holochain have different requirements than classic blockchain system in terms of key management. Namely there is no need for read-only or hardened wallets (Holochain handles these concepts through capabilities and membranes).
• Applications like Holochain still have need of hierarchy and determinism in key (or in this case seed) derivation.
• Since we're using libsodium for hashing, signature, and encryption algorithms, let's use it for derivation as well.
• To be psychologically compatible with the Bitcoin "HD Wallet" spec, we will do away with the "context" part of sodium KDF by always setting it to b"SeedBndl" and focusing on the subkey_id and can declare a chain of subsequent derivations of a 32 byte seed in the form m/68/1/65/8 where we apply subkey_ids 68, 1, 65, then 8 in turn.

hcSeedBundle Encoding Spec

Encoded in MSGPACK binary format.

To better facilitate rust/javascript interoperability, the rust library will treat msgpack "ext" types as binary data.

SeedBundle

``` // seedbundle is a top-level array 'seedbundle':array [ // literal 'hcsb0' version / heuristic marker 'id_ver':str,

// list of SeedCiphers define how to decrypt 'cipherlist':array [ 'cipher1':SeedCipher, 'cipher2':SeedCipher, // .. 'cipherN':SeedCipher, ],

// associated application data 'app_data':bin, ] ```

SeedCipher::PwHash

``` // the PwHash type SeedCipher defines a straight-forward // pwhash secret that is use to secretstream encrypt a seed 'seed_cipher':array [ // literal 'pw' indicates the pw hash cipher type 'type':str,

// argon2id 16 byte salt 'salt':bin,

// argon2id mem limit capped to u32 for js compatibility 'mem_limit':int,

// argon2id ops limit capped to u32 for js compatibility 'ops_limit':int,

// secretstream 24 byte header 'header':bin,

// secretstream 49 byte cipher 'cipher':bin, ] ```

SeedCipher::SecurityQuestions

``` // Security Questions SeedCipher defines a pwhash cipher // based on concatonating 3 answers that are lcased/trimmed 'seed_cipher':array [ // literal 'qa' indicates the security question cipher type 'type':str,

// argon2id 16 byte salt 'salt':bin,

// argon2id mem limit capped to u32 for js compatibility 'mem_limit':int,

// argon2id ops limit capped to u32 for js compatibility 'ops_limit':int,

// the first security question to be answered 'question_1':str,

// the second security question to be answered 'question_2':str,

// the third security question to be answered 'question_3':str,

// secretstream 24 byte header 'header':bin,

// secretstream 49 byte cipher 'cipher':bin, ] ```

Algorithms

• sodium_kdf32 - seed derivation
  • set to output 32 bytes ([32 byte sub-seed])
  • context bytes - fixed b"SeedBndl"
  • subkey_id clamped to u32 to better support javascript
• argon2id32 - generates secret for seed secretstream encryption
  • set to output 32 bytes ([32 secret bytes])
  • salt: [16 salt bytes from bundle]
  • memlimit: default MODERATE
  • opslimit: default MODERATE
  • passphrase: user-supplied
• secretstream_xchacha20poly1305
  • single push_final/pull_final with entire contents