Ported documentation (#413)

* ported documentation from develop

* adapted instructions

* fix broken English

docs/customization.md

@@ -0,0 +1,78 @@
+# <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
+
+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 `main.rs`.
+2.  Decide whether you want to use batch attestation. There is a boolean flag in
+    `ctap/mod.rs`. It is mandatory for U2F, and you can create your own
+    self-signed certificate. The flag is used for FIDO2 and has some privacy
+    implications. Please check
+    [WebAuthn](https://www.w3.org/TR/webauthn/#attestation) for more
+    information.
+3.  Decide whether you want to use signature counters. Currently, only global
+    signature counters are implemented, as they are the default option for U2F.
+    The flag in `ctap/mod.rs` only turns them off for FIDO2. The most privacy
+    preserving solution is individual or no signature counters. Again, please
+    check [WebAuthn](https://www.w3.org/TR/webauthn/#signature-counter) for
+    documentation.
+4.  Depending on your available flash storage, choose an appropriate maximum
+    number of supported resident keys and number of pages in
+    `ctap/storage.rs`.
+5.  Change the default level for the credProtect extension in `ctap/mod.rs`.
+    When changing the default, resident credentials become undiscoverable without
+    user verification. This helps privacy, but can make usage less comfortable
+    for credentials that need less protection.
+6.  Increase the default minimum length for PINs in `ctap/storage.rs`.
+    The current minimum is 4. Values from 4 to 63 are allowed. Requiring longer
+    PINs can help establish trust between users and relying parties. It makes
+    user verification harder to break, but less convenient.
+    NIST recommends at least 6-digit PINs in section 5.1.9.1 of their
+    [Digital Identity Guidelines](https://pages.nist.gov/800-63-3/sp800-63b.html).
+    You can add relying parties to the list of readers of the minimum PIN length.