Readme file - Update file verification section (to use keybase.io), clarify the download section, and other minor edits #285
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -46,7 +46,7 @@ If you have specific questions about the project, our [Telegram Group](https://t | |
| ### Considerations: | ||
| * Built for compatibility with Specter Desktop, Sparrow, and BlueWallet Vaults | ||
| * Device takes up to 60 seconds to boot before menu appears (be patient!) | ||
| * Always test your setup before transferring larger amounts of bitcoin (try Testnet first!) | ||
| * Taproot not quite yet supported | ||
| * Slightly rotating the screen clockwise or counter-clockwise should resolve lighting/glare issues | ||
| * If you think SeedSigner adds value to the Bitcoin ecosystem, please help us spread the word! (tweets, pics, videos, etc.) | ||
|
|
@@ -77,60 +77,144 @@ Notes: | |
|
|
||
| # Software Installation | ||
|
|
||
| ## A Special Note On Minimizing Trust | ||
| As is the nature of pre-packaged software downloads, downloading and using the prepared SeedSigner release images means implicitly placing trust in the individual preparing those images; in our project the release images are prepared and signed by the eponymous creator of the project, SeedSigner "the person". That individual is additionally the only person in possession of the PGP keys that are used to sign the release images. | ||
|
|
||
| However, one of the many advantages of the open source software model is that the need for this kind of trust can be negated by our users' ability to (1) review the project's source code and (2) assemble the operating image necessary to use the software themselves. From our project's inception, instructions to build a SeedSigner operating image (using precisely the same process that is used to create the prepared release images) have been made availabile. We have put a lot of thought and work into making these instructions easy to understand and follow, even for less technical users. These instructions can be found [here](docs/manual_installation.md). | ||
|
|
||
| ## Downloading the Software | ||
|
|
||
| To download the most recent software version, click [here](https://github.com/SeedSigner/seedsigner/releases), and then expand the *Assets* sub-heading. | ||
| Download these files to your computer: | ||
| 1. seedsigner_0_5_x.img.zip | ||
| 2. seedsigner_0_5_x.img.zip.sha256 | ||
| 3. seedsigner_0_5_x.img.zip.sha256.sig | ||
|
|
||
| **Note:** The version numbers of the latest files will be higher than this example, but the naming format will be the same. | ||
| Once the files have all finished downloading, follow the steps below to verify them, and then to write the software onto a MicroSD card. Insert the MicroSD into your assembled hardware and turn on the USB power. Allow about 45 seconds for our logo to appear, and then you can begin using your Seedsigner! | ||
|
|
||
|
|
||
|
|
||
|
|
||
| ## Verifying that the downloaded files are authentic (optional but highly recommended!) | ||
|
|
||
| You can quickly verify that the software you just downloaded is both authentic and unaltered, by following these instructions. | ||
| We assume you are running the commands from a computer where both [GPG](https://gnupg.org/download/index.html) and [shasum](https://command-not-found.com/shasum) are already installed, and that you also know [how to navigate on a terminal](https://terminalcheatsheet.com/guides/navigate-terminal). | ||
|
|
||
|
|
||
| ### Step 1. Verify that the signature (.sig) file is genuine: | ||
|
|
||
| Run GPG's *fetch-keys* command to import the SeedSigner projects public key from the popular online keyserver called *Keybase.io*, into your computers *keychain*. | ||
|
|
||
|
|
||
| ``` | ||
| gpg --fetch-keys https://keybase.io/SeedSigner/pgp_keys.asc | ||
| ``` | ||
| The result should confirm that 1 key was *either* imported or updated. *Ignore* any key ID's or email addresses shown. | ||
|
|
||
|  | ||
|
|
||
| Next, you will run the *verify* command on the signature (.sig) file. (*Verify* must be run from inside the same folder that you downloaded the files into earlier. The `*`'s in this command will auto-fill the version from your current folder, so it should be copied and pasted as-is.) | ||
| ``` | ||
| gpg --verify seedsigner_0_*_*.img.zip.sha256.sig | ||
| ``` | ||
|
|
||
| When the verify command completes successfully, it should display output like this: | ||
| <BR> | ||
|  | ||
| The result must display "**Good signature**". Ignore any email addresses - *only* matching Key fingerprints count here. Stop immediately if it displays "*Bad signature*"! | ||
| <BR> | ||
|
|
||
| On the *last* output line, look at your *rightmost* 16 characters (the 4 blocks of 4). | ||
| **Crucially, we must now check WHO that Primary key fingerprint /ID belongs to.** We will start by looking at Keybase.io to see if it is the *Seedsigner project* 's public key or not. | ||
|
|
||
| <details><summary> About the warning message:</summary> | ||
| <p> Since you are about to match the outputted fingerprint/ID against the proofs at Keybase.io/seedsigner, and thereby confirm who the pubkey really belongs to-, you can safely ignore this warning message: | ||
|
|
||
| ``` | ||
| > WARNING: This key is not certified with a trusted signature! | ||
| > There is no indication that the signature belongs to the owner. | ||
| ``` | ||
| </p> | ||
| </details> | ||
| <br> | ||
|
|
||
| <details><summary> More about how the verify command works:</summary> | ||
| <p> | ||
| The verify command will attempt to decrypt the signature file (sha256.sig) by trying each public key already imported into your computer. If the public key we just imported (via fetch-keys), manages to: (a) successfully decrypt the .sig file , and (b), that result matches exactly to the clear-text equivalent (.sha256) of the .sig file, then its "a good signature"! | ||
|
|
||
| Crucially, we must still manually check who *exactly* owns the Key ID which gave us that "Good signature". Thats what the warning message means- Who does the matching key really belong to? We will start by looking at keybase.io to see if it is "The Seedsigner project"'s public Key or not. | ||
| Note that it is the file hashes of .sig and .sha256 that *verify* compares, not their raw contents. | ||
|
|
||
| </p> | ||
| </details> | ||
| <br> | ||
|
|
||
| Now to determine ***who*** the Public key ID belongs to: Goto [Keybase.io/seedsigner](www.keybase.io/seedsigner) | ||
| <BR> | ||
|  | ||
|
|
||
|
|
||
|
|
||
| **You must now *manually* compare: The 16 character fingerprint ID (as circled in red above) to, those *rightmost* 16 characters from your *verify* command.** | ||
|
|
||
| **If they match exactly, then you have successfully confirmed that your .sig file is authentically from the Seedsigner Project!** | ||
| <BR> | ||
|
|
||
| <details><summary>Learn more about how keybase.io helps you check that someone (online) is who they say they are:</summary> | ||
| <p> | ||
| Keybase.io allows you to independently verify that the public key saved on Keybase.io, is both authentic and that it belongs to the organization it claims to represent. | ||
| Keybase has already checked the three pubkey file locations cryptographically when they were saved there. You can further verify the key publications if you would like: | ||
|
|
||
| - *via Keybase*: By clicking on any of the three blue badges to see that the "proof" was published at that location. (The blue badge marked as tweet, is in the most human-readable form and it is also a bi-directional link on Twitter) | ||
| or, | ||
| - *without keybase (out-of-band)*: By using these 3 links directly: [Twitter](https://twitter.com/seedsigner/status/1530555252373704707), [Github](https://gist.github.com/SeedSigner/5936fa1219b07e28a3672385b605b5d2) and [Seedsigner.com](https://seedsigner.com/keybase.txt). This method can be used if you would like to make an even deeper, independent inspection without relying on Keybase at all, or if the Keybase.io site is no longer valid or it is removed entirely. | ||
|
|
||
| Once you have used one of these methods, you will know if the Public Key stored on Keybase, is genuinely from the SeedSinger Project or not. | ||
| </p> | ||
| </details> | ||
| <br> | ||
|
|
||
| If the two ID's do *not* match, then you must stop here immediately. Do not continue. Contact us for assistance in the Telegram group address above. | ||
|
|
||
| <br> | ||
|
|
||
| ### 2. Verifying that the *software images/binaries* are genuine | ||
|
There was a problem hiding this comment. The last level3 header was "Step 1.", so here maybe "Step 2." instead of "2." There was a problem hiding this comment. Fixed in [a136a86] |
||
|
|
||
| Now that you have confirmed that you do have the real Seedsigner Project's Public Key (ie the 16 characters match) - you can return to your terminal window. Running the the *shasum* command, is the final verification step and will confirm (via file hashing) that the software code/image files (ie the binary files inside the zip file), were also not altered since publication, or even during your download process. | ||
|
|
||
| **On Linux or OSX:** Run this command | ||
| ``` | ||
| shasum -a 256 -c seedsigner_0_*_*.img.zip.sha256 | ||
| ``` | ||
|
|
||
| **On Windows (inside Powershell):** Run this command | ||
| ``` | ||
| CertUtil -hashfile seedsigner_0_*_*.img.zip SHA256 | findstr /v "hash" | ||
| ``` | ||
| <BR> | ||
|
|
||
| Wait about 30 seconds for the command to complete, and it should display: | ||
| ``` | ||
| seedsigner_0_5_x.img.zip: OK | ||
| shasum: WARNING: 4 Lines are improperly formatted | ||
| ``` | ||
| **If you receive the "OK" message** for your **seedsigner_[x.x.x.VersionNumber].img.zip file**, as shown above, then your verification is fully complete! | ||
| **All of your downloaded files have now been confirmed as both authentic and unaltered!** You can proceed to create/write your MicroSD card😄😄 !! | ||
|
|
||
| The warning message describing '4 lines being improperly formatted' can be safely ignored. | ||
| If your file result shows "FAILED", then you must stop here immediately. Do not continue. Contact us for assistance at the Telegram group address above. | ||
|
|
||
| <BR> | ||
|
|
||
| Please recognize that this process can only validate the software to the extent that the entity that first published the key is an honest actor, and their private key is not compromised or somehow being used by a malicious actor. | ||
| <BR> | ||
| <BR> | ||
|
|
||
|
|
||
| ## Writing the software to your MicroSD card | ||
| Insert more instructions here. | ||
| (to be done by MarcG) | ||
|
|
||
| --------------- | ||
|
|
||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.
"eponymous" becomes "anonymous"" That individual is additionally" becomes " That individual is also" or " Additionally, that individual is"
Is it 'SeedSigner "the person"', or is it 'SeedSigner "the man"' ???