auth: minor documentation updates

Signed-off-by: Patrick McHardy <kaber@trash.net>

2 files changed, 26 insertions, 16 deletions

diff --git a/include/dect/auth.h b/include/dect/auth.h
index e7f055f..34b556b 100644
--- a/include/dect/auth.h
+++ b/include/dect/auth.h
@@ -17,8 +17,6 @@ extern "C" {
  */
 
 #define DECT_AUTH_KEY_LEN	16
-#define DECT_AUTH_RAND_LEN	8
-#define DECT_AUTH_RES_LEN	4
 #define DECT_CIPHER_KEY_LEN	8
 
 /**
diff --git a/src/auth.c b/src/auth.c
index f5b82fd..3f0ff07 100644
--- a/src/auth.c
+++ b/src/auth.c
@@ -27,7 +27,7 @@
 #include <utils.h>
 
 /**
- * dect_pin_to_ac - convert PIN to authentication code
+ * Convert PIN to authentication code
  *
  * @param pin		PIN code
  * @param ac		buffer to store authentication code
@@ -54,14 +54,16 @@ void dect_pin_to_ac(const char *pin, uint8_t *ac, unsigned int ac_len)
 EXPORT_SYMBOL(dect_pin_to_ac);
 
 /**
- * dect_auth_b1 - derive authentication key K from UAK/AC
+ * B1 process: derive authentication key K from UAK/AC
  *
  * @param val		user authentication key (UAK) or authentication code (AC)
  * @param len		length of UAK/AC
- * @param k		buffer to store authentication key of size DECT_AUTH_KEY_LEN
+ * @param k		buffer to store authentication key of size #DECT_AUTH_KEY_LEN
  *
  * Derive an authentication key from a user authentication key or an
  * authentication code.
+ *
+ * @sa ETSI EN 300 175-7 (Security Features), sections 4.5.2.1 and 4.5.2.2.
  */
 void dect_auth_b1(const uint8_t *val, unsigned int len, uint8_t *k)
 {
@@ -73,16 +75,18 @@ void dect_auth_b1(const uint8_t *val, unsigned int len, uint8_t *k)
 EXPORT_SYMBOL(dect_auth_b1);
 
 /**
- * dect_auth_b2 - derive authentication key K from UAK and UPI
+ * B2 process: derive authentication key K from UAK and UPI
  *
  * @param uak		user authentication key (UAK)
  * @param uak_len	length of UAK
  * @param upi		user personal identity (UPI)
  * @param upi_len	length of UPI
- * @param k		buffer to store authentication key of size DECT_AUTH_KEY_LEN
+ * @param k		buffer to store authentication key of size #DECT_AUTH_KEY_LEN
  *
  * Derive an authentication key from a user authentication key and an user
  * personal identity.
+ *
+ * @sa ETSI EN 300 175-7 (Security Features), sections 4.5.2.3.
  */
 void dect_auth_b2(const uint8_t *uak, unsigned int uak_len,
 		  const uint8_t *upi, unsigned int upi_len, uint8_t *k)
@@ -110,14 +114,16 @@ static void dect_auth_calc(const uint8_t *key, uint64_t val, uint8_t *e)
 }
 
 /**
- * dect_auth_a11 - derive authentication session key
+ * A11 process: derive authentication session key
  *
  * @param k		authentication key K
  * @param rs		random seed
- * @param ks		buffer to store session authentication key of size DECT_AUTH_KEY_LEN
+ * @param ks		buffer to store session authentication key of size #DECT_AUTH_KEY_LEN
  *
  * Derive the session authentication keys KS from the authentication key K
  * and random seed RS.
+ *
+ * @sa ETSI EN 300 175-7 (Security Features), sections 4.5.3.1 and 5.2.1.
  */
 void dect_auth_a11(const uint8_t *k, uint64_t rs, uint8_t *ks)
 {
@@ -126,15 +132,17 @@ void dect_auth_a11(const uint8_t *k, uint64_t rs, uint8_t *ks)
 EXPORT_SYMBOL(dect_auth_a11);
 
 /**
- * dect_auth_a12 - derive cipher key and authentication response
+ * A12 process: derive cipher key and authentication response
  *
  * @param ks		session authentication key KS
  * @param rand_f	FP random value
- * @param dck		buffer to store derived cipher key (DCK) of size DECT_CIPHER_KEY_LEN
+ * @param dck		buffer to store derived cipher key (DCK) of size #DECT_CIPHER_KEY_LEN
  * @param res1		buffer to store authentication response
  *
  * Derive the derived cipher key DCK and authentication response RES1 from the
  * session authentication key KS and the random value rand_f.
+ *
+ * @sa ETSI EN 300 175-7 (Security Features), sections 4.5.3.2 and 5.3.1.
  */
 void dect_auth_a12(const uint8_t *ks, uint64_t rand_f, uint8_t *dck, uint32_t *res1)
 {
@@ -142,19 +150,21 @@ void dect_auth_a12(const uint8_t *ks, uint64_t rand_f, uint8_t *dck, uint32_t *r
 
 	dect_auth_calc(ks, rand_f, e);
 	memcpy(dck, e + 4, DECT_CIPHER_KEY_LEN);
-	memcpy(res1, e + 12, DECT_AUTH_RES_LEN);
+	memcpy(res1, e + 12, sizeof(*res1));
 }
 EXPORT_SYMBOL(dect_auth_a12);
 
 /**
- * dect_auth_a21 - derive authentication session key
+ * A21 process: derive authentication session key
  *
  * @param k		authentication key K
  * @param rs		random seed
- * @param ks		buffer to store session authentication key of size DECT_AUTH_KEY_LEN
+ * @param ks		buffer to store session authentication key of size #DECT_AUTH_KEY_LEN
  *
  * Derive the session authentication keys KS' from the authentication key K
  * and random seed RS.
+ *
+ * @sa ETSI EN 300 175-7 (Security Features), sections 4.5.3.1 and 5.2.2.
  */
 void dect_auth_a21(const uint8_t *k, uint64_t rs, uint8_t *ks)
 {
@@ -167,7 +177,7 @@ void dect_auth_a21(const uint8_t *k, uint64_t rs, uint8_t *ks)
 EXPORT_SYMBOL(dect_auth_a21);
 
 /**
- * dect_auth_a22 - derive authentication response
+ * A22 process: derive authentication response
  *
  * @param ks		session authentication key KS'
  * @param rand_p	PP random value
@@ -175,13 +185,15 @@ EXPORT_SYMBOL(dect_auth_a21);
  *
  * Derive the authentication response RES2 from the session authentication
  * key KS' and the random value rand_p.
+ *
+ * @sa ETSI EN 300 175-7 (Security Features), sections 4.5.3.2 and 5.3.2.
  */
 void dect_auth_a22(const uint8_t *ks, uint64_t rand_p, uint32_t *res2)
 {
 	uint8_t e[DECT_AUTH_KEY_LEN];
 
 	dect_auth_calc(ks, rand_p, e);
-	memcpy(res2, e + 12, DECT_AUTH_RES_LEN);
+	memcpy(res2, e + 12, sizeof(*res2));
 }
 EXPORT_SYMBOL(dect_auth_a22);