Skip to content

Latest commit

 

History

History
377 lines (306 loc) · 20.6 KB

ur-2-keys.md

File metadata and controls

377 lines (306 loc) · 20.6 KB
Raw

A Guide to Using URs for Key Material

Uniform Resources (URs) allow for the encoding of self-describing, structured binary data in text strings that can are optimized for transmission in QR Codes. The types of data that Blockchain Commons has specified for URs appear in Registry of UR Types and include a variety of key material including seeds, keys, and BIP-39 mnemonics. (SSKR shards can also be encoded as URs, but are the subject of a later article.)

Key material is the most valuable data in a cryptography system because private keys and the seeds from which they are derived control cryptocurrency, verify identity, and serve other crucial purposes. For this reason it should be carefully secured — if possible with airgapping, where the material is held in some non-networked place. That's where URs come in. They allow key material to be encoded as URs, converted into QRs, and then transmitted across an airgap in a way that's safe and secure, minimizing its vulnerability at the time when it's the most vulnerable.

The above image, drawn from our interoperability demo for LetheKit and Gordian Cosigner shows how an xpub and an xprv can be transmitted between airgapped devices using standardized, typed URs.

The following major categories of key material are available as URs: seeds, HD keys, and BIP 39 words.

Why Use URs for Key Material?

Why use URs for your key material when you could pass bare seeds, the mnemonic words themselves, or xprvs and xpubs for HD keys?

The biggest reason is interoperability. URs are all self-identifying, so you always know exactly what you're getting. They're also built to be encoded into QRs, which is a great way to transfer data across airgaps. The result is an easy, safe way to transfer key material and to expect that it will be understood by products produced by a variety of other manufacturers.

This is particularly important for key material because, as noted earlier, it is both the core of controlling cryptocurrency (and other digital assets) and uniquely vulnerable to theft or loss.

  1. By using a system that integrates well with airgaps, you can maximize the safety of key material without potentially falling prey to man-in-the-middle attacks and you can simultaneously maintain the security of airgapped devices.
  2. By using a self-describing, interoperable method to store key material, you can ensure that it will remain well-understood and thus usable far into the future, not becoming muddled with the huge variety of standards for key material that could otherwise result in it becoming effectively unsuable if a user has no idea what it is.

Key Material: crypto-seed

A seed is the basis of a Bitcoin account. It's typically generated by a wallet, or alternatively a seed generator such as Blockchain Commons' LetheKit or seedtool.

A Simple Seed

A simple, unadorned seed looks like this:

59F2293A5BCE7D4DE59E71B4207AC5D2

As discussed in the UR Overview, this seed can be converted to the CBOR A1015059F2293A5BCE7D4DE59E71B4207AC5D2 and then a ur:crypto-seed:

ur:crypto-seed/oyadgdhkwzdtfthptokigtvwnnjsqzcxknsktdhpyljeda

Decoding a Simple Seed

The Bytewords and CBOR apps demonstrate how this seed can then be broken down into its constituent parts.

The bytewords CLI can be used to convert the Bytewords minimal encoding used in URs to CBOR:

$ bytewords -i minimal -o hex OYADGDHKWZDTFTHPTOKIGTVWNNJSQZCXKNSKTDHPYLJEDA
a1015059f2293a5bce7d4de59e71b4207ac5d2

The CBOR CLI can then be used to decode the result, revealing a map with just one item, which is the seed itself:

$ cbor2diag -x a1015059f2293a5bce7d4de59e71b4207ac5d2
{1: h'59f2293a5bce7d4de59e71b4207ac5d2'}

UR was built to support clean and efficient conversion into QR codes. That same seed can be encoded into a QR code as following:

If you read this with a QR reader you'll get:

UR:CRYPTO-SEED/OYADGDHKWZDTFTHPTOKIGTVWNNJSQZCXKNSKTDHPYLJEDA

As shown in the following screenshot from Gordian QRTool:

A Seed with Metadata

More complex examples of ur:crypto-seed may incorporate a creation date (map element #2, tagged 100), a name (map element #3), and/or a note (map element #4) as detailed in the crypto-seed CDDL.

The CBOR for a ur:crypto-seed containing all of these elements could look like the following:

a4015059f2293a5bce7d4de59e71b4207ac5d202D8641A6092DC07036541636F726E046C436F66666565206D6F6E6579

This is a CBOR map containing four elements.

It breaks apart as shown:

A4                                     # map(4)
   01                                  # element #1
   50                                  # 16 bytes in length
      59F2293A5BCE7D4DE59E71B4207AC5D2 # SEED
   02                                  # element #2
   D8 64                               # tag(100) (date)
      1A 6092DC07                      # CREATION DATE (1620237319)
   03                                  # element #3
   65                                  # 5-character text
      41636F726E                       # NAME ("Acorn")
   04                                  # element #4
   6C                                  # 12-character text
      436F66666565206D6F6E6579         # NOTE("Coffee money")

The CBOR-CLI can similarly be used to decode this information:

$ cbor2diag -x a4015059f2293a5bce7d4de59e71b4207ac5d202D8641A6092DC07036541636F726E046C436F66666565206D6F6E6579
{
    1: h'59f2293a5bce7d4de59e71b4207ac5d2',
    2: 100(1620237319),
    3: "Acorn",
    4: "Coffee money"
}

Using the Bytewords CLI you can convert the CBOR to minimal Bytewords:

$ bytewords -i hex -o minimal a4015059f2293a5bce7d4de59e71b4207ac5d202D8641A6092DC07036541636F726E046C436F66666565206D6F6E6579
oxadgdhkwzdtfthptokigtvwnnjsqzcxknsktdaotpiecyhnmouoataxihfpiajljpjtaajzfxjliyiyihihcxjnjljtihkkpseernwl

And you have a crypto-seed:

UR:CRYPTO-SEED/OXADGDHKWZDTFTHPTOKIGTVWNNJSQZCXKNSKTDAOTPIECYHNMOUOATAXIHFPIAJLJPJTAAJZFXJLIYIYIHIHCXJNJLJTIHKKPSEERNWL

Mnemonic Words: crypto-bip39

BIP39 details how mnemonic words can be used to define a master seed. These words can also be encoded for transportation using URs, as defined in the CDDL for BIP39.

The encoding is simple, requiring a map with an array of words and a language.

The test vector A2018C66736869656C646567726F75706565726F6465656177616B65646C6F636B6773617573616765646361736865676C6172656477617665646372657765666C616D6565676C6F76650262656E demonstrates the usage:

cbor2diag -x A2018C66736869656C646567726F75706565726F6465656177616B65646C6F636B6773617573616765646361736865676C6172656477617665646372657765666C616D6565676C6F76650262656E
{
 1:
    [
     "shield",
     "group",
     "erode",
     "awake",
     "lock",
     "sausage",
     "cash",
     "glare",
     "wave",
     "crew",
     "flame",
     "glove"
    ],
 2: "en"
}

Converting this to minimal bytewords results in:

ur:crypto-bip39/oeadlkiyjkisinihjzieihiojpjlkpjoihihjpjlieihihhskthsjeihiejzjliajeiojkhskpjkhsioihieiahsjkisihiojzhsjpihiekthskoihieiajpihktihiyjzhsjnihihiojzjlkoihaoidihjtrkkndede

Key Material: crypo-hdkey

HD Keys allow for a hierarchy of keys. Both master keys and derived keys can be encoded using URs, as described in the CDDL for hdkeys.

A Master Key

The following master HD key is derived from the seed 59F2293A5BCE7D4DE59E71B4207AC5D2:

xprv9s21ZrQH143K4Mnjc7E8rpSMf8JB1XWmojYf7Ndk6zcNSbUYBsvTqJcdzTok1XwYcgytn5CRxtwhHu93NNXNQwGUbBqL3AHHZZrtKpEvmww

That Base58 xprv decodes to hex as follows:

0488ade4000000000000000000b40359eb975b5e662298db589f75ed694b17755abbd0a230c24ffb8ac2be66fd0046f8a7a92fc3ca4fd4cbf3cb5bacde4356ce790e2cd6bc206ea2574ef8991318fe6a22e3

BIP32 reveals that this information is partitioned as follows:

  • 04 ; version 4
  • 88ade4 ; xprv
  • 00 ; depth 0 == master key
  • 00000000 ; parent fingerprint
  • 00000000 ; child number
  • b40359eb975b5e662298db589f75ed694b17755abbd0a230c24ffb8ac2be66fd ; chain code
  • 0046f8a7a92fc3ca4fd4cbf3cb5bacde4356ce790e2cd6bc206ea2574ef8991318 ; key data
  • fe6a22e3 ; base58 checksum

Per the CDDL, creating the CBOR for this master key requires creating a map with 3 to 4 elements, which:

  1. identify the hdkey as a master key in map element #1;
  2. optionally mark it as private in map element #2; and
  3. encode the key data and chain code in map elements #3 and #4.

The resulting CBOR is:

A401F502F50358210046F8A7A92FC3CA4FD4CBF3CB5BACDE4356CE790E2CD6BC206EA2574EF8991318045820B40359EB975B5E662298DB589F75ED694B17755ABBD0A230C24FFB8AC2BE66FD

This decodes as follows:

$ cbor2diag -x A401F502F50358210046F8A7A92FC3CA4FD4CBF3CB5BACDE4356CE790E2CD6BC206EA2574EF8991318045820B40359EB975B5E662298DB589F75ED694B17755ABBD0A230C24FFB8AC2BE66FD
{
    1: true,
    2: true,
    3: h'0046f8a7a92fc3ca4fd4cbf3cb5bacde4356ce790e2cd6bc206ea2574ef8991318',
    4: h'b40359eb975b5e662298db589f75ed694b17755abbd0a230c24ffb8ac2be66fd'

}

As usual, converting to Bytewords then allows creation of the UR:

$ bytewords -i hex -o minimal A401F502F50358210046F8A7A92FC3CA4FD4CBF3CB5BACDE4356CE790E2CD6BC206EA2574EF8991318045820B40359EB975B5E662298DB589F75ED694B17755ABBD0A230C24FFB8AC2BE66FD
oxadykaoykaxhdclaefgyaosptdlsrsggwtysbwfsbhppsuefxhftokkbadwtbrfcxjtoehgglyanlbwcsaahdcxqzaxhkwmmshphyiycpmkuyhdnekpweingrchkphtrktioedysagwzolesarniyzcrhdntkbb

The result is:

ur:crypto-hdkey/oxadykaoykaxhdclaefgyaosptdlsrsggwtysbwfsbhppsuefxhftokkbadwtbrfcxjtoehgglyanlbwcsaahdcxqzaxhkwmmshphyiycpmkuyhdnekpweingrchkphtrktioedysagwzolesarniyzcrhdntkbb

A Derived Key

A derived key will similarly include the key data and chain code, but also tends to include a derivation path (map element #6) and a parent fingerprint (map element #8) as described in the CDDL for hdkeys. The following test vector demonstrates these elements as well as coininfo (map element #5) to denote the key as testnet. Note that both the coininfo and the derivation paths are defined with tags (305 and 304 respectively).

The following CBOR:

A5035821026FE2355745BB2DB3630BBC80EF5D58951C963C841F54170BA6E5C12BE7FC12A6045820CED155C72456255881793514EDC5BD9447E7F74ABB88C6D6B6480FD016EE8C8505D90131A1020106D90130A1018A182CF501F501F500F401F4081AE9181CF3

Breaks down as follows:

cbor2diag -x A5035821026FE2355745BB2DB3630BBC80EF5D58951C963C841F54170BA6E5C12BE7FC12A6045820CED155C72456255881793514EDC5BD9447E7F74ABB88C6D6B6480FD016EE8C8505D90131A1020106D90130A1018A182CF501F501F500F401F4081AE9181CF3
{
    3: h'026fe2355745bb2db3630bbc80ef5d58951c963c841f54170ba6e5c12be7fc12a6',
    4: h'ced155c72456255881793514edc5bd9447e7f74abb88c6d6b6480fd016ee8c85',
    5: 305({2: 1}),
    6: 304({1: [44, true, 1, true, 1, true, 0, false, 1, false]}),
    8: 3910671603
}

The coininfo element (#5) demonstrates use of the coininfo CDDL. Here, the network is set to testnet.

The key derivation element (#6) demonstrates use of the keypath CDDL. Here, the derivation path is set to m/44'/1'/1'/0/1.

The parent-fingerprint element (#8) is simply set to 3910671603 (or in hex: 1AE9181CF3).

The resulting crypto-hdkey after conversion to minimal Bytewords is:

ur:crypto-hdkey/onaxhdclaojlvoechgferkdpqdiabdrflawshlhdmdcemtfnlrctghchbdolvwsednvdztbgolaahdcxtottgostdkhfdahdlykkecbbweskrymwflvdylgerkloswtbrpfdbsticmwylklpahtaadehoyaoadamtaaddyoyadlecsdwykadykadykaewkadwkaycywlcscewfihbdaehn

Related Topics

A few other URs are related to key material:

  • SSKR allows for the transmission of shares that are recombined to reconstruct key material.
  • Response and Request represent a common way to ask for (and receiving) key material.

Each is covered in their own document.

Testing Key Material URs with Blockchain Commons' Reference Tools

Blockchain Commons reference tools allow for experimentation with the UR format. The following examples use our seedtool, keytool, and the bytewords CLIs, as well as the CBOR cli.

The Seed

A seed can be generated with seedtool:

$ seedtool
9c49536666b3f5cdbbe8d6da01aa6a66
$ seed=9c49536666b3f5cdbbe8d6da01aa6a66

Rather than outputting hex, seedtool can also output a UR for the crypto-seed:

$ seedtool -i hex $seed -u
ur:crypto-seed/oyadgdnsgaguiyiyqdyksnrkvstbtnadpkimiybzrycyck

bytewords can decode this output:

$ bytewords -i minimal -o hex oyadgdnsgaguiyiyqdyksnrkvstbtnadpkimiybzrycyck
a101509c49536666b3f5cdbbe8d6da01aa6a66

cbor2diag then reveals our original seed in the CBOR encoding:

$ cbor2diag -x a101509c49536666b3f5cdbbe8d6da01aa6a66
{1: h'9c49536666b3f5cdbbe8d6da01aa6a66'}

The BIP39

seedtool can also generate BIP39 words, in either mnemonic or UR format:

$ seedtool -i hex $seed -o bip39
ordinary enhance sunset sniff dismiss traffic use bracket sure ask once slot

$ seedtool -i hex $seed -o bip39 -u
ur:crypto-bip39/oyadlkisjljpieinjthsjpkkioihjtishsjtiaihiyjkkpjtjkihjyihjkjtiniyiyioieinjkjninjkjkiojyjphsiyiyiniaiakpjkihioidjphsiajeihjyiejkkpjpihiahsjkjeiejljtiaihiejkjzjljybyckylhl

Again, bytewords and cbor2diag can decode the UR:

$ bytewords -i minimal -o hex oyadlkisjljpieinjthsjpkkioihjtishsjtiaihiyjkkpjtjkihjyihjkjtiniyiyioieinjkjninjkjkiojyjphsiyiyiniaiakpjkihioidjphsiajeihjyiejkkpjpihiahsjkjeiejljtiaihiejkjzjljybyckylhl
a1018c686f7264696e61727967656e68616e63656673756e73657465736e696666676469736d69737367747261666669636375736567627261636b657464737572656361736b646f6e636564736c6f74

$ cbor2diag -x a1018c686f7264696e61727967656e68616e63656673756e73657465736e696666676469736d69737367747261666669636375736567627261636b657464737572656361736b646f6e636564736c6f74
{1:
    ["ordinary",
     "enhance",
     "sunset",
     "sniff",
     "dismiss",
     "traffic",
     "use",
     "bracket",
     "sure",
     "ask",
     "once",
     "slot"]
}

The Master Key

keytool supports key and address derivation. For example, it can produce a master xprv from a seed:

$ keytool --seed $seed master-key-base58
xprv9s21ZrQH143K3zAmshnnUZcq8YF2GPBnf5C7DhH5Y3EEBbSQCoPTsG6kFCQDKm4qSopjFQnMWhPuytDxezCYir9hdwAWGmJfSxKdaZZPHxj

keytool also can produce URs:

$ keytool --seed $seed master-key
ur:crypto-hdkey/oxadykaoykaxhdclaeswcspsndaezohttlpmfxdlqdcsaxfhuygwoteheylenbmolflninmsehmnhybdstaahdcxseoylrlbjkwmsfctzmetbyollbencftprprkswvwsrguesssnscxnbcftivsrlclbykiflbs

Again, we can decode that with bytewords and cbor2diag:

$ bytewords -i minimal -o hex oxadykaoykaxhdclaeswcspsndaezohttlpmfxdlqdcsaxfhuygwoteheylenbmolflninmsehmnhybdstaahdcxseoylrlbjkwmsfctzmetbyollbencftprprkswvwsrguesssnscxnbcftivsrlclbykiflbs
a401f502f503582100c618ac9b00fb5ad5ad432fb318033fdb4fa331328aa09282866997318e5e0bc7045820c1a1847f73ebcc1fff3811a67f3619d8b6bbc6e5c35339c49c20a019d0e8b721

$ cbor2diag -x a401f502f503582100c618ac9b00fb5ad5ad432fb318033fdb4fa331328aa09282866997318e5e0bc7045820c1a1847f73ebcc1fff3811a67f3619d8b6bbc6e5c35339c49c20a019d0e8b721
{
    1: true,
    2: true,
    3: h'00c618ac9b00fb5ad5ad432fb318033fdb4fa331328aa09282866997318e5e0bc7',
    4: h'c1a1847f73ebcc1fff3811a67f3619d8b6bbc6e5c35339c49c20a019d0e8b721'
}

A Derived Key

keytool can also create derived keys. The following example produced an xprv and a UR for the 44'/1'/1'/0/1 keypath:

$ /usr/local/bin/keytool --master-key xprv9s21ZrQH143K3zAmshnnUZcq8YF2GPBnf5C7DhH5Y3EEBbSQCoPTsG6kFCQDKm4qSopjFQnMWhPuytDxezCYir9hdwAWGmJfSxKdaZZPHxj --full-address-derivation-path m/44h/1h/1h/0/1 address-key-base58 address-key

xprvA3px5eB5pEbMi5bApo1CcoLeXHMubgFJ8hedudWE3gdMeHP6FQYXNJpPxcuznwE4PBHRcEodyp7ykLKvvpCrDK6zTLMBG899dnHTzJ3aKty

ur:crypto-hdkey/onaoykaxhdclaeknidehqdwsatwppfcfdklatdmkuyknckurlgnssrihsgdytniscntkwpcxsrmsnlaahdcxsazshllbztynlufnskreoefgdsztchihttnsahlkamlbcningefhnsjekoutyllkamoeadlecsdwykadykadykaewkadwkaocyahhfespfaycyrnnneooebkadltsn

The following shows the same for the xpub:

$ /usr/local/bin/keytool --master-key xprv9s21ZrQH143K3zAmshnnUZcq8YF2GPBnf5C7DhH5Y3EEBbSQCoPTsG6kFCQDKm4qSopjFQnMWhPuytDxezCYir9hdwAWGmJfSxKdaZZPHxj --full-address-derivation-path m/44h/1h/1h/0/1 address-pub-key-base58 address-pub-key

xpub6GpJV9hyec9evZfdvpYCywHP5KCQ18y9VvaEi1uqc2ALX5iEnwrmv78sotc3ZhwnSw1mvu437TsZ31mCwxMenzVpXsjtsB5UUaKMsYxexnG

ur:crypto-hdkey/oxaxhdclaottglktmoaoaerhonbygygejzzmhphfwnvaprjsfwfhdwsfvytpcxfxvavthkdiplaahdcxsazshllbztynlufnskreoefgdsztchihttnsahlkamlbcningefhnsjekoutyllkamoeadlecsdwykadykadykaewkadwkaocyahhfespfaycyrnnneooetldprhne

Here's the decoding of that xprv:

$ bytewords -i minimal -o hex onaoykaxhdclaeknidehqdwsatwppfcfdklatdmkuyknckurlgnssrihsgdytniscntkwpcxsrmsnlaahdcxsazshllbztynlufnskreoefgdsztchihttnsahlkamlbcningefhnsjekoutyllkamoeadlecsdwykadykadykaewkadwkaocyahhfespfaycyrnnneooebkadltsn
a502f5035821007a6231b3ef07ecb0192480d298db7a1edf8d9cc365ca30da6823cfec20c39799045820c2fa5d7ffcf68b3cc5b5a24626fc1765d19c058c067f23694a3f9c6b76ddf78c06a2018a182cf501f501f500f401f4021a055639b0081abe9e33a2

$ cbor2diag -x a502f5035821007a6231b3ef07ecb0192480d298db7a1edf8d9cc365ca30da6823cfec20c39799045820c2fa5d7ffcf68b3cc5b5a24626fc1765d19c058c067f23694a3f9c6b76ddf78c06a2018a182cf501f501f500f401f4021a055639b0081abe9e33a2
{
    2: true,
    3: h'007a6231b3ef07ecb0192480d298db7a1edf8d9cc365ca30da6823cfec20c39799',
    4: h'c2fa5d7ffcf68b3cc5b5a24626fc1765d19c058c067f23694a3f9c6b76ddf78c',
    6: {1: [44, true, 1, true, 1, true, 0, false, 1, false], 2: 89536944},
    8: 3198038946
}

Similarly, here's the decoded xpub:

{
    3: h'02d14e77920200b9a511514a6cff5b56f1e6b271423f2ccce1d82043e6e05927ae',
    4: h'c2fa5d7ffcf68b3cc5b5a24626fc1765d19c058c067f23694a3f9c6b76ddf78c',
    6: {1: [44, true, 1, true, 1, true, 0, false, 1, false], 2: 89536944},
    8: 3198038946
}

Integrating Key Material URs Into Your Code

You can incorporate URs into your own code using bc-ur for C++ or through conversions of that library to other languages such as Java and Swift.

bc-ur provides access to objects such as UREncoder, URDecoder, and Bytewords, which support many of the same functions as described here for the command line. They can also be used with other Blockchain Commons Crypto Commons Reference Libraries, which support a variety of cryptography functions.

Conclusion

Key material can be transferred using ur:crypto-seed, ur:crypto-bip39, and ur:crypto-hdkey. Doing so allows you to use airgaps, which increase the safety of these vulnerable operations; and also increases your interoperability, so that other software can work with you, and so that your key material remains usable far into the future.