| Message ID | 20200711093655.23686-14-arne@rfc2549.org |
|---|---|
| State | Changes Requested |
| Headers | show |
| Series | [Openvpn-devel,v5,01/14] Allow changing fallback cipher from ccd files/client-connect | expand |
Because this is documentation I have been a little harder on grammar. These are only suggestions to improve readability. On 11/07/2020 10:36, Arne Schwabe wrote: > Patch V5: Fix typos, clarify man page section about deferred client-connect > script. Add section to Changes.rst > > Signed-off-by: Arne Schwabe <arne@rfc2549.org> > --- > Changes.rst | 4 +++ > doc/openvpn.8 | 55 +++++++++++++++++++++++++++++++++++-- > include/openvpn-plugin.h.in | 21 ++++++++++---- > 3 files changed, 71 insertions(+), 9 deletions(-) > > diff --git a/Changes.rst b/Changes.rst > index 42f0d190..47fa6883 100644 > --- a/Changes.rst > +++ b/Changes.rst > @@ -3,6 +3,10 @@ Overview of changes in 2.5 > > New features > ------------ > +Deferred client-connect > + client-connect and the connect plugin API allow now asynchronous/deferred allow now -> now allow > + return of the configuration file in the same way as the auth-plugin. > + > Client-specific tls-crypt keys (``--tls-crypt-v2``) > ``tls-crypt-v2`` adds the ability to supply each client with a unique > tls-crypt key. This allows large organisations and VPN providers to profit > diff --git a/doc/openvpn.8 b/doc/openvpn.8 > index 03ae5ac5..7a0080bf 100644 > --- a/doc/openvpn.8 > +++ b/doc/openvpn.8 > @@ -3422,6 +3422,13 @@ is significant. If > .B script > returns a non\-zero error status, it will cause the client > to be disconnected. > + > +If a > +.B \-\-client\-connect cmd > +wants to defer the generating of the configuration the script, should wants to defer the generating of the configuration then the script should > +use the client_connect_deferred_file and client_connect_config_file > +environment variables and write status accordingly into these files environment variables. And write status accordingly into these files > +(See the environment section below for more details). > .\"********************************************************* > .TP > .B \-\-client\-disconnect cmd > @@ -3505,12 +3512,18 @@ This directory will be used by in the following cases: > > * > .B \-\-client\-connect > -scripts to dynamically generate client\-specific > -configuration files. > +scripts and > +.B OPENVPN_PLUGIN_CLIENT_CONNECT > +plugin hook > +to dynamically generate client\-specific configuration files > +and return success/failure via client_connect_deferred_file > +when using deferred client connect method > > * > .B OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY > -plugin hook to return success/failure via auth_control_file > +and > + > +plugin hook to return success/failure via auth_control_file/ > when using deferred auth method > > * > @@ -6654,6 +6667,42 @@ Set prior to execution of the > script. > .\"********************************************************* > .TP > +.B client_connect_config_file > +The path to the configuration file that should be written by > +the > +.B \-\-client\-connect > +script. The content of this environment variable is identical > +to the file as a argument of the called as an argument > +.B \-\-client\-connect > +script. > +.\"********************************************************* > +.TP > +.B client_connect_deferred_file > +This file can be optionally written to communicate a status > +code of the > +.TP > +.B \-\-client\-connect > +script. If used for deferring, this file must be written > +before the > +.B \-\-client\-connect > +script exits. The first character in the file has to be must be either: > +'1' is to indicate normal script execution, '0' indicates an > +error (in the same way that a non zero exit status does) and > +'2' indicates that the script deferred returning the config > +file. When the script defers returning the configuration, it > +must also write '2' to to the file to indicate the deferral. > +A background process or similar must then take care of writing the > +configuration to the file indicated by the > +.B > +client_connect_config_file > +environment variable and when finished, write the a '1' to this > +file (or '0' in case of an error). > + > +The absence of any character in the file when the script finishes > +executing is interpreted the same as '1'. This allows script that This allows scripts > +are not written to support the defer mechanism to be used unmodified. > +.\"********************************************************* > +.TP > .B common_name > The X509 common name of an authenticated client. > Set prior to execution of > diff --git a/include/openvpn-plugin.h.in b/include/openvpn-plugin.h.in > index 38fbe097..64b20886 100644 > --- a/include/openvpn-plugin.h.in > +++ b/include/openvpn-plugin.h.in > @@ -557,12 +557,21 @@ OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_op > * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure > * > * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by > - * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY. This enables asynchronous > - * authentication where the plugin (or one of its agents) may indicate > - * authentication success/failure some number of seconds after the return > - * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single > - * char to the file named by auth_control_file in the environmental variable > - * list (envp). > + * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY, OPENVPN_PLUGIN_CLIENT_CONNECT and > + * OPENVPN_PLUGIN_CLIENT_CONNECT_V2. This enables asynchronous > + * authentication or client connect where the plugin (or one of its agents) > + * may indicate authentication success/failure or client configuration some > + * number of seconds after the return of the function handler. > + * For OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY and OPENVPN_PLUGIN_CLIENT_CONNECT > + * this is done by writing a single char to the file named by > + * auth_control_file/client_connect_deferred_file > + * in the environmental variable list (envp). > + * > + * In addition the OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER and > + * OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER_V2 are called when OpenVPN tries to > + * get the deferred result. For a V2 call implementing this function is For a V2 call implementing this function it is > + * required as information is not passed by files. For the normal version required because information > + * the call is optional. > * > * first char of auth_control_file: > * '0' -- indicates auth failure >
So I'm looking into migrating this text over to the new .rst format ... and I have a question ... On 11/07/2020 11:36, Arne Schwabe wrote: > diff --git a/doc/openvpn.8 b/doc/openvpn.8 > index 03ae5ac5..7a0080bf 100644 > --- a/doc/openvpn.8 > +++ b/doc/openvpn.8 > @@ -3422,6 +3422,13 @@ is significant. If > .B script > returns a non\-zero error status, it will cause the client > to be disconnected. > + > +If a > +.B \-\-client\-connect cmd > +wants to defer the generating of the configuration the script, should > +use the client_connect_deferred_file and client_connect_config_file > +environment variables and write status accordingly into these files > +(See the environment section below for more details). > .\"********************************************************* > .TP > .B \-\-client\-disconnect cmd > @@ -3505,12 +3512,18 @@ This directory will be used by in the following cases: > > * > .B \-\-client\-connect > -scripts to dynamically generate client\-specific > -configuration files. > +scripts and > +.B OPENVPN_PLUGIN_CLIENT_CONNECT > +plugin hook > +to dynamically generate client\-specific configuration files > +and return success/failure via client_connect_deferred_file > +when using deferred client connect method > > * > .B OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY > -plugin hook to return success/failure via auth_control_file > +and > + > +plugin hook to return success/failure via auth_control_file/ > when using deferred auth method This part is oddly rendered, and it seems it lacks something ... * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY and plugin hook to return success/failure via auth_control_file/client_connect_deferred_file when using deferred auth method Is this what you intended to say? * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin hook and --client-connect scripts to return success/failure via auth_control_file/client_connect_deferred_file when using deferred auth method
Hi, On Thu, Jul 16, 2020 at 11:04:09PM +0200, David Sommerseth wrote: > So I'm looking into migrating this text over to the new .rst format ... and I > have a question ... This one *should* be identical to 6/6 from the "v7" series, but just for completeness - the "v5" series has been reworked completely and the last 6 patches been resent as v7. Doc patch is "v7 6/6" now, same subject otherwise. gert
On 16/07/2020 23:07, Gert Doering wrote: > Hi, > > On Thu, Jul 16, 2020 at 11:04:09PM +0200, David Sommerseth wrote: >> So I'm looking into migrating this text over to the new .rst format ... and I >> have a question ... > > This one *should* be identical to 6/6 from the "v7" series, but just for > completeness - the "v5" series has been reworked completely and the > last 6 patches been resent as v7. > > Doc patch is "v7 6/6" now, same subject otherwise. Ahh, thanks! Yeah, it looks like it's the same man page. I suggest we don't do anything with the man page in this patch-set (except of clarifying the content) and I'll ensure it gets ported into a reasonable shape into the new man page structure.
diff --git a/Changes.rst b/Changes.rst index 42f0d190..47fa6883 100644 --- a/Changes.rst +++ b/Changes.rst @@ -3,6 +3,10 @@ Overview of changes in 2.5 New features ------------ +Deferred client-connect + client-connect and the connect plugin API allow now asynchronous/deferred + return of the configuration file in the same way as the auth-plugin. + Client-specific tls-crypt keys (``--tls-crypt-v2``) ``tls-crypt-v2`` adds the ability to supply each client with a unique tls-crypt key. This allows large organisations and VPN providers to profit diff --git a/doc/openvpn.8 b/doc/openvpn.8 index 03ae5ac5..7a0080bf 100644 --- a/doc/openvpn.8 +++ b/doc/openvpn.8 @@ -3422,6 +3422,13 @@ is significant. If .B script returns a non\-zero error status, it will cause the client to be disconnected. + +If a +.B \-\-client\-connect cmd +wants to defer the generating of the configuration the script, should +use the client_connect_deferred_file and client_connect_config_file +environment variables and write status accordingly into these files +(See the environment section below for more details). .\"********************************************************* .TP .B \-\-client\-disconnect cmd @@ -3505,12 +3512,18 @@ This directory will be used by in the following cases: * .B \-\-client\-connect -scripts to dynamically generate client\-specific -configuration files. +scripts and +.B OPENVPN_PLUGIN_CLIENT_CONNECT +plugin hook +to dynamically generate client\-specific configuration files +and return success/failure via client_connect_deferred_file +when using deferred client connect method * .B OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY -plugin hook to return success/failure via auth_control_file +and + +plugin hook to return success/failure via auth_control_file/ when using deferred auth method * @@ -6654,6 +6667,42 @@ Set prior to execution of the script. .\"********************************************************* .TP +.B client_connect_config_file +The path to the configuration file that should be written by +the +.B \-\-client\-connect +script. The content of this environment variable is identical +to the file as a argument of the called +.B \-\-client\-connect +script. +.\"********************************************************* +.TP +.B client_connect_deferred_file +This file can be optionally written to communicate a status +code of the +.TP +.B \-\-client\-connect +script. If used for deferring, this file must be written +before the +.B \-\-client\-connect +script exits. The first character in the file has to be +'1' is to indicate normal script execution, '0' indicates an +error (in the same way that a non zero exit status does) and +'2' indicates that the script deferred returning the config +file. When the script defers returning the configuration, it +must also write '2' to to the file to indicate the deferral. +A background process or similar must then take care of writing the +configuration to the file indicated by the +.B +client_connect_config_file +environment variable and when finished, write the a '1' to this +file (or '0' in case of an error). + +The absence of any character in the file when the script finishes +executing is interpreted the same as '1'. This allows script that +are not written to support the defer mechanism to be used unmodified. +.\"********************************************************* +.TP .B common_name The X509 common name of an authenticated client. Set prior to execution of diff --git a/include/openvpn-plugin.h.in b/include/openvpn-plugin.h.in index 38fbe097..64b20886 100644 --- a/include/openvpn-plugin.h.in +++ b/include/openvpn-plugin.h.in @@ -557,12 +557,21 @@ OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_op * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure * * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by - * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY. This enables asynchronous - * authentication where the plugin (or one of its agents) may indicate - * authentication success/failure some number of seconds after the return - * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single - * char to the file named by auth_control_file in the environmental variable - * list (envp). + * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY, OPENVPN_PLUGIN_CLIENT_CONNECT and + * OPENVPN_PLUGIN_CLIENT_CONNECT_V2. This enables asynchronous + * authentication or client connect where the plugin (or one of its agents) + * may indicate authentication success/failure or client configuration some + * number of seconds after the return of the function handler. + * For OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY and OPENVPN_PLUGIN_CLIENT_CONNECT + * this is done by writing a single char to the file named by + * auth_control_file/client_connect_deferred_file + * in the environmental variable list (envp). + * + * In addition the OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER and + * OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER_V2 are called when OpenVPN tries to + * get the deferred result. For a V2 call implementing this function is + * required as information is not passed by files. For the normal version + * the call is optional. * * first char of auth_control_file: * '0' -- indicates auth failure
Patch V5: Fix typos, clarify man page section about deferred client-connect script. Add section to Changes.rst Signed-off-by: Arne Schwabe <arne@rfc2549.org> --- Changes.rst | 4 +++ doc/openvpn.8 | 55 +++++++++++++++++++++++++++++++++++-- include/openvpn-plugin.h.in | 21 ++++++++++---- 3 files changed, 71 insertions(+), 9 deletions(-)