diff options
Diffstat (limited to 'doc/management-notes.txt')
| -rw-r--r-- | doc/management-notes.txt | 229 |
1 files changed, 219 insertions, 10 deletions
diff --git a/doc/management-notes.txt b/doc/management-notes.txt index 96a0d7d..c203442 100644 --- a/doc/management-notes.txt +++ b/doc/management-notes.txt @@ -137,6 +137,16 @@ history while simultaneously activating real-time updates: The size of the echo buffer is currently hardcoded to 100 messages. + +Generally speaking, the OpenVPN Core does not understand echo +messages at all (so a cooperating GUI and Server can use this +mechanism for arbitrary information transport). + +This said, a few echo commands have been agreed upon between the +community maintained OpenVPN Windows GUI and Tunnelblick for MacOS, +and documentation of these can be found in doc/gui-notes.txt. + + COMMAND -- exit, quit --------------------- @@ -189,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: @@ -397,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: @@ -427,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. @@ -465,8 +481,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 +608,127 @@ 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 on via web. + + client-pending-auth {CID} {EXTRA} {TIMEOUT} + +The server will send AUTH_PENDING and INFO_PRE,{EXTRA} to the client. If the +client supports accepting keywords to AUTH_PENDING (announced via IV_PROTO), +TIMEOUT parameter will be also be announced to the client to allow it to modify +its own timeout. The client is expected to inform the user that authentication +is pending and display the extra information and also show the user the +remaining time to complete the auth if applicable. + +Receiving an AUTH_PENDING message will make the client change its timeout to +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 +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 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 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 + + 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 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 + + OPEN_URL:url + +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 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 +in the openvpn3 repository: + +https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md + +proxy_url +======== +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:<proxy>:<proxy_port>:<proxyuser_base64>:<proxy_password_base64>:url + +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 +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 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 address 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 inferred, only the <flags> +and <challenge_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. + +The client should return the response to the crtext challenge +using the cr-response command. + COMMAND -- client-deny (OpenVPN 2.1 or higher) ----------------------------------------------- @@ -802,34 +943,70 @@ 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 to a challenge/response +query via INFOMSG,CR_TEXT (client-only). The response should +be base64 encoded: + + cr-response SGFsbG8gV2VsdCE= + +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 be +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) +----------------------------------------------------------------- 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 @@ -920,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 ----------------------- @@ -969,6 +1149,35 @@ 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 + + Use of the cr-response command on the client side will trigger this + message on the server side. + + 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 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 + 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 of 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,... |