[PATCH v1 13/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/server.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 server.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/server.c | 203 +++++++++++++++++++++++++++++++++++++++------
 1 file changed, 177 insertions(+), 26 deletions(-)

diff --git a/src/tlshd/server.c b/src/tlshd/server.c
index 8bb769ff9f74..ca084a1a754b 100644
--- a/src/tlshd/server.c
+++ b/src/tlshd/server.c
@@ -1,9 +1,13 @@
-/*
- * Perform a TLSv1.3 server-side handshake.
+/**
+ * @file server.c
+ * @brief Perform a TLSv1.3 server-side handshake
  *
+ * @copyright
  * Copyright (c) 2023 Oracle and/or its affiliates.
  * Copyright (c) 2024 Red Hat, Inc.
- *
+ */
+
+/*
  * 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,13 +46,50 @@
 #include "tlshd.h"
 #include "netlink.h"
 
+/**
+ * @var gnutls_privkey_t tlshd_server_pq_privkey
+ * Server peer's post-quantum private key
+ */
 static gnutls_privkey_t tlshd_server_pq_privkey;
+
+/**
+ * @var gnutls_privkey_t tlshd_server_privkey
+ * Server peer's RSA private key
+ */
 static gnutls_privkey_t tlshd_server_privkey;
+
+/**
+ * @var unsigned int tlshd_server_pq_certs_len
+ * Count of server peer's PQ certificates
+ */
 static unsigned int tlshd_server_pq_certs_len = TLSHD_MAX_CERTS;
+
+/**
+ * @var unsigned int tlshd_server_certs_len
+ * Count of server peer's certificates
+ */
 static unsigned int tlshd_server_certs_len = TLSHD_MAX_CERTS;
+
+/**
+ * @var gnutls_pcert_st tlshd_server_certs
+ * Server peer's certificates
+ */
 static gnutls_pcert_st tlshd_server_certs[TLSHD_MAX_CERTS];
+
+/**
+ * @var gnutls_pk_algorithm_t tlshd_server_pq_pkalg
+ * Server peer certificate's public key algorithms
+ */
 static gnutls_pk_algorithm_t tlshd_server_pq_pkalg = GNUTLS_PK_UNKNOWN;
 
+/**
+ * @brief Retrieve server certificates to be used for ServerHello
+ * @param[in]     parms  Handshake parameters
+ *
+ * @retval true   Server certificates were found. Caller must release
+ *		  the certificates using tlshd_x509_server_put_certs.
+ * @retval false  No usable server certificates were found
+ */
 static bool tlshd_x509_server_get_certs(struct tlshd_handshake_parms *parms)
 {
 	if (parms->x509_cert != TLS_NO_CERT)
@@ -61,6 +102,9 @@ static bool tlshd_x509_server_get_certs(struct tlshd_handshake_parms *parms)
 				      &tlshd_server_pq_pkalg);
 }
 
+/**
+ * @brief Release server certificates that were used for ServerHello
+ */
 static void tlshd_x509_server_put_certs(void)
 {
 	unsigned int i;
@@ -69,6 +113,14 @@ static void tlshd_x509_server_put_certs(void)
 		gnutls_pcert_deinit(&tlshd_server_certs[i]);
 }
 
+/**
+ * @brief Retrieve the private key to be used for ServerHello
+ * @param[in]     parms  Handshake parameters
+ *
+ * @retval true   Private key was found. Caller must release the
+ *		  private key using tlshd_x509_server_put_privkey.
+ * @retval false  No usable private key was found
+ */
 static bool tlshd_x509_server_get_privkey(struct tlshd_handshake_parms *parms)
 {
 	if (parms->x509_privkey != TLS_NO_PRIVKEY)
@@ -79,12 +131,20 @@ static bool tlshd_x509_server_get_privkey(struct tlshd_handshake_parms *parms)
 					&tlshd_server_privkey);
 }
 
+/**
+ * @brief Release the private key that was used for ServerHello
+ */
 static void tlshd_x509_server_put_privkey(void)
 {
 	gnutls_privkey_deinit(tlshd_server_pq_privkey);
 	gnutls_privkey_deinit(tlshd_server_privkey);
 }
 
+/**
+ * @brief Audit trust chain of incoming client certificate
+ * @param[in]     req_ca_rdn
+ * @param[in]     nreqs
+ */
 static void tlshd_x509_log_issuers(const gnutls_datum_t *req_ca_rdn, int nreqs)
 {
 	char issuer_dn[256];
@@ -107,7 +167,18 @@ static void tlshd_x509_log_issuers(const gnutls_datum_t *req_ca_rdn, int nreqs)
 }
 
 /**
- * tlshd_x509_retrieve_key_cb - Initialize client's x.509 identity
+ * @brief Initialize the server peer's x.509 identity
+ * @param[in]     session  session in the midst of a handshake
+ * @param[in]     req_ca_rdn
+ * @param[in]     nreqs
+ * @param[in]     pk_algos
+ * @param[in]     pk_algos_length
+ * @param[out]    pcert
+ * @param[out]    pcert_length
+ * @param[out]    privkey
+ *
+ * @retval 0   Success; output parameters are set accordingly
+ * @retval -1  Failure
  *
  * Callback function is of type gnutls_certificate_retrieve_function2
  *
@@ -115,10 +186,6 @@ static void tlshd_x509_log_issuers(const gnutls_datum_t *req_ca_rdn, int nreqs)
  * gnutls/doc/examples/ex-cert-select.c.
  *
  * Sketched-in and untested.
- *
- * Return values:
- *   %0: Success; output parameters are set accordingly
- *   %-1: Failure
  */
 static int
 tlshd_x509_retrieve_key_cb(gnutls_session_t session,
@@ -197,6 +264,13 @@ tlshd_x509_retrieve_key_cb(gnutls_session_t session,
 	return 0;
 }
 
+/**
+ * @brief Initialize server-side trust store
+ * @param[out]    cred  Trust store to initialize
+ *
+ * @returns a GnuTLS error code. Caller must release credentials
+ * using gnutls_certificate_free_credentials(3).
+ */
 static int tlshd_server_get_truststore(gnutls_certificate_credentials_t cred)
 {
 	char *pathname;
@@ -227,9 +301,9 @@ static int tlshd_server_get_truststore(gnutls_certificate_credentials_t cred)
 }
 
 /**
- * tlshd_server_x509_verify_function - Verify remote's x.509 certificate
- * @session: session in the midst of a handshake
- * @parms: handshake parameters
+ * @brief Verify remote's x.509 certificate
+ * @param[in]     session  Session in the midst of a handshake
+ * @param[in]     parms    Handshake parameters
  *
  * A return value of %GNUTLS_E_SUCCESS indicates that the TLS session
  * has been allowed to continue. tlshd either sets the peerid array if
@@ -299,6 +373,13 @@ certificate_error:
 	return GNUTLS_E_CERTIFICATE_ERROR;
 }
 
+/**
+ * @brief Verify a remote peer's x.509 certificate (TLSv1.3)
+ * @param[in]     session  session in the midst of a handshake
+ *
+ * @retval GNUTLS_E_SUCCESS            Certificate has been successfully verified
+ * @retval GNUTLS_E_CERTIFICATE_ERROR  Certificate verification failed
+ */
 static int tlshd_tls13_server_x509_verify_function(gnutls_session_t session)
 {
 	struct tlshd_handshake_parms *parms = gnutls_session_get_ptr(session);
@@ -306,6 +387,10 @@ static int tlshd_tls13_server_x509_verify_function(gnutls_session_t session)
 	return tlshd_server_x509_verify_function(session, parms);
 }
 
+/**
+ * @brief Process an x.509-based TLS handshake with a server certificate
+ * @param[in]     parms  Handshake parameters
+ */
 static void tlshd_tls13_server_x509_handshake(struct tlshd_handshake_parms *parms)
 {
 	gnutls_certificate_credentials_t xcred;
@@ -386,17 +471,16 @@ out_free_creds:
 }
 
 /**
- * tlshd_server_psk_cb - Validate remote's username
- * @session: session in the midst of a handshake
- * @username: remote's username
- * @key: PSK matching @username
+ * @brief Validate the remote peer's username
+ * @param[in]     session   Session in the midst of a handshake
+ * @param[in]     username  Remote peer's username
+ * @param[in]     key       PSK matching "username"
  *
- * Searches for a key with description @username in the session
- * keyring, and stores the PSK data in @key if found.
+ * Searches for a key with description "username" in the session
+ * keyring, and stores the PSK data in "key" if found.
  *
- * Return values:
- *   %0: Matching key has been stored in @key
- *   %-1: Error during lookup, @key is not updated
+ * @retval 0  Matching key has been stored in "key"
+ * @retval -1 Error during lookup, "key" is not updated
  */
 static int tlshd_server_psk_cb(gnutls_session_t session,
 			       const char *username, gnutls_datum_t *key)
@@ -426,6 +510,10 @@ static int tlshd_server_psk_cb(gnutls_session_t session,
 	return 0;
 }
 
+/**
+ * @brief Process an PSK-based TLS handshake (TLSv1.3)
+ * @param[in]     parms   Handshake parameters
+ */
 static void tlshd_tls13_server_psk_handshake(struct tlshd_handshake_parms *parms)
 {
 	gnutls_psk_server_credentials_t psk_cred;
@@ -471,9 +559,8 @@ out_free_creds:
 }
 
 /**
- * tlshd_tls13_serverhello_handshake - send a TLSv1.3 ServerHello
- * @parms: handshake parameters
- *
+ * @brief Send a TLSv1.3 ServerHello
+ * @param[in]     parms  Handshake parameters
  */
 void tlshd_tls13_serverhello_handshake(struct tlshd_handshake_parms *parms)
 {
@@ -491,6 +578,17 @@ void tlshd_tls13_serverhello_handshake(struct tlshd_handshake_parms *parms)
 }
 
 #ifdef HAVE_GNUTLS_QUIC
+/**
+ * @brief Verify the ALPNs presented by a remote peer
+ * @param[in]      session
+ * @param[in]      htype
+ * @param[in]      when
+ * @param[in]      incoming
+ * @param[in]      msg
+ *
+ * @retval 0   ALPN verification was successful
+ * @retval -1  ALPN verification failed
+ */
 static int tlshd_quic_server_alpn_verify(gnutls_session_t session, unsigned int htype,
 					 unsigned int when, unsigned int incoming,
 					 const gnutls_datum_t *msg)
@@ -515,6 +613,25 @@ static int tlshd_quic_server_alpn_verify(gnutls_session_t session, unsigned int
 	return 0;
 }
 
+/**
+ * @brief Anti-reply protection
+ * @param[in]     dbf
+ * @param[in]     exp_time
+ * @param[in]     key
+ * @param[in]     data
+ *
+ * Currently, tlshd handles each handshake request in a new process
+ * rather than a thread. As a result, it cannot share the
+ * gnutls_anti_replay_t object across processes. This causes 0-RTT
+ * data to be automatically disabled, since
+ * _gnutls_anti_replay_check() fails validation in the absence of a
+ * shared anti-replay context.
+ *
+ * To properly support 0-RTT data, we need to enable sharing of the
+ * gnutls_anti_replay_t object across processes in some way.
+ *
+ * @retval 0  Not a replay
+ */
 static int tlshd_quic_server_anti_replay_db_add_func(void *dbf, time_t exp_time,
 						     const gnutls_datum_t *key,
 						     const gnutls_datum_t *data)
@@ -523,8 +640,19 @@ static int tlshd_quic_server_anti_replay_db_add_func(void *dbf, time_t exp_time,
 	return 0;
 }
 
+/**
+ * @var gnutls_anti_replay_t tlshd_quic_server_anti_replay
+ * Shared anti-replay context
+ */
 static gnutls_anti_replay_t tlshd_quic_server_anti_replay;
 
+/**
+ * @brief Verify a remote peer's x.509 certificate (QUIC)
+ * @param[in]     session  session in the midst of a handshake
+ *
+ * @retval GNUTLS_E_SUCCESS            Certificate has been successfully verified
+ * @retval GNUTLS_E_CERTIFICATE_ERROR  Certificate verification failed
+ */
 static int tlshd_quic_server_x509_verify_function(gnutls_session_t session)
 {
 	struct tlshd_quic_conn *conn = gnutls_session_get_ptr(session);
@@ -532,6 +660,18 @@ static int tlshd_quic_server_x509_verify_function(gnutls_session_t session)
 	return tlshd_server_x509_verify_function(session, conn->parms);
 }
 
+/**
+ * @brief Validate the remote peer's username
+ * @param[in]     session   Session in the midst of a handshake
+ * @param[in]     username  Remote peer's username
+ * @param[in]     key       PSK matching "username"
+ *
+ * Searches for a key with description "username" in the session
+ * keyring, and stores the PSK data in "key" if found.
+ *
+ * @retval 0  Matching key has been stored in "key"
+ * @retval -1 Error during lookup, "key" is not updated
+ */
 static int tlshd_quic_server_psk_cb(gnutls_session_t session, const char *username,
 				    gnutls_datum_t *key)
 {
@@ -562,6 +702,10 @@ found:
 	return 0;
 }
 
+/**
+ * @brief Prepare a session for a QUIC server handshake using an x.509 cert
+ * @param[in]     conn
+ */
 static void tlshd_quic_server_set_x509_session(struct tlshd_quic_conn *conn)
 {
 	struct tlshd_handshake_parms *parms = conn->parms;
@@ -631,6 +775,10 @@ err:
 	tlshd_log_gnutls_error(ret);
 }
 
+/**
+ * @brief Prepare a session for a QUIC client handshake using a pre-shared key
+ * @param[in]     conn
+ */
 static void tlshd_quic_server_set_psk_session(struct tlshd_quic_conn *conn)
 {
 	gnutls_psk_server_credentials_t cred;
@@ -665,9 +813,8 @@ err:
 }
 
 /**
- * tlshd_quic_serverhello_handshake - send a QUIC Server Initial
- * @parms: handshake parameters
- *
+ * @brief Send a QUIC Server Initial
+ * @param[in]     parms  Handshake parameters
  */
 void tlshd_quic_serverhello_handshake(struct tlshd_handshake_parms *parms)
 {
@@ -699,6 +846,10 @@ out:
 	tlshd_quic_conn_destroy(conn);
 }
 #else
+/**
+ * @brief Send a QUIC Server Initial
+ * @param[in]     parms  Handshake parameters
+ */
 void tlshd_quic_serverhello_handshake(struct tlshd_handshake_parms *parms)
 {
 	tlshd_log_debug("QUIC handshake is not enabled (%d)", parms->auth_mode);
-- 
2.51.0