@@ -4,7 +4,7 @@

 .\"             packet encryption, packet authentication, and

 .\"             packet compression.

 .\"

-.\"  Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net>

+.\"  Copyright (C) 2002-2016 OpenVPN Technologies, Inc. <sales@openvpn.net>

 .\"

 .\"  This program is free software; you can redistribute it and/or modify

 .\"  it under the terms of the GNU General Public License version 2

@@ -34,7 +34,7 @@

 .\" .ft -- normal face

 .\" .in +|-{n} -- indent

 .\"

-.TH openvpn 8 "17 November 2008"

+.TH openvpn 8 "25 August 2016"

 .\"*********************************************************

 .SH NAME

 openvpn - secure IP tunnel daemon.

@@ -2889,6 +2889,7 @@ This is a partial list of options which can currently be pushed:

 .B \-\-ip\-win32, \-\-dhcp\-option,

 .B \-\-inactive, \-\-ping, \-\-ping\-exit, \-\-ping\-restart,

 .B \-\-setenv,

+.B \-\-auth\-token,

 .B \-\-persist\-key, \-\-persist\-tun, \-\-echo,

 .B \-\-comp\-lzo,

 .B \-\-socket\-flags,

@@ -4830,6 +4831,57 @@ This directive does not affect the

 username/password.  It is always cached.

 .\"*********************************************************

 .TP

+.B \-\-auth\-token token

+This is not an option to be used directly in any configuration files,

+but rather push this option from a

+.B \-\-client\-connect

+script or a

+.B \-\-plugin

+which hooks into the OPENVPN_PLUGIN_CLIENT_CONNECT or

+OPENVPN_PLUGIN_CLIENT_CONNECT_V2 calls.  This option provides

+a possibility to replace the clients password with an authentication

+token during the lifetime of the OpenVPN client.

+

+Whenever the connection is renegotiated and the

+.B \-\-auth\-user\-pass\-verify

+script or

+.B \-\-plugin

+making use of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY hook is

+triggered, it will pass over this token as the password

+instead of the password the user provided.  The authentication

+token can only be reset by a full reconnect where the server

+can push new options to the client.  The password the user entered

+is never preserved once an authentication token have been set.  If

+the OpenVPN server side rejects the authentication token, the

+client will receive an AUTH_FAIL and disconnect.

+

+The purpose of this is to enable two factor authentication

+methods, such as HOTP or TOTP, to be used without needing to

+retrieve a new OTP code each time the connection is renegotiated.

+Another use case is to cache authentication data on the client

+without needing to have the users password cached in memory

+during the life time of the session.

+

+To make use of this feature, the

+.B \-\-client\-connect

+script or

+.B \-\-plugin

+needs to put

+

+.nf

+.ft 3

+.in +4

+push "auth\-token UNIQUE_TOKEN_VALUE"

+.in -4

+.ft

+.fi

+

+into the file/buffer for dynamic configuration data.  This

+will then make the OpenVPN server to push this value to the

+client, which replaces the local password with the

+UNIQUE_TOKEN_VALUE.

+.\"*********************************************************

+.TP

 .B \-\-tls\-verify cmd

 Run command

 .B cmd