New documentation for develop (#408)

* documentation refactoring

* documentation fixes

* distilled instructions for MDK

* remove deploy TODO after creating PR

* fixes typos

docs/customization.md

@@ -0,0 +1,66 @@
+# <img alt="OpenSK logo" src="img/OpenSK.svg" width="200px">
+
+## Customization
+
+### Cryptographic material
+
+All the generated certificates and private keys are stored in the directory
+`crypto_data/`. The expected content after running our `setup.sh` script is:
+
+File                     | Purpose
+------------------------ | --------------------------------------------------------
+`aaguid.txt`             | Text file containaing the AAGUID value
+`opensk_ca.csr`          | Certificate sign request for the Root CA
+`opensk_ca.key`          | ECC secp256r1 private key used for the Root CA
+`opensk_ca.pem`          | PEM encoded certificate of the Root CA
+`opensk_ca.srl`          | File generated by OpenSSL
+`opensk_cert.csr`        | Certificate sign request for the attestation certificate
+`opensk_cert.pem`        | PEM encoded certificate used for the authenticator
+`opensk.key`             | ECC secp256r1 private key used for the autenticator
+`opensk_upgrade.key`     | Private key for signing upgrades through CTAP
+`opensk_upgrade_pub.pem` | Public key added to the firmware for verifying upgrades
+
+If you want to use your own attestation certificate and private key,
+replace the `opensk_cert.pem` and `opensk.key` files. The script at
+`tools/configure.py` customizes an OpenSK device with the correct certificate
+and private key.
+
+Our build script `build.rs` is responsible for converting the `aaguid.txt` file
+into raw data that is then used by the Rust file `src/ctap/key_material.rs`.
+
+Please make sure to safely store all private key material before calling
+`reset.sh`, or the files will be lost.
+
+#### Certificate considerations
+
+The certificate on OpenSK is used for attestation. That means, whenever you
+register OpenSK on a website, you attest the legitimacy of your hardware. For
+self-generated certificates, this claim is rather trivial. Still, it is required
+by some websites and to use U2F.
+
+Usually, the attestation private key is shared between a batch of at least
+100,000 security keys of the same model. If you build your own OpenSK, your
+private key is unique to you. This makes you identifiable across registrations:
+Two websites could collaborate to track if registrations were attested with the
+same key material. If you use OpenSK beyond experimentation, please consider
+carefully if you want to take this privacy risk.
+
+### Software personalization
+
+If you build your own security key, depending on the hardware you use, there are
+a few things you can personalize:
+
+1.  If you have multiple buttons, choose the buttons responsible for user
+    presence in `src/main.rs`.
+1.  If you have colored LEDs, like different blinking patterns and want to play
+    around with the code in `src/main.rs` more, take a look at e.g. `wink_leds`.
+1.  You find more options and documentation in `src/ctap/customization.rs`,
+    including:
+    *   The default level for the credProtect extension.
+    *   The default minimum PIN length, and what relying parties can set it.
+    *   Whether you want to enforce alwaysUv.
+    *   Settings for enterprise attestation.
+    *   The maximum PIN retries.
+    *   Whether you want to use batch attestation.
+    *   Whether you want to use signature counters.
+    *   Various constants to adapt to different hardware.