Repository navigation
WIP: Private key management chapter #48
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
c1f950b
ef0051a
8cf2e6e
127ad29
a5cc631
bbd3d53
29b1fe0
a8650ff
8dd7d50
54267fb
0c4d645
a6c30ba
c386da6
e1cdd9f
742580d
832d52e
5ed3312
a2118f1
8eaee2d
490d5e3
755cda4
3e52728
28c2da1
375c88a
7974c45
ae74176
c488255
ca378f5
99d61b0
40753d7
47e7f35
c9f3ab0
851a764
a693465
3319461
32d04f8
51752ad
2316074
861b6cb
7c4598d
2806d1e
fd19bc8
040d0a5
0a8d82b
0e4fba0
ceeda39
968c56f
b1b2a76
cf75262
5647869
7a1b263
d417027
a7d8721
f07aedc
568f567
3609554
7a1f2cd
8e69d49
93f74f6
e9ab130
c3f720c
f636f33
9362409
8007be6
f9d7776
4024fba
5bc9469
567efda
502e47b
6278256
65de34d
328514f
7c256f6
487c014
3d3f76d
6fc2fe8
944d2ce
d5bb0f7
dd9fed4
df3c0d6
b411fa4
f03fb35
768862f
4e7c607
220d21d
89fbe85
ccf23e2
f2869d1
0d4dc5c
0be73df
560e1e4
fd26284
5f2822a
8b5bf6a
24384e1
7a113d4
5f3f2f2
53575df
763da52
f14c7eb
163a3c2
24618f5
3993bd2
377542b
948cb86
268e8fd
066c765
24cda11
a6c018e
57ce77c
48aaee0
7e74781
4a9cc71
521c320
b90200b
b9e5223
4870d1c
4acffd5
14a3c39
1d8803e
9e6f223
5a0506f
a4a4481
16cd223
fee43c1
47f22da
7f1cb81
c2014fa
41c6caf
1d675a7
80ffe19
64476a4
c6b5a3f
7e2d609
d13fa58
216b8bc
ba7d882
e5e1e30
2d2d525
7c91343
7d87961
d3880f0
a14129b
c4f654a
f2ced09
b8c283c
48ece3b
71ff4ad
6373685
605394a
c3af454
8e0a559
dccc305
9326f46
8597bba
00394d2
8bc2859
902f1eb
759ca19
20bd7d9
17c4c3a
7239244
545afae
d148a87
2bf7018
d602fc7
1db214f
c65fc6f
0a622a8
e2e56cc
15a5d2a
42977e2
51eeb6e
a680814
10bab6d
1663bdc
e11f72b
34907aa
3ee3857
b9ad8e6
12bd761
dfc071a
ab12b26
87359ad
ab07cd9
ed1f3e9
bb27468
82b39a8
b88ee74
63b0144
9369e8e
94ee31b
4d384e2
dc1c8cc
473fe83
41ad5d4
5d22793
4973f04
b5b3f3b
d3b8ba1
008e959
bbc3a05
af81e90
da8b677
1127aae
85f7659
9602469
1c2322d
00f8032
ef7a89e
69cae90
1dfa55e
ef42453
9f9abf8
4c41fef
f003877
d952e8b
94a2664
0872094
e55bddb
eda83c4
362ea5e
3a9aa62
8c950ed
0610cff
88dbcf3
ff62b93
82b7c11
a759a86
f5b7089
182fda9
588d44a
ada291c
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,12 @@ | ||
| <figure{% if include.layout %} class="-{{ include.layout }}"{% endif %}> | ||
| <a href="{{ include.link-url }}"> | ||
| <img | ||
| src="{{ include.image | relative_url }}" | ||
| {% if include.retina %} srcset="{{ include.image | relative_url }} 1x, {{ include.retina | relative_url }} 2x"{% endif %} | ||
| alt="{{ include.alt-text }}" | ||
| width="{{ include.width }}" | ||
| height="{{ include.height }}" | ||
| > | ||
| > | ||
| </a> | ||
| {% if include.caption %}<figcaption markdown="1">{{ include.caption | markdownify }}</figcaption>{% endif %} | ||
| </figure> |
Large diffs are not rendered by default.
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,147 @@ | ||
| --- | ||
| layout: guide | ||
| title: Case studies | ||
| description: A range of case study designs for bitcoin applications. | ||
| nav_order: 5 | ||
| parent: Private key management | ||
| permalink: /guide/private-key-management/case-studies/ | ||
| main_classes: -no-top-padding | ||
| image: /assets/images/guide/private-key-management/case-studies/page-case-studies.jpg | ||
| --- | ||
|
|
||
| <!-- | ||
|
|
||
| Editor's notes | ||
|
|
||
| A range of case study designs for bitcoin applications. | ||
|
|
||
| --> | ||
|
|
||
| {% include picture.html | ||
| image = "/assets/images/guide/private-key-management/case-studies.jpg" | ||
| retina = "/assets/images/guide/private-key-management/case-studies@2x.jpg" | ||
| mobile = "/assets/images/guide/private-key-management/case-studies-mobile.jpg" | ||
| mobileRetina = "/assets/images/guide/private-key-management/case-studies-mobile@2x.jpg" | ||
| alt-text = "Case studies header illustration" | ||
| width = 1600 | ||
| height = 600 | ||
| layout = "full-width" | ||
| %} | ||
|
|
||
| # Case studies | ||
|
|
||
| Before deciding on a private key management scheme it’s essential to have a good idea of what use case and target audience your product has. Let’s look at some hypothetical use case categories and what might be suitable approaches. | ||
|
|
||
| - [Cash / Daily spending]({{ '/guide/private-key-management/case-studies/#cash--daily-spending' | relative_url }}) | ||
| - [Current / Checking account]({{ '/guide/private-key-management/case-studies/#current--checking-account' | relative_url }}) | ||
| - [General upgradeable wallet]({{ '/guide/private-key-management/case-studies/#general-upgradeable-wallet' | relative_url }}) | ||
| - [Shared account]({{ '/guide/private-key-management/case-studies/#shared-account' | relative_url }}) | ||
|
|
||
| *** | ||
|
|
||
| ## Cash / Daily spending | ||
|
|
||
| Imagine a product which tries to solve the problem of quickly and easily sending smaller amounts of money to friends and family, or for small purchases. Ease and speed of use will be important as usage is likely to be on mobile devices and on the go. Users are not expected to be well versed in bitcoin technology or advanced private key management, which makes it reasonable to worry more about self-inflicted loss than from theft. | ||
|
|
||
| A single-key scheme with [automatic cloud backup]({{ '/guide/private-key-management/single-user-schemes/#automatic-cloud-backup' | relative_url }}) might be the best choice for the majority of users in this case. For more advanced users you could offer the option to opt-out of automatic cloud backup and instead use a recovery phrase. | ||
|
|
||
| <iframe style="border: 0px solid rgba(0, 0, 0, 0.1);" width="450" height="1000" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Fproto%2FSRWlaxbDulsacpPQn2TTri%2FCase-study-prototypes%3Fnode-id%3D1%253A3%26viewport%3D1204%252C392%252C0.5%26scaling%3Dmin-zoom" allowfullscreen></iframe> | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Locally (and I have power-machine and connection) these embeds take quite a while to load (~5 sec), is there something we can do to improve the performance?
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Good point.
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. As far as an image goes, how about we include all screens in the prototype laid out next to each other with arrows indicating the sequence? That allows readers to easily understand the full user flow, and we can still offer a "View prototype" option to feel out the interaction.
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Also think the prototype needs some explanation. "The following prototype shows how convenient a cloud backup user flow can be. Start by tapping 'Create wallet'." Prototypes are great to make designs feel more real, but they don't explain themselves at all.
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "Recieve" should be "Receive" in the prototype. |
||
|
|
||
| #### Design considerations | ||
| - Most users will be bitcoin beginners | ||
| - Quick and easy send/receive | ||
| - Onboarding with as little friction as possible | ||
|
|
||
| #### Technical considerations | ||
| - Back up encrypted recovery phrase automatically to retain export option in the future | ||
| - Use a platform-appropriate storage location (keychain with iCloud, Google Drive) | ||
| - Additional user authentication to consider: biometrics, pin | ||
| - Upgrade-path to other schemes if funds stored increase | ||
|
|
||
| You can find a prototype for this case study embedded above, and a Figma file with [outline designs here](https://www.figma.com/file/SRWlaxbDulsacpPQn2TTri/Case-study-prototypes?node-id=0%3A1){:target="_blank"}. | ||
|
|
||
| *** | ||
|
|
||
| ## Current / Checking account | ||
|
|
||
| In this section, we are looking at a product that is meant to be a replacement for what a bank would call a current/checking account where the user might receive their salary and pay their bills from. | ||
| Safeguards against loss will be a higher priority than with a cash product, and we might therefore accept more friction both when setting up the wallet and when transacting. | ||
| If users have no prior bitcoin knowledge we should expect to spend a significant effort educating them to put them in a position to safely operate the wallet product. | ||
|
|
||
| A 2-of-3 [multi-key setup]({{ '/guide/private-key-management/single-user-schemes/#multi-key' | relative_url }}) would seem the most appropriate here, although it will be a significant hurdle in onboarding. Other schemes could be considered but come with distinct downsides for amounts of value we can expect users to store in this use case. A single-key scheme with an automatic cloud backup, recovery phrase or single signing device could work at the lower end of the value scale, but start to look like less responsible recommendations with higher values due to their single points of failure. | ||
|
|
||
| An important question is the combination of key-storage devices and their distribution. We have many options here, and it might come down to the experience of the target audience and their expected access to the necessary hardware; | ||
|
|
||
| - As low friction as possible (co-managed, no purpose-built signing device) | ||
| - Middle ground (co-managed, one purpose-built signing device) | ||
| - Full sovereignty (one or more purpose-built signing devices) | ||
| - All keys off-line (two or more purpose-built signing devices) | ||
|
|
||
| For this case study we will go with the middle ground option which will require one purpose-built signing device such as a hardware wallet. The other two keys will be one created on the user’s main mobile device and automatically backed up to their cloud provider, and another key held by the wallet application provider on a server for recovery. Neither of the two keys in the user’s control (mobile and signing device) will require recovery phrase backups, although this could be offered as an option. | ||
|
|
||
| The idea here is that the user will control the wallet through an app on their main mobile device, but when they are sending funds (paying bills etc) they will need to confirm the transaction on the purpose-built signing device. | ||
|
|
||
| Should they lose either their main mobile device, or the purpose-built signing device they can replace the lost key (rotate in a new key) with the help of the recovery key. However, if they lose both the mobile and signing device they will not be able to recover their funds, unless they had also backed up either of the respective recovery phrases. | ||
|
|
||
| <iframe style="border: 0px solid rgba(0, 0, 0, 0.1);" width="450" height="1000" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Fproto%2FSRWlaxbDulsacpPQn2TTri%2FCase-study-prototypes%3Fnode-id%3D6%253A11%26viewport%3D479%252C82%252C0.5%26scaling%3Dscale-down" allowfullscreen></iframe> | ||
|
|
||
| #### Design considerations | ||
| - Suitable for monthly transactions | ||
| - Lots of edge cases and infrequent but important situations | ||
| - Key setup, rotation, recovery and signing flows | ||
|
|
||
| #### Technical considerations | ||
| - Complexities of multi-key setups | ||
| - Implement thorough backup code and instructions for users | ||
| - Usage could be simplified by having hardware device designed/customized by the software maker (compare banks and their digital token signers common in Europe) | ||
|
|
||
| You can find a prototype for this case study embedded above, and a Figma file with [outline designs here](https://www.figma.com/file/SRWlaxbDulsacpPQn2TTri/Case-study-prototypes?node-id=6%3A9){:target="_blank"}. | ||
|
|
||
| *** | ||
|
|
||
| ## Upgradeable wallet | ||
|
|
||
| Although it is generally easier to build a great experience with a specific use case in mind, let's look at a case where we would like to make a wallet that is made for a broad range of uses and audiences. It needs to be suitable both for beginners and expanding users, and for holding anything between small and significant amounts. How do we choose a single private key management scheme for this situation? | ||
|
|
||
| The solution in this case could be a wallet that enables the user to upgrade the scheme as their experience and funds grow. The idea is to provide progressive security that doesn't introduce unnecessary friction until it is required. Our wallet will be able to switch from; | ||
|
|
||
| - Automatic cloud backup - as default for new users, who often start out with small amounts | ||
| - External signing device - for more experienced users, and when funds have grown | ||
| - 2-of-3 multi-key - for seasoned users, and critical amounts | ||
| - 3-of-5 multi-key - for really serious situations and/or very high amounts | ||
|
|
||
| <iframe style="border: 0px solid rgba(0, 0, 0, 0.1);" width="450" height="1000" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Fproto%2FSRWlaxbDulsacpPQn2TTri%2FCase-study-prototypes%3Fnode-id%3D15%253A270%26viewport%3D1057%252C573%252C0.23897239565849304%26scaling%3Dscale-down" allowfullscreen></iframe> | ||
|
|
||
| #### Design considerations | ||
| - Low friction onboarding | ||
| - Guide the user through scheme upgrades as funds grow | ||
|
|
||
| #### Technical considerations | ||
| - Need to handle many schemes; automatic cloud backups, recovery phrases, external signing devices, multi-key | ||
|
|
||
| You can find a prototype for this case study embedded above, and a Figma file with [outline designs here](https://www.figma.com/file/SRWlaxbDulsacpPQn2TTri/Case-study-prototypes?node-id=15%3A269){:target="_blank"}. | ||
|
|
||
| *** | ||
|
|
||
| ## Shared account | ||
|
|
||
| A common real-world use case for shared accounts are couples managing their monthly spending, with both parties being able to spend from the account. For this situation we could consider the following private key management schemes: | ||
|
|
||
| - 1-of-2 multi-key - either party can spend without the other's approval | ||
| - 2-of-3 multi-key - either party can spend with approval from one additional key | ||
|
|
||
| The other person does not need to co-sign every transaction, but we might want a *spending limit*, above which both parties need to approve the transaction. All multi-key setups are represented by bitcoin scripts on the blockchain, and the spending limit can be introduced as a conditional for both the 1-of-2 or 2-of-3 scheme. | ||
|
|
||
| Although the 1-of-2 scheme could work here, it offers lower protection against both theft and self-inflicted loss, unless rigorous manual backups are implemented. For this example we will choose the 2-of-3 scheme, but still have to decide on who will hold the third key, and the location of the other two. | ||
|
|
||
| Depending on how tailor-made or interoperable we want this setup could be we have many options for the location of the three keys, including: | ||
|
|
||
| - Individual mobile keys for the two users, plus one held by the co-manager (the product maker) for recovery and co-signing | ||
| - Individual mobile keys for the two users, plus a shared external signing device | ||
| - Each user can choose their own key location (mobile, external device, etc.), plus a shared external signing device | ||
|
|
||
| We are looking for a low friction, easy-to-manage solution that could work for beginners so in this case we'll go with the two mobile keys and the third key held by the co-manager. | ||
|
|
||
| <iframe style="border: 0px solid rgba(0, 0, 0, 0.1);" width="450" height="1000" src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Fproto%2FSRWlaxbDulsacpPQn2TTri%2FCase-study-prototypes%3Fnode-id%3D15%253A824%26viewport%3D739%252C217%252C0.5%26scaling%3Dscale-down" allowfullscreen></iframe> | ||
|
|
||
| You can find a prototype for this case study embedded above, and a Figma file with [outline designs here](https://www.figma.com/file/SRWlaxbDulsacpPQn2TTri/Case-study-prototypes?node-id=15%3A822){:target="_blank"}. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,56 @@ | ||
| --- | ||
| layout: guide | ||
| title: Private key management | ||
| description: An overview of private key management schemes, including descriptions of available approaches, some advice and best practices. | ||
| nav_order: 2 | ||
| permalink: /private-key-management/introduction/ | ||
| has_children: true | ||
| permalink: /guide/private-key-management/introduction/ | ||
| main_classes: -no-top-padding | ||
| image: /assets/images/guide/private-key-management/page-private-key-management.jpg | ||
| --- | ||
|
|
||
| <!-- | ||
|
|
||
| Editor's notes | ||
|
|
||
| A brief introduction and summary of all pages in this section. The idea is that readers | ||
| scan this page to get an overview of the section and then decide which topics to dive into. | ||
|
|
||
| --> | ||
|
|
||
| {% include picture.html | ||
| image = "/assets/images/guide/private-key-management/private-key-management.jpg" | ||
| retina = "/assets/images/guide/private-key-management/private-key-management@2x.jpg" | ||
| mobile = "/assets/images/guide/private-key-management/private-key-management-mobile.jpg" | ||
| mobileRetina = "/assets/images/guide/private-key-management/private-key-management-mobile@2x.jpg" | ||
| alt-text = "Private key management chapter illustration" | ||
| width = 1600 | ||
| height = 600 | ||
| layout = "full-width" | ||
| %} | ||
|
|
||
| # Private key management | ||
|
|
||
| This chapter is in development at [PR #48](https://github.com/BitcoinDesign/Guide/pull/48){:target="_blank"}. Check the [preview](https://deploy-preview-48--sad-borg-390916.netlify.app/guide/private-key-management/introduction/){:target="_blank"}. | ||
| When designing a bitcoin-application, the way you choose to manage the [private key]({{ '/guide/glossary/#private-key' | relative_url }}){:target="_blank"} often dictates the fundamental user experience for your users. Being in control of a private key means you have access to the funds it holds. Keeping that key safe is like being in charge of the security of your own bank. It comes with a lot of freedom, but also a big responsibility that many users are not used to. | ||
|
danielnordh marked this conversation as resolved.
Resolved
|
||
|
|
||
| If it’s not secure enough, you risk loss of user's funds. But if it’s not convenient enough, you risk not getting or retaining many users in the first place. | ||
|
|
||
| This chapter is meant to give an overview of private key management schemes, including descriptions of available approaches, some advice and best practices. After this chapter, you should be able to choose a solution that is well suited to your product’s use case, and understand best-practices for the implementation of it. | ||
|
|
||
| --- | ||
|
|
||
| **[Private key schemes]({{ '/guide/private-key-management/schemes/' | relative_url }})** | ||
|
|
||
| An overview of the most common private key management schemes for bitcoin products, and thoughts on picking a suitable scheme for your target audience and their use case. | ||
|
|
||
| **[Principles]({{ '/guide/private-key-management/principles/' | relative_url }})** | ||
|
|
||
| Every use case and product is different but there are things that all wallet applications should strive for, and only diverge from with very good reasons. | ||
|
|
||
| **[Case studies]({{ '/guide/private-key-management/case-studies/' | relative_url }})** | ||
|
|
||
| A look at some hypothetical use case categories and what might be suitable approaches for private key management schemes for each of them. | ||
|
|
||
| --- | ||
|
|
||
| Let's get started with an overview of [private key schemes]({{ '/guide/private-key-management/schemes/' | relative_url }}). | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great section, sums up everything we talked about with examples. I love it.