Merge branch 'master' of gitlab.com:solokeys/solo

README.md

@@ -1,17 +1,53 @@
 # Solo
 
-This is the source code for Solo.  It implements the authenticator U2F and FIDO2 protocols.  It is designed 
+This is the source code for Solo.  Solo is a security key that implements FIDO2/U2F and supports USB, NFC, and extensions.  Extensions
-to be easily ported to lightweight embedded platforms, as well as run on the PC.
+include SSH, GPG, and cryptocurrency.  Solo is a work in progress.
+
+![](https://i.imgur.com/cXWtI1D.png)
+![](https://i.imgur.com/vwFbsQW.png?1)
+
+The Solo FIDO2/U2F code base is designed to be easily ported to different embedded systems.
+Right now, it has been ported to the NRF52840 and EFM32J.  Soon to be supported is the SAM L11.
+
+No hardware is needed for development.  You can run and extend the FIDO2 code base
+using just your PC.
+
+# Security
+
+Solo is based on the SAM L11 secure microcontroller.  It offers the following security features.
+
+- True random number generation to guarantee random keys.
+- Side channel resistant RAM and AES for physically secure key derivation.
+- ARM TrustZone to provide security isolation for master key.
+- Scrambled key storage to prevent invasive flash readout methods.
+- Secure boot to ensure application integrity.
+
+The SAM L11 is one of the best chips for this application in terms of security,
+when considering the NDA-free market.
+
+Solo can be trusted to be running the open source code.  The firmware can be readout using a debugger to verify that a Solo is running
+the code posted publicly.  The secret information is of course inaccessible.
+
+# How do I get one?
+
+We are still working on open sourcing an implementation that anyone can cheaply
+build and program, just like with U2F Zero.  This will be released soon.  It will be easy to solder :)
+
+In the meantime, you can port the code to your favorite microcontroller, or support
+us by [signing up for our Kickstarter](https://solokeys.com/).  Our aim is to crowdfund enough to make an economic
+bulk order and provide open source security tokens for everyone that is interested.  We will offer 
+"hackable" tokens that come with USB bootloaders and are reprogrammable.
+
+[Sign up here](https://solokeys.com/)!
 
-No hardware is needed for development.
 
 # Setting up
 
 Clone and Compile CBOR library and FIDO 2 client library.
 
 ```bash
-git clone https://github.com/conorpp/u2f-one
+git clone https://github.com/SoloKeysSec/solo
-cd u2f-one/
+cd solo/
 git submodule update --init
 
 cd tinycbor && make
@@ -22,6 +58,10 @@ python setup.py install
 
 ```
 
+Note that our python-fido2 fork will only connect to the software FIDO2 application,
+not a hardware authenticator.  Install Yubico's fork to do that.
+
+
 Open `crypto/tiny-AES-c/aes.h` in a text editor and make sure AES256 is selected as follows.
 
 ```
@@ -41,10 +81,8 @@ make
 The application is set up to send and recv USB HID messages over UDP to ease
 development and reduce need for hardware.
 
-Testing can be done using Yubico's client software.  Note that the client
+Testing can be done using our fork of Yubico's client software, `python-fido2`.  
-software is also a work in progress and the [FIDO 2.0
+Our fork of `python-fido2` has small changes to make it send
-specification](https://fidoalliance.org/specs/fido-v2.0-ps-20170927/fido-client-to-authenticator-protocol-v2.0-ps-20170927.html)
-is ultimate.  Some small changes to Yubico's Client software make it send
 USB HID over UDP to the authenticator application.
 
 Run FIDO 2 / U2F application.
@@ -53,16 +91,49 @@ Run FIDO 2 / U2F application.
 ./main
 ```
 
-Run client software.
+Run example client software.  This runs through a registration and authentication.
 
 ```
 python python-fido2/examples/credential.py
 ```
 
-You should see messages exchange between the client and the authenticator but that's it.  Follow specifications to develop further.
+Run the FIDO2 tests.
+
+```
+python tools/ctap_test.py
+```
+
+Follow specifications to really dig in.
 
 [https://fidoalliance.org/specs/fido-v2.0-ps-20170927/fido-client-to-authenticator-protocol-v2.0-ps-20170927.html](https://fidoalliance.org/specs/fido-v2.0-ps-20170927/fido-client-to-authenticator-protocol-v2.0-ps-20170927.html)
 
+## Extensions
+
+Extensions can be added to FIDO2/U2F to support things like SSH, GPG, and cryptocurrency.
+Right now, an experimental cryptocurrency extension can be found in `fido2/extensions` and `web/index.html`.
+More documentation to come.
+
+The main goal is to expose an extensible API on Solo, like the following:
+- Command to store private key
+- Command to sign arbitrary hash
+- Command to derive a public key
+- Commands for setting/changing/authenticating a pin code (like in FIDO2)
+- Command to expose entropy from TRNG.
+
+Using these generic commands, various external programs can be implemented for the security key.
+Since FIDO2/U2F are implemented, these programs can potentially work in the browser on desktops
+and mobile devices, with no drivers needed to be installed.
+
+
+## Porting
+
+The main code base is in `fido2/`.  See `targets/nrf52840`, `targets/efm32/src`, and `pc/`
+for examples of FIDO2/U2F ports.  In essence, you just need to reimplement `device.c`.  Optionally you can
+re-implement `crypto.c` to accelerate operations and/or add other security features.
+
+
+More documentation to come.
+
 # Contributors
 
 Contributors are welcome.  The ultimate goal is to have a FIDO 2 hardware token
@@ -70,10 +141,10 @@ capable of USB, Bluetooth, and NFC interfaces.  There could be multiple tokens
 for each interface.  [Hardware is still being decided
     on](https://github.com/conorpp/u2f-zero/issues/76).
     
+Look at the issues to see what is currently being worked on.  Feel free to add issues as well.
+
 This is an upgrade to [U2F
-Zero](https://github.com/conorpp/u2f-zero).  A lot of the hardware and software
+Zero](https://github.com/conorpp/u2f-zero).
-will be different so I think it's best to start a new repository.
-