From: "cron2 (Code Review)" Date: Tue, 15 Apr 2025 18:14:43 +0000 In-Reply-To: References: Reply-To: gert@...1296..., arne-openvpn@...1227..., openvpn-devel@lists.sourceforge.net, frank@...2641... Message-ID: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Disposition: inline Content-Type: multipart/alternative; boundary="VbfJw0Ark+4="; charset=UTF-8 Subject: [Openvpn-devel] [S] Change in openvpn[master]: Doxygen: Clean up tls-crypt documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: flichtenheld Cc: plaisthos , openvpn-devel --VbfJw0Ark+4= Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable cron2 has submitted this change. ( http://gerrit.openvpn.net/c/openvpn/+/93= 6?usp=3Demail ) Change subject: Doxygen: Clean up tls-crypt documentation ...................................................................... Doxygen: Clean up tls-crypt documentation - Fix broken links to OpenSSL documentation - Remove some unnecessary \c for function names. Doxygen does handle them automatically. - Add some \c for --option since otherwise -- gets converted to one character (e.g. – in HTML). Change-Id: I9a27248557fabcd9f7584deb4aba16cd71fb803c Signed-off-by: Frank Lichtenheld Acked-by: Arne Schwabe Message-Id: <20250415155720.13034-1-gert@...1296...> URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg31= 434.html Signed-off-by: Gert Doering --- M doc/doxygen/doc_control_tls.h M src/openvpn/tls_crypt.h 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/doxygen/doc_control_tls.h b/doc/doxygen/doc_control_tls.h index 7ff5e99..3c92a76 100644 --- a/doc/doxygen/doc_control_tls.h +++ b/doc/doxygen/doc_control_tls.h @@ -49,7 +49,7 @@ * * @par * The former role is described below. The latter is described in the - * documentation for the \c verify_callback() function. + * documentation for the verify_callback() function. * * @par * In other words, this module takes care of the confidentiality and @@ -61,7 +61,7 @@ * Because of the one-to-one relationship between control channel TLS * state and \c key_state structures, the initialization and cleanup of an * instance of the Control Channel TLS module's state happens within the - * \c key_state_init() and \c key_state_free() functions. In other words, + * key_state_init() and key_state_free() functions. In other words, * each \c key_state object contains exactly one OpenSSL SSL-BIO object, * which is initialized and cleaned up together with the rest of the \c * key_state object. @@ -69,26 +69,26 @@ * @par Packet processing functions * This object behaves somewhat like a black box with a ciphertext and a * plaintext I/O port. Its interaction with OpenVPN's control channel - * during operation takes place within the \c tls_process() function of + * during operation takes place within the tls_process() function of * the \link control_processor Control Channel Processor\endlink. The * following functions are available for processing packets: * - If ciphertext received from the remote peer is available in the \link * reliable Reliability Layer\endlink: * - Insert it into the ciphertext-side of the SSL-BIO. - * - Use function: \c key_state_write_ciphertext() + * - Use function: key_state_write_ciphertext() * - If ciphertext can be extracted from the ciphertext-side of the * SSL-BIO: * - Pass it to the \link reliable Reliability Layer\endlink for sending * to the remote peer. - * - Use function: \c key_state_read_ciphertext() + * - Use function: key_state_read_ciphertext() * - If plaintext can be extracted from the plaintext-side of the SSL-BIO: * - Pass it on to the \link control_processor Control Channel * Processor\endlink for local processing. - * - Use function: \c key_state_read_plaintext() + * - Use function: key_state_read_plaintext() * - If plaintext from the \link control_processor Control Channel * Processor\endlink is available to be sent to the remote peer: * - Insert it into the plaintext-side of the SSL-BIO. - * - Use function: \c key_state_write_plaintext() or \c + * - Use function: key_state_write_plaintext() or * key_state_write_plaintext_const() * * @par Transport Layer Security protocol implementation @@ -98,7 +98,7 @@ * @par * For more information on the OpenSSL library's BIO objects, please see: * - OpenSSL's generic BIO objects: - * http://www.openssl.org/docs/crypto/bio.html + * https://docs.openssl.org/master/man7/bio/#bio * - OpenSSL's SSL-BIO object: - * http://www.openssl.org/docs/crypto/BIO_f_ssl.html + * https://docs.openssl.org/master/man3/BIO_f_ssl/#bio_f_ssl */ diff --git a/src/openvpn/tls_crypt.h b/src/openvpn/tls_crypt.h index 1a604ce..87e9867 100644 --- a/src/openvpn/tls_crypt.h +++ b/src/openvpn/tls_crypt.h @@ -22,11 +22,11 @@ */ /** - * @defgroup tls_crypt Control channel encryption (--tls-crypt, --tls-cryp= t-v2) + * @defgroup tls_crypt Control channel encryption (tls-crypt, tls-crypt-v2) * @ingroup control_tls * @{ * - * Control channel encryption uses a pre-shared static key (like the --tls= -auth + * Control channel encryption uses a pre-shared static key (like the @c --= tls-auth * key) to encrypt control channel packets. * * Encrypting control channel packets has three main advantages: @@ -36,8 +36,8 @@ * - It provides "poor-man's" post-quantum security, against attackers who * will never know the pre-shared key (i.e. no forward secrecy). * - * --tls-crypt uses a tls-auth-style group key, where all servers and clie= nts - * share the same group key. --tls-crypt-v2 adds support for client-specif= ic + * @c --tls-crypt uses a tls-auth-style group key, where all servers and c= lients + * share the same group key. @c --tls-crypt-v2 adds support for client-spe= cific * keys, where all servers share the same client-key encryption key, and e= ach * clients receives a unique client key, both in plaintext and in encrypted * form. When connecting to a server, the client sends the encrypted key = to @@ -103,7 +103,7 @@ + sizeof(uint16_t))) /** - * Initialize a key_ctx_bi structure for use with --tls-crypt. + * Initialize a key_ctx_bi structure for use with @c --tls-crypt. * * @param key The key context to initialize * @param key_file The file to read the key from or the key itself if @@ -141,7 +141,7 @@ * @param dst Any data present in this buffer is first authenticated, th= en * the wrapped packet id and data from the src buffer are app= ended. * Must have at least tls_crypt_buf_overhead()+BLEN(src) head= room. - * @param opt The crypto state for this --tls-crypt instance. + * @param opt The crypto state for this @c --tls-crypt instance. * * @returns true iff wrapping succeeded. */ @@ -154,7 +154,7 @@ * * @param src Data to decrypt and authenticate. * @param dst Returns the decrypted data, if unwrapping was successful. - * @param opt The crypto state for this --tls-crypt instance. + * @param opt The crypto state for this @c --tls-crypt instance. * * @returns true iff unwrapping succeeded (data authenticated correctly an= d was * no replay). -- To view, visit http://gerrit.openvpn.net/c/openvpn/+/936?usp=3Demail To unsubscribe, or for help writing mail filters, visit http://gerrit.openv= pn.net/settings Gerrit-Project: openvpn Gerrit-Branch: master Gerrit-Change-Id: I9a27248557fabcd9f7584deb4aba16cd71fb803c Gerrit-Change-Number: 936 Gerrit-PatchSet: 2 Gerrit-Owner: flichtenheld Gerrit-Reviewer: plaisthos Gerrit-CC: openvpn-devel Gerrit-MessageType: merged --VbfJw0Ark+4= Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable

cron2 submitted this change.

View Change

Doxygen: Clean up tls-crypt documentation
<= br>- Fix broken links to OpenSSL documentation
- Remove some unnecessary= \c for function names.
Doxygen does handle them automatically.
- A= dd some \c for --option since otherwise --
gets converted to one chara= cter (e.g. &ndash; in
HTML).

Change-Id: I9a27248557fabcd9f7= 584deb4aba16cd71fb803c
Signed-off-by: Frank Lichtenheld <frank@...2716...= 1...>
Acked-by: Arne Schwabe <arne-openvpn@...1227...>
Messa= ge-Id: <20250415155720.13034-1-gert@...1296...>
URL: https://www.m= ail-archive.com/openvpn-devel@lists.sourceforge.net/msg31434.html
Signed= -off-by: Gert Doering <gert@...1296...>
---
M doc/doxygen/doc_c= ontrol_tls.h
M src/openvpn/tls_crypt.h
2 files changed, 16 insertions= (+), 16 deletions(-)

diff --git a/doc/doxygen/doc_control_tls.h b/doc/doxygen/doc_control_tls=
.h
index 7ff5e99..3c92a76 100644
--- a/doc/= doxygen/doc_control_tls.h
+++ b/doc/doxygen/doc_control_tls= .h
@@ -49,7 +49,7 @@
*
= * @par
* The former role is described below. The latter = is described in the
- *= documentation for the \c verify_callback() function.
+ * documentation for the verify_callback(= ) function.
*
* @par
= * In other words, this module takes care of the confidentiality and<= br>@@ -61,7 +61,7 @@
* Because of the one-to-one re= lationship between control channel TLS
* state and \c key= _state structures, the initialization and cleanup of an
*= instance of the Control Channel TLS module's state happens within the<= /span>
- * \c key_state_init()= and \c key_state_free() functions. In other words,
+ * key_state_init() and key_state_free() = functions. In other words,
* each \c key_state object co= ntains exactly one OpenSSL SSL-BIO object,
* which is ini= tialized and cleaned up together with the rest of the \c
= * key_state object.
@@ -69,26 +69,26 @@
*= @par Packet processing functions
* This object behaves s= omewhat like a black box with a ciphertext and a
* plaint= ext I/O port. Its interaction with OpenVPN's control channel
= - * during operation takes place = within the \c tls_process() function of
+ * during operation takes place within the tls_process(= ) function of
* the \link control_processor Control Chann= el Processor\endlink. The
* following functions are avai= lable for processing packets:
* - If ciphertext received = from the remote peer is available in the \link
* reliab= le Reliability Layer\endlink:
* - Insert it into the ci= phertext-side of the SSL-BIO.
- * - Use function: \c key_state_write_ciphertext()
+ * - Use function: key_state_wri= te_ciphertext()

* - If ciphertext can be extracted from t= he ciphertext-side of the
* SSL-BIO:
= * - Pass it to the \link reliable Reliability Layer\endlink for sending
* to the remote peer.
- * - Use function: \c key_state_read_ciphertext()
+ * - Use function: k= ey_state_read_ciphertext()
* - If plaintext can be extrac= ted from the plaintext-side of the SSL-BIO:
* - Pass it= on to the \link control_processor Control Channel
* = Processor\endlink for local processing.
- * - Use function: \c key_state_read_plaintext()=
+ * - Use function: key_s= tate_read_plaintext()
* - If plaintext from the \link con= trol_processor Control Channel
* Processor\endlink is a= vailable to be sent to the remote peer:
* - Insert it i= nto the plaintext-side of the SSL-BIO.
- * - Use function: \c key_state_write_plaintext() or \c<= /span>
+ * - Use function:= key_state_write_plaintext() or
* key_state_write_pla= intext_const()
*
* @par Transport Layer= Security protocol implementation
@@ -98,7 +98,7 @@<= br> * @par
* For more information on the OpenSSL l= ibrary's BIO objects, please see:
* - OpenSSL's = generic BIO objects:
- = * http://www.openssl.org/docs/crypto/bio.html
+ * https://docs.openssl.org/master/man7/bio= /#bio
* - OpenSSL's SSL-BIO object:
- * http://www.openssl.org/docs/cryp= to/BIO_f_ssl.html
+ *= https://docs.openssl.org/master/man3/BIO_f_ssl/#bio_f_ssl
*/

diff --git a/src/openvpn/tls_crypt.h b/src/openvpn/= tls_crypt.h
index 1a604ce..87e9867 100644
-= -- a/src/openvpn/tls_crypt.h
+++ b/src/openvpn/tls_crypt.h<= /span>
@@ -22,11 +22,11 @@
*/
<= /span>
/**
- = * @defgroup tls_crypt Control channel encryption (--tls-crypt, --tls-crypt-= v2)
+ * @defgroup tls= _crypt Control channel encryption (tls-crypt, tls-crypt-v2)
* @ingroup control_tls

* @{
*=
- * Control channel encryptio= n uses a pre-shared static key (like the --tls-auth
+ * Control channel encryption uses a pre-= shared static key (like the @c --tls-auth
* key) to encry= pt control channel packets.
*
* Encrypt= ing control channel packets has three main advantages:
@@ -= 36,8 +36,8 @@
* - It provides "poor-man's"= post-quantum security, against attackers who
* will n= ever know the pre-shared key (i.e. no forward secrecy).
*=
- * --tls-crypt uses a= tls-auth-style group key, where all servers and clients
- * share the same group key. --tls-crypt= -v2 adds support for client-specific
+ * @c --tls-crypt uses a tls-auth-style group key, where a= ll servers and clients
- * Initialize a k= ey_ctx_bi structure for use with --tls-crypt.
+ * Initialize a key_ctx_bi structure for use with= @c --tls-crypt.
*
* @param key = The key context to initialize
* @param key_file T= he file to read the key from or the key itself if
@@ -141,7= +141,7 @@
* @param dst Any data present in this buffer= is first authenticated, then
* the wrapped = packet id and data from the src buffer are appended.
* = Must have at least tls_crypt_buf_overhead()+BLEN(src) headroom.<= /span>
- * @param opt The cr= ypto state for this --tls-crypt instance.
+ * @param opt The crypto state for this @c --tls-cr= ypt instance.
*
* @returns true iff wra= pping succeeded.
*/
@@ -154,7 +154,7 @@
*
* @param src Data to decrypt and aut= henticate.
* @param dst Returns the decrypted data, if = unwrapping was successful.
- * @param opt The crypto state for this --tls-crypt instance.=
+ * @param opt The crypto= state for this @c --tls-crypt instance.
*
* @returns true iff unwrapping succeeded (data authenticated correctly = and was

* no replay).

To view, visit change 936. To unsubscribe, or for help writing mail filters, vi= sit settings.

Gerrit-Project: openvpn
Gerrit-Branch: master
Gerrit-Change-Id: I9a27248557fabcd9f7584deb4ab= a16cd71fb803c
Gerrit-Change-Number: 936
Gerrit-PatchSet: 2
Gerrit-Owner: flichtenheld <frank@...2723...= .>
Gerrit-Reviewer: plaisthos <arne-openvpn@...1186...= .1227...>
Gerrit-CC: openvpn-devel <openvpn-devel@...1484...= ts.sourceforge.net>
Gerrit-MessageType: merged
--VbfJw0Ark+4=--