Describe architecture

ARCHITECTURE.md

@@ -0,0 +1,63 @@
+# Architectural considerations for embedded-cal
+
+This document describes the architecture of embedded-cal.
+As of now, this consists of design considerations, boundary conditions and requirements:
+In the course of the implementation, those will be step in the background of a description of the full architecture.
+
+## Design considerations and requirements
+
+The main contributions in this project are
+
+* an interface towards cryptographic primitives that is easy to use safely on constrained systems
+* implementations of the interface ("backends") that can be combined:
+  * a formally verified implementation of the supported algorithms, and
+  * hardware accelerated implementations for some microcontrollers.
+
+The provided implementations are not exhaustive:
+A goal of the project is to encourage the development of implementations on a large variety of hardware backends.
+
+### Requirements and optional features
+
+Features being optional means that it is unsure whether embedded-cal can or should imlement them in a first iteration.
+At any rate, a provider of cryptographic primitives can offer any subset of them.
+
+* Usable with `no_std`
+    * No arbitrary size limits: If any constraints are technically necessary, they need to be easy to tune.
+* Provides access to cryptographic primitives:
+    * AEAD with streaming AAD
+    * ECDSA with streaming AAD
+    * ECDH
+    * Hashes
+    * HKDF
+    * HPKE (optional)
+    * Other post-quantum mechanism (optional)
+    * Symmetric encryption (optional; may be covered through AEAD if interfaces lean the COSE direction)
+    * Random number generation
+* Provides access to low-level cryptographic operations:
+    * Individual AES operations
+    * ECC coordinate operations (addition, multiplication etc.)
+    * These operations may be of limited visibility compared to the remaining public API for stability reasons.
+* Algorithm agility: Interfaces are algorithm generic at runtime.
+    * Implementations provide associated types that express supported algorithms.
+      These types avoid some misuse types (mixed use),
+      fully parametrize the algorithms,
+      and focus the error handling needed at runtime to well-understood spots.
+    * Algorithm agility can be disabled in the type system by a back-end that provides just a single algorithm of a type and employs a ZST algorithm marker associated type. (optional)
+    * Algorithms can be queried by COSE identifiers (required) or other established identifiers such as TLS (optional)
+* Secret protection:
+    * Keys are expressed using per-backend types that ensure that only matching operations are performed.
+    * Backends can use references to keys and thus not create them in memory.
+    * Secrets handled by the library are handled though zeroizing or similar interfaces.
+* Instances are accessed through an exclusive reference.
+    * A wrapper generic over a Mutex provides shared access (optional)
+* It can provide the required cryptographic operations for
+    * EDHOC (Lakers)
+    * OSCORE (libOSCORE)
+    * SUIT (as to be used in Ariel OS)
+    * TLS (no concrete implementation planned)
+
+Providing high-level COSE operations is an optional goal outside of the immediate scope of the trait.
+
+### Usage
+
+k