Docs on security

README.md

@@ -14,7 +14,7 @@ The goals of this library are to provide an updater that:
 - Recovers from non-fatal errors
 - Every request or command execution should timeout (nothing blocks)
 - Can recover from failures in its environment
-- Can run as an unpriviledged background service
+- Can run as an unprivileged background service
 - Has minimal, vendored dependencies
 - Is well tested
 - Is secure
@@ -31,12 +31,15 @@ The main package is the updater core, there are other support packages:
 
 - command: Executes a command with a timeout
 - keybase: Keybase specific behavior for updates
-- osx: Presents UI for OS X
+- osx: MacOS specific UI
 - process: Utilities to find and terminate Processes
+- saltpack: Verify updates with [saltpack](https://saltpack.org/)
 - service: Runs the updater as a background service
-- sources: Update sources (locations) for static remote (like S3), or locally (for testing)
+- sources: Update sources for remote locations (like S3), or locally (for testing)
 - test: Test resources
 - util: Utilities for updating, such as digests, env, file, http, unzip, etc.
+- watchdog: Utility to monitor processes and restart them (like launchd), for use with updater service
+- windows: Windows specific UI
 
 
 ### Development

SECURITY.md

@@ -0,0 +1,21 @@
+## Security
+
+In the future, we will be looking to integrate with [TUF](https://theupdateframework.github.io/)
+in order to make updates more secure. In the meantime, this document describes
+what the updater (in the context of the Keybase application) protects against.
+
+The updater may not protect against certain attacks.
+
+- Rollback attacks: The updater doesn't prevent an earlier update from being applied
+- Indefinite freeze attacks: An attacker could reply with old metadata
+- Endless data attacks: An attacker could cause the client to download endless data
+- Slow retrieval attacks: An attacker could prevent an update by being slow
+- Extraneous dependencies attacks: The updater doesn't know about dependencies and will only download and apply a single asset
+- Mix-and-match attacks: An attacker could mix metadata (use an old asset with new update)
+
+The Keybase updater does do the following (to prevent basic attacks):
+
+- Uses TLS with a pinned certificate for api.keybase.io (update source) for metadata
+- Uses TLS to download asset
+- Verifies asset digest (SHA256)
+- Verifies asset saltpack signature (key IDs are pinned)