From patchwork Tue Apr 15 15:57:11 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gert Doering X-Patchwork-Id: 4222 Return-Path: Delivered-To: patchwork@openvpn.net Received: by 2002:a05:7001:2e0a:b0:63e:cbae:3930 with SMTP id ry10csp2575483mab; Tue, 15 Apr 2025 08:57:52 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCUkpPtTYIUZhFmAASkknMFHeVBNWjLVUZpZDyryq3sV9iQ2ZxrcZQ7tKw0PNw/xdY8LU/lyRLklRF4=@openvpn.net X-Google-Smtp-Source: AGHT+IFv7R9g0piWgieNY9N40UJqwfRocN87PF61pw6tyIPM9hbenXmAh9GJzGtCP4qAvxNhsgpJ X-Received: by 2002:a05:6e02:3092:b0:3d3:f27a:9103 with SMTP id e9e14a558f8ab-3d7ec1ca09amr178485855ab.1.1744732672132; Tue, 15 Apr 2025 08:57:52 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1744732672; cv=none; d=google.com; s=arc-20240605; b=RmQ9uAVVzbj9wxZJzaMDGabbKhYcg749Crbt/J8Y9czHmiQO9uCRosYUSwz/nHyZtz bqNh2+lFvZNS+s5wblSuRpgTdXmawsGZM+H+7pVyTYWeyAltND8y/EtGNTkzWVhAYhgX nocHliT+xh6X71ypgfk75lI8aOi/1PuibPBpxlJZcd6U0KzYGh2qn1hK3NGcWFhpP3Zn /LiujfHASiI29JaTaF4/nW28Je/QN200Sp6AekgDY5uCQ4oEc5t27DfZ9cJw7xbH0FZV ozMSXu15eOLeXsXaqIXqYm6Ba08fmY1j2LYazhFvSHV0rkqETxF+YSFXj3V1cmHdYeqa hKDA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20240605; h=errors-to:content-transfer-encoding:list-subscribe:list-help :list-post:list-archive:list-unsubscribe:list-id:precedence:subject :mime-version:references:in-reply-to:message-id:date:to:from :dkim-signature:dkim-signature; bh=43E4f/CbRW7dqGyw2m2tWJvNPkCjA1aYe9BsTVYOfek=; fh=4NbAC/LsuMLI0S0hprUlLSLCiHwg6SCAifhH718Jh0Q=; b=kkudQNvFSoqhclVhSTtxjywe5+IRnds35aiw4/8ZymI3qqaz+caB2vg9cPH/DFGAbb 3F5RoqmfklpPb397DqsK7Ic/nYqUAf05+PfBBDga0pXlZjZfZYPmYFcqBImNYSRfSgXr WLUurPQCEGVkzJPx9Hl86hyZaHPV9GgowsB5ykLYWzV8JYXKGYS7CH0Kw1tW0f8SrlPY UhYo8xz9YAKwiiDyQ3zTsmw8OPBkBlIimTi3/gnkv95Q2Fp8F66eEF3vN4Ig0NVIfRqx WEwhRd9FXBu2+FgcFz0VutRhgowqMSDTSKMrk2uvfLpYWPHtUH1R1+OPPkpZR4dXFTuw wvbQ==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@sourceforge.net header.s=x header.b=R8tEICDV; dkim=neutral (body hash did not verify) header.i=@sf.net header.s=x header.b=eEfsj7qX; spf=pass (google.com: domain of openvpn-devel-bounces@lists.sourceforge.net designates 216.105.38.7 as permitted sender) smtp.mailfrom=openvpn-devel-bounces@lists.sourceforge.net; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=muc.de Received: from lists.sourceforge.net (lists.sourceforge.net. [216.105.38.7]) by mx.google.com with ESMTPS id e9e14a558f8ab-3d7dc5a5ba7si134818345ab.151.2025.04.15.08.57.51 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Tue, 15 Apr 2025 08:57:52 -0700 (PDT) Received-SPF: pass (google.com: domain of openvpn-devel-bounces@lists.sourceforge.net designates 216.105.38.7 as permitted sender) client-ip=216.105.38.7; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@sourceforge.net header.s=x header.b=R8tEICDV; dkim=neutral (body hash did not verify) header.i=@sf.net header.s=x header.b=eEfsj7qX; spf=pass (google.com: domain of openvpn-devel-bounces@lists.sourceforge.net designates 216.105.38.7 as permitted sender) smtp.mailfrom=openvpn-devel-bounces@lists.sourceforge.net; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=muc.de Received: from [127.0.0.1] (helo=sfs-ml-2.v29.lw.sourceforge.com) by sfs-ml-2.v29.lw.sourceforge.com with esmtp (Exim 4.95) (envelope-from ) id 1u4ifV-0005hr-0r; Tue, 15 Apr 2025 15:57:49 +0000 Received: from [172.30.29.66] (helo=mx.sourceforge.net) by sfs-ml-2.v29.lw.sourceforge.com with esmtps (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.95) (envelope-from ) id 1u4ifU-0005hl-AB for openvpn-devel@lists.sourceforge.net; Tue, 15 Apr 2025 15:57:49 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sourceforge.net; s=x; h=Content-Transfer-Encoding:MIME-Version:References: In-Reply-To:Message-ID:Date:Subject:To:From:Sender:Reply-To:Cc:Content-Type: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=m6wFrmPZrLiW/SZDgTM8p8M7tmWfMD1jru4gKibdb0M=; b=R8tEICDVAGo282CDLWWsw0dLCh YbFZK2rf0yWpPMFCR1vN9rgg/fLwVmwb+g3hgGzMYOYCOrItuGS9h7yaKh7fYo9m5+y/0B6m/1dNz mTXXg1hmcZz1mDCWVYw3eqNlT1suKxufPXmSNiDSSp0l3Qja79CqY7SYe5/ZZvLyLJy4=; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sf.net; s=x ; h=Content-Transfer-Encoding:MIME-Version:References:In-Reply-To:Message-ID: Date:Subject:To:From:Sender:Reply-To:Cc:Content-Type:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=m6wFrmPZrLiW/SZDgTM8p8M7tmWfMD1jru4gKibdb0M=; b=eEfsj7qX6kWA/pFm7ezpF6KVVY Hzo5IW4WM4CJ5GeozfLrQ4p3I47ygEWM0JvMKD/OS7p1lQyaLIinamFM3GT82LPeX2eY2XgUlYFLp jOYo6M8v45rpRnndObk4QWB26Vh5f0h7off9WHIeitNwtoLZQPEx4i1KIC4mOeMozQA4=; Received: from [193.149.48.143] (helo=blue.greenie.muc.de) by sfi-mx-2.v28.lw.sourceforge.com with esmtps (TLS1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.95) id 1u4ifE-0005KK-OO for openvpn-devel@lists.sourceforge.net; Tue, 15 Apr 2025 15:57:48 +0000 Received: from blue.greenie.muc.de (localhost [127.0.0.1]) by blue.greenie.muc.de (8.17.1.9/8.17.1.9) with ESMTP id 53FFvLGH013053 for ; Tue, 15 Apr 2025 17:57:21 +0200 Received: (from gert@localhost) by blue.greenie.muc.de (8.17.1.9/8.17.1.9/Submit) id 53FFvLen013052 for openvpn-devel@lists.sourceforge.net; Tue, 15 Apr 2025 17:57:21 +0200 From: Gert Doering To: openvpn-devel@lists.sourceforge.net Date: Tue, 15 Apr 2025 17:57:11 +0200 Message-ID: <20250415155720.13034-1-gert@greenie.muc.de> X-Mailer: git-send-email 2.49.0 In-Reply-To: References: MIME-Version: 1.0 X-Spam-Score: 1.7 (+) X-Spam-Report: Spam detection software, running on the system "util-spamd-2.v13.lw.sourceforge.com", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: From: Frank Lichtenheld - 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 [...] Content analysis details: (1.7 points, 6.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- 0.4 NO_DNS_FOR_FROM DNS: Envelope sender has no MX or A DNS records 0.0 RCVD_IN_VALIDITY_SAFE_BLOCKED RBL: ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. [193.149.48.143 listed in sa-trusted.bondedsender.org] 0.0 SPF_NONE SPF: sender does not publish an SPF Record 0.0 RCVD_IN_VALIDITY_RPBL_BLOCKED RBL: ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. [193.149.48.143 listed in bl.score.senderscore.com] 0.0 SPF_HELO_FAIL SPF: HELO does not match SPF record (fail) [SPF failed: Rejected by SPF record] 1.3 RDNS_NONE Delivered to internal network by a host with no rDNS X-Headers-End: 1u4ifE-0005KK-OO Subject: [Openvpn-devel] [PATCH v1] Doxygen: Clean up tls-crypt documentation X-BeenThere: openvpn-devel@lists.sourceforge.net X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: openvpn-devel-bounces@lists.sourceforge.net X-getmail-retrieved-from-mailbox: Inbox X-GMAIL-THRID: =?utf-8?q?1829484806626721885?= X-GMAIL-MSGID: =?utf-8?q?1829484806626721885?= From: Frank Lichtenheld - 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 --- This change was reviewed on Gerrit and approved by at least one developer. I request to merge it to master. Gerrit URL: https://gerrit.openvpn.net/c/openvpn/+/936 This mail reflects revision 1 of this Change. Acked-by according to Gerrit (reflected above): Arne Schwabe 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-crypt-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 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 all servers and clients + * share the same group 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 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, then * the wrapped packet id and data from the src buffer are appended. * Must have at 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. * * @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 and was * no replay).