From patchwork Tue Jun 1 17:42:52 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Selva Nair X-Patchwork-Id: 1843 Return-Path: Delivered-To: patchwork@openvpn.net Delivered-To: patchwork@openvpn.net Received: from director7.mail.ord1d.rsapps.net ([172.30.191.6]) by backend30.mail.ord1d.rsapps.net with LMTP id oFr1HrD+tmBDVQAAIUCqbw (envelope-from ) for ; Tue, 01 Jun 2021 23:44:48 -0400 Received: from proxy2.mail.ord1d.rsapps.net ([172.30.191.6]) by director7.mail.ord1d.rsapps.net with LMTP id OKLeHrD+tmDNdAAAovjBpQ (envelope-from ) for ; Tue, 01 Jun 2021 23:44:48 -0400 Received: from smtp1.gate.ord1d ([172.30.191.6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by proxy2.mail.ord1d.rsapps.net with LMTPS id cPWeHrD+tmBsCQAAfawv4w (envelope-from ) for ; Tue, 01 Jun 2021 23:44:48 -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: smtp1.gate.ord1d.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; dkim=fail (signature verification failed) header.d=gmail.com; dmarc=fail (p=none; dis=none) header.from=gmail.com X-Suspicious-Flag: YES X-Classification-ID: e07e17d4-c354-11eb-b44f-5254002d775b-1-1 Received: from [216.105.38.7] ([216.105.38.7:32948] helo=lists.sourceforge.net) by smtp1.gate.ord1d.rsapps.net (envelope-from ) (ecelerity 4.2.38.62370 r(:)) with ESMTPS (cipher=DHE-RSA-AES256-GCM-SHA384) id 7D/6B-00415-FAEF6B06; Tue, 01 Jun 2021 23:44:48 -0400 Received: from [127.0.0.1] (helo=sfs-ml-4.v29.lw.sourceforge.com) by sfs-ml-4.v29.lw.sourceforge.com with esmtp (Exim 4.90_1) (envelope-from ) id 1loHnC-0002IH-BQ; Wed, 02 Jun 2021 03:43:42 +0000 Received: from [172.30.20.202] (helo=mx.sourceforge.net) by sfs-ml-4.v29.lw.sourceforge.com with esmtps (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.90_1) (envelope-from ) id 1loHnA-0002IA-TK for openvpn-devel@lists.sourceforge.net; Wed, 02 Jun 2021 03:43:40 +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:Cc:To:From:Sender:Reply-To: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=l4gBdQPDyULQSrzDthEPFD9TCFZPYgv0jU2NzRKF9iY=; b=mi0Y5o3CdRnBltySWelp/7ozzK e0G3Z4tAGaKX7EypAGAOozHU+SHNLBBSGCBEz3uKhCODmVJyP4y+1Ip5ybxmNWSikwtKgwSPjgy68 ZMBZBlA68bXmvp/IRtBr1d7CaULbZXZM+uHHkmAE08kKRPibE7zXGud2deELlq1q+5Nk=; 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:Cc:To:From:Sender:Reply-To: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=l4gBdQPDyULQSrzDthEPFD9TCFZPYgv0jU2NzRKF9iY=; b=X7MzlGy+4IAroEJOcQlVTwlsh/ LlPjIcmtsQ7TOL+rVtismaahg6Eq52Ae4nnapmL5yitXG3K5nRmIKBcSXlQ1a3GdATSsZQGuQ9KyT bzGKncLcBByzdR8IcOlr4OlrRPa7RgvE4BF546zSK13ZTheMXcMEWm1U0DUXT+50AP3k=; Received: from mail-qt1-f181.google.com ([209.85.160.181]) by sfi-mx-2.v28.lw.sourceforge.com with esmtps (TLSv1.2:ECDHE-RSA-AES128-GCM-SHA256:128) (Exim 4.92.3) id 1loHn3-0004PQ-Tv for openvpn-devel@lists.sourceforge.net; Wed, 02 Jun 2021 03:43:42 +0000 Received: by mail-qt1-f181.google.com with SMTP id g17so887755qtk.9 for ; Tue, 01 Jun 2021 20:43:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=l4gBdQPDyULQSrzDthEPFD9TCFZPYgv0jU2NzRKF9iY=; b=jyyhgfnpCwmShHQ9WBa1cN3XZOkqSJAgb9GY+1dMl88Q7eotehNOmepgaY7u6jPd5c yre2l/Q3cnm1rZp1cwAYfXPrexJMFBMZUy1kdtYya05hK6bt4z9glhTzq5x8DNpKy9Zc 0XF5fkifsEaDfWI8yH89llqDUIGxs6+09bHxBlMfvBeDWpsPHZxF3tBCi1syZR/JvpId frOj05kDpzJtleoVv/znisVYjNgki1oxLxDDT5O6CfhjNvo9WygrPSIPOHTUy72aUUW1 nejGQqMlom0sY4yWIl2ps9imaVMQrssFxbcMO9ti7eVkWosRHfaz/OdtAjLSNs1H2/Fn 7x7g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=l4gBdQPDyULQSrzDthEPFD9TCFZPYgv0jU2NzRKF9iY=; b=JiwE6HE8hgk7uyFHCQ799/TwGSybI/ArKiyaD4ybZoTrQB9RPLjNEXWaijqbpYEksw QxhA+MIIVu9a+0Rzjw7BSLs60gyZE4iD1zrxjGa1p4hGx2kMjpA2cnvrOOJ8Fv6zWwQV dTMvmRgbzp0HBMXfVFTTFLT5JXDVJI03LYRKfjktN4R2tCKiKTXv2Do229DEgoBHV59s oNbk7KHYkRKdtdIvxLy+DVHAiRIbf19Sf7DLj9pgI8ehzvEz8rzTAqLK5aZF42cC31dl b2e+DYAYpeG9yqG6epCSdF1vMlJODakdhrAIsKE9LoQEYS1p026RxAy0jZUlcWqusyNM 525Q== X-Gm-Message-State: AOAM531KiHSeIO7+pihdM4iy4o1jtb+QxEXHd7Dk3XDuUk0w+HMEiH48 3YWCm7beCsv7bjXfzjBCv5LS7lGBf8yC5A== X-Google-Smtp-Source: ABdhPJy6wQh3RzBn33K+KbXmsvcNljk1DAP+NEjZLU6uwWg3ND3XhdCOnAo48q8zM4NsB3Gth+5LiA== X-Received: by 2002:ac8:6885:: with SMTP id m5mr9926709qtq.268.1622605406349; Tue, 01 Jun 2021 20:43:26 -0700 (PDT) Received: from uranus.home.sansel.ca (bras-vprn-tnhlon4053w-lp130-01-70-51-222-236.dsl.bell.ca. [70.51.222.236]) by smtp.gmail.com with ESMTPSA id d18sm476592qka.96.2021.06.01.20.43.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 01 Jun 2021 20:43:25 -0700 (PDT) From: selva.nair@gmail.com To: openvpn-devel@lists.sourceforge.net Date: Tue, 1 Jun 2021 23:42:52 -0400 Message-Id: <20210602034253.19984-2-selva.nair@gmail.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20210602034253.19984-1-selva.nair@gmail.com> References: <20210602034253.19984-1-selva.nair@gmail.com> MIME-Version: 1.0 X-Spam-Report: Spam Filtering performed by mx.sourceforge.net. See http://spamassassin.org/tag/ for more details. 0.0 FREEMAIL_FROM Sender email is commonly abused enduser mail provider (selva.nair[at]gmail.com) -0.0 RCVD_IN_DNSWL_NONE RBL: Sender listed at https://www.dnswl.org/, no trust [209.85.160.181 listed in list.dnswl.org] -0.0 SPF_PASS SPF: sender matches SPF record 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 0.0 RCVD_IN_MSPIKE_H3 RBL: Good reputation (+3) [209.85.160.181 listed in wl.mailspike.net] -0.1 DKIM_VALID_AU Message has a valid DKIM or DK signature from author's domain -0.1 DKIM_VALID Message has at least one valid DKIM or DK signature 0.1 DKIM_SIGNED Message has a DKIM or DK signature, not necessarily valid 0.0 RCVD_IN_MSPIKE_WL Mailspike good senders X-Headers-End: 1loHn3-0004PQ-Tv Subject: [Openvpn-devel] [PATCH 1/2] Improve documentation of AUTH_PENDING related directives 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 From: Selva Nair Also fix some typos. Signed-off-by: Selva Nair Acked-By: Arne Schwabe --- doc/man-sections/server-options.rst | 4 ++ doc/management-notes.txt | 101 +++++++++++++++++----------- 2 files changed, 67 insertions(+), 38 deletions(-) diff --git a/doc/man-sections/server-options.rst b/doc/man-sections/server-options.rst index 036323b9..047f2270 100644 --- a/doc/man-sections/server-options.rst +++ b/doc/man-sections/server-options.rst @@ -460,6 +460,10 @@ fast hardware. SSL/TLS authentication must be used in this mode. The UI version of a UI if one is running, for example :code:`de.blinkt.openvpn 0.5.47` for the Android app. + :code:`IV_SSO=[crtext,][openurl,][proxy_url]` + Additional authentication methods supported by the client. + This may be set by the client UI/GUI using ``--setenv`` + When ``--push-peer-info`` is enabled the additional information consists of the following data: diff --git a/doc/management-notes.txt b/doc/management-notes.txt index 3aff6eb6..9f064764 100644 --- a/doc/management-notes.txt +++ b/doc/management-notes.txt @@ -199,7 +199,7 @@ Command examples: COMMAND -- kill --------------- -In server mode, kill a particlar client instance. +In server mode, kill a particular client instance. Command examples: @@ -407,6 +407,7 @@ RECONNECTING -- A restart has occurred. EXITING -- A graceful exit is in progress. RESOLVE -- (Client only) DNS lookup TCP_CONNECT -- (Client only) Connecting to TCP server +AUTH_PENDING -- (Client only) Authentication pending Command examples: @@ -437,6 +438,11 @@ Fields (e)-(h) are shown for CONNECTED state, (e) is available starting from OpenVPN 2.1 (f)-(i) are available starting from OpenVPN 2.4 +For AUTH_PENDING, if (c) is present, it would read +as "timeout number" where number is the number of seconds +before authentication will timeout. It is printed as an +unsigned integer (%u). + Real-time state notifications will have a ">STATE:" prefix prepended to them. @@ -608,7 +614,7 @@ COMMAND -- client-pending-auth (OpenVPN 2.5 or higher) Instruct OpenVPN server to send AUTH_PENDING and INFO_PRE message to signal a pending authenticating to the client. A pending auth means that the connecting requires extra authentication like a one time -password or doing a single sign one via web. +password or doing a single sign on via web. client-pending-auth {CID} {EXTRA} {TIMEOUT} @@ -624,22 +630,22 @@ the timeout proposed by the server, even if the timeout is shorter. If the client does not receive a packet from the server for hand-window the connection times out regardless of the timeout. This ensures that the connection still times out relatively quickly in case of network problems. The client will -continously send PULL_REQUEST messages to the server until the timeout is reached. +continuously send PULL_REQUEST messages to the server until the timeout is reached. This message also triggers an ACK message from the server that resets the hand-window based timeout. Both client and server limit the maximum timeout to the smaller value of half the --tls-reneg minimum time and --hand-window time (defaults to 60s). -For the format of EXTRA see below. For the OpenVPN server this is a stateless +For the format of {EXTRA} see below. For OpenVPN server this is a stateless operation and needs to be followed by a client-deny/client-auth[-nt] command (that is the result of the out of band authentication). Before issuing a client-pending-auth to a client instead of a client-auth/client-deny, the server should check the IV_SSO -environment variable if the method is support. The currently -defined method are crtext for challenge/response using text -(e.g. TOTP), openurl and proxy_url for opening an URL in the client to +environment variable for whether the method is supported. Currently +defined methods are crtext for challenge/response using text +(e.g., TOTP), openurl and proxy_url for opening a URL in the client to continue authentication. A client supporting the first two methods would set @@ -649,17 +655,30 @@ The variable name IV_SSO is historic as AUTH_PENDING was first used to signal single sign on support. To keep compatibility with existing implementations the name IV_SSO is kept in lieu of a better name. +The management interface of the client receives notification of +pending auth via + +>STATE:datetime,AUTH_PENDING,[timeout number] + +If {EXTRA} is present the client is informed using INFOMSG +notification as + +>INFOMSG:{EXTRA} + +where {EXTRA} is formatted as received from the server. +Currently defined formats for {EXTRA} are detailed below. + openurl ======== For a web based extra authentication (like for -SSO/SAML) EXTRA should be +SSO/SAML) {EXTRA} should be OPEN_URL:url -and client should ask to the user to open the URL to continue. +and client should ask the user to open the URL to continue. The space in a control message is limited, so this url should be kept -short to avoid issues. If a loger url is required a URL that redirects +short to avoid issues. If a longer url is required a URL that redirects to the longer URL should be sent instead. A complete documentation how URLs should be handled on the client is available @@ -667,17 +686,18 @@ in the openvpn3 repository: https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md -url_proxy +proxy_url ======== -To avoid issues with OpenVPN connection persist-tun and not able -to reach the web server, a variant of openurl via a HTTPS -Proxy exists. The client should announce url_proxy in its IV_SSO -and parse the PROXY_URL message. The format is +This is a variant of openurl that allows opening a url via an +HTTP proxy. It could be used to avoid issues with OpenVPN connection's +persist-tun that may cause the web server to be unreachable. +The client should announce proxy_url in its IV_SSO and parse the +PROXY_URL message. The format of {EXTRA} in this case is PROXY_URL:::::url -The proxy should be a literal IPv4 address or IPv6 address in [] to avoid -ambiguity in parsing. A literal IP address is preferred as DNS might not be +The proxy should be a literal IPv4 address or IPv6 address enclosed in [] to avoid +ambiguity in parsing. A literal IP address is preferred as DNS might not be available when the client needs to open the url. The IP address will usually be the address that client uses to connect to the VPN server. For dual-homed VPN servers, the server should respond with the same address that the client @@ -685,19 +705,18 @@ connects to. This address is also usually excluded from being redirected over the VPN by a host route. If the platform (like Android) uses another way of protecting -the VPN connection routing loops the client needs to also exclude the +the VPN connection from routing loops, the client needs to also exclude the connection to the proxy in the same manner. Should another IP be used, then the VPN configuration should include a route -statement to exclude that route from being routed over the VPN. +statement to exclude that address from being routed over the VPN. crtext ======= - -The format of EXTRA is similar to the already used two step authentication +The format of {EXTRA} is similar to the already used two step authentication described in Challenge/Response Protocol section of this document. Since -most of the fields are not necessary or can be infered only the -and fields are used: +most of the fields are not necessary or can be inferred, only the +and fields are used: CR_TEXT:: @@ -707,7 +726,8 @@ and fields are used: : the challenge text to be shown to the user. - +The client should return the response to the crtext challenge +using the cr-response command. COMMAND -- client-deny (OpenVPN 2.1 or higher) ----------------------------------------------- @@ -925,17 +945,18 @@ To accept connecting to the host and port directly, use this command: COMMAND -- cr-response (OpenVPN 2.5 or higher) ------------------------------------------------- -Provides support for sending responses a challenge/response -query via INFOMSG,CR_TEXT. The response should be base64 encoded: +Provides support for sending responses to a challenge/response +query via INFOMSG,CR_TEXT (client-only). The response should +be base64 encoded: cr-response SGFsbG8gV2VsdCE= -The document is intended to be used after the client received a -CR_TEXT challenge (see send-pending-auth section). The answer is -the answer to the challenge and depends on the challenge itself -for a TOTP challenge this would the number encoded as base64 or -just a string for a challenge like "what day is it today?". - +This command is intended to be used after the client receives a +CR_TEXT challenge (see client-pending-auth section). The argument +to cr-response is the base64 encoded answer to the challenge and +depends on the challenge itself. For a TOTP challenge this would +a number encoded as base64; for a challenge like "what day is it today?" +it would be a string encoded as base64. COMMAND -- pk-sig (OpenVPN 2.5 or higher, management version > 1) COMMAND -- rsa-sig (OpenVPN 2.3 or higher, management version <= 1) @@ -1076,6 +1097,9 @@ PASSWORD -- Used to tell the management interface client that OpenVPN STATE -- Shows the current OpenVPN state, as controlled by the "state" command. +INFOMSG -- Authentication related info from server such as + CR_TEXT or OPEN_URL. See description under client-pending-auth + The CLIENT notification ----------------------- @@ -1133,14 +1157,15 @@ CLIENT notification types: >CLIENT:ENV,... >CLIENT:ENV,END - Using the cr-response command on the client side will trigger this + Use of the cr-response command on the client side will trigger this message on the server side. - CR_RESPONSE notification. The >CR_RESPONSE fulfils the same purpose as the + CR_RESPONSE notification fulfills the same purpose as the CRV1 response in the traditional challenge/response. See that section - below for more details. Since this still uses the same cid as the original - response, we do not use the username and opaque session data in this - response but only contains the actual response. + below for more details. Since this uses the same cid as in the original + client-pending-auth challenge, we do not include the username and opaque + session data in this notification. The string {response_base64} only contains + the actual response received from the client. It is important to note that OpenVPN2 merely passes the authentication information and does not do any further checks. (E.g. if a CR was issued @@ -1148,7 +1173,7 @@ CLIENT notification types: data has a valid base64 encoding) This interface should be be sufficient for almost all challenge/response - system that can be implemented with a single round and base64 encoding the + system that can be implemented with a single round and base64 encoding of the response. Mechanisms that need multiple rounds or more complex answers should implement a different response type than CR_RESPONSE.