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.
[v2 - Added lacking .B styling of options
- Clarified the token life time ]
Signed-off-by: David Sommerseth <davids@openvpn.net>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: <1474118415-14666-1-git-send-email-davids@openvpn.net>
URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg12506.html
Signed-off-by: Gert Doering <gert@greenie.muc.de>
... | ... |
@@ -4,7 +4,7 @@ |
4 | 4 |
.\" packet encryption, packet authentication, and |
5 | 5 |
.\" packet compression. |
6 | 6 |
.\" |
7 |
-.\" Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net> |
|
7 |
+.\" Copyright (C) 2002-2016 OpenVPN Technologies, Inc. <sales@openvpn.net> |
|
8 | 8 |
.\" |
9 | 9 |
.\" This program is free software; you can redistribute it and/or modify |
10 | 10 |
.\" it under the terms of the GNU General Public License version 2 |
... | ... |
@@ -34,7 +34,7 @@ |
34 | 34 |
.\" .ft -- normal face |
35 | 35 |
.\" .in +|-{n} -- indent |
36 | 36 |
.\" |
37 |
-.TH openvpn 8 "17 November 2008" |
|
37 |
+.TH openvpn 8 "25 August 2016" |
|
38 | 38 |
.\"********************************************************* |
39 | 39 |
.SH NAME |
40 | 40 |
openvpn \- secure IP tunnel daemon. |
... | ... |
@@ -2928,6 +2928,7 @@ This is a partial list of options which can currently be pushed: |
2928 | 2928 |
.B \-\-ip\-win32, \-\-dhcp\-option, |
2929 | 2929 |
.B \-\-inactive, \-\-ping, \-\-ping\-exit, \-\-ping\-restart, |
2930 | 2930 |
.B \-\-setenv, |
2931 |
+.B \-\-auth\-token, |
|
2931 | 2932 |
.B \-\-persist\-key, \-\-persist\-tun, \-\-echo, |
2932 | 2933 |
.B \-\-comp\-lzo, |
2933 | 2934 |
.B \-\-socket\-flags, |
... | ... |
@@ -5089,6 +5090,57 @@ This directive does not affect the |
5089 | 5089 |
username/password. It is always cached. |
5090 | 5090 |
.\"********************************************************* |
5091 | 5091 |
.TP |
5092 |
+.B \-\-auth\-token token |
|
5093 |
+This is not an option to be used directly in any configuration files, |
|
5094 |
+but rather push this option from a |
|
5095 |
+.B \-\-client\-connect |
|
5096 |
+script or a |
|
5097 |
+.B \-\-plugin |
|
5098 |
+which hooks into the OPENVPN_PLUGIN_CLIENT_CONNECT or |
|
5099 |
+OPENVPN_PLUGIN_CLIENT_CONNECT_V2 calls. This option provides |
|
5100 |
+a possibility to replace the clients password with an authentication |
|
5101 |
+token during the lifetime of the OpenVPN client. |
|
5102 |
+ |
|
5103 |
+Whenever the connection is renegotiated and the |
|
5104 |
+.B \-\-auth\-user\-pass\-verify |
|
5105 |
+script or |
|
5106 |
+.B \-\-plugin |
|
5107 |
+making use of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY hook is |
|
5108 |
+triggered, it will pass over this token as the password |
|
5109 |
+instead of the password the user provided. The authentication |
|
5110 |
+token can only be reset by a full reconnect where the server |
|
5111 |
+can push new options to the client. The password the user entered |
|
5112 |
+is never preserved once an authentication token have been set. If |
|
5113 |
+the OpenVPN server side rejects the authentication token, the |
|
5114 |
+client will receive an AUTH_FAIL and disconnect. |
|
5115 |
+ |
|
5116 |
+The purpose of this is to enable two factor authentication |
|
5117 |
+methods, such as HOTP or TOTP, to be used without needing to |
|
5118 |
+retrieve a new OTP code each time the connection is renegotiated. |
|
5119 |
+Another use case is to cache authentication data on the client |
|
5120 |
+without needing to have the users password cached in memory |
|
5121 |
+during the life time of the session. |
|
5122 |
+ |
|
5123 |
+To make use of this feature, the |
|
5124 |
+.B \-\-client\-connect |
|
5125 |
+script or |
|
5126 |
+.B \-\-plugin |
|
5127 |
+needs to put |
|
5128 |
+ |
|
5129 |
+.nf |
|
5130 |
+.ft 3 |
|
5131 |
+.in +4 |
|
5132 |
+push "auth\-token UNIQUE_TOKEN_VALUE" |
|
5133 |
+.in -4 |
|
5134 |
+.ft |
|
5135 |
+.fi |
|
5136 |
+ |
|
5137 |
+into the file/buffer for dynamic configuration data. This |
|
5138 |
+will then make the OpenVPN server to push this value to the |
|
5139 |
+client, which replaces the local password with the |
|
5140 |
+UNIQUE_TOKEN_VALUE. |
|
5141 |
+.\"********************************************************* |
|
5142 |
+.TP |
|
5092 | 5143 |
.B \-\-tls\-verify cmd |
5093 | 5144 |
Run command |
5094 | 5145 |
.B cmd |