diff options
Diffstat (limited to 'doc/management-notes.txt')
| -rw-r--r-- | doc/management-notes.txt | 228 |
1 files changed, 157 insertions, 71 deletions
diff --git a/doc/management-notes.txt b/doc/management-notes.txt index 908b981..96a0d7d 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: @@ -139,10 +140,10 @@ messages. COMMAND -- exit, quit --------------------- -Close the managment session, and resume listening on the +Close the management 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 --------------------------- @@ -460,10 +493,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 @@ -482,10 +515,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" @@ -503,7 +536,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: @@ -807,7 +840,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] @@ -880,7 +913,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. @@ -978,70 +1011,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> @@ -1054,28 +1133,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".) |