Add charon-tkm API documentation

2013-03-19 15:23:51 +01:00
parent 0063e03325
commit 7f21523abd
17 changed files with 158 additions and 16 deletions
@@ -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_ @}*/
@@ -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_ @}*/
@@ -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_ @}*/
@@ -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_ @}*/
@@ -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_ @}*/
@@ -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_ @}*/
@@ -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_ @}*/
@@ -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_ @}*/
@@ -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_ @}*/
@@ -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_ @}*/
@@ -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_ @}*/
@@ -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_ @}*/
@@ -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_ @}*/
@@ -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_ @}*/
@@ -14,6 +14,11 @@
 * for more details.
 */

+/**
+ * @defgroup tkm-pubkey public key
+ * @{ @ingroup tkm
+ */
+
 #ifndef TKM_PUBLIC_KEY_H_
 #define TKM_PUBLIC_KEY_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_ @}*/
@@ -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_ @}*/