Add more documentation to the main README and development infos

DEVELOPMENT.md

@@ -0,0 +1,24 @@
+# Development
+
+This document gives some pointers on where to start when modifying the library for your needs.
+
+The starting point for a user is the [`fido.h`](include/fido.h), which includes most of the functionality exposed to the user.
+
+When developing new features, you may orient on the [libfido2](https://github.com/Yubico/libfido2), which heavily inspired this project.
+
+## Adding extensions and alike
+
+As this library is designed without heap allocations and with as few copy operations as possible, we currently do not pass the extensions received from the authenticator in the `authenticatorGetInfo` command to the user directly.
+Instead, we parse the extensions received from the authenticator into a bitfield.
+To enable the parsing of a new extension, add the corresponding bitfield definition in [`info.h`](https://github.com/All-Your-Locks-Are-Belong-To-Us/libmicrofido2/blob/bb3678d0ba02f4762fc2eea19a956f4b5342e706/include/info.h#L23-L29), the string version at the top of the [`info.c`](https://github.com/All-Your-Locks-Are-Belong-To-Us/libmicrofido2/blob/bb3678d0ba02f4762fc2eea19a956f4b5342e706/src/info.c#L23-L28) and the parsing to the [`cbor_info_decode_extensions`](https://github.com/All-Your-Locks-Are-Belong-To-Us/libmicrofido2/blob/bb3678d0ba02f4762fc2eea19a956f4b5342e706/src/info.c#L123-L150) function.
+
+The procedure for adding parsing support of other cryptographic algorithms, transports, etc. is similar.
+
+## Adding a new command
+
+The structure when adding a new command is fairly simple.
+
+1. You'll have a function called like your commmand, [`fido_dev_get_assert`](https://github.com/All-Your-Locks-Are-Belong-To-Us/libmicrofido2/blob/bb3678d0ba02f4762fc2eea19a956f4b5342e706/src/assertion.c#L351).
+1. This function can perform some input validation and finally call a `wait` function, [`fido_dev_get_assert_wait`](https://github.com/All-Your-Locks-Are-Belong-To-Us/libmicrofido2/blob/bb3678d0ba02f4762fc2eea19a956f4b5342e706/src/assertion.c#L322).
+1. The `wait` function first calls the corresponding `tx` function to send the command to the authenticator ([`fido_dev_get_assert_tx`](https://github.com/All-Your-Locks-Are-Belong-To-Us/libmicrofido2/blob/bb3678d0ba02f4762fc2eea19a956f4b5342e706/src/assertion.c#L244)) and the `rx` function afterward to receive the response ([`fido_dev_get_assert_rx`](https://github.com/All-Your-Locks-Are-Belong-To-Us/libmicrofido2/blob/bb3678d0ba02f4762fc2eea19a956f4b5342e706/src/assertion.c#L290)).
+1. The receiving function will then parse the CBOR encoded data and write the result into a stack-allocatable structure.

README.md

@@ -1,10 +1,31 @@
 # libmicrofido2 - Minimal FIDO2 Library for Microcontrollers
 
-The **libmicrofido2** is a minimal FIDO2 library that is designed to be used in microcontrollers.
+**libmicrofido2** is a minimal FIDO2 library that is designed to be used in microcontrollers.
 It is heavily inspired by the [`libfido2`](https://github.com/Yubico/libfido2) and aims to have a similar API.
 
+It features:
+
+- **No heap allocations**: All structures are allocated on the stack.
+- **Physical layer agnostic**: The transport layer is left mostly to the user, so regardless of whether you want to use USB, NFC, or any other technology you can use this library. While we implemented the base layer for NFC, this can be easily implemented for other physical layers as well.
+- **Fully customizable cryptographic algorithms**: All of the cryptographic algorithms (Ed25519, AES GCM, SHA256, SHA512) can be replaced by the user entirely to enable hardware acceleration (see <examples/nrf52/hw_crypto/hw_crypto.c>).
+- **Simplicity**: In under 2000 lines of code, this library implements the minimal subset for a FIDO2 relying party on microcontrollers.
+
+## Limitations
+
+- Random Number Generation is currently not implemented. (#42)
+- The large blob currently cannot be written. (#43)
+- Only a minimal subset of the CTAP 2.1 commands are supported (`authenticatorGetInfo`, `authenticatorLargeBlobs`, `authenticatorGetAssertion`).
+- Only a minimal subset of cryptographic algorithms specified in the FIDO2 standard supported.
+- Variable length fields and fields with arbitrary values (like the extension field in `authenticatorGetInfo`) are not supported. Instead, these fields are parsed into statically allocatable structures (see [`info.h`](include/info.h) and [`info.c`](src/info.c) for examples of this).
+
 ## Building
 
+Building the library depends on the framework you use for your microcontroller.
+We provide examples for the [ESP-32 using ESP-IDF](examples/esp32) and the [nRF52 using Zephyr](examples/nrf52/).
+
+In case you only want to build a static library and use that later for linking, proceed as follows.
+Use one of the provided toolchain files (currently only for the ATmega, see #37).
+
 You need to install `cmake >= 3.10`. Having done that you can do:
 
 ```bash
@@ -15,6 +36,17 @@ cmake .. -DCMAKE_VERBOSE_MAKEFILE=1 -DCMAKE_TOOLCHAIN_FILE=../avr.toolchain -DCM
 cmake .. -DCMAKE_VERBOSE_MAKEFILE=1 -DCMAKE_TOOLCHAIN_FILE=../avr.toolchain -DCMAKE_BUILD_TYPE=Release
 ```
 
+## Usage
+
+We provide fairly extensive examples of using this library in the [examples](examples/) directory.
+Most of the time, you'll only need to [`#include <fido.h>`](include/fido.h) as that file includes most of the others.
+In case you want to overwrite the implementation of the cryptographic algorithms, also checkout the [`crypto.h`](include/crypto.h) file.
+
+## Development
+
+We are happy to receive any PRs that further improve this library.
+In case you want to modify the library for your needs, checkout [`DEVELOPMENT.md`](DEVELOPMENT.md).
+
 ## Acknowledgements
 
 This library uses code from: