summaryrefslogtreecommitdiff
path: root/doc/management-notes.txt
diff options
context:
space:
mode:
authorBernhard Schmidt <berni@debian.org>2020-08-15 21:29:54 +0200
committerBernhard Schmidt <berni@debian.org>2020-08-15 21:29:54 +0200
commit7c229d538824cb679351220ad8911f7b2daa7c23 (patch)
tree5c4d64b60da9018c7db3a9335a9787d326beade3 /doc/management-notes.txt
parentd3986a312f5fbcfd0e78e6b147eef419fb4e5f54 (diff)
parent1079962e4c06f88a54e50d997c1b7e84303d30b4 (diff)
Update upstream source from tag 'upstream/2.5_beta1'
Update to upstream version '2.5~beta1' with Debian dir d53f9a482ac24eb491a294b26c24bb1d87afad24
Diffstat (limited to 'doc/management-notes.txt')
-rw-r--r--doc/management-notes.txt171
1 files changed, 162 insertions, 9 deletions
diff --git a/doc/management-notes.txt b/doc/management-notes.txt
index 96a0d7d..61daaf0 100644
--- a/doc/management-notes.txt
+++ b/doc/management-notes.txt
@@ -465,8 +465,12 @@ Command examples:
COMMAND -- version
------------------
-Show the current OpenVPN and Management Interface versions.
+Set the version (integer) of Management Interface supported by the
+client or show the current OpenVPN and Management Interface versions.
+Command examples:
+ version 2 -- Change management version of client to 2 (default = 1)
+ version -- Show the version of OpenVPN and its Management Interface
COMMAND -- auth-retry
---------------------
@@ -588,6 +592,92 @@ interface to approve client connections.
CID,KID -- client ID and Key ID. See documentation for ">CLIENT:"
notification for more info.
+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.
+
+ client-pending-auth {CID} {EXTRA}
+
+The server will send AUTH_PENDING and INFO_PRE,{EXTRA} to the client.
+The client is expected to inform the user that authentication is pending and
+display the extra information. For the format of EXTRA see below
+For the OpenVPN server this is 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
+continue authentication. A client supporting the first two methods would
+set
+
+ setenv IV_SSO openurl,crtext
+
+The variable name IV_SSO is historic as AUTH_PENDING was first used
+to signal single sign on support. To keep compatiblity with existing
+implementations the name IV_SSO is kept in lieu of a better name.
+
+openurl
+========
+For a web based extra authentication (like for
+SSO/SAML) EXTRA should be
+
+ OPEN_URL:url
+
+and client should ask to 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
+to the longer URL should be sent instead.
+
+url_proxy
+========
+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
+
+ PROXY_URL:<proxy>:<proxy_port>:<proxyuser_base64>:<proxy_password_base64>: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
+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
+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
+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.
+
+crtext
+=======
+
+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 <flags>
+and <challgenge_text> fields are used:
+
+ CR_TEXT:<flags>:<challenge_text>
+
+<flags>: a series of optional, comma-separated flags:
+ E : echo the response when the user types it.
+ R : a response is required.
+
+<challenge_text>: the challenge text to be shown to the user.
+
+
+
COMMAND -- client-deny (OpenVPN 2.1 or higher)
-----------------------------------------------
@@ -802,34 +892,69 @@ To accept connecting to the host and port directly, use this command:
proxy NONE
-COMMAND -- rsa-sig (OpenVPN 2.3 or higher)
-------------------------------------------
+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:
+
+ 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?".
+
+
+COMMAND -- pk-sig (OpenVPN 2.5 or higher, management version > 1)
+COMMAND -- rsa-sig (OpenVPN 2.3 or higher, management version <= 1)
+-----------------------------------------------------------------
Provides support for external storage of the private key. Requires the
--management-external-key option. This option can be used instead of "key"
in client mode, and allows the client to run without the need to load the
-actual private key. When the SSL protocol needs to perform an RSA sign
+actual private key. When the SSL protocol needs to perform a sign
operation, the data to be signed will be sent to the management interface
via a notification as follows:
->RSA_SIGN:[BASE64_DATA]
+>PK_SIGN:[BASE64_DATA],[ALG] (if client announces support for management version > 2)
+>PK_SIGN:[BASE64_DATA] (if client announces support for management version > 1)
+>RSA_SIGN:[BASE64_DATA] (only older clients will be prompted like this)
-The management interface client should then create a PKCS#1 v1.5 signature of
+The management interface client should then create an appropriate signature of
the (decoded) BASE64_DATA using the private key and return the SSL signature as
follows:
-rsa-sig
+pk-sig (or rsa-sig)
[BASE64_SIG_LINE]
.
.
.
END
-Base64 encoded output of RSA_private_encrypt() (OpenSSL) or mbedtls_pk_sign()
-(mbed TLS) will provide a correct signature.
+Base 64 encoded output of RSA_private_encrypt for RSA or ECDSA_sign()
+for EC using OpenSSL or mbedtls_pk_sign() using mbed TLS will provide a
+correct signature.
+The rsa-sig interface expects PKCS1 padded signatures for RSA keys
+(RSA_PKCS1_PADDING). EC signatures are always unpadded.
This capability is intended to allow the use of arbitrary cryptographic
service providers with OpenVPN via the management interface.
+New and updated clients are expected to use the version command to announce
+a version > 1 and handle '>PK_SIGN' prompt and respond with 'pk-sig'.
+
+The signature algorithm is indicated in the PK_SIGN request only if the
+management client-version is > 2. In particular, to support TLS1.3 and
+TLS1.2 using OpenSSL 1.1.1, unpadded signature support is required and this
+can be indicated in the signing request only if the client version is > 2"
+
+The currently defined padding algorithms are:
+
+ - RSA_PKCS1_PADDING - PKCS1 padding and RSA signature
+ - RSA_NO_PADDING - No padding may be added for the signature
+ - ECDSA - EC signature.
+
+
COMMAND -- certificate (OpenVPN 2.4 or higher)
----------------------------------------------
Provides support for external storage of the certificate. Requires the
@@ -969,6 +1094,34 @@ CLIENT notification types:
>CLIENT:ADDRESS,{CID},{ADDR},{PRI}
+(5) Text based challenge/Response
+
+ >CLIENT:CR_RESPONSE,{CID},{KID},{response_base64}
+ >CLIENT:ENV,name1=val1
+ >CLIENT:ENV,name2=val2
+ >CLIENT:ENV,...
+ >CLIENT:ENV,END
+
+ Using 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
+ 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.
+
+ 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
+ before or if multiple CR responses were sent from the client or if
+ 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
+ response. Mechanisms that need multiple rounds or more complex answers
+ should implement a different response type than CR_RESPONSE.
+
+
Variables:
CID -- Client ID, numerical ID for each connecting client, sequence = 0,1,2,...