BIP85: Update/clarify spec, add change log, Portuguese language code, dice application (bitcoin#1600)

* BIP-85:

    * Add new maintainer (author unreachable)
    * Swap chain code and private key bytes in application 32' for consistentcy with BIP-32 (major change)
    * Correct derived entropy for application 128169' test vector (major change)
    * Clarify big endian serialization
    * Add the Portuguese language (9') to application 39'
    * Add dice application 89101'
    * Clarify Testnet support for XPRV application 32'
    * Minor grammar, format, clarity improvements

Author: akarve

README.mediawiki

@@ -452,7 +452,7 @@ Those proposing changes should consider that ultimately consent may rest with th
 | [[bip-0085.mediawiki|85]]
 | Applications
 | Deterministic Entropy From BIP32 Keychains
-| Ethan Kosakovsky
+| Ethan Kosakovsky, Aneesh Karve
 | Informational
 | Draft
 |- style="background-color: #cfffcf"

bip-0085.mediawiki

@@ -3,6 +3,7 @@
   Layer: Applications
   Title: Deterministic Entropy From BIP32 Keychains
   Author: Ethan Kosakovsky <[email protected]>
+          Aneesh Karve <[email protected]>
   Comments-Summary: No comments yet.
   Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0085
   Status: Draft
@@ -14,10 +15,10 @@
 
 ==Abstract==
 
-''"One Seed to rule them all,''
-''One Key to find them,''
-''One Path to bring them all,''
-''And in cryptography bind them."''
+''One Seed to rule them all,''<br>
+''One Key to find them,''<br>
+''One Path to bring them all,''<br>
+''And in cryptography bind them.''
 
 It is not possible to maintain one single (mnemonic) seed backup for all keychains used across various wallets because there are a variety of incompatible standards. Sharing of seeds across multiple wallets is not desirable for security reasons. Physical storage of multiple seeds is difficult depending on the security and redundancy required.
 
@@ -33,6 +34,9 @@ The terminology related to keychains used in the wild varies widely, for example
 # '''BIP39 mnemonic''' is the mnemonic phrase that is calculated from the entropy used before hashing of the mnemonic in BIP39.
 # '''BIP39 seed''' is the result of hashing the BIP39 mnemonic seed.
 
+When in doubt, assume '''big endian''' byte serialization, such that the leftmost
+byte is the most significant.
+
 ==Motivation==
 
 Most wallets implement BIP32 which defines how a BIP32 root key can be used to derive keychains. As a consequence, a backup of just the BIP32 root key is sufficient to include all keys derived from it. BIP32 does not have a human friendly serialization of the BIP32 root key (or BIP32 extended keys in general) which makes paper backups or manually restoring the key more error-prone. BIP39 was designed to solve this problem but rather than serialize the BIP32 root key, it takes some entropy, encoded to a "seed mnemonic", which is then hashed to derive the BIP39 seed which can be turned into the BIP32 root key. Saving the BIP39 mnemonic is enough to reconstruct the entire BIP32 keychain, but a BIP32 root key cannot be reversed back to the BIP39 mnemonic.
@@ -51,6 +55,9 @@ For each application that requires its own wallet, a unique private key is deriv
 
 The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].
 
+Application codes may be arbitrary but should be semantic, such as a BIP number,
+ASCII character code sequence, or similar.
+
 ===Test vectors===
 
 ====Test case 1====
@@ -78,7 +85,7 @@ BIP85-DRNG-SHAKE256 is a deterministic random number generator for cryptographic
 RSA key generation is an example of a function that requires orders of magnitude more than 64 bytes of random input. Further, it is not possible to precalculate the amount of random input required until the function has completed.
 
     drng_reader = BIP85DRNG.new(bip85_entropy)
-    rsa_key = RSA.generate_key(4096, drng_reader.read())
+    rsa_key = RSA.generate_key(4096, drng_reader.read)
 
 ===Test Vectors===
 INPUT:
@@ -93,14 +100,15 @@ OUTPUT
 
 ==Reference Implementation==
 
-* Python library implementation: [https://github.com/ethankosakovsky/bip85]
-* JavaScript library implementation: [https://github.com/hoganri/bip85-js]
+* 2.0 Python library implementation: [https://github.com/akarve/bipsea]
+* 1.0 Python library implementation: [https://github.com/ethankosakovsky/bip85]
+* 1.0 JavaScript library implementation: [https://github.com/hoganri/bip85-js]
 
 ==Applications==
 
 The Application number defines how entropy will be used post processing. Some basic examples follow:
 
-Derivation path uses the format <code>m/83696968'/{app_no}'/{index}'</code> where ''{app_no}'' is the path for the application, and ''{index}'' is the index.
+Derivation path uses the format <code>m/83696968'/{app}'/{index}'</code> where ''{app}'' is the '''path''' for the application, and ''{index}'' is the index.
 
 ===BIP39===
 Application number: 39'
@@ -143,6 +151,10 @@ Language Table
 |-
 | Czech
 | 8'
+|-
+| Portuguese
+| 9'
+|-
 |}
 
 Words Table
@@ -207,7 +219,12 @@ OUTPUT:
 ===HD-Seed WIF===
 Application number: 2'
 
-Uses 256 bits[1] of entropy as the secret exponent to derive a private key and encode as a compressed WIF which will be used as the hdseed for Bitcoin Core wallets.
+Uses the most significant 32 bytes<ref name="curve-order">
+There is a very small chance that you'll make an invalid
+key that is zero or bigger than the order of the curve. If this occurs, software
+should hard fail (forcing users to iterate to the next index).</ref>
+of entropy as the secret exponent to derive a private key and encode as a compressed
+WIF which will be used as the hdseed for Bitcoin Core wallets.
 
 Path format is <code>m/83696968'/2'/{index}'</code>
 
@@ -222,17 +239,26 @@ OUTPUT
 ===XPRV===
 Application number: 32'
 
-Taking 64 bytes of the HMAC digest, the first 32 bytes are the chain code, and second 32 bytes[1] are the private key for BIP32 XPRV value. Child number, depth, and parent fingerprint are forced to zero.
+Consistent with BIP32, use the first (leftmost) 32 bytes of the derived entropy as the
+private key<ref name="curve-order" />. Prepend an empty byte (<code>0x00</code>)
+per BIP32 on master key serialization. Use the last (rightmost) 32 bytes as the chain code.
+
+Child number, depth, and parent fingerprint are forced to zero, as with any root
+private key.
+
 
 Path format is <code>m/83696968'/32'/{index}'</code>
 
+
+Applications may support Testnet by emitting TPRV keys if and only if the input root key is a Testnet key.
+
 INPUT:
 * MASTER BIP32 ROOT KEY: xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb
 * PATH: m/83696968'/32'/0'
 
 OUTPUT
 * DERIVED ENTROPY=ead0b33988a616cf6a497f1c169d9e92562604e38305ccd3fc96f2252c177682
-* DERIVED XPRV=xprv9s21ZrQH143K2srSbCSg4m4kLvPMzcWydgmKEnMmoZUurYuBuYG46c6P71UGXMzmriLzCCBvKQWBUv3vPB3m1SATMhp3uEjXHJ42jFg7myX
+* DERIVED XPRV=xprv9s21ZrQH143K4Px85utdpu6DFvY2NpHkJajPoupAznfiacH2MC9LasyW4uvqKXNxLWcjqGTbHKAhoZoMAbmRe5g9tAPA7cUUX4UVA1vFKFm
 
 ===HEX===
 Application number: 128169'
@@ -285,7 +311,7 @@ INPUT:
 * PATH: m/83696968'/707764'/21'/0'
 
 OUTPUT
-* DERIVED ENTROPY=d7ad61d4a76575c5bad773feeb40299490b224e8e5df6c8ad8fe3d0a6eed7b85ead9fef7bcca8160f0ee48dc6e92b311fc71f2146623cc6952c03ce82c7b63fe
+* DERIVED ENTROPY=74a2e87a9ba0cdd549bdd2f9ea880d554c6c355b08ed25088cfa88f3f1c4f74632b652fd4a8f5fda43074c6f6964a3753b08bb5210c8f5e75c07a4c2a20bf6e9
 * DERIVED PWD=dKLoepugzdVJvdL56ogNV
 
 ===PWD BASE85===
@@ -295,7 +321,7 @@ The derivation path format is: <code>m/83696968'/707785'/{pwd_len}'/{index}'</co
 
 `10 <= pwd_len <= 80`
 
-Base85 encode the all 64 bytes of entropy.
+Base85 encode all 64 bytes of entropy.
 Remove any spaces or new lines inserted by Base64 encoding process. Slice base85 result string
 on index 0 to `pwd_len`. This slice is the password. `pwd_len` is limited to 80 characters.
 
@@ -326,6 +352,40 @@ OUTPUT
 * DERIVED ENTROPY=f7cfe56f63dca2490f65fcbf9ee63dcd85d18f751b6b5e1c1b8733af6459c904a75e82b4a22efff9b9e69de2144b293aa8714319a054b6cb55826a8e51425209
 * DERIVED PWD=_s`{TW89)i4`
 
+===DICE===
+
+Application number: 89101'
+
+The derivation path format is: <code>m/83696968'/89101'/{sides}'/{rolls}'/{index}'</code>
+
+    2 <= sides <= 2^32 - 1
+    1 <= rolls <= 2^32 - 1
+
+Use this application to generate PIN numbers or any other numeric secret.
+Roll values are zero-indexed, such that an N-sided die produces values in the range
+<code>[0, N-1]</code>, inclusive. Applications should separate printed rolls by a comma or similar.
+
+Create a BIP85 DRNG whose seed is the derived entropy. 
+
+Calculate the following integers:
+
+    bits_per_roll = ceil(log_2(sides))
+    bytes_per_roll = ceil(bits_per_roll / 8)
+
+Read <code>bytes_per_roll</code> bytes from the DRNG.
+Trim any bits in excess of <code>bits_per_roll</code> (retain the most
+significant bits). The resulting integer represents a single roll or trial.
+If the trial is greater than or equal to the number of sides, skip it and
+move on to the next one. Repeat as needed until all rolls are complete.
+
+INPUT:
+* MASTER BIP32 ROOT KEY: xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb
+* PATH: m/83696968'/89101'/6'/10'/0'
+
+OUTPUT
+* DERIVED ENTROPY=5e41f8f5d5d9ac09a20b8a5797a3172b28c806aead00d27e36609e2dd116a59176a738804236586f668da8a51b90c708a4226d7f92259c69f64c51124b6f6cd2
+* DERIVED ROLLS=1,0,0,2,0,1,5,5,2,4
+
 ===RSA===
 
 Application number: 828365'
@@ -374,9 +434,21 @@ Many thanks to Peter Gray and Christopher Allen for their input, and to Peter fo
 
 BIP32, BIP39
 
+==Change Log==
+
+* 1.0 (2020-07)
+* 2.0.0 (2024-09-22)
+    * Swap chain code and private key bytes in application 32' for consistentcy with BIP-32 (major change)
+    * Correct derived entropy for application 128169' test vector (major change)
+    * Clarify big endian serialization
+    * Add the Portuguese language (9') to application 39'
+    * Add dice application 89101'
+    * Clarify Testnet support for XPRV application 32'
+    * Minor grammar, format, clarity improvements
+
 ==Footnotes==
 
-[1] There is a very small chance that you'll make an invalid key that is zero or bigger than the order of the curve. If this occurs, software should hard fail (forcing users to iterate to the next index).
+<references />
 
 From BIP32:
 In case parse<sub>256</sub>(I<sub>L</sub>) is 0 or ≥ n, the resulting key is invalid, and one should proceed with the next value for i. (Note: this has probability lower than 1 in 2<sup>127</sup>.)