diff options
Diffstat (limited to 'bitmask_android/openvpn/doc/management-notes.txt')
| -rw-r--r-- | bitmask_android/openvpn/doc/management-notes.txt | 1039 |
1 files changed, 1039 insertions, 0 deletions
diff --git a/bitmask_android/openvpn/doc/management-notes.txt b/bitmask_android/openvpn/doc/management-notes.txt new file mode 100644 index 00000000..ef39b855 --- /dev/null +++ b/bitmask_android/openvpn/doc/management-notes.txt @@ -0,0 +1,1039 @@ +OpenVPN Management Interface Notes +---------------------------------- + +The OpenVPN Management interface allows OpenVPN to +be administratively controlled from an external program via +a TCP or unix domain socket. + +The interface has been specifically designed for developers +who would like to programmatically or remotely control +an OpenVPN daemon, and can be used when OpenVPN is running +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. + +The management protocol is currently cleartext without an explicit +security layer. For this reason, it is recommended that the +management interface either listen on a unix domain socket, +localhost (127.0.0.1), or on the local VPN address. It's possible +to remotely connect to the management interface over the VPN itself, +though some capabilities will be limited in this mode, such as the +ability to provide private key passwords. + +The management interface is enabled in the OpenVPN +configuration file using the following directive: + +--management + +See the man page for documentation on this and related +directives. + +Once OpenVPN has started with the management layer enabled, +you can telnet to the management port (make sure to use +a telnet client which understands "raw" mode). + +Once connected to the management port, you can use +the "help" command to list all commands. + +COMMAND -- bytecount +-------------------- + +The bytecount command is used to request real-time notification +of OpenVPN bandwidth usage. + +Command syntax: + + bytecount n (where n > 0) -- set up automatic notification of + bandwidth usage once every n seconds + bytecount 0 -- turn off bytecount notifications + +If OpenVPN is running as a client, the bytecount notification +will look like this: + + >BYTECOUNT:{BYTES_IN},{BYTES_OUT} + +BYTES_IN is the number of bytes that have been received from +the server and BYTES_OUT is the number of bytes that have been +sent to the server. + +If OpenVPN is running as a server, the bytecount notification +will look like this: + + >BYTECOUNT_CLI:{CID},{BYTES_IN},{BYTES_OUT} + +CID is the Client ID, BYTES_IN is the number of bytes that have +been received from the client and BYTES_OUT is the number of +bytes that have been sent to the client. + +Note that when the bytecount command is used on the server, every +connected client will report its bandwidth numbers once every n +seconds. + +When the client disconnects, the final bandwidth numbers will be +placed in the 'bytes_received' and 'bytes_sent' environmental variables +as included in the >CLIENT:DISCONNECT notification. + +COMMAND -- echo +--------------- + +The echo capability is used to allow GUI-specific +parameters to be either embedded in the OpenVPN config file +or pushed to an OpenVPN client from a server. + +Command examples: + + echo on -- turn on real-time notification of echo messages + echo all -- print the current echo history list + echo off -- turn off real-time notification of echo messages + echo on all -- atomically enable real-time notification, + plus show any messages in history buffer + +For example, suppose you are developing a OpenVPN GUI and +you want to give the OpenVPN server the ability to ask +the GUI to forget any saved passwords. + +In the OpenVPN server config file, add: + + push "echo forget-passwords" + +When the OpenVPN client receives its pulled list of directives +from the server, the "echo forget-passwords" directive will +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 +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. + +When the GUI connects to the OpenVPN management socket, it +can issue an "echo all" command, which would produce output +like this: + + 1101519562,forget-passwords + END + +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 +unix date/time when the echo parameter was received. + +If the management 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: + + >ECHO:1101519562,forget-passwords + +Like the log command, the echo command can atomically show +history while simultaneously activating real-time updates: + + echo on all + +The size of the echo buffer is currently hardcoded to 100 +messages. + +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. + +COMMAND -- help +--------------- + +Print a summary of commands. + +COMMAND -- hold +--------------- + +The hold command can be used to manipulate the hold flag, +or release OpenVPN from a hold state. + +If the hold flag is set on initial startup or +restart, OpenVPN will hibernate prior to initializing +the tunnel until the management interface receives +a "hold release" command. + +The --management-hold directive of OpenVPN can be used +to start OpenVPN with the hold flag set. + +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 +client: + + >HOLD:Waiting for hold release + +Command examples: + + hold -- show current hold flag, 0=off, 1=on. + hold on -- turn on hold flag so that future restarts + will hold. + hold off -- turn off hold flag so that future restarts will + not hold. + hold release -- leave hold state and start OpenVPN, but + do not alter the current hold flag setting. + +COMMAND -- kill +--------------- + +In server mode, kill a particlar client instance. + +Command examples: + + kill Test-Client -- kill the client instance having a + common name of "Test-Client". + kill 1.2.3.4:4000 -- kill the client instance having a + source address and port of 1.2.3.4:4000 + +Use the "status" command to see which clients are connected. + +COMMAND -- log +-------------- + +Show the OpenVPN log file. Only the most recent n lines +of the log file are cached by the management interface, where +n is controlled by the OpenVPN --management-log-cache directive. + +Command examples: + + log on -- Enable real-time output of log messages. + log all -- Show currently cached log file history. + log on all -- Atomically show all currently cached log file + history then enable real-time notification of + new log file messages. + log off -- Turn off real-time notification of log messages. + log 20 -- Show the most recent 20 lines of log file history. + +Real-time notification format: + +Real-time log messages begin with the ">LOG:" prefix followed +by the following comma-separated fields: + + (a) unix integer date/time, + (b) zero or more message flags in a single string: + I -- informational + F -- fatal error + N -- non-fatal error + W -- warning + D -- debug, and + (c) message text. + +COMMAND -- mute +--------------- + +Change the OpenVPN --mute parameter. The mute parameter is +used to silence repeating messages of the same message +category. + +Command examples: + + mute 40 -- change the mute parameter to 40 + mute -- show the current mute setting + +COMMAND -- net +-------------- + +(Windows Only) Produce output equivalent to the OpenVPN +--show-net directive. The output includes OpenVPN's view +of the system network adapter list and routing table based +on information returned by the Windows IP helper API. + +COMMAND -- pid +-------------- + +Shows the process ID of the current OpenVPN process. + +COMMAND -- password and username +-------------------------------- + + The password command is used to pass passwords to OpenVPN. + + If OpenVPN is run with the --management-query-passwords + directive, it will query the management interface for RSA + private key passwords and the --auth-user-pass + username/password. + + When OpenVPN needs a password from the management interface, + it will produce a real-time ">PASSWORD:" message. + + Example 1: + + >PASSWORD:Need 'Private Key' password + + OpenVPN is indicating that it needs a password of type + "Private Key". + + The management client should respond to this query as follows: + + password "Private Key" foo + + Example 2: + + >PASSWORD:Need 'Auth' username/password + + OpenVPN needs a --auth-user-pass password. The management + client should respond: + + username "Auth" foo + password "Auth" bar + + The username/password itself can be in quotes, and special + characters such as double quote or backslash must be escaped, + for example, + + password "Private Key" "foo\"bar" + + The escaping rules are the same as for the config file. + See the "Command Parsing" section below for more info. + + The PASSWORD real-time message type can also be used to + indicate password or other types of authentication failure: + + Example 3: The private key password is incorrect and OpenVPN + is exiting: + + >PASSWORD:Verification Failed: 'Private Key' + + Example 4: The --auth-user-pass username/password failed, + and OpenVPN is exiting: + + >PASSWORD:Verification Failed: 'Auth' + + Example 5: The --auth-user-pass username/password failed, + and the server provided a custom client-reason-text string + using the client-deny server-side management interface command. + + >PASSWORD:Verification Failed: 'custom server-generated string' + +COMMAND -- forget-passwords +--------------------------- + +The forget-passwords command will cause the daemon to forget passwords +entered during the session. + +Command example: + + forget-passwords -- forget passwords entered so far. + +COMMAND -- signal +----------------- + +The signal command will send a signal to the OpenVPN daemon. +The signal can be one of SIGHUP, SIGTERM, SIGUSR1, or SIGUSR2. + +Command example: + + signal SIGUSR1 -- send a SIGUSR1 signal to daemon + +COMMAND -- state +---------------- + +Show the current OpenVPN state, show state history, or +enable real-time notification of state changes. + +These are the OpenVPN states: + +CONNECTING -- OpenVPN's initial state. +WAIT -- (Client only) Waiting for initial response + from server. +AUTH -- (Client only) Authenticating with server. +GET_CONFIG -- (Client only) Downloading configuration options + from server. +ASSIGN_IP -- Assigning IP address to virtual network + interface. +ADD_ROUTES -- Adding routes to system. +CONNECTED -- Initialization Sequence Completed. +RECONNECTING -- A restart has occurred. +EXITING -- A graceful exit is in progress. + +Command examples: + + state -- Print current OpenVPN state. + state on -- Enable real-time notification of state changes. + state off -- Disable real-time notification of state changes. + state all -- Print current state history. + state 3 -- Print the 3 most recent state transitions. + state on all -- Atomically show state history while at the + same time enable real-time state notification + of future state transitions. + +The output format consists of 4 comma-separated parameters: + (a) the integer unix date/time, + (b) the state name, + (c) optional descriptive string (used mostly on RECONNECTING + and EXITING to show the reason for the disconnect), + (d) optional TUN/TAP local IP address (shown for ASSIGN_IP + and CONNECTED), and + (e) optional address of remote server (OpenVPN 2.1 or higher). + +Real-time state notifications will have a ">STATE:" prefix +prepended to them. + +COMMAND -- status +----------------- + +Show current daemon status information, in the same format as +that produced by the OpenVPN --status directive. + +Command examples: + +status -- Show status information using the default status + format version. + +status 3 -- Show status information using the format of + --status-version 3. + +COMMAND -- username +------------------- + +See the "password" section above. + +COMMAND -- verb +--------------- + +Change the OpenVPN --verb parameter. The verb parameter +controls the output verbosity, and may range from 0 (no output) +to 15 (maximum output). See the OpenVPN man page for additional +info on verbosity levels. + +Command examples: + + verb 4 -- change the verb parameter to 4 + mute -- show the current verb setting + +COMMAND -- version +------------------ + +Show the current OpenVPN and Management Interface versions. + + +COMMAND -- auth-retry +--------------------- + +Set the --auth-retry setting to control how OpenVPN responds to +username/password authentication errors. See the manual page +for more info. + +Command examples: + + auth-retry interact -- Don't exit when bad username/passwords are entered. + Query for new input and retry. + +COMMAND -- needok (OpenVPN 2.1 or higher) +------------------------------------------ + +Confirm a ">NEED-OK" real-time notification, normally used by +OpenVPN to block while waiting for a specific user action. + +Example: + + OpenVPN needs the user to insert a cryptographic token, + so it sends a real-time notification: + + >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 + 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: + + needok token-insertion-request ok + or + needok token-insertion-request cancel + +COMMAND -- needstr (OpenVPN 2.1 or higher) +------------------------------------------- + +Confirm a ">NEED-STR" real-time notification, normally used by +OpenVPN to block while waiting for a specific user input. + +Example: + + OpenVPN needs the user to specify some input, so it sends a + real-time notification: + + >NEED-STR:Need 'name' input MSG:Please specify your name + + The management 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: + + needstr name "John" + +COMMAND -- pkcs11-id-count (OpenVPN 2.1 or higher) +--------------------------------------------------- + +Retrieve available number of certificates. + +Example: + + pkcs11-id-count + >PKCS11ID-COUNT:5 + +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. + +Example: + + pkcs11-id-get 1 + PKCS11ID-ENTRY:'1', ID:'<snip>', BLOB:'<snip>' + +COMMAND -- client-auth (OpenVPN 2.1 or higher) +----------------------------------------------- + +Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request and specify +"client-connect" configuration directives in a subsequent text block. + +The OpenVPN server should have been started with the +--management-client-auth directive so that it will ask the management +interface to approve client connections. + + + client-auth {CID} {KID} + line_1 + line_2 + ... + line_n + END + +CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" +notification for more info. + +line_1 to line_n -- client-connect configuration text block, as would be +returned by a --client-connect script. The text block may be null, with +"END" immediately following the "client-auth" line (using a null text +block is equivalent to using the client-auth-nt command). + +A client-connect configuration text block contains OpenVPN directives +that will be applied to the client instance object representing a newly +connected client. + +COMMAND -- client-auth-nt (OpenVPN 2.1 or higher) +-------------------------------------------------- + +Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request without specifying +client-connect configuration text. + +The OpenVPN server should have been started with the +--management-client-auth directive so that it will ask the management +interface to approve client connections. + + client-auth-nt {CID} {KID} + +CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" +notification for more info. + +COMMAND -- client-deny (OpenVPN 2.1 or higher) +----------------------------------------------- + +Deny a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request. + + client-deny {CID} {KID} "reason-text" ["client-reason-text"] + +CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" +notification for more info. + +reason-text: a human-readable message explaining why the authentication +request was denied. This message will be output to the OpenVPN log +file or syslog. + +client-reason-text: a message that will be sent to the client as +part of the AUTH_FAILED message. + +Note that client-deny denies a specific Key ID (pertaining to a +TLS renegotiation). A client-deny command issued in response to +an initial TLS key negotiation (notified by ">CLIENT:CONNECT") will +terminate the client session after returning "AUTH-FAILED" to the client. +On the other hand, a client-deny command issued in response to +a TLS renegotiation (">CLIENT:REAUTH") will invalidate the renegotiated +key, however the TLS session associated with the currently active +key will continue to live for up to --tran-window seconds before +expiration. + +To immediately kill a client session, use "client-kill". + +COMMAND -- client-kill (OpenVPN 2.1 or higher) +----------------------------------------------- + +Immediately kill a client instance by CID. + + client-kill {CID} + +CID -- client ID. See documentation for ">CLIENT:" notification for more +info. + +COMMAND -- client-pf (OpenVPN 2.1 or higher) +--------------------------------------------- + +Push a packet filter file to a specific client. + +The OpenVPN server should have been started with the +--management-client-pf directive so that it will require that +VPN tunnel packets sent or received by client instances must +conform to that client's packet filter configuration. + + client-pf {CID} + line_1 + line_2 + ... + line_n + END + +CID -- client ID. See documentation for ">CLIENT:" notification for +more info. + +line_1 to line_n -- the packet filter configuration file for this +client. + +Packet filter file grammar: + + [CLIENTS DROP|ACCEPT] + {+|-}common_name1 + {+|-}common_name2 + . . . + [SUBNETS DROP|ACCEPT] + {+|-}subnet1 + {+|-}subnet2 + . . . + [END] + + Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS | "unknown" + + CLIENTS refers to the set of clients (by their common-name) which + this instance is allowed ('+') to connect to, or is excluded ('-') + from connecting to. Note that in the case of client-to-client + connections, such communication must be allowed by the packet filter + configuration files of both clients AND the --client-to-client + directive must have been specified in the OpenVPN server config. + + SUBNETS refers to IP addresses or IP address subnets which this + client instance may connect to ('+') or is excluded ('-') from + connecting to, and applies to IPv4 and ARP packets. The special + "unknown" tag refers to packets of unknown type, i.e. a packet that + is not IPv4 or ARP. + + DROP or ACCEPT defines default policy when there is no explicit match + for a common-name or subnet. The [END] tag must exist. + + Notes: + + * The SUBNETS section currently only supports IPv4 addresses and + subnets. + + * A given client or subnet rule applies to both incoming and + outgoing packets. + + * The CLIENTS list is order-invariant. Because the list is stored + as a hash-table, the order of the list does not affect its function. + + * The SUBNETS table is scanned sequentially, and the first item to + match is chosen. Therefore the SUBNETS table is NOT order-invariant. + + * No client-to-client communication is allowed unless the + --client-to-client configuration directive is enabled AND + the CLIENTS list of BOTH clients allows the communication. + +Example packet filter spec, as transmitted to the management interface: + + client-pf 42 + [CLIENTS ACCEPT] + -accounting + -enigma + [SUBNETS DROP] + -10.46.79.9 + +10.0.0.0/8 + [END] + END + +The above example sets the packet filter policy for the client +identified by CID=42. This client may connect to all other clients +except those having a common name of "accounting" or "enigma". +The client may only interact with external IP addresses in the +10.0.0.0/8 subnet, however access to 10.46.79.9 is specifically +excluded. + +Another example packet filter spec, as transmitted to the +management interface: + + client-pf 99 + [CLIENTS DENY] + +public + [SUBNETS ACCEPT] + +10.10.0.1 + -10.0.0.0/8 + -unknown + [END] + END + +The above example sets the packet filter policy for the client +identified by CID=99. This client may not connect to any other +clients except those having a common name of "public". It may +interact with any external IP address except those in the +10.0.0.0/8 netblock. However interaction with one address in +the 10.0.0.0/8 netblock is allowed: 10.10.0.1. Also, the client +may not interact with external IP addresses using an "unknown" +protocol (i.e. one that is not IPv4 or ARP). + +COMMAND -- remote (OpenVPN AS 2.1.5/OpenVPN 2.3 or higher) +-------------------------------------------- + +Provide remote host/port in response to a >REMOTE notification +(client only). Requires that the --management-query-remote +directive is used. + + remote ACTION [HOST PORT] + +The "remote" command should only be given in response to a >REMOTE +notification. For example, the following >REMOTE notification +indicates that the client config file would ordinarily connect +to vpn.example.com port 1194 (UDP): + + >REMOTE:vpn.example.com,1194,udp + +Now, suppose we want to override the host and port, connecting +instead to vpn.otherexample.com port 1234. After receiving +the above notification, use this command: + + remote MOD vpn.otherexample.com 1234 + +To accept the same host and port as the client would ordinarily +have connected to, use this command: + + remote ACCEPT + +To skip the current connection entry and advance to the next one, +use this command: + + remote SKIP + +COMMAND -- proxy (OpenVPN 2.3 or higher) +-------------------------------------------- + +Provide proxy server host/port and flags in response to a >PROXY +notification (client only). Requires that the --management-query-proxy +directive is used. + + proxy TYPE HOST PORT ["nct"] + +The "proxy" command must only be given in response to a >PROXY +notification. Use the "nct" flag if you only want to allow +non-cleartext auth with the proxy server. The following >PROXY +notification indicates that the client config file would ordinarily +connect to the first --remote configured, vpn.example.com using TCP: + + >PROXY:1,TCP,vpn.example.com + +Now, suppose we want to connect to the remote host using the proxy server +proxy.intranet port 8080 with secure authentication only, if required. +After receiving the above notification, use this command: + + proxy HTTP proxy.intranet 8080 nct + +You can also use the SOCKS keyword to pass a SOCKS server address, like: + + proxy SOCKS fe00::1 1080 + +To accept connecting to the host and port directly, use this command: + + proxy NONE + +COMMAND -- rsa-sig (OpenVPN 2.3 or higher) +------------------------------------------ +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 +operation, the data to be signed will be sent to the management interface +via a notification as follows: + +>RSA_SIGN:[BASE64_DATA] + +The management interface client should then sign BASE64_DATA +using the private key and return the SSL signature as follows: + +rsa-sig +[BASE64_SIG_LINE] +. +. +. +END + +Base64 encoded output of RSA_sign(NID_md5_sha1,... will provide a +correct signature. + +This capability is intended to allow the use of arbitrary cryptographic +service providers with OpenVPN via the management interface. + + +OUTPUT FORMAT +------------- + +(1) Command success/failure indicated by "SUCCESS: [text]" or + "ERROR: [text]". + +(2) For commands which print multiple lines of output, + the last line will be "END". + +(3) Real-time messages will be in the form ">[source]:[text]", + where source is "CLIENT", "ECHO", "FATAL", "HOLD", "INFO", "LOG", + "NEED-OK", "PASSWORD", or "STATE". + +REAL-TIME MESSAGE FORMAT +------------------------ + +The OpenVPN management interface produces two kinds of +output: (a) output from a command, or (b) asynchronous, +real-time output which can be generated at any time. + +Real-time messages start with a '>' character in the first +column and are immediately followed by a type keyword +indicating the type of real-time message. The following +types are currently defined: + +BYTECOUNT -- Real-time bandwidth usage notification, as enabled + by "bytecount" command when OpenVPN is running as + a client. + +BYTECOUNT_CLI -- Real-time bandwidth usage notification per-client, + as enabled by "bytecount" command when OpenVPN is + running as a server. + +CLIENT -- Notification of client connections and disconnections + on an OpenVPN server. Enabled when OpenVPN is started + with the --management-client-auth option. CLIENT + notifications may be multi-line. See "The CLIENT + notification" section below for detailed info. + +ECHO -- Echo messages as controlled by the "echo" command. + +FATAL -- A fatal error which is output to the log file just + prior to OpenVPN exiting. + +HOLD -- Used to indicate that OpenVPN is in a holding state + and will not start until it receives a + "hold release" command. + +INFO -- Informational messages such as the welcome message. + +LOG -- Log message output as controlled by the "log" command. + +NEED-OK -- OpenVPN needs the end user to do something, such as + insert a cryptographic token. The "needok" command can + be used to tell OpenVPN to continue. + +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 + needs a password, also to indicate password + verification failure. + +STATE -- Shows the current OpenVPN state, as controlled + by the "state" command. + +The CLIENT notification +----------------------- + +The ">CLIENT:" notification is enabled by the --management-client-auth +OpenVPN configuration directive that gives the management interface client +the responsibility to authenticate OpenVPN clients after their client +certificate has been verified. CLIENT notifications may be multi-line, and +the sequentiality of a given CLIENT notification, its associated environmental +variables, and the terminating ">CLIENT:ENV,END" line are guaranteed to be +atomic. + +CLIENT notification types: + +(1) Notify new client connection ("CONNECT") or existing client TLS session + renegotiation ("REAUTH"). Information about the client is provided + by a list of environmental variables which are documented in the OpenVPN + man page. The environmental variables passed are equivalent to those + that would be passed to an --auth-user-pass-verify script. + + >CLIENT:CONNECT|REAUTH,{CID},{KID} + >CLIENT:ENV,name1=val1 + >CLIENT:ENV,name2=val2 + >CLIENT:ENV,... + >CLIENT:ENV,END + +(2) Notify successful client authentication and session initiation. + Called after CONNECT. + + >CLIENT:ESTABLISHED,{CID} + >CLIENT:ENV,name1=val1 + >CLIENT:ENV,name2=val2 + >CLIENT:ENV,... + >CLIENT:ENV,END + +(3) Notify existing client disconnection. The environmental variables passed + are equivalent to those that would be passed to a --client-disconnect + script. + + >CLIENT:DISCONNECT,{CID} + >CLIENT:ENV,name1=val1 + >CLIENT:ENV,name2=val2 + >CLIENT:ENV,... + >CLIENT:ENV,END + +(4) Notify that a particular virtual address or subnet + is now associated with a specific client. + + >CLIENT:ADDRESS,{CID},{ADDR},{PRI} + +Variables: + +CID -- Client ID, numerical ID for each connecting client, sequence = 0,1,2,... +KID -- Key ID, numerical ID for the key associated with a given client TLS session, + sequence = 0,1,2,... +PRI -- Primary (1) or Secondary (0) VPN address/subnet. All clients have at least + one primary IP address. Secondary address/subnets are associated with + client-specific "iroute" directives. +ADDR -- IPv4 address/subnet in the form 1.2.3.4 or 1.2.3.0/255.255.255.0 + +In the unlikely scenario of an extremely long-running OpenVPN server, +CID and KID should be assumed to recycle to 0 after (2^32)-1, however this +recycling behavior is guaranteed to be collision-free. + +Command Parsing +--------------- + +The management interface uses the same command line lexical analyzer +as is used by the OpenVPN config file parser. + +Whitespace is a parameter separator. + +Double quotation or single quotation characters ("", '') can be used +to enclose parameters containing whitespace. + +Backslash-based shell escaping is performed, using the following +mappings, when not in single quotations: + +\\ Maps to a single backslash character (\). +\" Pass a literal doublequote character ("), don't + interpret it as enclosing a parameter. +\[SPACE] Pass a literal space or tab character, don't + interpret it as a parameter delimiter. + +Challenge/Response Protocol +--------------------------- + +The OpenVPN Challenge/Response Protocol allows an OpenVPN server to +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 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. + +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: + + CRV1:<flags>:<state_id>:<username_base64>:<challenge_text> + +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 formatted as base64 + +challenge_text : the challenge text to be shown to the user + +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: + +Username: [username decoded from username_base64] +Password: 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. + +Example response (suppose the user enters "8675309" for the token PIN): + + Username: cr1 ("Y3Ix" base64 decoded) + Password: CRV1::Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l::8675309 + +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. + +The "static-challenge" directive is used to give 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: + + >PASSWORD:Need 'Auth' username/password SC:<ECHO>,<TEXT> + + ECHO: "1" if response should be echoed, "0" to not echo + TEXT: challenge text that should be shown to the user to + facilitate their response + +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. + +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: + + username "Auth" foo + password "Auth" "SCRV1:<BASE64_PASSWORD>:<BASE64_RESPONSE>" + +For example, if the user 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: + +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. |