diff --git a/.gitignore b/.gitignore index c36065aa..537f522c 100644 --- a/.gitignore +++ b/.gitignore @@ -32,3 +32,6 @@ fastlane/report.xml build-ios/ build-mac/ + +## Mac specific (added by HvC) +.DS_Store \ No newline at end of file diff --git a/CLA-signed/CLA.henkvancann.BB59C0E48A9D75BDA4DC9CD2428218FF30BC7338.asc b/CLA-signed/CLA.henkvancann.BB59C0E48A9D75BDA4DC9CD2428218FF30BC7338.asc new file mode 100644 index 00000000..c8b3a286 --- /dev/null +++ b/CLA-signed/CLA.henkvancann.BB59C0E48A9D75BDA4DC9CD2428218FF30BC7338.asc @@ -0,0 +1,74 @@ +-----BEGIN PGP SIGNED MESSAGE----- +Hash: SHA256 + +# Contributor License Agreement + +Version 1.0 + +Name: Henk van Cann + +E-Mail: hvancann@bcws.io + +Legal Jurisdiction: Wyoming, United States of America + +Project: https://github.com/BlockchainCommons/GordianGuardian-iOS + +Date: Feb 24 2021 + +## Purpose + +This agreement gives Blockchain Commons, LLC the permission it needs in order to accept my contributions into its open software project and to manage the intellectual property in that project over time. + +## License + +I hereby license Blockchain Commons, LLC to: + +1. do anything with my contributions that would otherwise infringe my copyright in them + +2. do anything with my contributions that would otherwise infringe patents that I can or become able to license + +3. sublicense these rights to others on any terms they like + +## Reliability + +I understand that Blockchain Commons will rely on this license. I may not revoke this license. + +## Awareness + +I promise that I am familiar with legal rules, like ["work made for hire" rules](http://worksmadeforhire.com), that can give employers and clients ownership of intellectual property in work that I do. I am also aware that legal agreements I might sign, like confidential information and invention assignment agreements, will usually give ownership of intellectual property in my work to employers, clients, and companies that I found. If someone else owns intellectual property in my work, I need their permission to license it. + +## Copyright Guarantee + +I promise not to offer contributions to the project that contain copyrighted work that I do not have legally binding permission to contribute under these terms. When I offer a contribution with permission, I promise to document in the contribution who owns copyright in what work, and how they gave permission to contribute it. If I later become aware that one of my contributions may have copyrighted work of others that I did not have permission to contribute, I will notify Blockchain Commons, in confidence, immediately. + +## Patent Guarantee + +I promise not to offer contributions to the project that I know infringe patents of others that I do not have permission to contribute under these terms. + +## Open Source Guarantee + +I promise not to offer contributions that contain or depend on the work of others, unless that work is available under a license that [Blue Oak Council rates bronze or better](https://blueoakconcil.org/list), such as the MIT License, two- or three-clause BSD License, the Apache License Version 2.0, or the Blue Oak Model License 1.0.0. When I offer a contribution containing or depending on others' work, I promise to document in the contribution who licenses that work, along with copies of their license terms. + +## Disclaimers + +***As far as the law allows, my contributions come as is, without any warranty or condition. Other than under [Copyright Guarantee](#copyright-guarantee), [Patent Guarantee](#patent-guarantee), or [Open Source Guarantee](#open-source-guarantee), I will not be liable to anyone for any damages related to my contributions or this contributor license agreement, under any kind of legal claim.*** + +- --- + +To sign this Contributor License Agreement, fill in `$name`, `$email`, and `$date` above. Then sign using GPG using the following command `gpg --armor --clearsign --output ./CLA-signed/CLA.YOURGITHUBNAME.YOURGPGFINGERPRINT.asc CLA.md`, then either submit your signed Contributor License Agreement to this repo as a GPG signed Pull Request or email it to [ChristopherA@BlockchainCommons.com](mailto:ChristopherA@BlockchainCommons.com). +-----BEGIN PGP SIGNATURE----- + +iQIzBAEBCAAdFiEEXeu9vqPm1xjqG5CZAYzS2yZOUEIFAmA2P30ACgkQAYzS2yZO +UELCsA//YbZ+NZ4H0lWbM4I9sg/CFLowVAoSaKIn0sebYKHyNrqB/a+NxsL9mDWA +KwT1hCSc0x3idCg3LdF6oXNv2kVa2q3TSoVP84FTvr7RiAXSfZAZ5pDUaTHkTAeV +tqGeNAQK649ONELgj5CA0Qg9P6zfCIqiHwsZZJgTvgvsqixuixHEAVrHbPCc4VUP +CEE4C9HRCRGKBQzb0dTGMvypFO7TIUTjAW609T/7vHfRVn71s/dwlNri/BRnV/Wr +Y8rXakc0vXqQAndJNejEhyqjKs1xwZYSO5z1aOinaHkyKEEPg1uIszN6XWEb7Gbc ++4LX+Cqj1AABC+ujD9FLP81r7ogz1Wg7Jm8Nb4ilTgLDd2y4BqdJN0qLgDjl79MV +cQhW7YJ9PqlNafNFcRJMskzlfRsKclit1ULyCfzAFU2lWfUkw9elBiYwN846UXM0 +E4LqMULka2mih0M7sbAQ5nKR8JrIB4ddPCvV79+jhhyw9trfOzFvyb7aGnLlvu4E +axNHAWRwVFKEzrwzuvy4POWMWPXRC6PCxaIrZtjqD72gWx+OYZSTArVs3WzlAohG +szjjqvFB3R3vKX5nSZxkDfsgkKY8ucyqLiyBq5kK0KypfqOOzhzphAmx3JbhfQXO +MQYITJMj/WojlTWftBZsBvXD1hTQkfHD8CAdDImMFgZkKsF0o8Q= +=TJwV +-----END PGP SIGNATURE----- diff --git a/Docs/Definitions.md b/Docs/Definitions.md new file mode 100644 index 00000000..e8734fb4 --- /dev/null +++ b/Docs/Definitions.md @@ -0,0 +1,182 @@ +# Definitions + +_The following defintiopns are only applicable in the context of Gordian Seed Tool. We acknowledge that there's controversy in the space about which term means what means what to whom. However, for the novice learner it's indespensible to have some sort of hand rail to hold on to while climbing the steps of the steep learning curve that proper key management involves._ + +Words in `this format`, such as `BIP39 `, will not be defined further, but definitions and descriptions are available on the internet. + +## Table of Contents + +- Definitions: + - [Account Map](#account-map) + - [Airgap](#airgap) + - [Biometric authentication](#biometric-authentication) + - [Bytewords](#bytewords) + - [Clipboard](#clipboard) + - [Concise Binary Object Representation](#concise-binary-object-representation) + - [Content-addressable hash](#content-addressable-hash) + - [Controller](#controller) + - [Cryptocurrency](#cryptocurrency) + - [Descriptor wallet](#descriptor-wallet) + - [Entropy](#entropy) + - [Gordian](#gordian) + - [Key](#key) + - [Multi-signature signing](#multi-signature-signing) + - [Normative](#normative) + - [Non-normative](#non-normative) + - [Object Identity Block](#object-identity-block) + - [Output descriptor](#output-descriptor) + - [Payload](#payload) + - [Public Key Infrastructure](#public-key-infrastructure) + - [QR code](#qr-code) + - [Seed (key)](#seed--key-) + - [Sharded Secret Key Reconstruction](#sharded-secret-key-reconstruction) + - [Torgap](#torgap) + - [Transfer](#transfer) + - [Verification keys](#verification-keys) + - [Wallet](#wallet) + - [Wallet descriptor](#wallet-descriptor) + - [xpub](#xpub) + +## Abbreviations + +`2FA` = Two factor authentication\ +CBOR = [Concise Binary Object Representation](#concise-binary-object-representation)\ +`DKMI` = Decentralized Key Mangement Infrastructure\ +`HSM` = Hardware Security Module\ +OIB = [Object Identity Block](#object-identity-block)\ +PKI = [Public Key Infrastructure](#public-key-infrastructure)\ +`PR` = Pull Request; github terminology\ +PSBT = [Partially Signed Bitcoin Transaction](#crypto-pbst)\ +QR = [Quick Response (code)](#qr-code)\ +`RAM` = Random Access Memory\ +SSKR = [Sharded Secret Key Reconstruction](#sharded-secret-key-reconstruction)\ +`SSSS` = Shamir Secret Sharing Scheme\ +`URs` = Uniform Resources\ +`UUID` = Universally unique identifier\ + +## Definitions + +### Account Map +A dataset with xpubs, wallet descriptors, and other metadata for fully restoring a multisig account. + +### Airgap +A _network security measure_ employed on one or more computers to ensure that a secure computer network is _physically isolated_ from unsecured networks.\ +[More on Wikipedia](https://en.wikipedia.org/wiki/Air_gap_(networking)). + +#### Biometric authentication +Body measurements and calculations related to human characteristics. Biometric authentication (or realistic authentication) is used in computer science as a form of identification and access control.\ +[More on Wikipedia](https://en.wikipedia.org/wiki/Biometrics). + +#### Bytewords +A format to encode binary data as English words. This Blockchain Commons specification has similar goals as `BIP39` and `SLIP39`, with a few unique characteristics.\ +[More in specification](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-012-bytewords.md). + +#### Clipboard +A buffer that some operating systems provide for short-term storage and transfer within and between application programs. The clipboard is usually temporary and unnamed, and its contents reside in the computer's [RAM](#Abbreviations).\ +[More on Wikipedia](https://en.wikipedia.org/wiki/Clipboard_(computing)). + +#### Concise Binary Object Representation +Also CBOR, a binary data serialization format loosely based on `JSON`. Like JSON it allows the transmission of data objects that contain name–value pairs, but in a more concise manner. This increases processing and transfer speeds at the cost of human readability. \ +[More on Wikipedia](https://en.wikipedia.org/wiki/CBOR). + +#### Content-addressable hash +A way to find data in a network using its content rather than its location. This is done by taking the content of the content and hashing it. For example, you might upload an image to IPFS and retrieve the hash. In the IPFS ecosystem, this hash is called Content Identifier, or CID. + +#### Controller +The entity that has the ability to make changes to an _identity_, _cryptocurrency_ or _verifiable credential_. + +The controller of an `autonomous identifier` is the entity (person, organization, or autonomous software) that has the capability, as defined by derivation, to make changes to an `Event Log`. This capability is typically asserted by the control of a single inception key. In DIDs, this is typically asserted by the control of set of cryptographic keys used by software acting on behalf of the controller, though it may also be asserted via other mechanisms. In KERI ,an AID has one single controller. Note that a DID may have more than one controller, and the DID `subject` can be the DID controller, or one of them. + +#### Cryptocurrency +A digital asset designed to work as a medium of exchange. In the most common deployments, individual coin ownership records are stored in a digital ledger or computerized database using strong cryptography to secure transaction record entries, to control the creation of additional digital coin records. [More on Wikipedia](https://en.wikipedia.org/wiki/Cryptocurrency).\ +Note: Gordian **Seed Tool is not a cryptocurrency wallet**. It neither stores nor transmits value in any cryptocurrency. + +#### Crypto-request +A UR with a UUID that requests specific information from the recipient. [More in specification](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2021-001-request.md), [More in documentation](https://github.com/BlockchainCommons/crypto-commons/blob/master/Docs/ur-99-request-response.md). + +#### Crypto-response +A UR that responds to a `crypto-request` with the specified information and the same UUID. [More in specification](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2021-001-request.md), [More in documentation](https://github.com/BlockchainCommons/crypto-commons/blob/master/Docs/ur-99-request-response.md). + +#### Crypto-pbst +A UR that embeds a PSBT. + +#### Descriptor wallet +A wallet that stores output descriptors and uses them to create addresses and sign transactions. By abstracting address creation and transaction signing to a largely standalone module, such wallets can upgrade to using new address types much more easily.\ +For most users, the only visible effects will be in wallet import/export. Descriptors will only be shown during exporting, and descriptors should only be handled by the user when they want to import their wallet. Wallets that use descriptors internally shouldn't have any noticeable effect to the user.\ +[More on Stackexchange](https://bitcoin.stackexchange.com/questions/99540/what-are-output-descriptors). + +#### Entropy +Unpredictable information. Often used as a _secret_ or as input to a _key_ generation algorithm. The term entropy is also used to describe the degree of unpredictability of a message. + +Entropy is measured in bits. The degree or strength of randomness determines how difficult it would be for someone else to reproduce the same large random number. [More in source](https://en.wikipedia.org/wiki/Entropy_(information_theory)). + +#### Gordian +Gordian is the umbrella name for open source products, services and technologies from Blockchain Commons that abide by the [Gordian Principles](https://www.blockchaincommons.com/vision.html#principle).\ +![](https://github.com/BlockchainCommons/Gordian/blob/master/Images/logos/gordian-overview-screen.png?raw=true) +[More in Gordian repo](https://github.com/BlockchainCommons/Gordian). + +#### Key +A mechanism for granting or restricing access to something. MAY be used to issue and prove, MAY be used to control of transfer _identity_ or _cryptocurrency_. \ +[More on Wikipedia](https://en.wikipedia.org/wiki/Key_(cryptography)). + +#### Multi-signature signing +Also multi-signature or multisig. A digital signature scheme which allows a group of users to jointly sign a transaction or message, each using their own key.\ +[More in Wikipedia](https://en.wikipedia.org/wiki/Multisignature). + +#### Normative +In general, a theory is “normative” if it, in some sense, tells you what you should do: what action you should take. If it includes a usable procedure for determining the optimal action in a given scenario. [More on Quora](https://www.quora.com/What-is-the-difference-between-normative-and-non-normative?share=1). + +#### Non-normative +A theory is non-normative if it does not do that. In general, the purpose of non-normative theories is not to give answers, but rather to describe possibilities or predict what might happen as a result of certain actions. +[More on Quora](https://www.quora.com/What-is-the-difference-between-normative-and-non-normative?share=1). + +#### Object Identity Block +Also OIB. A UI technique for making any digital object immediately recognizable to users. Example:\ +![](https://github.com/BlockchainCommons/Research/raw/master/papers/bcr-2021-002/oib-1.png) + +[More in specification](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2021-002-digest.md#object-identity-block). + +#### Output Descriptor +See [Wallet Descriptor](#wallet-descriptor). + +#### Payload +The 'interesting' information in a chunk of data, as opposed to the overhead needed to support it. It is borrowed from transportation, where it refers to the part of the load that 'pays'. For example, a tanker truck may carry 20 tons of oil, but the fully loaded vehicle weighs much more than that: there's the vehicle itself, the driver, fuel, the tank, etc. It costs money to move all these, but the customer only cares about (and pays for) the oil, hence, 'pay-load'. [More on Stackexchange](https://softwareengineering.stackexchange.com/questions/158603/what-does-the-term-payload-mean-in-programming). + +#### Public Key Infrastructure +A public key infrastructure (PKI) is a set of roles, policies, hardware, software, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates and manage public-key encryption. [More on Wikipedia].(https://en.wikipedia.org/wiki/Public_key_infrastructure). + +#### QR Code +A quick response code: a type of matrix barcode (or two-dimensional barcode) invented in 1994 by a Japanese automotive company. A barcode is a machine-readable `optical label` or identifier that can contain information about the item to which it is attached.\ + +[More on Wikipedia](https://en.wikipedia.org/wiki/QR_code). + +#### Seed +A large random number that provides entropy and is the starting point for other things, such as keys and cryptocurrency addresses. +Gordian Seed Tool supports seeds in a variety of formats, including **mnemonic** seeds, which use the `BIP39` standard word list or Bytewords. `BIP32` master keys are generated from a seed. + +#### Sharded Secret Key Reconstruction +Also SSKR. Allows you to split your seed into pieces and send them to trusted parties, who can send them back to you in an emergency for seed recovery. You can even use an entirely offline device (no internet access) to store your seeds and use [QR codes](#qr-codes) to exchange necessary information with online devices running compatible wallet or signing software.\ +[More on github](https://github.com/BlockchainCommons/crypto-commons/blob/master/Docs/README.md#sharded-secret-key-reconstruction-sskr), [More in Documentation](https://github.com/BlockchainCommons/crypto-commons/blob/master/Docs/sskr-overview.md). + +#### Torgap +A Blockchain Commons security and privacy architecture model for creating gaps between connected apps and microservices. See also [Airgap](#airgap).\ +[More in repo](https://github.com/BlockchainCommons/torgap). + +#### Transfer +The process of changing the _controller_ of _cryptocurrency_, _identity_ or _verifiable credential_. MAY require the use of a _key_. + +#### Verification keys +{TBW} + +#### Wallet +Software and sometimes hardware that serves as a key store and provide functionality for those keys. Keys can be private keys or public keys, hashes, or pointers. Functionality can include signatures, invoices (receive), sending, virtual credentials, delegation, etc. \ +[More about cryto Wallets](https://cryptocurrencyfacts.com/what-is-a-cryptocurrency-wallet/). + +#### Wallet descriptor +An **output descriptor** (note that output descriptor and wallet descriptor refer to the same thing) is a human readable string that represents an output script (a scriptPubKey) and everything needed in order to _solve_ for that script. Descriptors also have a bech32-like checksum which allows for the descriptor to be given to others with less risk of accidentally mistyping or losing some characters in the descriptor string.\ +_Solving_ a script means that one would be able to create a final scriptSig/witness with valid signatures if they had a private key. This means that all public keys and other scripts are available.\ +Descriptors are unambiguous as to the public keys to use (derivation paths for extended keys are explicit) and the scripts to use. This makes them suitable for importing to other wallets without confusion. In contrast, traditional import mechanisms support only keys with special versioning to indicate the scripts to produce, and don't provide the derivation paths. This creates a situation where a user imports an extended key into a wallet but is unable to see their addresses because that wallet uses a different derivation path than the original wallet. Descriptors avoids this issue entirely by specifying the derivation paths (if any) and the scripts to produce.\ +[More on stackexchange](https://bitcoin.stackexchange.com/questions/99540/what-are-output-descriptors). + +#### xpub +An extended public key. The foundation of a series of addresses. diff --git a/Docs/MANUAL.md b/Docs/MANUAL.md index a777be39..9f1108d6 100644 --- a/Docs/MANUAL.md +++ b/Docs/MANUAL.md @@ -83,7 +83,7 @@ The main functionality of **Seed Tool** is laid out in this manual to demonstrat The main menu of **Seed Tool** contains three buttons along the top in the menu bar: -* **Information** (circled "i"). Read documentation on all of the specifications and data types found in **Seed Tool**. (Info buttons linnking to specific questions are also available throughout the app.) +* **Information** (circled "i"). Read documentation on all of the specifications and data types found in **Seed Tool**. (Info buttons linking to specific questions are also available throughout the app.) * **Scan** (qr code). Import a seed (see "Importing a Seed") or a `crypto-request` (see "Using a Seed") or a PSBT (see "Signing PSBTs") from a QR code; or import text from the Clipboard. * **Settings** (gear). Change major ways in which the App works. diff --git a/Docs/Q-and-A.md b/Docs/Q-and-A.md new file mode 100644 index 00000000..3b41f2e8 --- /dev/null +++ b/Docs/Q-and-A.md @@ -0,0 +1,327 @@ +# Q&A about Gordian Seed Tool + +## Introduction + +Gordian Seed Tool + +This document refers to a common list of [Definitions](./Definitions.md). + +Why should you read or step through this Q&A? To get a different angle on the same topic, Gordian Seed Tool. + +**The questions are of a varied level: basic and detailed. The answers are mostly directed towards generally interested people and newbies.**\ +*Q = one star question. Novice to Gordian Seed Tool, advanced in public private key (PKI)\ +**Q = two star question. Proficient in PKI and advanced in Gordian Seed Tool\ +***Q = three star question. Expert in PKI and proficient in Gordian Seed Tool + +```text +{TBW} means: to be written +{TBW prio 1} means to be written with the highest priority, 3 = no urgency, 2 = intermediate} +``` + +- [Q&A about Gordian Seed Tool](#qa-about-gordian-seed-tool) + - [Disclaimer](#disclaimer) + - [List of questions and definitions](#list-of-questions-and-definitions) + - [Knowledge you should be confidently applying](#knowledge-you-should-be-confidently-applying) + - [Actions you should be comfortable with](#actions-you-should-be-comfortable-with) +- [Jump table to categories](#jump-table-to-categories) + +**Beware: A Q&A is always *work in progress*. Tips & help welcome** + +## Disclaimer + +There are no references added to the answers. We think it's unnecessary to disclose who answered the question. We'll seek confirmation of the given answers by peer review. Most of the editing is done by Henk van Cann, which might have introduced ommission, errors, language glitches and such. Sorry for that, feel free to correct by submitting a pull request (PR).\ +For practical reasons educational images uploaded by Github members have been downloaded. We de-personalised them by giving images a new name. Under these new names these images have been uploaded to github and used in the Q&A to clarify the questions and answers. + +Gordian Seed Tool's content is licensed under the [CC by SA 4.0. license](https://creativecommons.org/licenses/by-sa/4.0/). + +We've done our best to protect the privacy of the Github by investigating the images we used. We haven't come across personal identifiable information (pii). However, should we have made a mistake after all, please let us know and we'll correct this immediately. + +### List of questions and definitions + +_Please note that our definitions are only applicable in the context of Gordian Seed Tool and within the Blockchaincommons domain. We acknowledge that there's some controversion in the space about which term means what means what to who. However, for the novice learner it's indespensible to have some sort of hand rail to hold on to while climbing the steps of the steep learning curve that proper key management involves._ + +- [Definitions:](#definitions) + - [Account Map](./Definitions#account-map) + - [Airgap](./Definitions#airgap) + - [Biometric authentication](./Definitions#biometric-authentication) + - [Bytewords](./Definitions#bytewords) + - [Clipboard](./Definitions#clipboard) + - [Concise Binary Object Representation](./Definitions#concise-binary-object-representation) + - [Content-addressable hash](./Definitions#content-addressable-hash) + - [Controller](./Definitions#controller) + - [Cryptocurrency](./Definitions#cryptocurrency) + - [Descriptor wallet](./Definitions#descriptor-wallet) + - [Entropy](./Definitions#entropy) + - [Gordian](./Definitions#gordian) + - [Key](./Definitions#key) + - [Multi-signature signing](./Definitions#multi-signature-signing) + - [Normative](./Definitions#normative) + - [Non-normative](./Definitions#non-normative) + - [Object Identity Block](./Definitions#object-identity-block) + - [Output descriptor](./Definitions#output-descriptor) + - [Payload](./Definitions#payload) + - [Public Key Infrastructure](./Definitions#public-key-infrastructure) + - [QR code](./Definitions#qr-code) + - [Seed (key)](./Definitions#seed--key-) + - [Sharded Secret Key Reconstruction](./Definitions#sharded-secret-key-reconstruction) + - [Torgap](./Definitions#torgap) + - [Transfer](./Definitions#transfer) + - [Verification keys](./Definitions#verification-keys) + - [Wallet](./Definitions#wallet) + - [Wallet descriptor](./Definitions#wallet-descriptor) + - [xpub](./Definitions#xpub) + +Table of contents generated with markdown-toc + +## Preparation + +### Knowledge you should be confidently applying + +- The definitions in the [glossary](./Definitions.md) +- Public/private key pairs +- Hashing and hashes +- Signatures and Seeds + +### Actions you should be comfortable with + +- Learn new knowledge and keep existing knowledge up to date +- Create a key pair safely and back it up safely +- Sweep to a new wallet + +## Jump table to categories + +- [General](#qa-section-general) +- [Gordian Seed Tool](#qa-gordian-seed-tool) +- [Schemes](#qa-section-schemes) +- [Wallets](#qa-section-wallets) +- [Private Key Management](#qa-section-private-key-management) +- [Security](#qa-section-security) +- [Gordian Seed Tool operational](#qa-section-gordian-seed-tool-operational) + +## Q&A: General + +### *Q: What is Gordian? + +A set of reference tools from [BlockchainCommons](https://www.blockchaincommons.com). They are based on a set of strong and innovative [principles](https://github.com/BlockchainCommons/Gordian#gordian-principles). + +The name is a [symbol](https://en.wikipedia.org/wiki/Gordian_Knot) for untying a seemingly impossibly tangled knot. +[More](https://github.com/BlockchainCommons/Gordian). + +### *Q: Why Gordian? + +[Background](https://github.com/BlockchainCommons/Gordian/blob/master/Docs/Why-Gordian.md#why-gordian). + +### *Q: What is Gordian Seed Tool? + +Gordian Seed Tool protects your cryptographic seeds while also making them available for easy use. Using Seed Tool, you can generate seeds and store them securely on your device. You can then derive and share multi-signature signing and verification keys from those seeds.\ +[More info](https://github.com/BlockchainCommons/GordianSeedTool-iOS) on the github homepage. + +### *Q: What is GordianGuardian? + +The old name for the Gordian Seed Tool, it's a synonym. + +### *Q: Where has QR Vault gone? + +This is now called QR Tool! "QR Vault" is legacy and a synonym for QR Tool. + +**Gordian Seed Tool and Gordian QR Tool are distinctive and separate**. Gordian QR Tool just stores QRs to iCloud. It's intended as a more secure place to save them than your camera roll. Those QRs can include things like Covid credentials, SSKR shares, and 2FA details. + +### *Q: What is larger Gordian ecosystem? + +Gordian Seed Tool can be used in conjunction with other Gordian tools: + +Gordian App Map + +More on the Gordian App Map [here](https://github.com/BlockchainCommons/Gordian#overview-gordian-app-map). + +However, it can also be used with other wallets of your choice; one of the ultimate goals is to create an interoperable landscape. + +### **Q: Is there crypto-request for Output Descriptors or Account Descriptors as well? + +We haven't defined them yet (December 2021). + + + +### For who is Gordian Seed Tool? + +The core audiene of Gordian Seed Tools is developers. It's a reference app intended to demonstrate the Gordian Principles and the Blockchain Commons specifications. However, it's also a useful tool for sophisticated users, and so we make it available via the Apple App Store. + +### Why should I use Gordian Seed Tool? + Because storing your seeds in the unecrypted RAM of a fully networked device is a major security vulnerability tjat leaves your seeds vulnerable to loss. It's both a Single Point of Compromise and a Single Point of Failure. Seed Tool resolves both of these problems.\ +[More in the manual](https://github.com/BlockchainCommons/GordianSeedTool-iOS/blob/master/Docs/MANUAL.md#gordian-seed-tool-manual-v13-41). + +### When should I use Gordian Seed Tool? + +You should use Gordian Seed Tool to store any seeds with addresses that hold any notable amounts of money. + +## Q&A: Operational + +### *Q: On which platforms is Gordian Seed Tool available + +Gordian Seed Tool is available for iOS and Mac 1.3 (December 2021, HC) + +### *Q: Why do I need to use iCloud? + +It's not strictly required, but it's recommended; if activated, **Seed Tool** can use automated iCloud backup and recovery. + +### Does Gordian Seed Tool run on a Mac? +It runs on the Mac as an iPad app, not Mac native. + +### **Q: What is the 'primary asset' switch for? + +The "Primary Asset" switch can be changed between Bitcoin and Ethereum. When Ethereum is selected, the following changes apply: + +1. In the Seed Detail view, the green "Cosigner Public Key" changes to "Ethereum Address" for quick export of the Ethereum Address derived from the seed. +2. After clicking "Authenticate," the "Derive Key" popup has an item that changes from "Cosigner Private Key" to "Ethereum Private Key." +3. In the "Other Key Derivations" view, the default derivation path for Ethereum is now `44'/60'/0'/0/0` which is compatible with many existing wallets. +4. The bottom of the "Other Key Derivations" view now contains an "Address" box for exporting the Ethereum address. +5. In the "Other Key Derivations" view, when deriving Ethereum, a new "Private Key" box appears that can be used to export the Ethereum private key. When printed, this page also includes the Ethereum address. +6. All visual hashes (identicons) associated with Ethereum keys or addresses now use "Blockies", which is widely recognized in the Ethereum world, instead of the usual LifeHash algorithm. + +### **Q: I get confused by a _seed request_ on one device. Could you explain more? + +Typically a seed request from "another device" **will not** be the current device. If the requested seed is not already on the device, it obviously can't send it, and will tell you so. It also makes clear the consequences of sending the seed (via the QR Code) to another device.\ +The request URs available [in the test PDFs](https://github.com/BlockchainCommons/GordianGuardian-iOS/tree/master/Testing) are so that you can test a UR similar to what another device would show when requesting a seed from this device. + +_In reference to github [issue 40](https://github.com/BlockchainCommons/GordianGuardian-iOS/issues/40)_ + +### *Q: What is the vision behind the Seed Tool? + +Gordian Seed Tool demonstrates the Gordian principles. It allows you maintain control of your own key material (independence), stores them on your closely held mobile device (privacy), protects them with 2FA and biometrics (resilience), and communicates via QRs and URs (openness).\ +[Info straight from the app](../SeedTool/Markdown/about-seed-tool.md). + +### **Q: Under what license has Gordian Seed Tool been released? + +The use of Gordian Seed Tool is under the [BSD 2-Clause Plus Patent License](https://spdx.org/licenses/BSD-2-Clause-Patent.html).\ +[More info straight from the app](../SeedTool/Markdown/license-and-disclaimer.md) + +### *Q:What is a cosigner + +A Cosigner is one of the people (or more generally, one of the keys) that signs a multi-sig transaction.\ +[More info straight from the app](../SeedTool/Markdown/what-is-a-cosigner.md) + +## Q&A: Specifications + +### *Q:What are bytewords + +ByteWords is a method (invented at BlockchainCommons) of encoding a sequence of bytes as four-letter English words. It's intended to translate a binary string into human-readable words.\ +[More info straight from the app](../SeedTool/Markdown/what-are-bytewords.md). + +### *Q: What is a lifehash? + +A LifeHash is a small picture that helps you recognize [seeds](#what-is-a-seed) and other digital objects at a glance.\ +[More info straight from the app](../SeedTool/Markdown/what-is-a-lifehash.md). + +### *Q: What is a Seed? + +A seed is a large random number used in cryptography.\ +[More info straight from the app](../SeedTool/Markdown/what-is-a-seed.md). + +### *Q: What is a UR? + +A "Uniform Resource" or UR, is a way of encoding binary data in a format that is suitable for transmission as plain text or inside a QR code. URs are a type of Uniform Resource Identifier (URI) and look similar to the web `http:` URL addresses you're familiar with. Unlike a web address, which points to a resource on the Internet, a UR is itself a complete resource.\ +[More info straight from the app](../SeedTool/Markdown/what-is-a-ur.md). + +### *Q: Wat is BIP39? + +BIP39 is Bitcoin’s traditional mnemonic word specification, which translates seeds into words and vice versa. It allows for the encoding of a seed in human-readable form, and has traditionally been used as a back-up mechanism, with the words often being stamped in metal for best survivability.\ +[More info straight from the app](../SeedTool/Markdown/what-is-bip-39.md). + +### *Q: What is key derivation? + +The core idea of [seeds](#what-is-a-seed) is that they can be used to create (derive) a whole hierarchy of keys based on the BIP-32 specification for a Hierarchical Deterministic (HD) wallet. One seed leads to many keys (and thus many addresses).\ +To derive a key requires a derivation path. This describes which precise key you're talking about of the infinite keys that could be derived from a specific seed. \ +[More info straight from the app](../SeedTool/Markdown/what-is-key-derivation.md). + +### *Q: What is SSKR? + +Sharded Secret Key Reconstruction (SSKR) is a method of taking a secret (like a [seed](#what-is-a-seed)) and breaking it up into pieces called `shards`.\ +[More info straight from the app](../SeedTool/Markdown/what-is-sskr.md). + +### **Q: Is SSKR a rebrand of SSSS, Shamir Secret Sharing scheme? + +Under the hood SSKR is using the technique of Shamir's Secret Sharing (SSS) but SSKR is a particular packaging of that technique optimized for `CBOR` and `UR`s. + + +_In reference to github [issue 37](https://github.com/BlockchainCommons/GordianGuardian-iOS/issues/37)_ + +## Q&A Security + +### *Q: Why do I need 2FA? + +It improves the privacy and resilience of your seeds. Once protected via 2FA, you must login in to your Apple account, then you must verify whenever you access private data. + +### **Q: What is the most secure way to create a new seed from scratch? + +Using coin flips, die rolls, or playing cards. But you must properly flip every coin, roll every die, or draw every card, no matter how tedious it is.\ +[More in the manual](https://github.com/henkvancann/GordianSeedTool-iOS/blob/master/Docs/MANUAL.md#creating-a-seed). + +### **Q: What is the least secure way to create a new seed from scratch? + +Quick Create. It depends on your mobile device's randomization to create a seed. If there is ever an exploit revealed, you'll be forced to sweep all of your funds.\ +[More in the manual](https://github.com/henkvancann/GordianSeedTool-iOS/blob/master/Docs/MANUAL.md#creating-a-seed). + +### ***Q: Which algorithms have been used to create entropy for creating seeds? + +_Quick Create_ depends on your mobile device's randomization to create a seed.\ +_Coin_ (binary) and _Die_ entropy in Gordian Seed Tool matches that of [Ian Coleman's BIP-39 Mnemonic Code Converter](https://iancoleman.io/bip39/).\ +Card drawing entropy is generated by {TBW1} + +### *Q: Can I import the same seed twice? + +*I can't think of a reason why I would want to import the same seed twice.* + +`ur:crypto-seed` contains metadata like name and notes that can be different. It's up to the user to reconcile these differences. + + +_In reference to github [issue 41](https://github.com/BlockchainCommons/GordianGuardian-iOS/issues/41)_ + +### *Q: Why it is recommended to delete all data from the device before deleting the app? + +The warning message has been clarified: "All data will be erased from the app, including ALL seeds stored in the device keychain. This is recommended before deleting the app from your device, because deleting an app does not guarantee deletion of all data added to the keychain by that app." + + + +_In reference to github [issue 36](https://github.com/BlockchainCommons/GordianGuardian-iOS/issues/36)_ + +### *Q: I swiped to delete a seed, now the settings cog asks me to delete ALL seeds?? + +**You don't have to swipe on a seed to delete it**. Just tap the Edit button and then tap one of the Delete buttons that appear. This is iOS-standard behavior. Swipe-to-delete is a shortcut. + +If you see the "Erase All Data" Danger Zone box, then it's likely you accidentally hit the gear that brings you to the settings page. You should click "Done" to exit the Settings. + +| Swipe left | Click on | +| -------- | -------- | +| || + +_In reference to github [issue 42](https://github.com/BlockchainCommons/GordianGuardian-iOS/issues/42)_ + +### *Q: Is a Copy-paste of a BIP39 seed a good idea? + +There are security issues related to copy-pasting when your computer has been compromised. On the other hand it's easy and less error prone to copy and paste. It's your choice. You can also type in the 24 word seed. + +### **Q: To which formats can I export my GST keys? + +Key Export: Master keys derived from seeds can now be exported to Output Descriptors (`crypto-output`) or Account Descriptors (`crypto-account`). + +### **Q: How can I export my GST keys? + +To see this new feature: + +1. choose a seed from the Seed List +2. In the Encrypted Data section, tap Authenticate +3. Tap Derive Key and then Other Key Derivations +4. In the Parameters area, make sure Bitcoin and Master Key are selected +5. Scroll down to the Secondary Derivation section and choose Output Descriptor or Account Descriptor +6. Choose Output Descriptor or Account Descriptor, and edit the Account Number field if desired +7. If you chose Output Descriptor, then choose an Output Type +8. Scroll down to the bottom to export your Output Descriptor or Account Descriptor. + +Output Descriptors may be exported as text format or `ur:crypto-output` format. Account Descriptors may be exported in `ur:crypto-account` format. + +## Wallet + +### *Q Can I store my bitcoin and ethereum in Gordian Seed Tool? + +No, Gordian **Seed Tool is not a cryptocurrency wallet**. It neither stores nor transmits value in any cryptocurrency.\ +What it is and what it does, see Gordian Seed Tool's [Github homepage](https://github.com/BlockchainCommons/GordianSeedTool-iOS). diff --git a/Docs/Testing.md b/Docs/Testing.md new file mode 100644 index 00000000..3bda9166 --- /dev/null +++ b/Docs/Testing.md @@ -0,0 +1,33 @@ +# Testing Gordian Seed Tool + +This is step by step that guides a tester through the [Testing](https://github.com/BlockchainCommons/GordianSeedTool-iOS/tree/master/Testing) environment of Gordian **Seed Tool**. +It's aimed at the novice user of Seed Tool. +adding seeds, storing seeds, using seeds, exporting seeds, and removing seeds. + + +**Buckle up, we're going through an exciting journey towards safe, resilient and fun key management!** + +## Preparatory work +1. Read the [Readme] (../README.md) about Gordian Seed Tool +2. [Install](./MANUAL.md#installing-seed-tool) Gordian Seed Tool on at least one of the available platforms +3. Check wether you have any Questions that have been posed already in the [Q&A](./Q-and-A.md) and/or whether you have any terms that you'd like to be sure of how we've defined them in the context of Gordian Seed Tool in the list of [definitions and abbreviations](./Definitions.md). + +**All set? Let's go forward!** + +## Testing material +The directory [Testing](https://github.com/BlockchainCommons/GordianSeedTool-iOS/tree/master/Testing) contains input QR-codes, keys, etc.\ +The examples below will link to input docs and images directly. Please report if any file is missing or links broken. + +# Step by step +We're going through the process laid out in this document with predictable and measurable results and will train the basic operations for **Seed Tool** at the same time. +1. add seeds, +2. store seeds, +3. use seeds, +4. export seeds, +5. remove seeds. + +WM: To test the app's scanning capabilities, you can find a PDF containing a "ur:crypto-seed" QR code attached, or at this URL: https://github.com/BlockchainCommons/GordianSeedTool-iOS/blob/master/Testing/DPAL%20Seed.pdf + +WM: * For compatibility testing with third-party wallets that have already implemented this, a bare `ur:crypto-psbt` may now be scanned and signed. Using `ur:crypto-request` is Blockchain Commons' recommended method for requesting PSBT signing, so when a bare `ur:crypto-psbt` is scanned, users are notified of this, thus this capability should be used only for developer compatibility testing and developers are encourage to adopt `ur:crypto-request` as soon as possible. +* When a `ur:crypto-psbt` is scanned, two possible outputs are offered: the signed bare `ur:crypto-psbt` and a dummy `ur:crypto-response`. This is a "dummy" response because it is not actually a response to a particular `ur:crypto-request` and thus the transaction ID included in the response is random and does not correspond to any actual prior request. +* Two new example QR codes have been added to the [Testing](https://github.com/BlockchainCommons/GordianSeedTool-iOS/tree/master/Testing) folder: `Bare PSBT 1 of 2.png` and `Bare PSBT 2 of 2.png` which can be used to test the bare PSBT signing capability. These are the same transactions also provided in `ur:crypto-request` form. \ No newline at end of file diff --git a/README.md b/README.md index 46f5b76b..31983235 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ To compile from source, simply choose "Code > Open with Xcode" from the top of t * [**Manual**](Docs/MANUAL.md). An overview of installing and using **Seed Tool**, including info on adding seeds, storing seeds, using seeds, exporting seeds, and removing seeds. * [**Integrating Seed Tool with Other Apps**](Docs/Integration.md). Using **Seed Tool** as a real-life seedstore for live transactions coordinated by other apps. +* [**Test instructions**](Docs/Testing.md) A step by step that guides a tester through the [Testing](https://github.com/BlockchainCommons/GordianSeedTool-iOS/tree/master/Testing) environment of Gordian **Seed Tool**. ## Gordian Principles