diff options
Diffstat (limited to 'doc/management-notes.txt')
| -rw-r--r-- | doc/management-notes.txt | 171 |
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,... |