[PATCH v1 08/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/ktls.c

[Chuck Lever <cel@kernel.org>]

From: Chuck Lever <chuck.lever@oracle.com>

I started the ktls-utils project using the Linux kernel flavor of
Doxygen commenting which user-space Doxygen does not recognize by
default.

Convert existing comments in ktls.c to what a normal user space
Doxygen run expects to see. This will enable deployment of an
automatically-generated documentation web site.

Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
---
 src/tlshd/ktls.c | 118 ++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 102 insertions(+), 16 deletions(-)

diff --git a/src/tlshd/ktls.c b/src/tlshd/ktls.c
index 50381bf3fd4b..810460ada721 100644
--- a/src/tlshd/ktls.c
+++ b/src/tlshd/ktls.c
@@ -1,9 +1,13 @@
-/*
- * Initialize a kTLS socket. In some cases initialization might
- * be handled by the TLS library.
+/**
+ * @file ktls.c
+ * @brief Initialize a kTLS socket. In some cases initialization might
+ *	  be handled by the TLS library
  *
+ * @copyright
  * Copyright (c) 2022 Oracle and/or its affiliates.
- *
+ */
+
+/*
  * ktls-utils is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License as
  * published by the Free Software Foundation; version 2.
@@ -42,6 +46,13 @@
 #include "tlshd.h"
 #include "netlink.h"
 
+/**
+ * @brief Concatenate two NUL-terminated C strings
+ * @param[in]     str1  left-hand string
+ * @param[in]     str2  right-hand string
+ *
+ * @returns "str1" followed by "str2"
+ */
 static char *tlshd_string_concat(char *str1, const char *str2)
 {
 	size_t len = 0;
@@ -69,6 +80,14 @@ static char *tlshd_string_concat(char *str1, const char *str2)
 }
 
 #ifdef HAVE_GNUTLS_TRANSPORT_IS_KTLS_ENABLED
+/**
+ * @brief Determine if a session is kTLS-enabled
+ * @param[in]     session  An established TLS session
+ * @param[in]     read     Which side of the duplex to check
+ *
+ * @retval  true   The session is prepared to use kTLS
+ * @retval  false  The session is not prepared to use kTLS
+ */
 static bool tlshd_is_ktls_enabled(gnutls_session_t session, unsigned read)
 {
 	int ret;
@@ -90,6 +109,14 @@ static bool tlshd_is_ktls_enabled(gnutls_session_t session, unsigned read)
 }
 
 #else
+/**
+ * @brief Determine if a session is kTLS-enabled
+ * @param[in]     session  An established TLS session
+ * @param[in]     read     Which side of the duplex to check
+ *
+ * @retval  true   The session is prepared to use kTLS
+ * @retval  false  The session is not prepared to use kTLS
+ */
 static bool tlshd_is_ktls_enabled(__attribute__ ((unused)) gnutls_session_t session,
 				  __attribute__ ((unused)) unsigned read)
 {
@@ -97,6 +124,16 @@ static bool tlshd_is_ktls_enabled(__attribute__ ((unused)) gnutls_session_t sess
 }
 #endif
 
+/**
+ * @brief Call setsockopt(3), with error logging
+ * @param[in]     sock     An open socket descriptor
+ * @param[in]     read     Read or write side
+ * @param[in]     info     The value to set
+ * @param[in]     infolen  The size of "info", in bytes
+ *
+ * @retval  true   The option was set successfully
+ * @retval  false  The option was not set
+ */
 static bool tlshd_setsockopt(int sock, unsigned read, const void *info,
 			     socklen_t infolen)
 {
@@ -123,6 +160,15 @@ static bool tlshd_setsockopt(int sock, unsigned read, const void *info,
 }
 
 #if defined(TLS_CIPHER_AES_GCM_128)
+/**
+ * @brief Configure TLS session for AES-GCM-128 encryption
+ * @param[in]     session  An established TLS session
+ * @param[in]     sock     An open socket descriptor
+ * @param[in]     read     Read or write side
+ *
+ * @retval  true   The session was configured successfully
+ * @retval  false  The session was not configured
+ */
 static bool tlshd_set_aes_gcm128_info(gnutls_session_t session, int sock,
 				      unsigned read)
 {
@@ -162,6 +208,15 @@ static bool tlshd_set_aes_gcm128_info(gnutls_session_t session, int sock,
 #endif
 
 #if defined(TLS_CIPHER_AES_GCM_256)
+/**
+ * @brief Configure TLS session for AES-GCM-256 encryption
+ * @param[in]     session  An established TLS session
+ * @param[in]     sock     An open socket descriptor
+ * @param[in]     read     Read or write side
+ *
+ * @retval  true   The session was configured successfully
+ * @retval  false  The session was not configured
+ */
 static bool tlshd_set_aes_gcm256_info(gnutls_session_t session, int sock,
 				      unsigned read)
 {
@@ -201,6 +256,15 @@ static bool tlshd_set_aes_gcm256_info(gnutls_session_t session, int sock,
 #endif
 
 #if defined(TLS_CIPHER_AES_CCM_128)
+/**
+ * @brief Configure TLS session for AES-CCM-128 encryption
+ * @param[in]     session  An established TLS session
+ * @param[in]     sock     An open socket descriptor
+ * @param[in]     read     Read or write side
+ *
+ * @retval  true   The session was configured successfully
+ * @retval  false  The session was not configured
+ */
 static bool tlshd_set_aes_ccm128_info(gnutls_session_t session, int sock,
 				      unsigned read)
 {
@@ -240,6 +304,15 @@ static bool tlshd_set_aes_ccm128_info(gnutls_session_t session, int sock,
 #endif
 
 #if defined(TLS_CIPHER_CHACHA20_POLY1305)
+/**
+ * @brief Configure TLS session for ChaCha-Poly1305 encryption
+ * @param[in]     session  An established TLS session
+ * @param[in]     sock     An open socket descriptor
+ * @param[in]     read     Read or write side
+ *
+ * @retval  true   The session was configured successfully
+ * @retval  false  The session was not configured
+ */
 static bool tlshd_set_chacha20_poly1305_info(gnutls_session_t session, int sock,
 					     unsigned read)
 {
@@ -275,10 +348,10 @@ static bool tlshd_set_chacha20_poly1305_info(gnutls_session_t session, int sock,
 #endif
 
 /**
- * tlshd_initialize_ktls - Initialize socket for use by kTLS
- * @session: TLS session descriptor
+ * @brief Initialize a socket for use by kTLS
+ * @param[in]     session  TLS session descriptor
  *
- * Returns zero on success, or a positive errno value.
+ * @returns zero on success, or a positive errno value.
  */
 unsigned int tlshd_initialize_ktls(gnutls_session_t session)
 {
@@ -320,6 +393,13 @@ unsigned int tlshd_initialize_ktls(gnutls_session_t session)
 	return EIO;
 }
 
+/**
+ * @brief Concatenate a cipher name to a string
+ * @param[in]     pstring  NUL-terminated C string
+ * @param[in]     cipher   GnuTLS cipher number
+ *
+ * @retval A NUL-terminated C string; caller must free the string with free(3)
+ */
 static char *tlshd_cipher_string_emit(char *pstring, unsigned int cipher)
 {
 	switch (cipher) {
@@ -350,6 +430,13 @@ static gnutls_priority_t	tlshd_gnutls_priority_psk;
 static gnutls_priority_t	tlshd_gnutls_priority_psk_sha256;
 static gnutls_priority_t	tlshd_gnutls_priority_psk_sha384;
 
+/**
+ * @brief Initialize GnuTLS priority caches
+ * @param[in]     ciphers       Array of GnuTLS cipher numbers
+ * @param[in]     cipher_count  count of elements in "ciphers"
+ *
+ * @retval Zero on success; a negative errno if a failure occurred.
+ */
 static int tlshd_gnutls_priority_init_list(const unsigned int *ciphers,
 					   int cipher_count)
 {
@@ -498,9 +585,9 @@ static int tlshd_gnutls_priority_init_list(const unsigned int *ciphers,
 }
 
 /**
- * tlshd_gnutls_priority_init - Initialize GnuTLS priority caches
+ * @brief Initialize GnuTLS priority caches
  *
- * Returns zero on success, or a negative errno value if a failure
+ * @returns zero on success, or a negative errno value if a failure
  * occurred.
  */
 int tlshd_gnutls_priority_init(void)
@@ -532,12 +619,12 @@ out:
 }
 
 /**
- * tlshd_gnutls_priority_set - Initialize priorities per-session
- * @session: session to initialize
- * @parms: handshake parameters
- * @psk_len: size of pre-shared key in bytes, or zero
+ * @brief Select GnuTLS priority cache to use for "session"
+ * @param[in]     session  Session to initialize
+ * @param[in]     parms    Handshake parameters
+ * @param[in]     psk_len  Size of pre-shared key in bytes, or zero
  *
- * Returns GNUTLS_E_SUCCESS on success, otherwise an error code.
+ * @returns GNUTLS_E_SUCCESS on success, otherwise an error code.
  */
 int tlshd_gnutls_priority_set(gnutls_session_t session,
 			      const struct tlshd_handshake_parms *parms,
@@ -558,8 +645,7 @@ int tlshd_gnutls_priority_set(gnutls_session_t session,
 }
 
 /**
- * tlshd_gnutls_priority_deinit - Free GnuTLS priority caches
- *
+ * @brief Free GnuTLS priority caches
  */
 void tlshd_gnutls_priority_deinit(void)
 {
-- 
2.51.0