diff --git a/doc/DISCLAIMER.md b/doc/DISCLAIMER.md index 842c1e6..e69de29 100644 --- a/doc/DISCLAIMER.md +++ b/doc/DISCLAIMER.md @@ -1,286 +0,0 @@ -## Trust - -This app does the hash calculation in the browser using the -[WebCryptoAPI](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest). -This means we can trust the hash calculation under the following assumptions: - - - The integrity of the application has been preserved when it executes in the - browser. - - The browser and any extensions can be trusted. - -### Integrity of the TrustyHash itself - -Because the application itself is a single HTML file which can be saved locally, -there are various means for verifying integrity. - -#### Trusted Hash Utility - -The most reliable way to verify is to compute the hash of the HTML file with a -trusted hash utility on the local system, and compare against the values -published below. - -#### Code Audit - -Someone familiar with JavaScript can spend a few minutes reading the concise -source to be assured that the program does what it claims to. - -#### No Hash Utility, Can't Audit Code? - -Hmm, no trusted hash utility, can't audit the code... you just can't give up -and use your copy of TrustyHash without trusting it! While you could try some -half-measure like getting some kind of consensus on the hash value of -TrustyHash from untrusted hash utilities on the web, maybe other copies of -TrustyHash found elsewhere... ultimately if you really need to trust -TrustyHash, you've got to be a bit more rigorous. - -Without knowing a thing about JavaScript until this moment, you can create a -very small, simple program in about 5 minutes, that while not as nice as -TrustyHash perhaps, will get the job of hashing a local file done. As long as -you can follow along as the following code is explained, and you can be pretty -confident the code is not doing anything fishy, you can use this to verify -TrustyHash itself. I'll show you the whole program up-front before I explain -it - see, 5 minutes, no more! - -``` - - - - - - -``` - -JavaScript programmers may take offense with the lack of conventional -formatting above, but I'm trying to making this easy to re-type for someone who -shouldn't need to be concerned with formatting conventions. - -Now a more-or-less line-by-line explanation: - -``` - - - - - - - -``` - -Oh, and we need these lines to formally close the HTML document. - -If you followed all that, put this code into a file called -`TrustyHashLite.html` and open it up in your browser. I recommend re-typing, -rather than copy-pasting, since there are a bunch of sneaky ways someone could -trick you into copy-pasting something besides what you see on a web page. If -creating HTML files by hand is a bit confusing, you can save [the file I -created for -you](https://raw.githubusercontent.com/sprin/TrustyHash/master/TrustyHashLite.html) -as long as you promise you will make sure the code matches the above after you -have saved it. One way to do this is to open the file in a browser, right-click -and select "View Page Source". - -Open the `TrustyHashLite.html` file in your browser, click the file input -button, select the `TrustyHash.html` you saved earlier. If the printed hex code -matches the published hash values, congratulations, you just wrote a program -that computes SHA-256 hashes *and* used it to validate TrustyHash! - -### Hash Values - -TODO: Publish hash value for 1.0.0 - -### Integrity of the Browser - -In order to trust the results of TrustyHash, we need to trust the browser that -it runs in. Is the implementation of WebCryptoAPI to be trusted? Are extensions -able to modify the result the user sees? - -If one is able to see the source of the browser and deterministic, reproducible -builds are possible, then we can start to form a strong basis of trust. Closed -source browsers must be excluded - the vendor is not able to assert a strong -claim of *what* they are distributing. At best, they may be able to publish -complete specifications for all functionality, but users still must trust the -vendor ultimately to actually implement the specifications as claimed. The -point is moot since no closed-source browser vendor publishes complete -specifications anyway. - -Currently, open-source browsers are little better off. Deterministic builds are -still a work-in-progress for all popular open-source browsers -([Tor Browser](https://blog.torproject.org/category/tags/deterministic-builds), -[Firefox](https://bugzilla.mozilla.org/show_bug.cgi?id=885777), -[Chromium](https://bugs.chromium.org/p/chromium/issues/detail?id=314403). -Without deterministic builds, we must still trust the vendor ultimately to -build and distribute what they say they are building. If we trust the vendor -when they say, "deterministic builds are hard, we are working on it", and we -can trust them to secure their build environment, then we can take the signed -hash values they publish to represent the objects built from the published -sources. - -So then there are three realistic ways we might have a trusted browser on our -systems: - - - A verified open-source browser was bundled with our trusted operating system - distro. - - We installed an open-source browser from a trusted package manager that - handled checking verification for us. - - We downloaded the open-source browser directly from the vendor and checked - the signatures/hashes ourselves. - -The third possible way, which is only feasible for a tiny fraction of extremely -diligent users, is to build the browser from source, rebuilding whenever -security updates are pushed to users. - -Since the majority of browser users do not use an operating system that bundles -a verified open-source browser nor supplies a package manager which can -download and verify an open-source browser for them, this leaves manually -verifying. Because no operating system makes it easy or obvious to verify -signed downloads and awareness of the importance of verification is very low, -we have to conclude that the majority of browser users have very little basis -for trusting their browser. Similar arguments can be made for the operating -system as a whole. - -So where does that leave us? Is running any program inside a browser with any -degre of trust hopeless for the vast majority of users? I would say that we may -be forced to accept some uncertainty that a program such as TrustyHash will -produce the correct results in an untrusted browser. If we accept this -uncertainty, we can use TrustyHash to bootstrap trust for a new browser or even -operating system. This, I think, is the real value of TrustyHash - to bootstrap -trust on a system by providing the best possible effort at producing trusted -hash values in an accessible way. - -## Deployment - -The entire application is packaged in a single, brief HTML file. Simply deploy -the file under the web server root directory. - -## Why only SHA-256? - -SHA-256 remains the de facto standard for verifying files via hash in 2016. -Here are some popular projects have standardized on SHA-256 for verifying -release materials: - - - [Tor Browser](https://www.torproject.org/docs/verifying-signatures.html#BuildVerification) - - [OpenBSD](http://man.openbsd.org/signify) - - [FreeBSD](https://www.freebsd.org/releases/10.2R/signatures.html) - - [Centos](http://mirror.centos.org/centos/7/isos/x86_64/sha256sum.txt) - - [Fedora](https://getfedora.org/verify) - -In the interests of standardization and keeping things simple, only SHA-256 -will be shown. A possible addition to this project is to allow the user to -select other hash algorithms, with SHA-256 remaining the default. - -## Limitations - -When the application is retrieved on an HTTPS connection, the application -cannot fetch HTTP URLs due to restrictions against [mixed active -content](https://developer.mozilla.org/en-US/docs/Security/Mixed_content#Mixed_active_content]). -A workaround for this is to save the page locally and open the local copy in -the browser, as recommended anyway.