[Openvpn-devel,v2] Clarify and expand management interface documentation

Message ID nEV9l80I3peitTd26qmQFpeoaQbEO-IR74B1gOvCLv-IfvQKjNfL9UnZq1aWr20480nGcbkSnhA-mSGEI5kG7JBMsGpNbNf2FExV3CSzRf4=@protonmail.com
State Accepted
Headers show
Series
  • [Openvpn-devel,v2] Clarify and expand management interface documentation
Related show

Commit Message

Rolf Fokkens via Openvpn-devel Aug. 8, 2018, 11:35 a.m.
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 <jkbullard@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(-)



------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot

Comments

tincanteksup Aug. 8, 2018, 12:33 p.m. | #1
Hi,

I have had my arm twisted into doing some spell checking of docs.

There is one spelling error (an old over looked one)
which you could fix with this patch. (inline)


On 08/08/18 12:35, Jonathan K. Bullard via Openvpn-devel wrote:
> 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 <jkbullard@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

managment --> management

>   management port for connections from other clients. Currently,

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
Selva Nair Aug. 8, 2018, 5 p.m. | #2
Hi,

Thanks for the v2.

On Wed, Aug 8, 2018 at 7:35 AM, Jonathan K. Bullard via Openvpn-devel
<openvpn-devel@lists.sourceforge.net> wrote:
> 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 <jkbullard@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(-)

Looks good now.

The typo pointed out by tincanteksup is not a fault of this patch
but this may be a good time to fix it -- could be done at merge time?

On line 143 of doc/management-notes.txt after applying this patch:

managment --> management

Acked-by: selva.nair@gmail.com

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
Gert Doering Aug. 9, 2018, 12:38 p.m. | #3
Your patch has been applied to the master and release/2.4 branch, with
the extra "managment" spelling fix.

(As a side note: your protonmail account works with git send-email,
but the list mangles the From: header due to DMARC p=reject, and thus,
git records "Jonathan K. Bullard <openvpn-devel@lists.sourceforge.net>"
as patch author... which sucks, of course.  Manually fixed)

commit a6fd48ba36ede465b0905a95568c3ec0d425ca71 (master)
commit 9b71d1d24fd2fe6a2399686a6bc4104ef3835f23 (release/2.4)
Author: Jonathan K. Bullard
Date:   Wed Aug 8 11:35:37 2018 +0000

     Clarify and expand management interface documentation

     Signed-off-by: Jonathan K. Bullard <jkbullard@gmail.com>
     Acked-by: Selva Nair <selva.nair@gmail.com>
     Message-Id: <nEV9l80I3peitTd26qmQFpeoaQbEO-IR74B1gOvCLv-IfvQKjNfL9UnZq1aWr20480nGcbkSnhA-mSGEI5kG7JBMsGpNbNf2FExV3CSzRf4=@protonmail.com>
     URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg17390.html
     Signed-off-by: Gert Doering <gert@greenie.muc.de>


--
kind regards,

Gert Doering


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot

Patch

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".)