From: "flichtenheld (Code Review)" Date: Wed, 9 Apr 2025 09:57:59 +0000 References: Reply-To: frank@...2641..., arne-openvpn@...1227..., openvpn-devel@lists.sourceforge.net Message-ID: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Disposition: inline Content-Type: multipart/alternative; boundary="3CtGaLwvflU="; 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: plaisthos Cc: openvpn-devel --3CtGaLwvflU= Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Attention is currently required from: plaisthos. Hello plaisthos, I'd like you to do a code review. Please visit http://gerrit.openvpn.net/c/openvpn/+/936?usp=3Demail to review the following change. 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 --- M doc/doxygen/doc_control_tls.h M src/openvpn/tls_crypt.h 2 files changed, 16 insertions(+), 16 deletions(-) git pull ssh://gerrit.openvpn.net:29418/openvpn refs/changes/36/936/1 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: 1 Gerrit-Owner: flichtenheld Gerrit-Reviewer: plaisthos Gerrit-CC: openvpn-devel Gerrit-Attention: plaisthos Gerrit-MessageType: newchange --3CtGaLwvflU= Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable

Attention is currently required from: plaisthos.

flichtenheld would like plaisthos to review this change.

Vi= ew Change

Doxygen: Clean up tls-crypt documentation

- Fix broken= links to OpenSSL documentation
- Remove some unnecessary \c for functio= n names.
Doxygen does handle them automatically.
- Add some \c for = --option since otherwise --
gets converted to one character (e.g. &= ;ndash; in
HTML).

Change-Id: I9a27248557fabcd9f7584deb4aba16cd7= 1fb803c
Signed-off-by: Frank Lichtenheld <frank@...2641...>
---=
M doc/doxygen/doc_control_tls.h
M src/openvpn/tls_crypt.h
2 files= changed, 16 insertions(+), 16 deletions(-)

git pull ssh://gerrit=
.openvpn.net:29418/openvpn refs/changes/36/936/1
diff --git a/doc/d=
oxygen/doc_control_tls.h b/doc/doxygen/doc_control_tls.h
in= dex 7ff5e99..3c92a76 100644
--- a/doc/doxygen/doc_control_t= ls.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 th= e \c verify_callback() function.
+ * documentation for the verify_callback() function. *
* @par
* In other words, thi= s module takes care of the confidentiality and
@@ -61,7 +61= ,7 @@
* Because of the one-to-one relationship between co= ntrol channel TLS
* state and \c key_state structures, th= e initialization and cleanup of an
* instance of the Cont= rol Channel TLS module's state happens within the
- * \c key_state_init() and \c key_state_fre= e() functions. In other words,
+ * key_state_init() and key_state_free() functions. In other w= ords,
* each \c key_state object contains exactly one Ope= nSSL SSL-BIO object,
* which is initialized and cleaned u= p together with the rest of the \c
* key_state object.
@@ -69,26 +69,26 @@
* @par Packet processin= g functions
* This object behaves somewhat like a black b= ox with a ciphertext and a
* plaintext I/O port. Its inte= raction with OpenVPN's control channel
- * during operation takes place within the \c tls_proc= ess() 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 p= ackets:
* - If ciphertext received from the remote peer i= s available in the \link
* reliable Reliability Layer\e= ndlink:
* - Insert it into the ciphertext-side of the S= SL-BIO.
- * - Use fun= ction: \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_cipherte= xt()
* - If plaintext can be extracted from the plaintext= -side of the SSL-BIO:
* - Pass it on to the \link contr= ol_processor Control Channel
* Processor\endlink for = local processing.
- * = - Use function: \c key_state_read_plaintext()
+ * - Use function: key_state_read_plaintext()<= /span>
* - 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_plai= ntext() or
* key_state_write_plaintext_const()=
*
* @par Transport Layer Security protocol im= plementation
@@ -98,7 +98,7 @@
* @par
* For more information on the OpenSSL library's BIO obje= cts, please see:
* - OpenSSL's generic BIO objects:<= /span>
- * http://www.opens= sl.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.open= ssl.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
@@ -2= 2,11 +22,11 @@
*/

/**<= /span>
- * @defgroup tls_crypt= Control channel encryption (--tls-crypt, --tls-crypt-v2)
+ * @defgroup tls_crypt Control channe= l encryption (tls-crypt, tls-crypt-v2)
* @ingroup control= _tls
* @{
*
- * Control channel encryption uses a pre-shared s= tatic key (like the --tls-auth
+ * Control channel encryption uses a pre-shared static key (like= the @c --tls-auth
* key) to encrypt control channel pack= ets.
*
* Encrypting control channel pac= kets has three main advantages:
@@ -36,8 +36,8 @@ * - It provides "poor-man's" post-quantum security,= against attackers who
* will never know the pre-share= d 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 c= lient-specific
+ * @c= --tls-crypt uses a tls-auth-style group key, where all servers and clients=
+ * share the same g= roup key. @c --tls-crypt-v2 adds support for client-specific
* keys, where all servers share the same client-key encryption key, and= each

* clients receives a unique client key, both in pla= intext and in encrypted
* form. When connecting to a ser= ver, the client sends the encrypted key to
@@ -103,7 +103,7= @@
+ = sizeof(uint16_t)))

/**
- * Initialize a key_ctx_bi structure fo= r 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 ke= y from or the key itself if
@@ -141,7 +141,7 @@
<= span> * @param dst Any data present in this buffer is first authenticate= d, then

* the wrapped packet id and data fro= m the src buffer are appended.
* Must have a= t least tls_crypt_buf_overhead()+BLEN(src) headroom.
- * @param opt The crypto state for this -= -tls-crypt instance.
= + * @param opt The crypto state for this @c --tls-crypt instance.<= br> *
* @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 succes= sful.
- * @param opt = The crypto state for this --tls-crypt instance.
+ * @param opt The crypto state for this @c --= tls-crypt instance.
*
* @returns true i= ff unwrapping succeeded (data authenticated correctly and was
* no replay).


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

Gerrit-Project: openvpn
Gerrit-Branch: master
Gerrit-Change-Id: I9a27248557fabcd9f7584deb4ab= a16cd71fb803c
Gerrit-Change-Number: 936
Gerrit-PatchSet: 1
Gerrit-Owner: flichtenheld <frank@...2723...= .>
Gerrit-Reviewer: plaisthos <arne-openvpn@...1186...= .1227...>
Gerrit-CC: openvpn-devel <openvpn-devel@...1484...= ts.sourceforge.net>
Gerrit-Attention: plaisthos <arne-openvpn@...220...= ..1227...>
Gerrit-MessageType: newchange
--3CtGaLwvflU=--