Document the --auth-token option
PATCH 1/1 Document the --auth-token option
This isn't an option to be used directly in any configuration files, but to be used via --client-connect scripts or --plugin making use of OPENVPN_PLUGIN_CLIENT_CONNECT or OPENVPN_PLUGIN_CLIENT_CONNECT_V2.
Signed-off-by David Sommerseth <[email protected]...>
--- doc/openvpn.8 | 51 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-)
doc/openvpn.8 +49 -2
@@ -4,7 +4,7 @@ .\" packet encryption, packet authentication, and .\" packet compression. .\" -.\" Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <[email protected]...> +.\" Copyright (C) 2002-2016 OpenVPN Technologies, Inc. <[email protected]...> .\" .\" 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.
@@ -2931,6 +2931,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,
@@ -5023,6 +5024,52 @@ 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 a temporary +authentication token. + +Whenever the connection is renegotiated and the +\-\-auth\-user\-pass\-verify +script or +\-\-plugin +making use of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY hook is +triggered, it will then pass over this token as the password +instead of the password the user provided. + +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 +\-\-client\-connect +script or +\-\-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
Signature · 1 line
1.8.3.1
Hi,
Thanks for documenting this.
Quoted 6 lines · David Sommerseth
.\"********************************************************* .TP
+.B \-\-auth\-token tokendoc/openvpn.8 +2
-0+This is not an option to be used directly in any configuration files, +but rather push this option from a
doc/openvpn.8 This directive does not affect the · line 5039
Quoted 10 lines
doc/openvpn.8 +10
-0+.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 a temporary +authentication token. + +Whenever the connection is renegotiated and the +\-\-auth\-user\-pass\-verify
To be consistent, that would be ".B \-\-auth\-user\-pass\-verify"
+script or
Quoted 2 lines
+\-\-plugin
same here and a couple of instances below.
doc/openvpn.8 This directive does not affect the · line 5044
Quoted 4 lines
doc/openvpn.8 +3
-0+making use of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY hook is +triggered, it will then pass over this token as the password +instead of the password the user provided.
Based on some quick checks it seems the token is passed as password not just during reneg or after a SIGUSR1 but even after a SIGHUP. It would be useful to clarify if/when the token gets cleared so that username/password prompt will happen again at client-side. It also helps a script/plugin developer to know when to reset the token and expect the usual password.
+
doc/openvpn.8 This directive does not affect the · line 5054
Quoted 10 lines
doc/openvpn.8 +9
-0+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 +\-\-client\-connect
.B ...
Quoted 3 lines
+script or
+\-\-plugin
.B ...
Quoted 9 lines
doc/openvpn.8 +9
-0+needs to put + +.nf +.ft 3 +.in +4 +push "auth-token UNIQUE_TOKEN_VALUE" +.in -4 +.ft +.fi
doc/openvpn.8 This directive does not affect the · line 5075
Quoted 10 lines
doc/openvpn.8 +7
-0+ +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
Selva
PATCH v2 1/1 Document the --auth-token option
In reply to David SommersethThis isn't an option to be used directly in any configuration files, but to be used via --client-connect scripts or --plugin making use of OPENVPN_PLUGIN_CLIENT_CONNECT or OPENVPN_PLUGIN_CLIENT_CONNECT_V2.
[v2 - Added lacking .B styling of options
- Clarified the token life time ]
Signed-off-by David Sommerseth <[email protected]...>
--- doc/openvpn.8 | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-)
doc/openvpn.8 +54 -2
@@ -4,7 +4,7 @@ .\" packet encryption, packet authentication, and .\" packet compression. .\" -.\" Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <[email protected]...> +.\" Copyright (C) 2002-2016 OpenVPN Technologies, Inc. <[email protected]...> .\" .\" 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.
@@ -2931,6 +2931,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,
@@ -5023,6 +5024,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
Signature · 1 line
1.8.3.1
ACK.
Documentation text leaves endless possibilities for twisting words around, but this is much better than "no documentation" :-)
Your patch has been applied to the master and release/2.3 branch.
commit f8a367f7c51af5482013fa3d783cade376b047ed (master) commit d5cb6b4948b9bb64684e6be800d2cbaaf3c32768 (release/2.3)
Author: David Sommerseth Date: Sat Sep 17 16:20:15 2016 +0300
Document the --auth-token option
Signed-off-by: David Sommerseth <[email protected]...>
Acked-by: Gert Doering <[email protected]...>
Message-Id: <[email protected]...>
URL: https://www.mail-archive.com/[email protected]/msg12506.html
Signed-off-by: Gert Doering <[email protected]...>--
kind regards,
Gert Doering