From 2c83308ec2ad77888c021946f11318ac83b86cd1 Mon Sep 17 00:00:00 2001
From: chrysn <chrysn@fsfe.org>
Date: Thu, 6 Feb 2020 11:15:42 +0100
Subject: [PATCH] pkg/libcose: Add to documentation

---
 pkg/libcose/doc.txt | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 pkg/libcose/doc.txt

diff --git a/pkg/libcose/doc.txt b/pkg/libcose/doc.txt
new file mode 100644
index 0000000000..a9720cf982
--- /dev/null
+++ b/pkg/libcose/doc.txt
@@ -0,0 +1,45 @@
+/**
+ * @defgroup pkg_libcose  libcose for RIOT
+ * @ingroup  pkg
+ * @brief    Constrained node COSE library
+ * @see      https://github.com/bergzand/libcose
+ *
+ * Usage
+ * -----
+ *
+ * Add as a package in the Makefile of your application:
+ *
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.mk}
+ * USEPKG += libcose
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * The main consumers of libcose are other libraries or system components, for
+ * example @ref sys_suit "SUIT".
+ *
+ * The use of the library itself [is described in the libcose
+ * documentation](https://bergzand.github.io/libcose/), and some example code
+ * can be found in
+ * [`tests/pkg_libcose/`](https://github.com/RIOT-OS/RIOT/tree/master/tests/pkg_libcose).
+ *
+ * Backends
+ * --------
+ *
+ * The libcose library does not implement cryptographic algorithms itself, but
+ * fans that out to other libraries (which are pulled into the dependency tree
+ * as packages) and exposes a consistent interface for the
+ * operations they provide.
+ *
+ * Backends are selected by any of those pseudomodules:
+ *
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.mk}
+ * USEMODULE += libcose_crypt_hacl
+ * USEMODULE += libcose_crypt_monocypher
+ * USEMODULE += libcose_crypt_c25519
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * The selection of pseudomodules determines the available algorithms:
+ *
+ * * @ref pkg_hacl "HACL" and @ref pkg_monocypher "Monocypher" both provide ChaCha20-Poly1305 and Ed25519.
+ * * @ref pkg_c25519 "C25519" only provides the Ed25519 algorithm.
+ *
+ */