Add charon-tkm API documentation

diff --git a/src/charon-tkm/src/ees/ees_callbacks.h b/src/charon-tkm/src/ees/ees_callbacks.h
index f8598f238be2d795bfc6090df9ccf69df3948f85..b73dc6cb5821bbbef7cfb9e886c55ddc14f36069 100644 (file)
--- a/src/charon-tkm/src/ees/ees_callbacks.h
+++ b/src/charon-tkm/src/ees/ees_callbacks.h
@@ -14,6 +14,16 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-eescallbacks ees callbacks
+ * @{ @ingroup tkm
+ *
+ * ESP SA Event Service (EES) callbacks.
+ * The xfrm-proxy forwards acquire and expire events from the kernel to
+ * charon-tkm using the EES interface. Upon reception of an event the
+ * corresponding callback is executed.
+ */
+
 #ifndef EES_CALLBACKS_H_
 #define EES_CALLBACKS_H_
 
@@ -29,4 +39,4 @@ void charon_esa_expire(result_type *res, const sp_id_type sp_id,
                                           const esp_spi_type spi_rem, const protocol_type protocol,
                                           const expiry_flag_type hard);
 
-#endif /** EES_CALLBACKS_H_ */
+#endif /** EES_CALLBACKS_H_ @}*/

diff --git a/src/charon-tkm/src/ehandler/eh_callbacks.h b/src/charon-tkm/src/ehandler/eh_callbacks.h
index 1be924913435d3deb5cac432228c5f6d92cb511b..db325dcd266c42ea3761381961d12cbdaaf69cac 100644 (file)
--- a/src/charon-tkm/src/ehandler/eh_callbacks.h
+++ b/src/charon-tkm/src/ehandler/eh_callbacks.h
@@ -14,6 +14,15 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-ehandler exception handler
+ * @{ @ingroup tkm
+ *
+ * The exception handler callback is registered as global exception action in
+ * the Ada runtime. If an exception is raised in Ada code this callback is
+ * executed.
+ */
+
 #ifndef EH_CALLBACKS_H_
 #define EH_CALLBACKS_H_
 
@@ -22,4 +31,4 @@
  */
 void charon_terminate(char *msg);
 
-#endif /** EH_CALLBACKS_H_ */
+#endif /** EH_CALLBACKS_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm.h b/src/charon-tkm/src/tkm/tkm.h
index 9d559d9fc313fff6ff0c6ec6d311e142d2ce1f9b..7c711312b428d1c28ce721ed57b79ca3df4abfb2 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm.h
+++ b/src/charon-tkm/src/tkm/tkm.h
@@ -14,6 +14,59 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm tkm
+ *
+ * @addtogroup tkm
+ * @{
+ *
+ * Untrusted IKEv2 component used with Trusted Key Manager for IKE
+ * disaggregation.
+ *
+ * The untrusted IKEv2 component used in conjunction with the Trusted Key
+ * Manager infrastructure is implemented as a separate charon instance located
+ * in its own directory below the strongSwan top-level source directory
+ * (src/charon-tkm). This has the advantage that the TKM code is contained and
+ * does not mix with other strongSwan files. The charon-tkm binary startup code
+ * is modeled after the charon-nm instance, a special charon daemon variant to
+ * be used with the GNOME NetworkManager project. The major difference is the
+ * registration of custom TKM plugins as the final step of the startup phase.
+ * The charon-tkm daemon does not rely on the dynamic plugin loading mechanism
+ * for its core plugins, they are statically registered before entering the main
+ * processing loop.
+ *
+ * The following diagram shows the main components of the system and how they
+ * communicate.
+   @verbatim
+
+       +------------+            +------------+             +------------+
+       | xfrm-proxy |<-[tkm-rpc->| charon-tkm |<-[tkm-rpc]->|    TKM     |
+       +------------+            +------------+             +------------+
+             ^                                                    ^
+    [Netlink | XFRM]                                        [XFRM | Netlink]
+             |                                                    v
+       +-----------------------------------------------------------------+
+       |                            Kernel                               |
+       +-----------------------------------------------------------------+
+
+   @endverbatim
+ * Since the charon-tkm code uses the tkm-rpc library written in Ada, the daemon
+ * has to be built using an Ada-aware toolchain. The integration of Ada code
+ * into the strongSwan codebase is explained in the TKM documentation, section
+ * 5.4.1: http://www.codelabs.ch/tkm#anchor-doc.
+ *
+ * The Trusted Key Manager (TKM) is a minimal Trusted Computing Base which
+ * implements security-critical functions of the IKEv2 protocol.
+ *
+ * The xfrm-proxy receives XFRM Acquire and Expiry events from the kernel and
+ * forwards them to the charon-tkm IKE daemon for further processing.
+ *
+ * The underlying concept of IKE disaggregation and the design of TKM and all
+ * related components, of which charon-tkm is one component, is presented in
+ * detail in the project documentation found at
+ * http://www.codelabs.ch/tkm#anchor-doc.
+ */
+
 #ifndef TKM_H_
 #define TKM_H_
 
@@ -57,4 +110,4 @@ void tkm_deinit();
  */
 extern tkm_t *tkm;
 
-#endif /** TKM_H_ */
+#endif /** TKM_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_chunk_map.h b/src/charon-tkm/src/tkm/tkm_chunk_map.h
index 746de7d4be451b8078b205c49e805cdfbee74303..2d8ea8f76f6de2ecc07bb84762155855185a69ba 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_chunk_map.h
+++ b/src/charon-tkm/src/tkm/tkm_chunk_map.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-chunk-map chunk map
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_CHUNK_MAP_H_
 #define TKM_CHUNK_MAP_H_
 
@@ -64,4 +69,4 @@ struct tkm_chunk_map_t {
  */
 tkm_chunk_map_t *tkm_chunk_map_create();
 
-#endif /** TKM_CHUNK_MAP_H_ */
+#endif /** TKM_CHUNK_MAP_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_cred.h b/src/charon-tkm/src/tkm/tkm_cred.h
index 362e228c8126435ef3d4384693886dac746c4c05..1cfb5b9c735f5d4e78beab2b88651537dabe7001 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_cred.h
+++ b/src/charon-tkm/src/tkm/tkm_cred.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-credential credential set
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_CRED_H_
 #define TKM_CRED_H_
 
@@ -43,4 +48,4 @@ struct tkm_cred_t {
  */
 tkm_cred_t *tkm_cred_create();
 
-#endif /** TKM_CRED_H_ */
+#endif /** TKM_CRED_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_diffie_hellman.h b/src/charon-tkm/src/tkm/tkm_diffie_hellman.h
index 0f457931aeed75c5111d19bd6038e822e60702c8..a144303faa2c8f2e5f5c3f4d5c9c5c2e09224189 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_diffie_hellman.h
+++ b/src/charon-tkm/src/tkm/tkm_diffie_hellman.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-dh diffie hellman
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_DIFFIE_HELLMAN_H_
 #define TKM_DIFFIE_HELLMAN_H_
 
@@ -49,4 +54,4 @@ struct tkm_diffie_hellman_t {
  */
 tkm_diffie_hellman_t *tkm_diffie_hellman_create(diffie_hellman_group_t group);
 
-#endif /** TKM_DIFFIE_HELLMAN_H_ */
+#endif /** TKM_DIFFIE_HELLMAN_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_encoder.h b/src/charon-tkm/src/tkm/tkm_encoder.h
index e97e1e301a0fba2c80aaece97ebde2821ba9c193..7c6a4989d71e6a02127b8f5216d6235cf7503127 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_encoder.h
+++ b/src/charon-tkm/src/tkm/tkm_encoder.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-credential-enc credential encoder
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_ENCODER_H_
 #define TKM_ENCODER_H_
 
@@ -25,4 +30,4 @@
 bool tkm_encoder_encode(cred_encoding_type_t type, chunk_t *encoding,
                                                va_list args);
 
-#endif /** TKM_ENCODER_H_ */
+#endif /** TKM_ENCODER_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_id_manager.h b/src/charon-tkm/src/tkm/tkm_id_manager.h
index b1c1160a09a9676027050655549f96d17b75a1a9..0fc9ff8efba2e801eb5faf1991c8f617d2c36d6d 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_id_manager.h
+++ b/src/charon-tkm/src/tkm/tkm_id_manager.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-id-manager id manager
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_ID_MANAGER_H_
 #define TKM_ID_MANAGER_H_
 
@@ -91,4 +96,4 @@ struct tkm_id_manager_t {
  */
 tkm_id_manager_t *tkm_id_manager_create(const tkm_limits_t limits);
 
-#endif /** TKM_ID_MANAGER_H_ */
+#endif /** TKM_ID_MANAGER_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_kernel_ipsec.h b/src/charon-tkm/src/tkm/tkm_kernel_ipsec.h
index bb30d1c61b093628dfd6aa2d34b2c82273235ddb..14db21266cf3cdf04c38bbad42ca255ba7b83b14 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_kernel_ipsec.h
+++ b/src/charon-tkm/src/tkm/tkm_kernel_ipsec.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-kernel-ipsec kernel ipsec
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_KERNEL_IPSEC_H_
 #define TKM_KERNEL_IPSEC_H_
 
@@ -39,4 +44,4 @@ struct tkm_kernel_ipsec_t {
  */
 tkm_kernel_ipsec_t *tkm_kernel_ipsec_create();
 
-#endif /** TKM_KERNEL_IPSEC_H_ */
+#endif /** TKM_KERNEL_IPSEC_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_kernel_sad.h b/src/charon-tkm/src/tkm/tkm_kernel_sad.h
index 6863584f4a274ab63c321c414e92c6fa6a1d9bd4..0194cd3bca77ab80288a98e83f2742a87a50557c 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_kernel_sad.h
+++ b/src/charon-tkm/src/tkm/tkm_kernel_sad.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-kernel-sad kernel sad
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_KERNEL_SAD_H_
 #define TKM_KERNEL_SAD_H_
 
@@ -75,4 +80,4 @@ struct tkm_kernel_sad_t {
  */
 tkm_kernel_sad_t *tkm_kernel_sad_create();
 
-#endif /** TKM_KERNEL_SAD_H_ */
+#endif /** TKM_KERNEL_SAD_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_keymat.h b/src/charon-tkm/src/tkm/tkm_keymat.h
index 207f9728e47f1c2019eb20d01ff61aa7df9e3c6d..ee90bead5e45208df102e6e259f2122f3d772a0d 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_keymat.h
+++ b/src/charon-tkm/src/tkm/tkm_keymat.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-keymat keymat
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_KEYMAT_H_
 #define TKM_KEYMAT_H_
 
@@ -69,4 +74,4 @@ struct tkm_keymat_t {
  */
 tkm_keymat_t *tkm_keymat_create(bool initiator);
 
-#endif /** KEYMAT_TKM_H_ */
+#endif /** KEYMAT_TKM_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_listener.h b/src/charon-tkm/src/tkm/tkm_listener.h
index 262d66e33a57d76c69ea23c96ff473bc8de526e0..1162a77be0ef972dbc367e217a9c2b17cbe91354 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_listener.h
+++ b/src/charon-tkm/src/tkm/tkm_listener.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-listener listener
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_LISTENER_H_
 #define TKM_LISTENER_H_
 
@@ -44,4 +49,4 @@ struct tkm_listener_t {
  */
 tkm_listener_t *tkm_listener_create();
 
-#endif /** TKM_LISTENER_H_ */
+#endif /** TKM_LISTENER_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_nonceg.h b/src/charon-tkm/src/tkm/tkm_nonceg.h
index 25ec48a64a775cc60c4728e4047429b8510e527e..ceadb081f8fda994e788ff97245965fcf425f52d 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_nonceg.h
+++ b/src/charon-tkm/src/tkm/tkm_nonceg.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-nonceg nonce generator
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_NONCEG_H_
 #define TKM_NONCEG_H_
 
@@ -48,4 +53,4 @@ struct tkm_nonceg_t {
  */
 tkm_nonceg_t *tkm_nonceg_create();
 
-#endif /** TKM_NONCEG_H_ */
+#endif /** TKM_NONCEG_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_private_key.h b/src/charon-tkm/src/tkm/tkm_private_key.h
index 343752f28ec8029ecb98ec8a65fb73298f52f831..ded8300ca2d34e0cfcac726dead2188d2b6a1835 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_private_key.h
+++ b/src/charon-tkm/src/tkm/tkm_private_key.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-privkey private key
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_PRIVATE_KEY_H_
 #define TKM_PRIVATE_KEY_H_
 
@@ -37,4 +42,4 @@ struct tkm_private_key_t {
  */
 tkm_private_key_t *tkm_private_key_init(identification_t * const id);
 
-#endif /** TKM_PRIVATE_KEY_H_ */
+#endif /** TKM_PRIVATE_KEY_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_public_key.h b/src/charon-tkm/src/tkm/tkm_public_key.h
index 383c7dd4c41682dda30bcc150f590193cdbde102..5b21287b7f80c561fa4d41a64b9dc343cc10149f 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_public_key.h
+++ b/src/charon-tkm/src/tkm/tkm_public_key.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-pubkey public key
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_PUBLIC_KEY_H_
 #define TKM_PUBLIC_KEY_H_
 

diff --git a/src/charon-tkm/src/tkm/tkm_types.h b/src/charon-tkm/src/tkm/tkm_types.h
index 96a3bb273e316b9d662f782d961bdf89cbe8b713..cef53deb3fd9dfd13b2dc2d9d7d0c9cbb562238f 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_types.h
+++ b/src/charon-tkm/src/tkm/tkm_types.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-types types
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_TYPES_H_
 #define TKM_TYPES_H_
 
@@ -120,4 +125,4 @@ struct sign_info_t {
 
 };
 
-#endif /** TKM_TYPES_H_ */
+#endif /** TKM_TYPES_H_ @}*/

diff --git a/src/charon-tkm/src/tkm/tkm_utils.h b/src/charon-tkm/src/tkm/tkm_utils.h
index 37a2c7ce549ab94532abcf4272b34974e983700f..ac8fac74264a398d332cc0626aa41b6d75248526 100644 (file)
--- a/src/charon-tkm/src/tkm/tkm_utils.h
+++ b/src/charon-tkm/src/tkm/tkm_utils.h
@@ -14,6 +14,11 @@
  * for more details.
  */
 
+/**
+ * @defgroup tkm-utils utils
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_UTILS_H_
 #define TKM_UTILS_H_
 
@@ -40,4 +45,4 @@ void sequence_to_chunk(const byte_t * const first, const uint32_t len,
 void chunk_to_sequence(const chunk_t * const chunk, void *sequence,
                const uint32_t typelen);
 
-#endif /** TKM_UTILS_H_ */
+#endif /** TKM_UTILS_H_ @}*/