Add test descriptions as code comment in security core tests

Signed-off-by: Dennis Potman <dennis.potman@adlinktech.com>

src/security/core/tests/access_control.c

@@ -153,6 +153,10 @@ CU_TheoryDataPoints(ddssec_access_control, config_parameters_file) = {
     CU_DataPoints(bool,         true,   true,     true,    true,     true,   true,   true,  true,   true,  true,   true,   false,  false, false),   // include empty config elements
     CU_DataPoints(bool,         false,  true,     true,    true,     true,   true,   true,  true,   false, true,   false,  true,   true,  true)     // expect failure
 };
+/* Testing configuration parameters for the access control security plugin,
+   using configuration from file. The test cases include using non-existing
+   files, empty configuration files, mixing configudation from file and inline
+   in the cyclone XML configuration. */
 CU_Theory((const char * test_descr, const char * gov, const char * perm, const char * ca, bool incl_empty_els, bool exp_fail),
     ddssec_access_control, config_parameters_file)
 {
@@ -198,6 +202,9 @@ CU_TheoryDataPoints(ddssec_access_control, permissions_expiry) = {
 #undef D
 #undef H
 #undef M
+/* Testing expiry of the (signed) permissions XML. Test cases include using
+   permissions config that is valid for 1 minute, was valid in the past minute,
+   expires before data is written, expires during writing data. */
 CU_Theory(
   (const char * test_descr,
     int32_t perm1_not_before, int32_t perm1_not_after, int32_t perm2_not_before, int32_t perm2_not_after,
@@ -254,6 +261,9 @@ CU_Theory(
 #define N_WR 3
 #define N_NODES (N_RD + N_WR)
 #define PERM_EXP_BASE 3
+/* Tests permissions configuration expiry using multiple writers, to validate
+   that a reader still received data from writers that still have valid
+   permissions config */
 CU_Test(ddssec_access_control, permissions_expiry_multiple, .timeout=20)
 {
   char topic_name[100];
@@ -419,7 +429,10 @@ CU_TheoryDataPoints(ddssec_access_control, hooks) = {
     CU_DataPoints(bool, na,    na,    na,    false, na,    true,  true,  true,  true,  false, false),  // exp_rd_wr_sync_fail
 };
 #undef na
-
+/* Test that the security implementation in DDSI is correctly handling denial of
+   creating enities, e.g. local participant not allowed, local writer not allowed,
+   remote topic not allowed, etc. This test is initializing the wrapper plugin in a
+   not-allowed mode to force denial of a specified entity. */
 CU_Theory(
   (const char * init_fn, bool exp_pp_fail, bool exp_local_topic_fail, bool exp_remote_topic_fail, bool exp_wr_fail, bool exp_rd_fail, bool exp_wr_rd_sync_fail, bool exp_rd_wr_sync_fail),
   ddssec_access_control, hooks, .timeout=60)
@@ -493,6 +506,8 @@ CU_TheoryDataPoints(ddssec_access_control, join_access_control) = {
     CU_DataPoints(bool, false, false, false, na,    na),   /* expect handshake failure */
 };
 #undef na
+/* Testing handshake result using join access control setting enabled/disabled and
+   valid/invalid permissions for 2 participants. */
 CU_Theory(
   (const char * test_descr, bool join_ac_pp1, bool join_ac_pp2, bool perm_inv_pp1, bool perm_inv_pp2, bool exp_pp1_fail, bool exp_pp2_fail, bool exp_hs_fail),
   ddssec_access_control, join_access_control, .timeout=30)
@@ -627,7 +642,9 @@ static void test_discovery_liveliness_protection(enum test_discovery_liveliness
 
   access_control_fini (2, (void * []) { gov_config1, gov_config2, gov_topic_rule1, gov_topic_rule2, grants[0], grants[1], perm_config, ca, id1_subj, id2_subj, id1, id2 }, 12);
 }
-
+/* Testing discovery and liveliness protection by checking that encode_datawriter_submessage
+   is called for SEDP_BUILTIN_PUBLICATIONS_SECURE_WRITER and/or P2P_BUILTIN_PARTICIPANT_MESSAGE_SECURE_WRITER
+   depending on the discovery and liveliness protection settings in security configuration. */
 CU_Theory(
   (const char * test_descr, bool enable_discovery_protection_pp1, bool enable_discovery_protection_pp2,
     DDS_Security_ProtectionKind discovery_protection_kind_pp1, DDS_Security_ProtectionKind discovery_protection_kind_pp2,
@@ -697,6 +714,9 @@ static void test_encoding_mismatch(
   access_control_fini (2, (void * []) { gov_config1, gov_config2, gov_topic_rule1, gov_topic_rule2, grants[0], grants[1], perm_config, ca, id1_subj, id2_subj, id1, id2 }, 12);
 }
 
+/* Testing handshake result for any combination of protection kind values for rtps, discovery,
+   liveliness, metadata (submsg) and payload encoding. In all cases where there is an encoding
+   mismatch, the security handshake is expect to fail */
 static DDS_Security_ProtectionKind pk[] = { PK_N, PK_S, PK_E, PK_SOA, PK_EOA };
 static DDS_Security_BasicProtectionKind bpk[] = { BPK_N, BPK_S, BPK_E };
 
@@ -787,7 +807,9 @@ static void test_readwrite_protection (
 
   access_control_fini (2, (void * []) { gov_config, gov_topic_rule, rules_xml, grants[0], grants[1], perm_config, ca, id1_subj, id2_subj, id1, id2 }, 11);
 }
-
+/* Test read/write access control by running test cases with different combinations
+   of allow and deny rules for publishing and subscribing on a topic, and check correct
+   working of the default policy. */
 CU_Test(ddssec_access_control, readwrite_protection, .timeout=60)
 {
   for (int allow_pub = 0; allow_pub <= 1; allow_pub++)
@@ -815,7 +837,8 @@ CU_Test(ddssec_access_control, readwrite_protection, .timeout=60)
               }
 }
 
-
+/* Test that all attributes and token retrieved from the access control plugin
+   are correctly returned. */
 CU_Test(ddssec_access_control, check_returns)
 {
   char topic_name[100];
@@ -858,7 +881,8 @@ CU_Test(ddssec_access_control, check_returns)
   access_control_fini (2, (void * []) { gov_config, gov_topic_rule, grants[0], grants[1], perm_config, ca, id1_subj, id2_subj, id1, id2 }, 10);
 }
 
-
+/* Check that communication for a topic that is allowed in the permissions config
+   keeps working in case the publisher also creates a writer for a non-allowed topic */
 CU_Test(ddssec_access_control, denied_topic)
 {
   char topic_name[100], denied_topic_name[100];

src/security/core/tests/authentication.c

@@ -183,7 +183,9 @@ CU_TheoryDataPoints(ddssec_authentication, id_ca_certs) = {
 };
 #undef FM_CA
 #undef FM_INVK
-
+/* Test the security handshake result in test-cases using identity CA's that match and do not
+   match (i.e. a different CA that was not used for creating the identity) the identities used
+   in the participants security configuration. */
 CU_Theory((const char * test_descr, const char * id2, const char *key2, const char *ca2,
     bool exp_fail_pp1, bool exp_fail_pp2,
     bool exp_fail_local, const char * fail_local_msg,
@@ -218,6 +220,8 @@ CU_TheoryDataPoints(ddssec_authentication, trusted_ca_dir) = {
     CU_DataPoints(const char *, "",    ".",   "/nonexisting", NULL),
     CU_DataPoints(bool,         false, false, true,           false)
 };
+/* Test correct and incorrect values for the trusted CA directory in the
+   authentication plugin configuration */
 CU_Theory((const char * ca_dir, bool exp_fail), ddssec_authentication, trusted_ca_dir)
 {
   print_test_msg ("Testing custom CA dir: %s\n", ca_dir);
@@ -259,6 +263,9 @@ CU_TheoryDataPoints(ddssec_authentication, expired_cert) = {
     CU_DataPoints(uint32_t,  1,     0,     0,     0,     1,     0,     1,     10000 ),  /* write/read data during x ms */
     CU_DataPoints(bool,      false, false, false, false, false, false, false, true  ),  /* expect read data failure */
 };
+/* Test the security handshake result and check communication for scenarios using
+   valid identities, identities that are expired and identities that are not yet valid.
+   A test case using an identity that expires during the test is also included. */
 CU_Theory(
   (const char * test_descr, int32_t ca_not_before, int32_t ca_not_after,
     int32_t id1_not_before, int32_t id1_not_after, bool id1_local_fail,
@@ -300,7 +307,10 @@ CU_Theory(
 #undef H
 #undef M
 
-
+/* Test communication for a non-secure participant with a secure participant that
+   allows unauthenticated nodes in its governance configuration. Samples for a secured
+   topic should not be received by a reader in the non-secure participant; samples for
+   a non-secure topic should. */
 CU_Test(ddssec_authentication, unauthenticated_pp)
 {
   char topic_name_secure[100];

src/security/core/tests/crypto.c

@@ -125,6 +125,10 @@ CU_TheoryDataPoints(ddssec_crypto, inject_plain_data) = {
     CU_DataPoints(DDS_Security_ProtectionKind,      PK_N,  PK_N,  PK_E,  PK_S,  PK_N,  PK_N),   /* submessage protection */
     CU_DataPoints(DDS_Security_ProtectionKind,      PK_N,  PK_N,  PK_N,  PK_N,  PK_E,  PK_S),   /* rtps protection */
 };
+/* This test validates that non-encrypted data will not be received by a reader that has protection
+   enabled for rtps/submsg/payload. The test uses a crypto plugin wrapper mode that force the plugin
+   to write plain data in the encoded output buffer to DDSI, ignoring the security attributes for the
+   reader and writer. */
 CU_Theory((const char * test_descr, DDS_Security_BasicProtectionKind payload_pk, DDS_Security_ProtectionKind submsg_pk, DDS_Security_ProtectionKind rtps_pk),
   ddssec_crypto, inject_plain_data, .timeout=30)
 {

src/security/core/tests/handshake.c

@@ -105,6 +105,8 @@ static void handshake_fini(void)
   CU_ASSERT_EQUAL_FATAL (ret, DDS_RETCODE_OK);
 }
 
+/* Happy-day test for the security handshake, that tests succesfull handshake for
+   two participants using the same typical security settings. */
 CU_Test(ddssec_handshake, happy_day)
 {
   struct Handshake *hs_list;
@@ -129,6 +131,9 @@ CU_Test(ddssec_handshake, happy_day)
   handshake_fini ();
 }
 
+/* This test checks that all tokens that are sent to a remote participant are received
+   correctly by that participant and the token-data stored in the remote participant
+   is equal to the data in the token that was sent. */
 CU_Test(ddssec_handshake, check_tokens)
 {
   handshake_init (

src/security/core/tests/secure_communication.c

@@ -387,6 +387,8 @@ static void test_payload_secret(DDS_Security_ProtectionKind rtps_pk, DDS_Securit
   ddsrt_free (sample.text);
 }
 
+/* Test communication between 2 nodes for all combinations of RTPS, metadata (submsg)
+   and payload protection kinds using a single reader and writer */
 CU_Test(ddssec_secure_communication, protection_kinds, .timeout = 120)
 {
   DDS_Security_ProtectionKind rtps_pk[] = { PK_N, PK_S, PK_E };
@@ -404,6 +406,8 @@ CU_Test(ddssec_secure_communication, protection_kinds, .timeout = 120)
   }
 }
 
+/* Test communication between 2 nodes for all combinations of discovery and
+   liveliness protection kinds using a single reader and writer */
 CU_Test(ddssec_secure_communication, discovery_liveliness_protection, .timeout = 60)
 {
   DDS_Security_ProtectionKind discovery_pk[] = { PK_N, PK_S, PK_E };
@@ -417,6 +421,8 @@ CU_Test(ddssec_secure_communication, discovery_liveliness_protection, .timeout =
   }
 }
 
+/* Test that a specific character sequence from the plain data does not appear in
+   encrypted payload, submessage or rtps message when protection kind is ENCRYPT*/
 CU_Test(ddssec_secure_communication, check_encrypted_secret, .timeout = 60)
 {
   DDS_Security_ProtectionKind rtps_pk[] = { PK_N, PK_E, PK_EOA };
@@ -434,6 +440,8 @@ CU_Test(ddssec_secure_communication, check_encrypted_secret, .timeout = 60)
   }
 }
 
+/* Test communication with specific combinations payload and submsg protection
+   kinds for 1-3 domains, 1-3 participants per domain and 1-3 readers per participant */
 CU_TheoryDataPoints(ddssec_secure_communication, multiple_readers) = {
     CU_DataPoints(size_t, 1, 1, 1, 3), /* number of domains */
     CU_DataPoints(size_t, 1, 3, 1, 3), /* number of participants per domain */
@@ -452,6 +460,9 @@ CU_Theory((size_t n_dom, size_t n_pp, size_t n_rd), ddssec_secure_communication,
   }
 }
 
+/* Test communication with specific combinations payload and submsg protection
+   kinds for 1-2 domains, 1-3 participants per domain, 1-3 readers per participant
+   and 1-3 writers per participant */
 CU_TheoryDataPoints(ddssec_secure_communication, multiple_readers_writers) = {
     CU_DataPoints(size_t, 1, 1, 2), /* number of reader domains */
     CU_DataPoints(size_t, 1, 3, 3), /* number of readers per domain */