From 233fbcdb380ec11d1b4f3dcfbd0c72618c861778 Mon Sep 17 00:00:00 2001
From: PeterKietzmann <peter.kietzmann@haw-hamburg.de>
Date: Thu, 9 Jul 2020 14:48:53 +0200
Subject: [PATCH] sys/random: improve documentation on SHA based generator

---
 sys/random/doc.txt    | 32 ++++++++++++++++++++++++++++++++
 sys/random/shaxprng.c |  8 ++------
 2 files changed, 34 insertions(+), 6 deletions(-)
 create mode 100644 sys/random/doc.txt

diff --git a/sys/random/doc.txt b/sys/random/doc.txt
new file mode 100644
index 0000000000..216d9d7cad
--- /dev/null
+++ b/sys/random/doc.txt
@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2020 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @defgroup    sys_random_shaxprng SHAX random number generator
+ * @ingroup     sys_random
+ *
+ * @brief   SHA based random number generator implementation(CSPRNG).
+ *
+ * The generator bases on an internal structure that has been presented in
+ * FIPS 186-1 Appendix 3.2, which is why it is sometimes named as "DSA PRNG" or
+ * "FIPS PRNG" in the literature. Outputs are generated by hashing the internal
+ * generator state, and the feedback path applies a linear transformation to the
+ * state which is hashed again to create further next outputs. Thus, a potential
+ * state compromise may allow recovering preceding generator outputs, because
+ * linear operations in the feedback path are invertible. Thereby, this generator
+ * gets along with a single hash computation per block which makes the generator
+ *  lightweight in comparison to more advanced CSPRNGs.
+ *
+ * This implementation can be run with the SHA-1 or SHA-256 hash function
+ * for creating outputs. SHA-1 has been deprecated by NIST in 2011 due to
+ * a collision- and potential brute-force attack. Thus, SHA-256 can be used as
+ * an alternative. To select one or the other, export
+ * `USEMODULE += prng_sha1prng` or
+ * `USEMODULE += prng_sha256prng`
+ * during compilation.
+ */
\ No newline at end of file
diff --git a/sys/random/shaxprng.c b/sys/random/shaxprng.c
index cdfbd9652c..e3808c899f 100644
--- a/sys/random/shaxprng.c
+++ b/sys/random/shaxprng.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2018 HAW Hamburg
+ * Copyright (C) 2018, 2020 HAW Hamburg
  *
  * This file is subject to the terms and conditions of the GNU Lesser
  * General Public License v2.1. See the file LICENSE in the top level
@@ -10,14 +10,10 @@
  */
 
  /**
- * @ingroup sys_random
+ * @ingroup sys_random_shaxprng
  * @{
  * @file
  *
- * @brief   SHA based PRNG random number generator implementation
- *
- * BLABLA
- *
  * @author Peter Kietzmann <peter.kietzmann@haw-hamburg.de>
  * @}
  */