From patchwork Mon Jul 20 04:27:03 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Arne Schwabe X-Patchwork-Id: 1316 Return-Path: Delivered-To: patchwork@openvpn.net Delivered-To: patchwork@openvpn.net Received: from director10.mail.ord1d.rsapps.net ([172.30.191.6]) by backend30.mail.ord1d.rsapps.net with LMTP id 2NyRO/qpFV/uGwAAIUCqbw for ; Mon, 20 Jul 2020 10:28:11 -0400 Received: from proxy12.mail.ord1d.rsapps.net ([172.30.191.6]) by director10.mail.ord1d.rsapps.net with LMTP id uLRhO/qpFV9FMwAApN4f7A ; Mon, 20 Jul 2020 10:28:10 -0400 Received: from smtp21.gate.ord1c ([172.30.191.6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by proxy12.mail.ord1d.rsapps.net with LMTP id uD82O/qpFV/vWgAA7PHxkg ; Mon, 20 Jul 2020 10:28:10 -0400 X-Spam-Threshold: 95 X-Spam-Score: 0 X-Spam-Flag: NO X-Virus-Scanned: OK X-Orig-To: openvpnslackdevel@openvpn.net X-Originating-Ip: [216.105.38.7] Authentication-Results: smtp21.gate.ord1c.rsapps.net; iprev=pass policy.iprev="216.105.38.7"; spf=pass smtp.mailfrom="openvpn-devel-bounces@lists.sourceforge.net" smtp.helo="lists.sourceforge.net"; dkim=fail (signature verification failed) header.d=sourceforge.net; dkim=fail (signature verification failed) header.d=sf.net; dmarc=none (p=nil; dis=none) header.from=rfc2549.org X-Suspicious-Flag: YES X-Classification-ID: 3be16612-ca95-11ea-a2dc-a0369f0d8808-1-1 Received: from [216.105.38.7] ([216.105.38.7:37752] helo=lists.sourceforge.net) by smtp21.gate.ord1c.rsapps.net (envelope-from ) (ecelerity 4.2.38.62370 r(:)) with ESMTPS (cipher=DHE-RSA-AES256-GCM-SHA384) id F3/FB-16318-9F9A51F5; Mon, 20 Jul 2020 10:28:09 -0400 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.90_1) (envelope-from ) id 1jxWlA-0006bh-0o; Mon, 20 Jul 2020 14:27:16 +0000 Received: from [172.30.20.202] (helo=mx.sourceforge.net) by sfs-ml-2.v29.lw.sourceforge.com with esmtps (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jxWl8-0006bS-MX for openvpn-devel@lists.sourceforge.net; Mon, 20 Jul 2020 14:27:14 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sourceforge.net; s=x; h=References:In-Reply-To:Message-Id:Date:Subject:Cc: To:From:Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: 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=pvd2wwovus+TMc24ca2K2nh9WLT9NHKWpHrHjjKYsF8=; b=l/p/CL6bgGc80L4VHFY0airnGd mz1FjvdI+BiIwz8eQF5ZgHPKRjxMfwIPJFPhB/0Y45z5Bh118VNd96UJVyxmfdzGO7LjMHKsETLxW HnclvPcgxyJfbXmXLzuJpvJwFI7sL5iBk25gA7tUxscRj7pXCyLK61YeFlkLI5Zx56KY=; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sf.net; s=x ; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender:Reply-To :MIME-Version:Content-Type:Content-Transfer-Encoding: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=pvd2wwovus+TMc24ca2K2nh9WLT9NHKWpHrHjjKYsF8=; b=KJWMfiCUSnDDxn/iA0v8DuVixa asKc3V7dWZ4i5bK3gXma6bPU7WFAkL4tDDMu5rGoshVhTOvDRdJbnHfiqG25wLn1EwNv0FOari6FL YkcGv86LM5P2Ysil9F8yY25Zo4KnIDgJc9cjV6J9leY4gjpuv7+m70J6GjHrQRWdxbPw=; Received: from mail.blinkt.de ([192.26.174.232]) by sfi-mx-3.v28.lw.sourceforge.com with esmtps (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.92.2) id 1jxWl5-00AtNt-CI for openvpn-devel@lists.sourceforge.net; Mon, 20 Jul 2020 14:27:14 +0000 Received: from kamera.blinkt.de ([2001:638:502:390:20c:29ff:fec8:535c]) by mail.blinkt.de with smtp (Exim 4.94 (FreeBSD)) (envelope-from ) id 1jxWkx-000IOu-TW; Mon, 20 Jul 2020 16:27:03 +0200 Received: (nullmailer pid 3372 invoked by uid 10006); Mon, 20 Jul 2020 14:27:03 -0000 From: Arne Schwabe To: openvpn-devel@lists.sourceforge.net Date: Mon, 20 Jul 2020 16:27:03 +0200 Message-Id: <20200720142703.3324-1-arne@rfc2549.org> X-Mailer: git-send-email 2.17.1 In-Reply-To: References: X-Spam-Report: Spam Filtering performed by mx.sourceforge.net. See http://spamassassin.org/tag/ for more details. 0.0 HEADER_FROM_DIFFERENT_DOMAINS From and EnvelopeFrom 2nd level mail domains are different 0.0 SPF_NONE SPF: sender does not publish an SPF Record 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 0.0 AWL AWL: Adjusted score from AWL reputation of From: address X-Headers-End: 1jxWl5-00AtNt-CI Subject: [Openvpn-devel] [PATCH v7] client-connect: Add documentation for the deferred client connect feature 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: , Cc: David Sommerseth MIME-Version: 1.0 Errors-To: openvpn-devel-bounces@lists.sourceforge.net X-getmail-retrieved-from-mailbox: Inbox Signed-off-by: David Sommerseth Signed-off-by: Arne Schwabe Patch V5: Fix typos, clarify man page section about deferred client-connect script. Add section to Changes.rst Patch V6: Convert manpage to rst It also incoroporates suggested changes from Richard Bonhomme [0] [0] Message-ID: <82c2d70f-e2f9-f810-2c55-788358a0cb08@gmail.com> URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg20331.html Patch V7: Reinclude the changes of Changes.rst and openvpn-plugin.h Clarify some parts of the documentation. Acked-by: Gert Doering --- Changes.rst | 5 +++++ doc/man-sections/generic-options.rst | 11 ++++++---- doc/man-sections/script-options.rst | 33 ++++++++++++++++++++++++++++ include/openvpn-plugin.h.in | 21 +++++++++++++----- 4 files changed, 60 insertions(+), 10 deletions(-) diff --git a/Changes.rst b/Changes.rst index 34abcd97..78a66650 100644 --- a/Changes.rst +++ b/Changes.rst @@ -25,6 +25,11 @@ Improved Data channel cipher negotiation Asynchronous (deferred) authentication support for auth-pam plugin. See src/plugins/auth-pam/README.auth-pam for details. +Deferred client-connect + The ``--client-connect`` option and the connect plugin API allow + asynchronous/deferred return of the configuration file in the same way + as the auth-plugin. + Deprecated features ------------------- For an up-to-date list of all deprecated options, see this wiki page: diff --git a/doc/man-sections/generic-options.rst b/doc/man-sections/generic-options.rst index d44dc05f..a07fe7e7 100644 --- a/doc/man-sections/generic-options.rst +++ b/doc/man-sections/generic-options.rst @@ -394,11 +394,14 @@ which mode OpenVPN is configured as. This directory will be used by in the following cases: - * ``--client-connect`` scripts to dynamically generate client-specific - configuration files. + * ``--client-connect`` scripts and :code:`OPENVPN_PLUGIN_CLIENT_CONNECT` + plug-in hook to dynamically generate client-specific configuration + :code:`client_connect_config_file` and return success/failure via + :code:`client_connect_deferred_file` when using deferred client connect + method - * :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plugin hook to return - success/failure via ``auth_control_file`` when using deferred auth + * :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plug-in hooks returns + success/failure via :code:`auth_control_file` when using deferred auth method * :code:`OPENVPN_PLUGIN_ENABLE_PF` plugin hook to pass filtering rules diff --git a/doc/man-sections/script-options.rst b/doc/man-sections/script-options.rst index ddc1363c..a1d489b8 100644 --- a/doc/man-sections/script-options.rst +++ b/doc/man-sections/script-options.rst @@ -137,6 +137,13 @@ SCRIPT HOOKS returns a non-zero error status, it will cause the client to be disconnected. + If a ``--client-connect`` wants to defer the generating of the + configuration then the script should use the + :code:`client_connect_deferred_file` and + :code:`client_connect_config_file` environment variables. And write + status accordingly into these files. See the `Environmental Variables`_ + section for more details. + --client-disconnect cmd Like ``--client-connect`` but called on client instance shutdown. Will not be called unless the ``--client-connect`` script and plugins (if @@ -512,6 +519,32 @@ instances. Total number of bytes sent to client during VPN session. Set prior to execution of the ``--client-disconnect`` script. +:code:`client_connect_config_file` + The path to the configuration file that should be written by the + ``--client-connect`` script. The content of this environment variable + is identical to the file as an argument of the called + ``--client-connect`` script. + +:code:`client_connect_deferred_file` + This file can be optionally written to to communicate a status code of + the ``--client-connect`` script. The first character in the file must + be either :code:`1` to indicate normal script execution, :code:`0` + indicates an error (in the same way that a non zero exit status does) + or :code:`2` to indicate that the script deferred returning the config + file. When the script defers returning the configuration, it must also + write :code:`2` to the file to indicate the deferral. + + A background process or similar must then take care of writing the + configuration to the file indicated by the + :code:`client_connect_config_file` environment variable and when + finished, write the a :code:`1` to this file (or :code:`0` in case of + an error). + + The absence of any character in the file when the script finishes + executing is interpreted the same as :code:`1`. This allows scripts + that are not written to support the defer mechanism to be used + unmodified. + :code:`common_name` The X509 common name of an authenticated client. Set prior to execution of ``--client-connect``, ``--client-disconnect`` and diff --git a/include/openvpn-plugin.h.in b/include/openvpn-plugin.h.in index 38fbe097..64b20886 100644 --- a/include/openvpn-plugin.h.in +++ b/include/openvpn-plugin.h.in @@ -557,12 +557,21 @@ OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_op * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure * * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by - * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY. This enables asynchronous - * authentication where the plugin (or one of its agents) may indicate - * authentication success/failure some number of seconds after the return - * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single - * char to the file named by auth_control_file in the environmental variable - * list (envp). + * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY, OPENVPN_PLUGIN_CLIENT_CONNECT and + * OPENVPN_PLUGIN_CLIENT_CONNECT_V2. This enables asynchronous + * authentication or client connect where the plugin (or one of its agents) + * may indicate authentication success/failure or client configuration some + * number of seconds after the return of the function handler. + * For OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY and OPENVPN_PLUGIN_CLIENT_CONNECT + * this is done by writing a single char to the file named by + * auth_control_file/client_connect_deferred_file + * in the environmental variable list (envp). + * + * In addition the OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER and + * OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER_V2 are called when OpenVPN tries to + * get the deferred result. For a V2 call implementing this function is + * required as information is not passed by files. For the normal version + * the call is optional. * * first char of auth_control_file: * '0' -- indicates auth failure