Added and fixed security protocols comments

Author: Mika Leppänen

source/Security/protocols/eap_tls_sec_prot/eap_tls_sec_prot.c

@@ -35,7 +35,7 @@
 
 #ifdef HAVE_WS
 
-#define TRACE_GROUP "eaptls_secp"
+#define TRACE_GROUP "eapt"
 
 typedef enum {
     EAP_TLS_STATE_INIT = SEC_STATE_INIT,
@@ -63,7 +63,7 @@ static const trickle_params_t eap_tls_trickle_params = {
     .Imin = 50,            /* 5000ms; ticks are 100ms */
     .Imax = 150,           /* 15000ms */
     .k = 0,                /* infinity - no consistency checking */
-    .TimerExpirations = 4  //TRICKLE_EXPIRATIONS_INFINITE
+    .TimerExpirations = 4
 };
 
 static uint16_t eap_tls_sec_prot_size(void);

source/Security/protocols/eap_tls_sec_prot/eap_tls_sec_prot.h

@@ -18,7 +18,29 @@
 #ifndef EAP_TLS_SEC_PROT_H_
 #define EAP_TLS_SEC_PROT_H_
 
+/*
+ * EAP-TLS security protocol. Specified in RFC 5216 and and Wi-SUN FANWG-FANTPS.
+ *
+ */
+
+/**
+ * eap_tls_supp_sec_prot_register register authenticator EAP-TLS protocol to KMP service
+ *
+ * \param service KMP service
+ *
+ * \return < 0 failure
+ * \return >= 0 success
+ */
 int8_t eap_tls_supp_sec_prot_register(kmp_service_t *service);
+
+/**
+ * eap_tls_auth_sec_prot_register register authenticator EAP-TLS protocol to KMP service
+ *
+ * \param service KMP service
+ *
+ * \return < 0 failure
+ * \return >= 0 success
+ */
 int8_t eap_tls_auth_sec_prot_register(kmp_service_t *service);
 
 #endif /* EAP_TLS_SEC_PROT_H_ */

source/Security/protocols/fwh_sec_prot/auth_fwh_sec_prot.c

@@ -38,7 +38,7 @@
 
 #ifdef HAVE_WS
 
-#define TRACE_GROUP "fwh_secp"
+#define TRACE_GROUP "afwh"
 
 typedef enum {
     FWH_STATE_INIT = SEC_STATE_INIT,
@@ -76,7 +76,7 @@ static const trickle_params_t fwh_trickle_params = {
     .Imin = 50,            /* 5000ms; ticks are 100ms */
     .Imax = 150,           /* 15000ms */
     .k = 0,                /* infinity - no consistency checking */
-    .TimerExpirations = 4  //TRICKLE_EXPIRATIONS_INFINITE
+    .TimerExpirations = 4
 };
 
 static uint16_t auth_fwh_sec_prot_size(void);

source/Security/protocols/fwh_sec_prot/auth_fwh_sec_prot.h

@@ -18,6 +18,20 @@
 #ifndef AUTH_FWH_SEC_PROT_H_
 #define AUTH_FWH_SEC_PROT_H_
 
+/*
+ * Authenticator Four Way Handshake (4WH) security protocol. 4WH protocol is
+ * specified in IEEE 802.11 and Wi-SUN FANWG-FANTPS.
+ *
+ */
+
+/**
+ * auth_fwh_sec_prot_register register authenticator 4WH protocol to KMP service
+ *
+ * \param service KMP service
+ *
+ * \return < 0 failure
+ * \return >= 0 success
+ */
 int8_t auth_fwh_sec_prot_register(kmp_service_t *service);
 
 #endif /* AUTH_FWH_SEC_PROT_H_ */

source/Security/protocols/fwh_sec_prot/supp_fwh_sec_prot.c

@@ -38,7 +38,7 @@
 
 #ifdef HAVE_WS
 
-#define TRACE_GROUP "fwh_secp"
+#define TRACE_GROUP "sfwh"
 
 typedef enum {
     FWH_STATE_INIT = SEC_STATE_INIT,
@@ -80,7 +80,7 @@ static const trickle_params_t fwh_trickle_params = {
     .Imin = 50,            /* 5000ms; ticks are 100ms */
     .Imax = 150,           /* 15000ms */
     .k = 0,                /* infinity - no consistency checking */
-    .TimerExpirations = 4  //TRICKLE_EXPIRATIONS_INFINITE
+    .TimerExpirations = 4
 };
 
 static uint16_t supp_fwh_sec_prot_size(void);

source/Security/protocols/fwh_sec_prot/supp_fwh_sec_prot.h

@@ -18,6 +18,20 @@
 #ifndef SUPP_FWH_SEC_PROT_H_
 #define SUPP_FWH_SEC_PROT_H_
 
+/*
+ * Supplicant Four Way Handshake (4WH) security protocol. 4WH protocol is
+ * specified in IEEE 802.11 and Wi-SUN FANWG-FANTPS.
+ *
+ */
+
+/**
+ * supp_fwh_sec_prot_register register supplicant 4WH protocol to KMP service
+ *
+ * \param service KMP service
+ *
+ * \return < 0 failure
+ * \return >= 0 success
+ */
 int8_t supp_fwh_sec_prot_register(kmp_service_t *service);
 
 #endif /* SUPP_FWH_SEC_PROT_H_ */

source/Security/protocols/gkh_sec_prot/gkh_sec_prot.c

@@ -35,7 +35,7 @@
 
 #ifdef HAVE_WS
 
-#define TRACE_GROUP "gkh_secp"
+#define TRACE_GROUP "cgkh"
 
 typedef enum {
     GKH_STATE_INIT = SEC_STATE_INIT,
@@ -64,7 +64,7 @@ static const trickle_params_t gkh_trickle_params = {
     .Imin = 50,            /* 5000ms; ticks are 100ms */
     .Imax = 150,           /* 15000ms */
     .k = 0,                /* infinity - no consistency checking */
-    .TimerExpirations = 4  //TRICKLE_EXPIRATIONS_INFINITE
+    .TimerExpirations = 4
 };
 
 static uint16_t gkh_sec_prot_size(void);

source/Security/protocols/gkh_sec_prot/gkh_sec_prot.h

@@ -18,7 +18,30 @@
 #ifndef GKH_SEC_PROT_H_
 #define GKH_SEC_PROT_H_
 
+/*
+ * Group Key Handshake (GKH) security protocol. GKH protocol is specified
+ * in IEEE 802.11 and Wi-SUN FANWG-FANTPS.
+ *
+ */
+
+/**
+ * gkh_supp_sec_prot_register register authenticator GKH protocol to KMP service
+ *
+ * \param service KMP service
+ *
+ * \return < 0 failure
+ * \return >= 0 success
+ */
 int8_t gkh_supp_sec_prot_register(kmp_service_t *service);
+
+/**
+ * gkh_auth_sec_prot_register register supplicant GKH protocol to KMP service
+ *
+ * \param service KMP service
+ *
+ * \return < 0 failure
+ * \return >= 0 success
+ */
 int8_t gkh_auth_sec_prot_register(kmp_service_t *service);
 
 #endif /* GKH_SEC_PROT_H_ */

source/Security/protocols/key_sec_prot/key_sec_prot.c

@@ -36,7 +36,7 @@
 
 #ifdef HAVE_WS
 
-#define TRACE_GROUP "key_secp"
+#define TRACE_GROUP "ksep"
 
 typedef enum {
     KEY_INIT = 0,

source/Security/protocols/key_sec_prot/key_sec_prot.h

@@ -18,6 +18,21 @@
 #ifndef KEY_SEC_PROT_H_
 #define KEY_SEC_PROT_H_
 
+/*
+ * EAPOL-Key security protocol. Protocol is used for sending and receiving
+ * initial EAPOL-Key message that is used to start the supplicant
+ * authentication. Specified in Wi-SUN FANWG-FANTPS.
+ *
+ */
+
+/**
+ * key_sec_prot_register register EAPOL-Key protocol to KMP service
+ *
+ * \param service KMP service
+ *
+ * \return < 0 failure
+ * \return >= 0 success
+ */
 int8_t key_sec_prot_register(kmp_service_t *service);
 
 #endif /* KEY_SEC_PROT_H_ */

source/Security/protocols/sec_prot.h

@@ -18,6 +18,15 @@
 #ifndef SEC_PROT_H_
 #define SEC_PROT_H_
 
+/*
+ * Interface between KMP API and key management security protocols. Interface
+ * provides abstraction for different security protocols for KMP API module.
+ *
+ * For security protocols it provides access to network, timing, callback
+ * security keys and network address services.
+ *
+ */
+
 typedef enum {
     SEC_RESULT_OK = 0,
     SEC_RESULT_ERR_NO_MEM = -1,
@@ -172,7 +181,6 @@ typedef void sec_prot_timer_timeout(sec_prot_t *prot, uint16_t ticks);
  */
 typedef void sec_prot_eui64_addr_get(sec_prot_t *prot, uint8_t *local_eui64, uint8_t *remote_eui64);
 
-
 // Security protocol data
 struct sec_prot_s {
     sec_prot_create_request       *create_req;           /**< Create request */
@@ -202,6 +210,4 @@ struct sec_prot_s {
     uint8_t                       data;                  /**< Protocol internal data */
 };
 
-
-
 #endif /* SEC_PROT_H_ */

source/Security/protocols/sec_prot_keys.c

@@ -29,7 +29,7 @@
 
 #ifdef HAVE_WS
 
-#define TRACE_GROUP "skeys"
+#define TRACE_GROUP "spke"
 
 sec_prot_keys_t *sec_prot_keys_create(sec_prot_gtk_keys_t *gtks)
 {

source/Security/protocols/sec_prot_keys.h

@@ -18,38 +18,87 @@
 #ifndef SEC_PROT_KEYS_H_
 #define SEC_PROT_KEYS_H_
 
+/*
+ * Security protocols Wi-Sun EAPOL key storage module. This is used by Wi-Sun EAPOL
+ * protocols to store and update key information.
+ *
+ */
+
 #define PMK_LEN       32
 #define PTK_LEN       48
 #define GTK_LEN       16
 
 #define PMKID_LEN     16
 
 typedef struct {
-    uint8_t             key[GTK_LEN];          /**< GTK (128 bits) */
+    uint8_t             key[GTK_LEN];          /**< Group Transient Key (128 bits) */
     uint32_t            lifetime;              /**< Lifetime is seconds */
-    uint8_t             set:1;                 /**< GTK set (valid value) */
-    uint8_t             live:1;                /**< GTK live (as indicated by authenticator) */
-    uint8_t             hash:1;                /**< GTK matches to hash */
+    uint8_t             set:1;                 /**< Group Transient Key set (valid value) */
+    uint8_t             live:1;                /**< Group Transient Key live (as indicated by authenticator) */
+    uint8_t             hash:1;                /**< Group Transient Key matches to hash */
 } gtk_key_t;
 
 typedef struct {
-    gtk_key_t           gtk[4];                /**< 4 GTKs */
+    gtk_key_t           gtk[4];                /**< 4 Group Transient Keys */
 } sec_prot_gtk_keys_t;
 
 // Security key data
 typedef struct {
-    uint64_t             pmk_key_replay_cnt;    /**< PMK key replay counter */
-    uint8_t              pmk[PMK_LEN];          /**< PMK (256 bits) */
-    uint8_t              ptk[PTK_LEN];          /**< PTK (384 bits) */
-    int8_t               gtk_set_index;         /**< GTK to insert */
-    sec_prot_gtk_keys_t  *gtks;                 /**< GTKs */
+    uint64_t             pmk_key_replay_cnt;    /**< Pairwise Master Key replay counter */
+    uint8_t              pmk[PMK_LEN];          /**< Pairwise Master Key (256 bits) */
+    uint8_t              ptk[PTK_LEN];          /**< Pairwise Transient key (384 bits) */
+    int8_t               gtk_set_index;         /**< Group Transient Key to insert */
+    sec_prot_gtk_keys_t  *gtks;                 /**< Group Transient Key */
 } sec_prot_keys_t;
 
+/**
+ * sec_prot_keys_create allocates memory for security keys
+ *
+ * \param gtks GTK keys
+ *
+ * \return security keys or NULL
+ */
 sec_prot_keys_t *sec_prot_keys_create(sec_prot_gtk_keys_t *gtks);
+
+/**
+ * sec_prot_keys_init initialises security keys
+ *
+ * \param sec_keys security keys
+ * \param gtks GTK keys
+ *
+ */
 void sec_prot_keys_init(sec_prot_keys_t *sec_keys, sec_prot_gtk_keys_t *gtks);
+
+/**
+ * sec_prot_keys_delete frees security keys memory
+ *
+ * \param sec_keys security keys
+ *
+ */
 void sec_prot_keys_delete(sec_prot_keys_t *sec_keys);
+
+/**
+ * sec_prot_keys_gtks_create allocates memory for GTK keys
+ *
+ * \return GTK keys or NULL
+ *
+ */
 sec_prot_gtk_keys_t *sec_prot_keys_gtks_create(void);
+
+/**
+ * sec_prot_keys_gtks_init initialises GTK keys
+ *
+ * \param gtks GTK keys
+ *
+ */
 void sec_prot_keys_gtks_init(sec_prot_gtk_keys_t *gtks);
+
+/**
+ * sec_prot_keys_gtks_delete frees GTK keys memory
+ *
+ * \param gtks GTK keys
+ *
+ */
 void sec_prot_keys_gtks_delete(sec_prot_gtk_keys_t *gtks);
 
 #endif /* SEC_PROT_KEYS_H_ */

source/Security/protocols/sec_prot_lib.c

@@ -40,7 +40,7 @@
 
 #ifdef HAVE_WS
 
-#define TRACE_GROUP "fwh_secp"
+#define TRACE_GROUP "secl"
 
 void sec_prot_init(sec_prot_common_t *data)
 {

source/Security/protocols/sec_prot_lib.h

@@ -18,6 +18,13 @@
 #ifndef SEC_PROT_LIB_H_
 #define SEC_PROT_LIB_H_
 
+/*
+ * Library functions used by security protocols. These include helper functions
+ * related to different hash functions, common message handling functions, and
+ * common timer and state machine functions.
+ *
+ */
+
 #define FWH_NONCE_LENGTH           32
 #define EUI64_LEN                  8