Clarify and expand the documentation for the management interface:
* Add examples of static and dynamic challenge/response sequences in
the "COMMAND -- password and username" section.
* Expand the "Challenge/Response" section with more detail.
* Use "management interface client" throughout (instead of "management
client", which was used in several places previously).
* Clarify when both a username and password are needed, not just a
username or a password.
* Clarify that an exit with a fatal error for a dynamic C/R will occur
only if "--auth-retry none" (the default) is in effect.
* Fix a typo. ("posesses" => "possesses").
Signed-off-by: Jonathan K. Bullard <jkbull...@gmail.com>
---
v2:
* Incorporate Selva Nair’s suggestions (thanks!).
* Remove incorrect quotes in Example 8.
* Use "base 64" throughout instead of "base64".
doc/management-notes.txt | 232 ++++++++++++++++++++++++++++++++---------------
1 file changed, 159 insertions(+), 73 deletions(-)
diff --git a/doc/management-notes.txt b/doc/management-notes.txt
index 96470d0..3935715 100644
--- a/doc/management-notes.txt
+++ b/doc/management-notes.txt
@@ -12,7 +12,8 @@ as a client or server.
The management interface is implemented using a client/server TCP
connection or unix domain socket where OpenVPN will listen on a
-provided IP address and port for incoming management client connections.
+provided IP address and port for incoming management interface client
+connections.
The management protocol is currently cleartext without an explicit
security layer. For this reason, it is recommended that the
@@ -104,7 +105,7 @@ be in the list, and it will cause the management interface
to save the "forget-passwords" string in its list of echo
parameters.
-The management client can use "echo all" to output the full
+The management interface client can use "echo all" to output the full
list of echoed parameters, "echo on" to turn on real-time
notification of echoed parameters via the ">ECHO:" prefix,
or "echo off" to turn off real-time notification.
@@ -118,10 +119,10 @@ like this:
Essentially the echo command allowed us to pass parameters from
the OpenVPN server to the OpenVPN client, and then to the
-management client (such as a GUI). The large integer is the
+management interface client (such as a GUI). The large integer is the
unix date/time when the echo parameter was received.
-If the management client had issued the command "echo on",
+If the management interface client had issued the command "echo on",
it would have enabled real-time notifications of echo
parameters. In this case, our "forget-passwords" message
would be output like this:
@@ -141,8 +142,8 @@ COMMAND -- exit, quit
Close the managment session, and resume listening on the
management port for connections from other clients. Currently,
-the OpenVPN daemon can at most support a single management client
-any one time.
+the OpenVPN daemon can at most support a single management interface
+client any one time.
COMMAND -- help
---------------
@@ -167,7 +168,7 @@ The hold flag setting is persistent and will not
be reset by restarts.
OpenVPN will indicate that it is in a hold state by
-sending a real-time notification to the management
+sending a real-time notification to the management interface
client, the parameter indicates how long OpenVPN would
wait without UI (as influenced by connect-retry exponential
backoff). The UI needs to wait for releasing the hold if it
@@ -275,7 +276,7 @@ COMMAND -- password and username
OpenVPN is indicating that it needs a password of type
"Private Key".
- The management client should respond to this query as follows:
+ The management interface client should respond as follows:
password "Private Key" foo
@@ -283,8 +284,8 @@ COMMAND -- password and username
>PASSWORD:Need 'Auth' username/password
- OpenVPN needs a --auth-user-pass password. The management
- client should respond:
+ OpenVPN needs a --auth-user-pass username and password. The
+ management interface client should respond:
username "Auth" foo
password "Auth" bar
@@ -307,7 +308,8 @@ COMMAND -- password and username
>PASSWORD:Verification Failed: 'Private Key'
Example 4: The --auth-user-pass username/password failed,
- and OpenVPN is exiting:
+ and OpenVPN will exit with a fatal error if '--auth-retry none'
+ (which is the default) is in effect:
>PASSWORD:Verification Failed: 'Auth'
@@ -322,6 +324,37 @@ COMMAND -- password and username
>PASSWORD:Auth-Token:foobar
+ Example 7: Static challenge/response:
+
+ >PASSWORD:Need 'Auth' username/password SC:1,Please enter token PIN
+
+ OpenVPN needs an --auth-user-pass username and password and the
+ response to a challenge. The user's response to "Please enter
+ token PIN" should be obtained and included in the management
+ interface client's response along with the username and password
+ formatted as described in the Challenge/Response Protocol section
+ below.
+
+ Example 8: Dynamic challenge/response:
+
+ >PASSWORD:Verification Failed:
['CRV1:R,E:Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l:Y3Ix:Please enter token PIN']
+
+ The previous --auth-user-pass username/password failed or is not
+ fully complete, and the server provided a custom
+ client-reason-text string indicating that a dynamic
+ challenge/response should occur the next time that a "Need 'Auth'
+ username/password" message is seen.
+
+ When the next "Need 'Auth' username/password" without a static
+ challenge is seen, the user's response to "Please enter token PIN"
+ should be obtained and included in the management interface client's
+ response along with the username and password formatted as described
+ in the Challenge/Response Protocol section below
+
+See the "Challenge/Response Protocol" section below for more details
+about examples 7 and 8, including how the management interface client
+should respond.
+
COMMAND -- forget-passwords
---------------------------
@@ -464,10 +497,10 @@ Example:
>NEED-OK:Need 'token-insertion-request' confirmation MSG:Please insert
your cryptographic token
- The management client, if it is a GUI, can flash a dialog
+ The management interface client, if it is a GUI, can flash a dialog
box containing the text after the "MSG:" marker to the user.
When the user acknowledges the dialog box,
- the management client can issue this command:
+ the management interface client should issue either:
needok token-insertion-request ok
or
@@ -486,10 +519,10 @@ Example:
>NEED-STR:Need 'name' input MSG:Please specify your name
- The management client, if it is a GUI, can flash a dialog
+ The management interface client, if it is a GUI, can flash a dialog
box containing the text after the "MSG:" marker to the user.
When the user acknowledges the dialog box,
- the management client can issue this command:
+ the management interface client should issue this command:
needstr name "John"
@@ -507,7 +540,7 @@ COMMAND -- pkcs11-id-get (OpenVPN 2.1 or higher)
-------------------------------------------------
Retrieve certificate by index, the ID string should be provided
-as PKCS#11 identity, the blob is BASE64 encoded certificate.
+as PKCS#11 identity, the blob is a base 64 encoded certificate.
Example:
@@ -797,9 +830,9 @@ pk-sig (or rsa-sig)
.
END
-Base64 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.
+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.
This capability is intended to allow the use of arbitrary cryptographic
service providers with OpenVPN via the management interface.
@@ -817,7 +850,7 @@ to the management interface with a hint as follows:
>NEED-CERTIFICATE:macosx-keychain:subject:o=OpenVPN-TEST
The management interface client should use the hint to obtain the specific
-SSL certificate and then return base64 encoded certificate as follows:
+SSL certificate and then return base 64 encoded certificate as follows:
certificate
[BASE64_CERT_LINE]
@@ -890,7 +923,7 @@ NEED-STR -- OpenVPN needs information from end, such as
a certificate to use. The "needstr" command can
be used to tell OpenVPN to continue.
-PASSWORD -- Used to tell the management client that OpenVPN
+PASSWORD -- Used to tell the management interface client that OpenVPN
needs a password, also to indicate password
verification failure.
@@ -988,70 +1021,116 @@ generate challenge questions that are shown to the
user, and to see
the user's responses to those challenges. Based on the responses, the
server can allow or deny access.
-In this way, the OpenVPN Challenge/Response Protocol can be used
-to implement multi-factor authentication. Two different
-variations on the challenge/response protocol are supported: the
-"Dynamic" and "Static" protocols.
+The protocol can be used to implement multi-factor authentication
+because the user must enter an additional piece of information,
+in addition to a username and password, to successfully authenticate.
+In multi-factor authentication, this information is used to prove
+that the user possesses a certain key-like device such as
+cryptographic token or a particular mobile phone.
+
+Two variations on the challenge/response protocol are supported:
+the "static" and "dynamic" protocols:
+
+ * The static protocol uses OpenVPN's "--static-challenge" option.
-The basic idea of Challenge/Response is that the user must enter an
-additional piece of information, in addition to the username and
-password, to successfully authenticate. Normally, this information
-is used to prove that the user posesses a certain key-like device
-such as cryptographic token or a particular mobile phone.
+ * The dynamic protocol does not involve special OpenVPN options
+ or actions. It is an agreement between the auth-user-pass
+ verification process on the server and the management interface
+ client to use custom strings that begin with "['CRV1" in
+ "Verification Failed" messages. (The "[" character and a matching
+ "]" character at the end of the message are added by the client
+ OpenVPN program, and are not present in the string generated by the
+ auth-user-pass verification process or in the string sent by the
+ server.)
Dynamic protocol:
The OpenVPN dynamic challenge/response protocol works by returning
a specially formatted error message after initial successful
-authentication. This error message contains the challenge question,
-and is formatted as such:
+authentication. The error message has two purposes:
+
+ 1. It causes OpenVPN to restart the connection attempt.
+
+ 2. It contains information about the challenge, which should be used
+ to construct the response to the next authentication request (which
+ will occur after the restart).
+
+Notes:
- CRV1:<flags>:<state_id>:<username_base64>:<challenge_text>
+ * '--auth-retry interact' must be in effect so that the
+ connection is restarted and credentials are requested again.
-flags: a series of optional, comma-separated flags:
- E : echo the response when the user types it
- R : a response is required
+ * '--auth-retry none' (which is the default) will cause
+ OpenVPN to exit with a fatal error without retrying and the dynamic
+ challenge/response will never happen because "Need 'Auth'
+ username/password" will not be sent.
-state_id: an opaque string that should be returned to the server
- along with the response.
+The error message is formatted as follows:
-username_base64 : the username formatted as base64
+ >PASSWORD:Verification Failed: 'Auth'
['CRV1:<flags>:<state_id>:<username_base64>:<challenge_text>']
-challenge_text : the challenge text to be shown to the user
+<flags>: a series of optional, comma-separated flags:
+ E : echo the response when the user types it.
+ R : a response is required.
+
+<state_id>: an opaque string that should be returned to the server
+ along with the response.
+
+<username_base64>: the username encoded as base 64.
+
+<challenge_text>: the challenge text to be shown to the user.
+
+<state_id> may not contain colon characters (":"), but <challenge_text>
+may.
Example challenge:
CRV1:R,E:Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l:Y3Ix:Please enter token PIN
-After showing the challenge_text and getting a response from the user
-(if R flag is specified), the client should submit the following
-auth creds back to the OpenVPN server:
+The next time the username and password are requested with
+
+ >PASSWORD:Need 'Auth' username/password
+
+the management interface client should display the challenge text and,
+if the R flag is specified, get a response from the user. The management
+interface client should respond:
-Username: [username decoded from username_base64]
-Password: CRV1::<state_id>::<response_text>
+ username "Auth" <username>
+ password "Auth" CRV1::<state_id>::<response_text>
-Where state_id is taken from the challenge request and response_text
-is what the user entered in response to the challenge_text.
-If the R flag is not present, response_text may be the empty
-string.
+Where <username> is the username decoded from <username_base64>,
+<state_id> is taken from the challenge request, and <response_text>
+is what the user entered in response to the challenge, which can be an
+empty string. If the R flag is not present, <response_text> should
+be an empty string.
+
+(As in all username/password responses described in the "COMMAND --
+password and username" section above, the username and/or password
+can be in quotes, and special characters such as double quotes or
+backslashes must be escaped. See the "Command Parsing" section above
+for more info.)
Example response (suppose the user enters "8675309" for the token PIN):
- Username: cr1 ("Y3Ix" base64 decoded)
- Password: CRV1::Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l::8675309
+ username "Auth" cr1
+ password "Auth" CRV1::Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l::8675309
+
+("Y3Ix" is the base 64 encoding of "cr1".)
Static protocol:
The static protocol differs from the dynamic protocol in that the
-challenge question and response field is given to the user in the
-initial username/password dialog, and the username, password, and
-response are delivered back to the server in a single transaction.
+challenge question is sent to the management interface client in a
+a username/password request, and the username, password, and
+response are delivered back to the server in response to that
+request.
-The "static-challenge" directive is used to give the challenge text
-to OpenVPN and indicate whether or not the response should be echoed.
+OpenVPN's --static-challenge option is used to provide the
+challenge text to OpenVPN and indicate whether or not the response
+should be echoed.
-When the "static-challenge" directive is used, the management
-interface will respond as such when credentials are needed:
+When credentials are needed and the --static-challenge option is
+used, the management interface will send:
>PASSWORD:Need 'Auth' username/password SC:<ECHO>,<TEXT>
@@ -1064,28 +1143,35 @@ For example:
>PASSWORD:Need 'Auth' username/password SC:1,Please enter token PIN
The above notification indicates that OpenVPN needs a --auth-user-pass
-password plus a response to a static challenge ("Please enter token PIN").
-The "1" after the "SC:" indicates that the response should be echoed.
+username and password plus a response to a static challenge ("Please
+enter token PIN"). The "1" after the "SC:" indicates that the response
+should be echoed.
The management interface client in this case should add the static
challenge text to the auth dialog followed by a field for the user to
-enter a response. Then the client should pack the password and response
-together into an encoded password:
+enter a response. Then the management interface client should pack the
+password and response together into an encoded password and send:
- username "Auth" foo
- password "Auth" "SCRV1:<BASE64_PASSWORD>:<BASE64_RESPONSE>"
+ username "Auth" <username>
+ password "Auth" "SCRV1:<password_base64>:<response_base64>"
-For example, if the user entered "bar" as the password and 8675309
+Where <username> is the username entered by the user, <password_base64>
+is the base 64 encoding of the password entered by the user, and
+<response_base64> is the base 64 encoding of the response entered by
+the user. The <password_base64> and/or the <response_base64> can be
+empty strings.
+
+(As in all username/password responses described in the "COMMAND --
+password and username" section above, the username can be in quotes,
+and special characters such as double quotes or backslashes must be
+escaped. See the "Command Parsing" section above for more info.)
+
+For example, if user "foo" entered "bar" as the password and 8675309
as the PIN, the following management interface commands should be
issued:
username "Auth" foo
- password "Auth" "SCRV1:Zm9v:ODY3NTMwOQ=="
-
-Client-side support for challenge/response protocol:
+ password "Auth" "SCRV1:YmFy:ODY3NTMwOQ=="
-Currently, the Access Server client and standalone OpenVPN
-client support both static and dynamic challenge/response
-protocols. However, any OpenVPN client UI that drives OpenVPN
-via the management interface needs to add explicit support
-for the challenge/response protocol.
+ ("YmFy" is the base 64 encoding of "bar" and "ODY3NTMwOQ==" is the
+ base 64 encoding of "8675309".)
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Openvpn-devel mailing list
Openvpn-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/openvpn-devel
