Docs: Rework all Documentation

CONTRIBUTION.md

@@ -10,15 +10,16 @@ Your coding style should follow the [official rust style guide](https://doc.rust
 
 ## Error Handling
 
-* Errors should, when available be wrapped with `CalError` before returning. 
-    * Make use of `CalErrorKind` categories. 
-    * The source error should be wrapped into an `anyhow::Error` and be set as source.
-    * Errors should be logged with `tracing::error!()` right where they are first seen.
-    * Structured logging should always be preffered: `tracing::error!(error=the_error_Im_logging, "My error message")` ✔️
-    * Do not log `CalError` as debug print: `tracing::error!("{:?}", the_error_Im_logging)` ❌
-    * Consider using `#[tracing::instrument(level = "trace")]` for complex functions.
-    * Consider using `#[tracing::instrument]` for important functions, like `delete()`.
-    * **Never log secrets!**. Skip secrets: `#[instrument(skip(secret1, secret2))]` or `#[instrument(skip_all)]`
+* Errors:
+  * Prefer structured errors (nested enums).
+  * Prefer one structured error per logical unit (function / module).
+  * Errors should not be generic (anyhow, eyre), but rather specific, structured and parsable.
+* Logging:
+  * Prefer structured logging: `tracing::error!(error=the_error_Im_logging, "My error message")` ✔️
+  * Do not log errors as debug print: `tracing::error!("{:?}", the_error_Im_logging)` ❌
+  * Consider using `#[tracing::instrument(level = "trace")]` for complex functions.
+  * Consider using `#[tracing::instrument]` for important functions, like `delete()`.
+  * **Never log secrets!**. Skip secrets: `#[instrument(skip(secret1, secret2))]` or `#[instrument(skip_all)]`
 
 
 ## Commits
@@ -28,7 +29,7 @@ Commits must follow [Conventional Commits](https://www.conventionalcommits.org/e
 
 ## Branch Names
 
-Branch names must adhere to the following schme: `the-operation/the-thing-being-worked-on`
+Branch names must adhere to the following scheme: `the-operation/the-thing-being-worked-on`
 
 ```
 feature/structured-error-logging
@@ -40,7 +41,7 @@ fix/program-crash-on-second-provider-creation
 
 ## Pull Requests
 
-A PR should have a good description of what has been added, changed and removed. Examples might be usefull.
+A PR should have a good description of what has been added, changed and removed. Examples might be useful.
 
 Before merging a PR go over the [checklist](.github/PULL_REQUEST_TEMPLATE/default.md).
 
@@ -54,5 +55,5 @@ The examples should cover the core use cases of the library.
 
 ### README
 
-The README of the subprojects should describe how to build and test the subprojects.
+The README of the subprojekts should describe how to build and test the subprojekts.
 

Cargo.toml

@@ -105,3 +105,7 @@ test-case = "3.3.1"
 tempfile = "3.15.0"
 lazy_static = "1.5.0"
 rstest = "0.25.0"
+
+[package.metadata.docs.rs]
+features = []
+rustdoc-args = ["--cfg", "docsrs"]

README.md

@@ -6,36 +6,34 @@
 
 </div>
 
-> [!WARNING]
+> [!CAUTION]
 > Work in Progress
 
-> [!WARNING]
-> Might not compile on `x86_64-pc-windows-gnu`.
-
 Crypto Layer is a comprehensive and flexible cryptographic library designed to provide a unified interface for various cryptographic operations and algorithms.
 It offers a wide range of functionalities, including encryption, decryption, signing, signature verification, and hashing, while supporting both symmetric and asymmetric cryptography.
 
 
 ## Features
 
+> [!NOTE]
+> Support for specific algorithms and features is dependent on the target platform.
+
 - **Encryption Algorithms**: Supports a variety of encryption algorithms, including:
 
   - Asymmetric Encryption: RSA, ECC (Elliptic Curve Cryptography) with various curve types (P-256, P-384, P-521, secp256k1, Brainpool curves, Curve25519, Curve448, FRP256v1)
   - Symmetric Block Ciphers: AES (GCM, CBC)
   - Stream Ciphers: ChaCha20, XChaCha20
 
-
 - **Hashing Algorithms**: Supports a wide range of hashing algorithms, including:
 
   - SHA-2 (SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, SHA-512/256)
   - SHA-3 (SHA3-224, SHA3-256, SHA3-384, SHA3-512)
 
-
 - **Key Management**: Provides a unified interface for creating, loading, and managing cryptographic keys, supporting various key usages and algorithms.
 
 - **Cross-Platform Support**: Designed to work seamlessly across multiple platforms, including Android, Apple, Linux and Windows, with platform-specific implementations for key handling and security module integration.
 
-- **Security Module Integration**: Integrates with Hardware Security Modules (HSMs) and Trusted Platform Modules (TPMs) for secure key storage and cryptographic operations, ensuring enhanced security and compliance with industry standards.
+- **Security Module Integration**: Integrates with ~~Hardware Security Modules (HSMs) and~~ Trusted Platform Modules (TPMs) for secure key storage and cryptographic operations, ensuring enhanced security and compliance with industry standards.
 
 - **Extensibility**: The modular design of the Crypto Layer allows for easy extension and integration of additional cryptographic algorithms and security modules in the future.
 
@@ -57,7 +55,6 @@ classDiagram
     Provider "1" --> "0..*" KeyHandle : manages
     Provider "1" --> "0..*" KeyPairHandle : manages
     Provider "1" --> "0..*" DHExchange : creates ephemeral
-    KeyPairHandle "1" --> "1" DHExchange : creates
     DHExchange "1" --> "1" KeyHandle : results in
 
     class Provider {
@@ -130,16 +127,60 @@ Examples for the rust crate can be found in the [example folder](./examples/).
 
 ### [Usage Flutter Plugin](./flutter_plugin/README.md)
 
-### [Example Flutter App integration](./flutter_app/README.md)
+### [Example Flutter App](./flutter_app/README.md)
 
 ### [Usage NodeJS Plugin](https://github.com/nmshd/crypto-layer-node)
 
+## Documentation
+
+### Build Documentation
+
+To build the documentation run:
+```sh
+RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc  --open
+```
+Or in Powershell:
+```sh
+$env:RUSTDOCFLAGS="--cfg docsrs"
+cargo +nightly doc  --open
+```
+
+Or if you have [task](https://taskfile.dev/) installed, run:
+```sh
+task build-documentation
+```
 
 ## Contributing
 
 Contributions to the Crypto Layer are welcome!
 If you find any issues or have suggestions for improvements, please open an issue or submit a pull request on the project's GitHub repository.
 
+## Development
+
+### Taskfile
+
+Many of the necessary workflows are automated with [task](https://taskfile.dev/).
+See the [Taskfile](./Taskfile.yml).
+
+Useful commands are:
+```sh
+# Test crypto layer with the software provider:
+task testrs
+
+# Install TS and dart dependencies:
+task pre
+
+# Generate ts types.
+task gents tests
+
+# Generate dart bindings
+task gendt testdt
+
+# Generate docs
+task bdoc
+```
+
+
 
 ## License
 

Taskfile.yml

@@ -18,11 +18,11 @@ tasks:
       - npm run prepare
 
   prerequisites-dt:
-      aliases: [predt]
-      desc: Installs dart dependencies.
-      dir: ./cal_flutter_plugin/
-      cmds:
-        - dart pub get
+    aliases: [predt]
+    desc: Installs dart dependencies.
+    dir: ./cal_flutter_plugin/
+    cmds:
+      - dart pub get
 
   generate:
     desc: Generates ts types and dart bindings.
@@ -44,7 +44,7 @@ tasks:
     dir: ./cal_flutter_plugin/
     cmds:
       - flutter_rust_bridge_codegen generate --rust-preamble "use std::future::Future; use std::pin::Pin; use crypto_layer::common::config::DynFuture;"
-     # - flutter pub run build_runner build
+      # - flutter pub run build_runner build
 
   test:
     desc: Execute non interactive tests.
@@ -87,3 +87,11 @@ tasks:
     dir: ./flutter_app/
     cmds:
       - flutter test integration_test/cal_test.dart
+
+  build-documentation:
+    desc: Build the documentation of crypto-layer
+    aliases: [bdoc]
+    env:
+      RUSTDOCFLAGS: --cfg docsrs
+    cmds:
+      - cargo +nightly doc

cSpell.json

@@ -1,5 +1,7 @@
 {
     "words": [
+        "androideabi",
+        "armv",
         "arrayref",
         "asym",
         "blake",
@@ -9,14 +11,18 @@
         "chacha",
         "ciphertext",
         "codegen",
+        "Cryptoki",
         "dalek",
+        "DEVICEID",
         "Diffie",
+        "docsrs",
         "ecdh",
         "Ecdsa",
         "esapi",
         "github",
         "hcvault",
         "hmac",
+        "initializable",
         "Itertools",
         "jalgorithm",
         "javax",
@@ -27,7 +33,9 @@
         "libloading",
         "libsodium",
         "nmshd",
+        "Ocsp",
         "pkcs",
+        "Pkix",
         "pwsh",
         "qufiwefefwoyn",
         "redb",
@@ -37,16 +45,23 @@
         "robusta",
         "rstest",
         "rusqlite",
+        "rustdoc",
+        "RUSTDOCFLAGS",
         "rustup",
+        "sdkmanager",
+        "secp",
+        "Secp",
         "securestore",
         "serde",
+        "simctl",
         "sodiumoxide",
         "sqlite",
         "Sqlite",
         "Swatinem",
         "Taskfile",
         "thiserror",
         "typia",
+        "xcrun",
         "yubi",
         "yubikey",
         "zeroize",

cal_flutter_plugin/README.md

@@ -1,26 +1,40 @@
-# cal_flutter_plugin
+# `cal_flutter_plugin`
 
-A new Flutter FFI plugin project.
-
-## Getting Started
-
-This project is a starting point for a Flutter
-[FFI plugin](https://flutter.dev/to/ffi-package),
-a specialized package that includes native code directly invoked with Dart FFI.
+Flutter FFI plugin for the crypto layer project.
 
 ## Project structure
 
-This template uses the following structure:
-
-* `src`: Contains the native source code, and a CmakeFile.txt file for building
-  that source code into a dynamic library.
+This project has the following structure:
 
 * `lib`: Contains the Dart code that defines the API of the plugin, and which
   calls into the native code using `dart:ffi`.
 
 * platform folders (`android`, `ios`, `windows`, etc.): Contains the build files
   for building and bundling the native code library with the platform application.
 
+
+## Binding to native code
+
+To use the native code, bindings in Dart are needed.
+To avoid writing these by hand, they are generated from the header file
+(`src/cal_flutter_plugin.h`) by `package:ffigen`.
+Regenerate the bindings by running `dart run ffigen --config ffigen.yaml`.
+
+
+## Reading logs
+
+Crypto-layer uses structured logging. See the [tracing documentation](https://docs.rs/tracing/latest/tracing/#spans).
+
+### IOS Emulator
+
+On apple platforms spans are logged as activities.
+
+To read logs and activities from the command line, you may use `xcrun` with `grep`:
+```sh
+xcrun simctl spawn booted log stream -level debug | grep -E "cal\_flutter\_plugin|eu\.nmshd\.crypto\-layer"
+```
+
+
 ## Building and bundling native code
 
 The `pubspec.yaml` specifies FFI plugins as follows:
@@ -68,13 +82,6 @@ The native build systems that are invoked by FFI (and method channel) plugins ar
   * See the documentation in linux/CMakeLists.txt.
   * See the documentation in windows/CMakeLists.txt.
 
-## Binding to native code
-
-To use the native code, bindings in Dart are needed.
-To avoid writing these by hand, they are generated from the header file
-(`src/cal_flutter_plugin.h`) by `package:ffigen`.
-Regenerate the bindings by running `dart run ffigen --config ffigen.yaml`.
-
 ## Invoking native code
 
 Very short-running native functions can be directly invoked from any isolate.