Merge pull request #11936 from pokgak/tinydtls-add-docs

pkg/tinydtls: documents usage and configuration options

pkg/tinydtls/doc.txt

@@ -4,4 +4,89 @@
  * @ingroup  net net_dtls
  * @brief    Provides the Eclipse TinyDTLS to RIOT
  * @see      https://projects.eclipse.org/projects/iot.tinydtls
+ *
+ * Usage
+ * -----
+ *
+ * Add as a package in the Makefile of your application:
+ *
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.mk}
+ * USEPKG += tinydtls
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * Supported Cipher Suites
+ * -----------------------
+ *
+ * TinyDTLS only has support for `TLS_PSK_WITH_AES_128_CCM_8` and
+ * `TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8`. To choose which cipher suite
+ * to use, add one of the following to your Makefile:
+ *
+ * For `TLS_PSK_WITH_AES_128_CCM_8` support (default):
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.mk}
+ * CFLAGS += -DDTLS_PSK
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * For `TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8` support:
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.mk}
+ * CFLAGS += -DDTLS_ECC
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  */
+
+/**
+ * @defgroup    tinydtls_config Tinydtls compile time configuration
+ * @ingroup     pkg_tinydtls config
+ * @brief       Provides compile-time configuration for tinydtls
+ *
+ * @{
+ */
+
+ /**
+ * @brief Adds support for TLS_PSK_WITH_AES_128_CCM_8 when defined
+ * @note  Activated by default if @ref DTLS_ECC is not defined
+ */
+#ifndef DTLS_PSK
+#define DTLS_PSK
+#endif
+
+/**
+ * @brief Adds support for TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 when defined
+ */
+#ifndef DTLS_ECC
+#define DTLS_ECC
+#endif
+
+/**
+ * @brief The maximum number of DTLS context at the same time
+ */
+#ifndef DTLS_CONTEXT_MAX
+#define DTLS_CONTEXT_MAX    (2)
+#endif
+
+ /**
+ * @brief The maximum number DTLS peers (i.e. sessions)
+ */
+#ifndef DTLS_PEER_MAX
+#define DTLS_PEER_MAX       (1)
+#endif
+
+ /**
+ * @brief The maximum number of concurrent DTLS handshakes
+ */
+#ifndef DTLS_HANDSHAKE_MAX
+#define DTLS_HANDSHAKE_MAX  (2)
+#endif
+
+ /**
+ * @brief The maximum number of concurrently used cipher keys
+ */
+#ifndef DTLS_SECURITY_MAX
+#define DTLS_SECURITY_MAX   (DTLS_HANDSHAKE_MAX + DTLS_PEER_MAX)
+#endif
+
+ /**
+ * @brief The maximum number of hash functions that can be used in parallel
+ */
+#ifndef DTLS_HASH_MAX
+#define DTLS_HASH_MAX       (3 * DTLS_PEER_MAX)
+#endif
+/** @} */