From: Adrian-Ken Rueegsegger <ken@codelabs.ch>
Date: Wed, 30 Jan 2013 10:16:16 +0000 (+0100)
Subject: Add charon-tkm API documentation
X-Git-Tag: 5.0.3rc1~39^2~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7f21523abd0775b0d515b526b4f2d12bf1d4b7de;p=thirdparty%2Fstrongswan.git

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 f8598f238b..b73dc6cb58 100644
--- 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 1be9249134..db325dcd26 100644
--- 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 9d559d9fc3..7c711312b4 100644
--- 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 746de7d4be..2d8ea8f76f 100644
--- 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 362e228c81..1cfb5b9c73 100644
--- 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 0f457931ae..a144303faa 100644
--- 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 e97e1e301a..7c6a4989d7 100644
--- 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 b1c1160a09..0fc9ff8efb 100644
--- 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 bb30d1c61b..14db21266c 100644
--- 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 6863584f4a..0194cd3bca 100644
--- 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 207f9728e4..ee90bead5e 100644
--- 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 262d66e33a..1162a77be0 100644
--- 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 25ec48a64a..ceadb081f8 100644
--- 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 343752f28e..ded8300ca2 100644
--- 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 383c7dd4c4..5b21287b7f 100644
--- 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 96a3bb273e..cef53deb3f 100644
--- 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 37a2c7ce54..ac8fac7426 100644
--- 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_ @}*/