[Openvpn-devel] wanted: mechanism to send text messages to client

[Openvpn-devel] wanted: mechanism to send text messages to client

[Gert Doering]

[-- Attachment #1: Type: text/plain, Size: 446 bytes --]

Hi,

I find myself looking for a mechanism by which I could send informational
messages ("your cert expires in two weeks, go refresh!" - "your openvpn
client needs an upgrade") from the openvpn server to incoming clients.

Of course this should work with all connecting clients, that is, "text
clients", windows GUI, Tunnelblick, iOS Connect, Android.

As far as I am aware, there is no such mechanism today.

Do we want to make one?

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Arne Schwabe]

Am 20.12.2020 um 11:54 schrieb Gert Doering:
> Hi,
>
> I find myself looking for a mechanism by which I could send informational
> messages ("your cert expires in two weeks, go refresh!" - "your openvpn
> client needs an upgrade") from the openvpn server to incoming clients.
>
> Of course this should work with all connecting clients, that is, "text
> clients", windows GUI, Tunnelblick, iOS Connect, Android.
>
> As far as I am aware, there is no such mechanism today.
>
> Do we want to make one?
>
>
>  From the server / openvpn core side, it could be something totally trivial:
>
>    push "info-msg hey there!"
>
> ... and the client would then either print this on the console
> (if !management) or dump it to management, where the GUI/Tunnelblick
> could pick it up and create a popup window.
>
See --echo.  That is basically what you desribe as info-msg in your mail


Arne

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Selva Nair]

[-- Attachment #1: Type: text/plain, Size: 1071 bytes --]

Hi,

On Sun, Dec 20, 2020 at 5:55 AM Gert Doering <gert@...1296...> wrote:

> Hi,
>
> I find myself looking for a mechanism by which I could send informational
> messages ("your cert expires in two weeks, go refresh!" - "your openvpn
> client needs an upgrade") from the openvpn server to incoming clients.
>
> Of course this should work with all connecting clients, that is, "text
> clients", windows GUI, Tunnelblick, iOS Connect, Android.
>
> As far as I am aware, there is no such mechanism today.
>

We once had extensive discussions on using echo for this. As echo
commands are up to the UI to interpret, adding new one's does
not require any changes in the core.

I had posted a draft implementation for OpenVPN-GUI (not sure it still
works, though) along with some details of the message syntax:
https://github.com/selvanair/openvpn-gui/releases/tag/v11-echo-msg

IIRC, Jonathan had written up documentation for the proposed syntax.
I don't have links to the relevant mails at hand, but should be in the
archives.

It may be best to resurrect that effort.

Selva

[-- Attachment #2: Type: text/html, Size: 1747 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Gert Doering]

[-- Attachment #1: Type: text/plain, Size: 1100 bytes --]

Hi,

On Sun, Dec 20, 2020 at 04:00:13PM +0100, Arne Schwabe wrote:
> > ... and the client would then either print this on the console
> > (if !management) or dump it to management, where the GUI/Tunnelblick
> > could pick it up and create a popup window.
> >
> See --echo.  That is basically what you desribe as info-msg in your mail

While echo sounds as if it would do what I want, it doesn't.

Echo is "something magic" - it is never printed by the 2.x client, it
is not even logged.  And it's not displayed by the GUIs either, but
instead it can be used to "do things"...

So less "echo to user" but "send this string to the management interface
and make the mgmt client do something magic"...

gert

-- 
"If was one thing all people took for granted, was conviction that if you 
 feed honest figures into a computer, honest figures come out. Never doubted 
 it myself till I met a computer with a sense of humor."
                             Robert A. Heinlein, The Moon is a Harsh Mistress

Gert Doering - Munich, Germany                             gert@...1296...

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 630 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Greg Cox]

[-- Attachment #1: Type: text/plain, Size: 3726 bytes --]

tl;dr - anything that lets me selectively put a message in front of my
users is great.  Yes please.


The number one problem my users come across is expired certs.  Nobody reads
logs until they're forced to.

A notif mechanism like you're describing would be great.
With that I can set up scripts that push notices when someone is
connected + within some amount of expiry, and instructions on what to do.

But there's also those users that almost never connect.  I dream of having
GUI clients changing their text/icons and/or refusing to even attempt to
connect, with an explicit warning of "your cert is expired", rather than
connections failing 'silently' when they use the VPN for the first time in
forever.  A user complaint of "it says my cert is expired, what do I do?"
is much easier to handle than "is the vpn broken? it worked yesterday!"
95% of the time it's certs, but I still have to triage it more fully for
the times it's not.


So IMO, 1-2 are fundamental, 3-5 are
wishlist/consideration/extensions/ideas, use or ignore as you see fit:
* Make the ability for receiving messages on a client as described.
Enabled by default, maybe selectively disable-able because someone will
think it's spammy, but I'd almost suggest not allowing it.
* Make the ability to send a user a message via management.  Enabled by
default, maybe selectively disable-able as a safety mechanism / make
someone "key the mic to speak."
* Make the ability to 'wall' a message out to all connected users in one
command, e.g. 'wall "server going down in 5 mins"' or something like that.
* Make the ability to 'post' a message for some amount of time, e.g.
'wallpost 60m "server going down at 1700"'  Sending a message gets someone
who is connected now, but misses the user who connects 2m after I go
through the list of users and I stop looking.  So, this would hang around
and pop a message to everyone connected now, plus each new connection, for
the next 60m.
* Add an option ala --[no-]use-expired-certs.  When true, proceed like you
do today; when false, if certs are expired, have the client feed itself a
message via this mechanism to popup that your certs are expired, so a user
knows right away what's wrong.  It'd be a spammy option if it tried to tell
you what to do, so I'm keeping the idea simple and generic.

Thanks for considering.

On Sun, Dec 20, 2020 at 10:55 AM Gert Doering <gert@...1296...> wrote:

> Hi,
>
> I find myself looking for a mechanism by which I could send informational
> messages ("your cert expires in two weeks, go refresh!" - "your openvpn
> client needs an upgrade") from the openvpn server to incoming clients.
>
> Of course this should work with all connecting clients, that is, "text
> clients", windows GUI, Tunnelblick, iOS Connect, Android.
>
> As far as I am aware, there is no such mechanism today.
>
> Do we want to make one?
>
>
> From the server / openvpn core side, it could be something totally trivial:
>
>   push "info-msg hey there!"
>
> ... and the client would then either print this on the console
> (if !management) or dump it to management, where the GUI/Tunnelblick
> could pick it up and create a popup window.
>
> What do you think?
>
> gert
> --
> "If was one thing all people took for granted, was conviction that if you
>  feed honest figures into a computer, honest figures come out. Never
> doubted
>  it myself till I met a computer with a sense of humor."
>                              Robert A. Heinlein, The Moon is a Harsh
> Mistress
>
> Gert Doering - Munich, Germany
> gert@...1296...
> _______________________________________________
> Openvpn-devel mailing list
> Openvpn-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/openvpn-devel
>

[-- Attachment #2: Type: text/html, Size: 6152 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Selva Nair]

[-- Attachment #1: Type: text/plain, Size: 1806 bytes --]

Hi,

On Sun, Dec 20, 2020 at 5:38 PM Gert Doering <gert@...1296...> wrote:

> Hi,
>
> On Sun, Dec 20, 2020 at 04:00:13PM +0100, Arne Schwabe wrote:
> > > ... and the client would then either print this on the console
> > > (if !management) or dump it to management, where the GUI/Tunnelblick
> > > could pick it up and create a popup window.
> > >
> > See --echo.  That is basically what you desribe as info-msg in your mail
>
> While echo sounds as if it would do what I want, it doesn't.
>
> Echo is "something magic" - it is never printed by the 2.x client, it
> is not even logged.  And it's not displayed by the GUIs either, but
> instead it can be used to "do things"...
>

The "not  getting logged" concern is easy to fix.

What echo does is to get a message from the server to the client-side UI.
Currently GUI's do not display them because so far the only meanings we
have assigned to echo commands are as directives like save-password or
forget-password.

But that doesn't mean we can't use them for messages.And, that's exactly
what we discussed 3 years ago -- see the draft implementation from Nov 2017
that I posted. Here is the link again.
https://github.com/selvanair/openvpn-gui/releases/tag/v11-echo-msg
I got no feedback then nor now.


> So less "echo to user" but "send this string to the management interface
> and make the mgmt client do something magic"...
>

A message to the user can be delivered in a useful fashion only if there is
a UI. The core itself can only write the message to log which may not be
seen in time, or to the console if one exists. And, IMO, any decent UI of
openvpn should use the management interface -- almost all do (except NM?).

I thought we already went through this when we discussed the proposed "echo
msg" in considerable detail 3 years ago.

Selva

[-- Attachment #2: Type: text/html, Size: 2852 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Maximilian Wilhelm]

Anno domini 2020 Greg Cox scripsit:

Hi,

[...]
> So IMO, 1-2 are fundamental, 3-5 are
> wishlist/consideration/extensions/ideas, use or ignore as you see fit:
> * Make the ability for receiving messages on a client as described.
> Enabled by default, maybe selectively disable-able because someone will
> think it's spammy, but I'd almost suggest not allowing it.
> * Make the ability to send a user a message via management.  Enabled by
> default, maybe selectively disable-able as a safety mechanism / make
> someone "key the mic to speak."
> * Make the ability to 'wall' a message out to all connected users in one
> command, e.g. 'wall "server going down in 5 mins"' or something like that.
> * Make the ability to 'post' a message for some amount of time, e.g.
> 'wallpost 60m "server going down at 1700"'  Sending a message gets someone
> who is connected now, but misses the user who connects 2m after I go
> through the list of users and I stop looking.  So, this would hang around
> and pop a message to everyone connected now, plus each new connection, for
> the next 60m.
> * Add an option ala --[no-]use-expired-certs.  When true, proceed like you
> do today; when false, if certs are expired, have the client feed itself a
> message via this mechanism to popup that your certs are expired, so a user
> knows right away what's wrong.  It'd be a spammy option if it tried to tell
> you what to do, so I'm keeping the idea simple and generic.

From what I learnedof our university VPN setup: +1 to everything he said :)

Best
Max
-- 
 "First they ignore you,
  then they laugh at you,
  then they fight you,
  then you win."         -- Mahatma Gandhi

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[tincanteksup]

Gert,

using server side scripting, I can push *literally* anything I want to 
the server via --push-peer-info and setenv UV_*

Example:
setenv UV_PING 10
setenv UV_PINGRESTART 60

My server side script allows the client to effectively configure 
--keepalive (and a LOT more)

My guess would be to push some expected and custom variables to the 
client at logon.

And the user can fend for themselves.

No --up .. no --issue

I guess something like --pull-peer-info would be suitable. That way, 
what ever is received can be vetted.



If computers Did have sense of humour then you lot would probably have 
gone insane by now.



On 20/12/2020 10:54, Gert Doering wrote:
> Hi,
> 
> I find myself looking for a mechanism by which I could send informational
> messages ("your cert expires in two weeks, go refresh!" - "your openvpn
> client needs an upgrade") from the openvpn server to incoming clients.
> 
> Of course this should work with all connecting clients, that is, "text
> clients", windows GUI, Tunnelblick, iOS Connect, Android.
> 
> As far as I am aware, there is no such mechanism today.
> 
> Do we want to make one?
> 
> 
>  From the server / openvpn core side, it could be something totally trivial:
> 
>    push "info-msg hey there!"
> 
> ... and the client would then either print this on the console
> (if !management) or dump it to management, where the GUI/Tunnelblick
> could pick it up and create a popup window.
> 
> What do you think?
> 
> gert
> 
> 
> 
> _______________________________________________
> Openvpn-devel mailing list
> Openvpn-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/openvpn-devel
> 

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Gert Doering]

[-- Attachment #1: Type: text/plain, Size: 786 bytes --]

Hi,

On Sun, Dec 20, 2020 at 07:31:42PM -0500, Selva Nair wrote:
> I thought we already went through this when we discussed the proposed "echo
> msg" in considerable detail 3 years ago.

Yeah, sorry.  Seems I got distracted and forgot all about the discussed
"solution space", and just remembered the itch.

I'm sure the thread is still sitting in my mailbox... will go looking for
it today.

gert
-- 
"If was one thing all people took for granted, was conviction that if you 
 feed honest figures into a computer, honest figures come out. Never doubted 
 it myself till I met a computer with a sense of humor."
                             Robert A. Heinlein, The Moon is a Harsh Mistress

Gert Doering - Munich, Germany                             gert@...1296...

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 630 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[@ 2020-12-21 7:57 UTC (permalink / raw)]

[-- Attachment #1: Type: text/plain, Size: 4545 bytes --]

пн, 21 дек. 2020 г. в 03:37, Greg Cox <gcox@...1057...>:

> tl;dr - anything that lets me selectively put a message in front of my
> users is great.  Yes please.
>
>
> The number one problem my users come across is expired certs.  Nobody
> reads logs until they're forced to.
>


that's interesting point.
being dependent on whether users logs or not does not look very good.
I'd say it is identity management related thing to renew user cert when it
is about to expire.
i.e. notify user in proper way and tell him to renew.

as a side question, how do you inform users ? i.e. is it some self service
portal ?



>
> A notif mechanism like you're describing would be great.
> With that I can set up scripts that push notices when someone is
> connected + within some amount of expiry, and instructions on what to do.
>
> But there's also those users that almost never connect.  I dream of having
> GUI clients changing their text/icons and/or refusing to even attempt to
> connect, with an explicit warning of "your cert is expired", rather than
> connections failing 'silently' when they use the VPN for the first time in
> forever.  A user complaint of "it says my cert is expired, what do I do?"
> is much easier to handle than "is the vpn broken? it worked yesterday!"
> 95% of the time it's certs, but I still have to triage it more fully for
> the times it's not.
>
>
> So IMO, 1-2 are fundamental, 3-5 are
> wishlist/consideration/extensions/ideas, use or ignore as you see fit:
> * Make the ability for receiving messages on a client as described.
> Enabled by default, maybe selectively disable-able because someone will
> think it's spammy, but I'd almost suggest not allowing it.
> * Make the ability to send a user a message via management.  Enabled by
> default, maybe selectively disable-able as a safety mechanism / make
> someone "key the mic to speak."
> * Make the ability to 'wall' a message out to all connected users in one
> command, e.g. 'wall "server going down in 5 mins"' or something like that.
> * Make the ability to 'post' a message for some amount of time, e.g.
> 'wallpost 60m "server going down at 1700"'  Sending a message gets someone
> who is connected now, but misses the user who connects 2m after I go
> through the list of users and I stop looking.  So, this would hang around
> and pop a message to everyone connected now, plus each new connection, for
> the next 60m.
> * Add an option ala --[no-]use-expired-certs.  When true, proceed like you
> do today; when false, if certs are expired, have the client feed itself a
> message via this mechanism to popup that your certs are expired, so a user
> knows right away what's wrong.  It'd be a spammy option if it tried to tell
> you what to do, so I'm keeping the idea simple and generic.
>
> Thanks for considering.
>
> On Sun, Dec 20, 2020 at 10:55 AM Gert Doering <gert@...1296...> wrote:
>
>> Hi,
>>
>> I find myself looking for a mechanism by which I could send informational
>> messages ("your cert expires in two weeks, go refresh!" - "your openvpn
>> client needs an upgrade") from the openvpn server to incoming clients.
>>
>> Of course this should work with all connecting clients, that is, "text
>> clients", windows GUI, Tunnelblick, iOS Connect, Android.
>>
>> As far as I am aware, there is no such mechanism today.
>>
>> Do we want to make one?
>>
>>
>> From the server / openvpn core side, it could be something totally
>> trivial:
>>
>>   push "info-msg hey there!"
>>
>> ... and the client would then either print this on the console
>> (if !management) or dump it to management, where the GUI/Tunnelblick
>> could pick it up and create a popup window.
>>
>> What do you think?
>>
>> gert
>> --
>> "If was one thing all people took for granted, was conviction that if you
>>  feed honest figures into a computer, honest figures come out. Never
>> doubted
>>  it myself till I met a computer with a sense of humor."
>>                              Robert A. Heinlein, The Moon is a Harsh
>> Mistress
>>
>> Gert Doering - Munich, Germany
>> gert@...1296...
>> _______________________________________________
>> Openvpn-devel mailing list
>> Openvpn-devel@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/openvpn-devel
>>
> _______________________________________________
> Openvpn-devel mailing list
> Openvpn-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/openvpn-devel
>

[-- Attachment #2: Type: text/html, Size: 7083 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Selva Nair]

[-- Attachment #1: Type: text/plain, Size: 1037 bytes --]

On Mon, Dec 21, 2020 at 2:04 AM Gert Doering <gert@...1296...> wrote:

> Hi,
>
> On Sun, Dec 20, 2020 at 07:31:42PM -0500, Selva Nair wrote:
> > I thought we already went through this when we discussed the proposed
> "echo
> > msg" in considerable detail 3 years ago.
>
> Yeah, sorry.  Seems I got distracted and forgot all about the discussed
> "solution space", and just remembered the itch.
>
> I'm sure the thread is still sitting in my mailbox... will go looking for
> it today.
>

For those who have lost the original threads:

https://sourceforge.net/p/openvpn/mailman/openvpn-users/thread/CAEsd45T%2Bd6FUJ9Po0KHwtHjfuL9Q2D-poG8yFtY45Qyh%2BtHjkg%40mail.gmail.com/#msg36136236

https://sourceforge.net/p/openvpn/mailman/openvpn-devel/thread/CAKuzo_jPThhvXTJAtzhqVUVOLPW1VGu6h2jQhVsHicY8P2WRqA%40mail.gmail.com/#msg36141193

That was in Nov-Dec 2017. Actually, I was also thinking of reviving this
only the other day when intimating users about some updates came up..
Somehow such itches re-surface at the end of the year :)

Selva

[-- Attachment #2: Type: text/html, Size: 1881 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Greg Cox]

[-- Attachment #1: Type: text/plain, Size: 2237 bytes --]

On Mon, Dec 21, 2020 at 7:57 AM Илья Шипицин <chipitsine@...277...> wrote:

> that's interesting point.
> being dependent on whether users logs or not does not look very good.
>

We only go to their logs when they come to us with issues.  When we can
head the users off ahead of time, it's easier.


> I'd say it is identity management related thing to renew user cert when it
> is about to expire.
> i.e. notify user in proper way and tell him to renew.
>
> as a side question, how do you inform users ? i.e. is it some self service
> portal ?
>

It's definitely "an IAM problem" to begin with... but it becomes "a VPN
problem" eventually.  (abstractly speaking).

We have a cron that, every day, looks at the CA's VPN certs.  If you are at
14, 7, 3, 2, or 1 days left, you get an email warning of the impending
expiration and links to the login portal + docs so you can renew (or revoke
the cert and stop being nagged).  At 2 days expired you get a final mail
explaining that it's expired and you won't be nagged anymore and what to do
if you need back in.

This helps tickets a lot, but when people filter their mail and never read
it, the lack of access falls through to being "a VPN problem."  We did what
we could to head off the issue ahead of time from the IAM side, and it
becomes a situation where, as the support personnel, "well, there MUST be
something vastly wrong because surely nobody would miss 6 emails and end up
here asking me to look at a problem." ... except, they do.

My contention is, a VPN client has enough information from its own certs to
know when its certs are expired and thus not going to work (Yes, there's
plenty of OTHER reasons a connection can fail, but in a well designed
setup, the user's certs will go stale long before the server).  It tells
you this problem in the logs, which folks never read.  If the software were
to contain a mechanism to make certain failure cases automatically more
prominent, particularly for 'simple' users who have GUI clients, it'll be a
big win for supportability on larger installs.

And I realize this is getting into advocacy and away from what's right for
a -devel list, so I'll stop here on this thread.

[-- Attachment #2: Type: text/html, Size: 3766 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Gert Doering]

[-- Attachment #1: Type: text/plain, Size: 2493 bytes --]

Hi,

On Mon, Dec 21, 2020 at 06:24:36PM +0000, Greg Cox wrote:
> My contention is, a VPN client has enough information from its own certs to
> know when its certs are expired and thus not going to work (Yes, there's
> plenty of OTHER reasons a connection can fail, but in a well designed
> setup, the user's certs will go stale long before the server).  It tells
> you this problem in the logs, which folks never read.  

We consciously decided to make this not more prominent (so, warning only,
not error) because the client's machine's time might be wrong - and 
ultimately it's the server's notion of time that decides if the cert
is valid or not.  So this is a hint, but not a "IT WILL NOT WORK!" hard
error.

> If the software were
> to contain a mechanism to make certain failure cases automatically more
> prominent, particularly for 'simple' users who have GUI clients, it'll be a
> big win for supportability on larger installs.

This is indeed getting into philosophy... we do send different types of
AUTH_FAILED today (like, for token expired).  Maybe we could send an
"AUTH_FAILED,cert expired" and have the client display this?

(I admit that I'm neither an expert on AUTH_FAILED message, nor on
"what is the client doing on variations of it", nor on "what *should*
be the expected outcome?".  Selva, Arne will know more).

> And I realize this is getting into advocacy and away from what's right for
> a -devel list, so I'll stop here on this thread.

I find this a very useful exchange, and I would call it "on-topic on
openvpn-devel".  The openvpn-users list is more about "end user issues",
but what you and Max bring forward is "this is where openvpn could be 
more helpful for admins" - and we developers want to listen to that :-)

For me, openvpn usually does what I want (and if not, I start threads
like this one, and try to either code it myself or convince one of the
others that "we!" want to have this and they should code it :-) ) - but
since this is openvpn, there is a myriad other ways to use it which I
might have never thought about...

gert
-- 
"If was one thing all people took for granted, was conviction that if you 
 feed honest figures into a computer, honest figures come out. Never doubted 
 it myself till I met a computer with a sense of humor."
                             Robert A. Heinlein, The Moon is a Harsh Mistress

Gert Doering - Munich, Germany                             gert@...1296...

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 630 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Arne Schwabe]

Am 21.12.20 um 20:11 schrieb Gert Doering:
> Hi,
> 
> On Mon, Dec 21, 2020 at 06:24:36PM +0000, Greg Cox wrote:
>> My contention is, a VPN client has enough information from its own certs to
>> know when its certs are expired and thus not going to work (Yes, there's
>> plenty of OTHER reasons a connection can fail, but in a well designed
>> setup, the user's certs will go stale long before the server).  It tells
>> you this problem in the logs, which folks never read.  
> 
> We consciously decided to make this not more prominent (so, warning only,
> not error) because the client's machine's time might be wrong - and 
> ultimately it's the server's notion of time that decides if the cert
> is valid or not.  So this is a hint, but not a "IT WILL NOT WORK!" hard
> error.
> 
>> If the software were
>> to contain a mechanism to make certain failure cases automatically more
>> prominent, particularly for 'simple' users who have GUI clients, it'll be a
>> big win for supportability on larger installs.
> 
> This is indeed getting into philosophy... we do send different types of
> AUTH_FAILED today (like, for token expired).  Maybe we could send an
> "AUTH_FAILED,cert expired" and have the client display this?
> 
> (I admit that I'm neither an expert on AUTH_FAILED message, nor on
> "what is the client doing on variations of it", nor on "what *should*
> be the expected outcome?".  Selva, Arne will know more).

It is easy to add that message, however the question is if we want to.
Sending different AUTH_FAILED message also leaks information. Especially
with authentication you don't want to give an attacker an idea how they
get before failing the authentication. I.e. if you send User disable,
certificate expired, account not allow to use VPN etc. an attacker gets
information about the account/profile he using to connect.

So with these AUTH_FAILED codes you have to be very careful not to
accidently leak information. I.e. AUTH_FAILED, cert expired happens only
if user/pass is right/wrong, otherwise you get a normal AUTH_FAILED.

HOWEVER, on the client side. We can transform a normal AUTH_FAILED into
an AUTH_FAILED, server gave no reason, [client certificate is expired]
or something like that.

Arne

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Selva Nair]

[-- Attachment #1: Type: text/plain, Size: 2827 bytes --]

Hi,

On Mon, Dec 21, 2020 at 3:27 PM Arne Schwabe <arne@...1227...> wrote:

> Am 21.12.20 um 20:11 schrieb Gert Doering:
> > Hi,
> >
> > On Mon, Dec 21, 2020 at 06:24:36PM +0000, Greg Cox wrote:
> >> My contention is, a VPN client has enough information from its own
> certs to
> >> know when its certs are expired and thus not going to work (Yes, there's
> >> plenty of OTHER reasons a connection can fail, but in a well designed
> >> setup, the user's certs will go stale long before the server).  It tells
> >> you this problem in the logs, which folks never read.
> >
> > We consciously decided to make this not more prominent (so, warning only,
> > not error) because the client's machine's time might be wrong - and
> > ultimately it's the server's notion of time that decides if the cert
> > is valid or not.  So this is a hint, but not a "IT WILL NOT WORK!" hard
> > error.
> >
> >> If the software were
> >> to contain a mechanism to make certain failure cases automatically more
> >> prominent, particularly for 'simple' users who have GUI clients, it'll
> be a
> >> big win for supportability on larger installs.
> >
> > This is indeed getting into philosophy... we do send different types of
> > AUTH_FAILED today (like, for token expired).  Maybe we could send an
> > "AUTH_FAILED,cert expired" and have the client display this?
> >
> > (I admit that I'm neither an expert on AUTH_FAILED message, nor on
> > "what is the client doing on variations of it", nor on "what *should*
> > be the expected outcome?".  Selva, Arne will know more).
>
> It is easy to add that message, however the question is if we want to.
> Sending different AUTH_FAILED message also leaks information. Especially
> with authentication you don't want to give an attacker an idea how they
> get before failing the authentication. I.e. if you send User disable,
> certificate expired, account not allow to use VPN etc. an attacker gets
> information about the account/profile he using to connect.
>
> So with these AUTH_FAILED codes you have to be very careful not to
> accidently leak information. I.e. AUTH_FAILED, cert expired happens only
> if user/pass is right/wrong, otherwise you get a normal AUTH_FAILED.
>
> HOWEVER, on the client side. We can transform a normal AUTH_FAILED into
> an AUTH_FAILED, server gave no reason, [client certificate is expired]
> or something like that.
>

We already warn on the client if the certificate has expired and warnings
show up in red at least in OpenvPN-GUI. Sure, UI's can add more bold-face
warnings and popups showing probable reasons, but better leave the core as
is.

To chime in with Arne, a client presenting an invalid cert (expired, in CRL
or otherwise bogus) has to be treated as rogue and should not be given any
additional feedback from the server on the reason for failure.

Selva

[-- Attachment #2: Type: text/html, Size: 3522 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[@ 2020-12-22 5:37 UTC (permalink / raw)]

[-- Attachment #1: Type: text/plain, Size: 2754 bytes --]

пн, 21 дек. 2020 г. в 23:26, Greg Cox <gcox@...1057...>:

> On Mon, Dec 21, 2020 at 7:57 AM Илья Шипицин <chipitsine@...277...> wrote:
>
>> that's interesting point.
>> being dependent on whether users logs or not does not look very good.
>>
>
> We only go to their logs when they come to us with issues.  When we can
> head the users off ahead of time, it's easier.
>
>
>> I'd say it is identity management related thing to renew user cert when
>> it is about to expire.
>> i.e. notify user in proper way and tell him to renew.
>>
>> as a side question, how do you inform users ? i.e. is it some self
>> service portal ?
>>
>
> It's definitely "an IAM problem" to begin with... but it becomes "a VPN
> problem" eventually.  (abstractly speaking).
>
> We have a cron that, every day, looks at the CA's VPN certs.  If you are
> at 14, 7, 3, 2, or 1 days left, you get an email warning of the impending
> expiration and links to the login portal + docs so you can renew (or revoke
> the cert and stop being nagged).  At 2 days expired you get a final mail
> explaining that it's expired and you won't be nagged anymore and what to do
> if you need back in.
>

wow.

it is exactly how I meant it :)


>
> This helps tickets a lot, but when people filter their mail and never read
> it, the lack of access falls through to being "a VPN problem."  We did what
> we could to head off the issue ahead of time from the IAM side, and it
> becomes a situation where, as the support personnel, "well, there MUST be
> something vastly wrong because surely nobody would miss 6 emails and end up
> here asking me to look at a problem." ... except, they do.
>

if there's self service portal, can we use dhcp option 114 (which is used
for captive portal) ?



> My contention is, a VPN client has enough information from its own certs
> to know when its certs are expired and thus not going to work (Yes, there's
> plenty of OTHER reasons a connection can fail, but in a well designed
> setup, the user's certs will go stale long before the server).  It tells
> you this problem in the logs, which folks never read.  If the software were
> to contain a mechanism to make certain failure cases automatically more
> prominent, particularly for 'simple' users who have GUI clients, it'll be a
> big win for supportability on larger installs.
>
> And I realize this is getting into advocacy and away from what's right for
> a -devel list, so I'll stop here on this thread.
>

we are still on topic.


>
> _______________________________________________
> Openvpn-devel mailing list
> Openvpn-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/openvpn-devel
>

[-- Attachment #2: Type: text/html, Size: 5159 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Michael Kress]

Hi,
Am Sun, 20 Dec 2020 11:54:30 +0100
schrieb Gert Doering <gert@...1296...>:
> I find myself looking for a mechanism by which I could send
> informational messages ("your cert expires in two weeks, go refresh!"
> - "your openvpn client needs an upgrade") from the openvpn server to
> incoming clients.
 
I'm quite late to the party, but something similar like this I asked a
few days ago (06.12.2020):
https://sourceforge.net/p/openvpn/mailman/message/37170200/

I proposed a generic way to send whatever you like over the
control channel. A plugin could be triggerd by hooks which react on
this generic push command. The plugins for all different OS and UIs
could trigger messages in new windows or network managers.

Your wish is to send a message, mine was to send a certificate. A
generic push command could achive both, as long the plugin is
installed.

echo could be a possibility, but fiddling with log files must also be
implemented (by a plugin?)

Servus
  Michael

> Of course this should work with all connecting clients, that is, "text
> clients", windows GUI, Tunnelblick, iOS Connect, Android.
> 
> As far as I am aware, there is no such mechanism today.
> 
> Do we want to make one?
> 
> 
> From the server / openvpn core side, it could be something totally
> trivial:
> 
>   push "info-msg hey there!"
> 
> ... and the client would then either print this on the console 
> (if !management) or dump it to management, where the GUI/Tunnelblick
> could pick it up and create a popup window.
> 
> What do you think?
> 
> gert

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Steffan Karger]

Hi,

On 21-12-2020 21:25, Arne Schwabe wrote:
> Am 21.12.20 um 20:11 schrieb Gert Doering:
>> On Mon, Dec 21, 2020 at 06:24:36PM +0000, Greg Cox wrote:
>>> If the software were
>>> to contain a mechanism to make certain failure cases automatically more
>>> prominent, particularly for 'simple' users who have GUI clients, it'll be a
>>> big win for supportability on larger installs.
>>
>> This is indeed getting into philosophy... we do send different types of
>> AUTH_FAILED today (like, for token expired).  Maybe we could send an
>> "AUTH_FAILED,cert expired" and have the client display this?
>>
>> (I admit that I'm neither an expert on AUTH_FAILED message, nor on
>> "what is the client doing on variations of it", nor on "what *should*
>> be the expected outcome?".  Selva, Arne will know more).
> 
> It is easy to add that message, [...]

Uhm, I would say it's impossible to send that message. AUTH_FAILED
messages are sent over the control channel, while in case of certificate
errors the control channel will never be initialized.

We could however do something that has the same effect: don't prevent
TLS from sending it's "certificate_expired" alert. OpenVPN 2 (don't know
about 3) currently just doesn't respond at all if it detects a TLS error.

IIRC, this extra-paranoid behaviour has saved us from at least one of
the timing-based attacks on TLS from the past, but I can't recall which one.

At the same time, the TLS protocol and it's implementation have matured
a lot since heartbleed. Possibly beyond the point where usability
concerns now outweigh the security concerns. Before anyone suggests
making this optional: no. no. no. I strongly believer we should
carefully consider if we want to allow TLS to send alerts, or leave this
as-is.

David actually already brought this up in 2016, see this thread:
https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg12892.html

Note that any of this is separate from the initial discussion, where
Gert proposes to send notifications *before* the certificate expires.

-Steffan

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Jan Just Keijser]

[-- Attachment #1: Type: text/plain, Size: 1750 bytes --]

On 21/12/20 18:22, Selva Nair wrote:
>
>
> On Mon, Dec 21, 2020 at 2:04 AM Gert Doering <gert@...1296... 
> <mailto:gert@...1296...>> wrote:
>
>     Hi,
>
>     On Sun, Dec 20, 2020 at 07:31:42PM -0500, Selva Nair wrote:
>     > I thought we already went through this when we discussed the
>     proposed "echo
>     > msg" in considerable detail 3 years ago.
>
>     Yeah, sorry.  Seems I got distracted and forgot all about the
>     discussed
>     "solution space", and just remembered the itch.
>
>     I'm sure the thread is still sitting in my mailbox... will go
>     looking for
>     it today.
>
>
> For those who have lost the original threads:
>
> https://sourceforge.net/p/openvpn/mailman/openvpn-users/thread/CAEsd45T%2Bd6FUJ9Po0KHwtHjfuL9Q2D-poG8yFtY45Qyh%2BtHjkg%40mail.gmail.com/#msg36136236
>
> https://sourceforge.net/p/openvpn/mailman/openvpn-devel/thread/CAKuzo_jPThhvXTJAtzhqVUVOLPW1VGu6h2jQhVsHicY8P2WRqA%40mail.gmail.com/#msg36141193
>
> That was in Nov-Dec 2017. Actually, I was also thinking of reviving 
> this only the other day when intimating users about some updates 
> came up.. Somehow such itches re-surface at the end of the year :)
>
sorry to chip on so late, but at some point we did have a way to push 
env vars to the client (back in v2.2 at least):

inside a client-connect script you can/could do

echo "push \"setenv-safe MSG1 'hello'\"" > $1
echo "push \"setenv-safe MSG2 'download version 2.5 please'\"" >> $1

and then on the client-side you'd simply have to process them (as 
OPENVPN_MSG1 and OPENVPN_MSG2) - couldn't we reuse that to send messages 
to a connected client?

Sending messages to an unauthenticated client - other than "wrong 
password , go away" - seems dangerous to me.

JM2CW,

JJK



[-- Attachment #2: Type: text/html, Size: 3580 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Selva Nair]

[-- Attachment #1: Type: text/plain, Size: 2309 bytes --]

Hi,

Merry Christmas!

On Wed, Dec 23, 2020 at 6:15 AM Jan Just Keijser <janjust@...1147...> wrote:

> On 21/12/20 18:22, Selva Nair wrote:
>
>
>
> On Mon, Dec 21, 2020 at 2:04 AM Gert Doering <gert@...1296...> wrote:
>
>> Hi,
>>
>> On Sun, Dec 20, 2020 at 07:31:42PM -0500, Selva Nair wrote:
>> > I thought we already went through this when we discussed the proposed
>> "echo
>> > msg" in considerable detail 3 years ago.
>>
>> Yeah, sorry.  Seems I got distracted and forgot all about the discussed
>> "solution space", and just remembered the itch.
>>
>> I'm sure the thread is still sitting in my mailbox... will go looking for
>> it today.
>>
>
> For those who have lost the original threads:
>
>
> https://sourceforge.net/p/openvpn/mailman/openvpn-users/thread/CAEsd45T%2Bd6FUJ9Po0KHwtHjfuL9Q2D-poG8yFtY45Qyh%2BtHjkg%40mail.gmail.com/#msg36136236
>
>
> https://sourceforge.net/p/openvpn/mailman/openvpn-devel/thread/CAKuzo_jPThhvXTJAtzhqVUVOLPW1VGu6h2jQhVsHicY8P2WRqA%40mail.gmail.com/#msg36141193
>
> That was in Nov-Dec 2017. Actually, I was also thinking of reviving this
> only the other day when intimating users about some updates came up..
> Somehow such itches re-surface at the end of the year :)
>
> sorry to chip on so late, but at some point we did have a way to push env
> vars to the client (back in v2.2 at least):
>
> inside a client-connect script you can/could do
>
> echo "push \"setenv-safe MSG1 'hello'\"" > $1
> echo "push \"setenv-safe MSG2 'download version 2.5 please'\"" >> $1
>

setenv-safe is not passed on to the UI/GUI, so not very useful for sending
messages to the user. In fact we already use echo to send env variables to
the UI -- OpenVPN-GUI interprets
push "echo setenv foo bar" and passes it in the env to scripts run by the
GUI.
See https://github.com/OpenVPN/openvpn-gui/pull/200
In one of our setups we use it to pass file server names, SMB shares to map
etc.

Among options that already exist, "echo" is the best candidate for this
purpose, and it's designed for sending "commands" (which could be messages)
from server to client side UI. It's use only requires an agreement on the
syntax so that all UI authors can code to interpret them consistently.

I find it hard to imagine why everyone seems to be avoiding "echo" and
trying to find alternatives.

Selva

[-- Attachment #2: Type: text/html, Size: 4435 bytes --]

[Openvpn-devel] [PATCH] Document common uses of 'echo' directive, re-enable logging for 'echo'.

[Gert Doering]

The 'echo' command can be used to signal information to an OpenVPN
GUI driving the openvpn core via management interface.  Which commands
exists and their syntax has so far been mostly undocumented.

Condense the long and good discussion between Selva Nair and
Jonathan K. Bullard into doc/gui-notes.txt (initial draft from
Jonathan, comments from Selva and Arne), with a pointer added
to doc/management-notes.txt.

See:

https://sourceforge.net/p/openvpn/mailman/openvpn-users/thread/CAEsd45T%2Bd6FUJ9Po0KHwtHjfuL9Q2D-poG8yFtY45Qyh%2BtHjkg%40mail.gmail.com/#msg36136236

and

https://sourceforge.net/p/openvpn/mailman/openvpn-devel/thread/CAKuzo_jPThhvXTJAtzhqVUVOLPW1VGu6h2jQhVsHicY8P2WRqA%40mail.gmail.com/#msg36141193

for the details.

Re-enable logging of 'echo' statements, but only for the particular
class of messages starting with 'echo msg...'.

Signed-off-by: Gert Doering <gert@...1296...>
---
 doc/Makefile.am          |   2 +-
 doc/gui-notes.txt        | 363 +++++++++++++++++++++++++++++++++++++++
 doc/management-notes.txt |  10 ++
 src/openvpn/options.c    |  15 +-
 4 files changed, 382 insertions(+), 8 deletions(-)
 create mode 100644 doc/gui-notes.txt

diff --git a/doc/Makefile.am b/doc/Makefile.am
index df2f54a3..e411f5f9 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -15,7 +15,7 @@ MAINTAINERCLEANFILES = \
 SUBDIRS = doxygen
 
 dist_doc_DATA = \
-	management-notes.txt
+	management-notes.txt gui-notes.txt
 
 dist_noinst_DATA = \
 	README.plugins interactive-service-notes.rst \
diff --git a/doc/gui-notes.txt b/doc/gui-notes.txt
new file mode 100644
index 00000000..9715e8f6
--- /dev/null
+++ b/doc/gui-notes.txt
@@ -0,0 +1,363 @@
+Management Interface "echo" protocol
+
+================================================================================
+THIS IS A PRELIMINARY VERSION OF THIS DOCUMENT. ALL INFORMATION IN IT
+IS SUBJECT TO CHANGE.
+================================================================================
+
+
+    CONTENTS
+        THE OPENVPN --ECHO OPTION
+        ENVIRONMENT COMMAND
+        MESSSAGE COMMANDS
+        PASSWORD COMMANDS
+        QUOTING
+        COMMMAND DETAILS
+
+
+=========================
+THE OPENVPN --ECHO OPTION
+=========================
+
+The OpenVPN --echo option causes commands to be sent out through the
+management interface, typically to a Graphic User Interface (GUI) such
+as "OpenVPN for Android", "Tunnelblick" (for macOS), or "Windows
+OpenVPN GUI". It can be included in a configuration file or on a
+command line, or can be pushed from the server.
+
+This document describes the commands that can be sent and how they are
+interpreted by various GUIs.
+
+ * OpenVPN does not process the commands in an --echo option; it only
+sends them out through the management interface.
+
+ * "echo" commands are processed by the GUI if, as, when, and in the
+order they are received. If no GUI is present the processing of
+commands may be delayed, the commands may never be processed, or only
+some commands may be processed. (That can happen if OpenVPN discards
+commands because its buffer for the commands fills up.)
+
+ * There is no mechanism for the GUI to acknowledge the receipt,
+success, or failure of a command.
+
+ * "echo" commands are stored by OpenVPN (within limits, see the next
+point) and sent only when the GUI requests them through the management
+interface. "echo" commands in the configuration file or the command
+line are typically requested and processed at the start of a
+connection attempt. "echo" commands that are pushed by the server are
+also typically asked for at the start of a connection attempt but can
+be sent at any time. They are processed in the middle of a connection
+attempt or after a connection is established, as the "push" options
+are received by the client from the server.
+
+  * OpenVPN's storage for echo commands is limited in size, so a large
+number of commands or commands with long messages may require that
+some commands be removed from the storage. If that happens, some of
+the commands may not be sent through the management interface when a
+GUI does connect to it or asks for the "echo" commands.
+
+ * On SIGUSR1 and SIGHUP connection restarts, "echo" commands that
+were sent through the management interface and have been saved by
+OpenVPN are sent again and will be re-processed by the GUI. (The
+message commands include a mechanism for muting (skipping) duplicate
+messages, see MESSAGE COMMANDS, below.)
+
+ * OpenVPN limits the number of separate arguments in each line of a
+configuration file. Arguments may be quoted to work around this
+limitation, see QUOTING, below.
+
+ * OpenVPN limits the size of each "echo" command sent over the
+management interface to 255 bytes, including overhead characters. To
+allow messages of arbitrary length, several message commands can be
+concatenated together before being displayed to the user, see MESSAGE
+COMMANDS, below.
+
+ * There no indication to the GUI of the source of the command
+(configuration file, command line option, or pushed from a server). It
+might be possible for the GUI to deduce that a command was pushed from
+a server because of timing or other management interface interactions.
+
+
+===================
+ENVIRONMENT COMMAND
+===================
+
+Typically, a GUI allows users to specify shell commands (typically
+scripts) to run at certain points in the connection/disconnection
+process, in addition to those provided by OpenVPN options such as
+"--up" and "--down".
+
+The "setenv" command can be used to set environment variables that are
+available to the scripts run by the GUI. Each "setenv" command
+specifies a value for one environment variable that is available to
+the scripts that the GUI runs.
+
+This is similar to Openvpn's "--setenv" option, which specifies an
+additional environment variable that is included in the environment
+variables that are available to the scripts that OpenVPN runs.
+
+
+=================
+MESSSAGE COMMANDS
+=================
+
+Four commands can be used to display a message to the user from the
+OpenVPN configuration or server:
+
+    msg
+    msg-n
+    msg-window
+    msg-notify
+
+"msg" and "msg-n" commands are concatenated to construct a message.
+When a "msg-window"or "msg-notify" command is received the message is
+displayed to the user.
+
+Identical messages (same title, text, and destination) received during
+one connection may be ignored or muted. Some GUIs may only show the
+first message for a connection, or the first message shown in a window
+and the first message shown as a notification.
+
+
+=================
+PASSWORD COMMANDS
+=================
+
+Three commands can be used to control the GUI's storage of usernames,
+passwords, and private keys:
+
+    disable-save-passwords
+    forget-passwords
+    save-passwords
+
+
+=======
+QUOTING
+=======
+
+ * In a configuration file, the rest of the line is parsed into
+separate arguments  and then 'echo' and the arguments are passed, each
+separated by a single space, through the management interface. For
+example:
+
+    echo     argument1 argument2
+    echo    "     argument1      argument2"
+
+will be sent through the management interface as
+
+    >ECHO:timestamp,argument1,argument2
+    >ECHO:timestamp,     argument1,     argument2
+
+ * In a command line option, the single argument following "--echo" is
+parsed similarly, so
+
+    --echo   "argument1     argument2"
+    --echo    "'    argument1     argument2'"
+
+will be sent through the management interface as
+
+    >ECHO:timestamp,argument1,argument2
+    >ECHO:timestamp,     argument1,     argument2
+
+ * In a "push" option in a server configuration file, the single
+option following "push" is parsed similarly, so
+
+    push "echo argument1 argument2 argument3   argument4"
+    push echo "'    argument1 argument2 argument3   argument4'"
+
+will be sent through the management interface as
+
+    >ECHO:timestamp,argument1,argument2,argument3 argument4
+    >ECHO:timestamp,     argument1,argument2 argument3   argument4
+
+
+================
+COMMMAND DETAILS
+================
+
+
+COMMAND -- disable-save-passwords
+---------------------------------
+
+Syntax: disable-save-passwords
+
+The GUI is instructed to not allow the user to save passwords or
+private keys for the configuration. The user is still allowed to save
+usernames. Any passwords or private keys that have been saved will be
+forgotten.
+
+This command will be effective at startup only if present in the
+configuration file or as a command line option. If pushed from the
+server, saving passwords will be disabled in password prompts only
+after the initial prompt has been shown to the user.
+
+    Android: ??????
+
+    Tunnelblick: Planned. This command will disable saving of
+passwords or private keys and forget any saved usernames, passwords,
+or private keys regardless of the normal (non-forced) global or
+per-configuration settings. A computer administrator can "force" this
+setting, overriding this command.
+
+    Windows OpenVPN GUI: Planned. This command will disable saving of
+passwords or private keys and forget any saved usernames, passwords,
+or private keys regardless of any global settings.
+
+
+COMMAND -- forget-passwords
+---------------------------
+
+Syntax: forget-passwords
+
+The GUI is instructed to forget any usernames, passwords, and private
+keys it has saved for the configuration. Useful when pushed from the
+server so that it is processed after authentication.
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: supported since release 2.4.1 (GUI version 11.5.0)
+
+
+COMMAND -- msg
+--------------
+
+Syntax: msg text
+
+The text is appended to any previous text from "msg" or "msg-n"
+commands, and a newline is appended after that.
+
+A trailing newline will be removed from the completed message before
+it is displayed to the user.
+
+The text may include any UTF-8 character except a comma (","), CR
+(0x0D), LF (0x0A), or NUL (0x00).
+
+The text may not contain percent ("%") except in "percent encoding"
+sequences. To display a percent sign, use %25.
+
+The text may not contain commas (",") because of constraints imposed
+by OpenVPN. Commas should be encoded using "percent encoding" (URL
+encoding): a '%' character followed by two hexadecimal digits, the
+high- and then low-nibble of the ASCII code for the character to be
+shown. Examples: a comma is encoded as %2C or %2c; a percent sign is
+encoded as %25.
+
+The insertion of line endings (CR, LF) in the text is discouraged
+because it is OS dependent. Instead, use the "msg" command, which
+appends a line ending appropriate for the OS on which the GUI is
+running.
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: Planned.
+
+COMMAND -- msg-n
+----------------
+
+Syntax: msg-n text
+
+The text is appended to any previous text from "msg"" or "msg-n""
+commands. (Like "msg" except that no newline is appended.)
+
+See "COMMAND -- msg" for details about "text".
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: Planned.
+
+COMMAND -- msg-notify
+---------------------
+
+Syntax: msg-notify title
+
+The text from previous "msg" and/or "msg-n" commands is displayed to
+the user as a notification with title "title" and the previous text is
+forgotten.
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: Planned.
+
+Note: The max length that will correctly display as a notification
+message is OS dependent.
+
+
+COMMAND -- msg-window title
+---------------------------
+
+Syntax: msg-window title
+
+The text from previous "msg" and/or "msg-n" commands is displayed to
+the user in a non-modal popup window with title "title" and the
+previous text is forgotten..
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: Planned.
+
+
+COMMAND -- save-passwords
+-------------------------
+
+Syntax: save-passwords
+
+The GUI is instructed to allow the user to save usernames, passwords
+and private keys for the configuration.
+
+This command will be effective at startup only if present in the
+configuration file or as a command line option. If pushed from the
+server, saving passwords will be allowed in password prompts only
+after the initial prompt has been shown to the user.
+
+This command typically has the effect of presenting the password
+dialogs to the user with a "save password" checkbox checked. The user
+may still uncheck it during the dialog.
+
+    Android: ??????
+
+    Tunnelblick: Planned. Tunnelblick ignores this command. Usernames,
+passwords, and private keys may be saved by default, and this command
+will not override the separate Tunnelblick global or per-configuration
+settings used to disable saving them.
+
+    Windows OpenVPN GUI: Supported since release 2.4.1 (GUI version 11.5.0)
+
+
+COMMAND -- setenv
+-----------------
+
+Syntax: setenv name value
+
+Sets an environment variable that will be available to the scripts run
+by the GUI.
+
+This will set environment variable "OPENVPN_name" to value "value" for
+the scripts run by the GUI. "name" is changed to "OPENVPN_name" to
+prevent overwriting sensitive variables such as PATH. Variables are
+set in the order received, with later values replacing earlier ones
+for the same "name".
+
+Names may include only alphanumeric characters and underscores. A
+"setenv" command with an invalid name will be ignored.
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: Planned. When the variables set by "setenv"
+are merged with those for the process environment, the variables set
+by "setenv" are listed first, but any duplicates in the process
+environment are not removed. This means that any variables with the
+same name will have the value of the variable in the process
+environment.
+
diff --git a/doc/management-notes.txt b/doc/management-notes.txt
index 61daaf07..50f0f567 100644
--- a/doc/management-notes.txt
+++ b/doc/management-notes.txt
@@ -137,6 +137,16 @@ history while simultaneously activating real-time updates:
 The size of the echo buffer is currently hardcoded to 100
 messages.
 
+
+Generally speaking, the OpenVPN Core does not understand echo
+messages at all (so a cooperating GUI and Server can use this
+mechanism for arbitrary information transport).
+
+This said, a few echo commands have been agreed upon between the
+community maintained OpenVPN Windows GUI and Tunnelblick for MacOS,
+and documentation of these can be found in doc/gui-notes.txt.
+
+
 COMMAND -- exit, quit
 ---------------------
 
diff --git a/src/openvpn/options.c b/src/openvpn/options.c
index ff3954d5..36009f4f 100644
--- a/src/openvpn/options.c
+++ b/src/openvpn/options.c
@@ -5306,13 +5306,14 @@ add_option(struct options *options,
         }
         if (good)
         {
-#if 0
-            /* removed for now since ECHO can potentially include
-             * security-sensitive strings */
-            msg(M_INFO, "%s:%s",
-                pull_mode ? "ECHO-PULL" : "ECHO",
-                BSTR(&string));
-#endif
+            /* only message-related ECHO are logged, since other ECHOs
+             * can potentially include security-sensitive strings */
+            if (strncmp(p[1],"msg",3) == 0)
+            {
+                msg(M_INFO, "%s:%s",
+                    pull_mode ? "ECHO-PULL" : "ECHO",
+                    BSTR(&string));
+            }
 #ifdef ENABLE_MANAGEMENT
             if (management)
             {
-- 
2.26.2

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Gert Doering]

[-- Attachment #1: Type: text/plain, Size: 1507 bytes --]

Hi,

On Mon, Dec 21, 2020 at 12:22:20PM -0500, Selva Nair wrote:
> > I'm sure the thread is still sitting in my mailbox... will go looking for
> > it today.
> 
> For those who have lost the original threads:
> 
> https://sourceforge.net/p/openvpn/mailman/openvpn-users/thread/CAEsd45T%2Bd6FUJ9Po0KHwtHjfuL9Q2D-poG8yFtY45Qyh%2BtHjkg%40mail.gmail.com/#msg36136236
> 
> https://sourceforge.net/p/openvpn/mailman/openvpn-devel/thread/CAKuzo_jPThhvXTJAtzhqVUVOLPW1VGu6h2jQhVsHicY8P2WRqA%40mail.gmail.com/#msg36141193
> 
> That was in Nov-Dec 2017. Actually, I was also thinking of reviving this
> only the other day when intimating users about some updates came up..

Thanks for digging these up for me.  Very interesting read, this :-)

I have tried to shape this into a "v 0.1" patch which should hit the list
"right now", also in reply-to to your e-mail.  Comments and corrections
welcome, I'll whack this as long as needed.  It's in patch form, but 
basically a draft, inviting comments.


> Somehow such itches re-surface at the end of the year :)

Let's see if we can progress this a bit more :-)

gert
-- 
"If was one thing all people took for granted, was conviction that if you 
 feed honest figures into a computer, honest figures come out. Never doubted 
 it myself till I met a computer with a sense of humor."
                             Robert A. Heinlein, The Moon is a Harsh Mistress

Gert Doering - Munich, Germany                             gert@...1296...

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 630 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Gert Doering]

[-- Attachment #1: Type: text/plain, Size: 967 bytes --]

Hi,

On Fri, Dec 25, 2020 at 12:08:16PM -0500, Selva Nair wrote:
> I find it hard to imagine why everyone seems to be avoiding "echo" and
> trying to find alternatives.

Well, in the beginning of this thread, having all forgotten about the
previous thread (still puzzling me) I only had the nagging memory that
"nobody understands 'echo' but it does not do what I want".

Since then I have been converted to the One True Echo and agree with
you that *for this purpose* it's the approach that needs the least
changes to existing infrastructure, and will get the job done.

gert
-- 
"If was one thing all people took for granted, was conviction that if you 
 feed honest figures into a computer, honest figures come out. Never doubted 
 it myself till I met a computer with a sense of humor."
                             Robert A. Heinlein, The Moon is a Harsh Mistress

Gert Doering - Munich, Germany                             gert@...1296...

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 630 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Gert Doering]

[-- Attachment #1: Type: text/plain, Size: 3239 bytes --]

Hi,

On Sun, Dec 20, 2020 at 07:06:57PM +0000, Greg Cox wrote:
> So IMO, 1-2 are fundamental, 3-5 are
> wishlist/consideration/extensions/ideas, use or ignore as you see fit:
> * Make the ability for receiving messages on a client as described.
> Enabled by default, maybe selectively disable-able because someone will
> think it's spammy, but I'd almost suggest not allowing it.
> * Make the ability to send a user a message via management.  Enabled by
> default, maybe selectively disable-able as a safety mechanism / make
> someone "key the mic to speak."

These two can be done with the proposed "echo msg..." mechanism (and
suppressed with "pull-filter ignore echo" already today, and possibly
with buttons to-be-added in the GUIs).

> * Make the ability to 'wall' a message out to all connected users in one
> command, e.g. 'wall "server going down in 5 mins"' or something like that.

This is an interesting challenge.  Parts of openvpn client might assume 
that a PUSH_REPLY is only seen at initial or renegotion time, so sending
a message with the proposed mechanism ("PUSH_REPLY echo msg server shutdown")
might trigger surprising effects.

It might just work.

But it can not be triggered from the server via client-connect scripts/
files/plugins as those are gone.  Maybe it can be triggered from the
servers-side management interface.  Not sure.


> * Make the ability to 'post' a message for some amount of time, e.g.
> 'wallpost 60m "server going down at 1700"'  Sending a message gets someone
> who is connected now, but misses the user who connects 2m after I go
> through the list of users and I stop looking.  So, this would hang around
> and pop a message to everyone connected now, plus each new connection, for
> the next 60m.

This is something outside "openvpn core", more tied to your client-connect
scripts/plugins on the server.  Put messages with an expire date "somewhere"
(database, filesystem, ...) and on connect, find everything that is still
valid and generate 'push "echo msg..."' messages accordingly.

> * Add an option ala --[no-]use-expired-certs.  When true, proceed like you
> do today; when false, if certs are expired, have the client feed itself a
> message via this mechanism to popup that your certs are expired, so a user
> knows right away what's wrong.  It'd be a spammy option if it tried to tell
> you what to do, so I'm keeping the idea simple and generic.

Interesting idea :-) - not sure what to do about this one.  Since all
"major" GUIs already look at the log file, and present warnings in some
form to the user, maybe this is more a GUI task - if we warn about
"cert might be expired" AND then there is a AUTH_FAILED response, 
change that warning (or even "all warnings logged") into a popup window?

Related but slightly different problem.

gert
-- 
"If was one thing all people took for granted, was conviction that if you 
 feed honest figures into a computer, honest figures come out. Never doubted 
 it myself till I met a computer with a sense of humor."
                             Robert A. Heinlein, The Moon is a Harsh Mistress

Gert Doering - Munich, Germany                             gert@...1296...

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 630 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Gert Doering]

[-- Attachment #1: Type: text/plain, Size: 1029 bytes --]

Hi,

On Sun, Dec 20, 2020 at 07:31:42PM -0500, Selva Nair wrote:
> Here is the link again.
> https://github.com/selvanair/openvpn-gui/releases/tag/v11-echo-msg
> I got no feedback then nor now.

I have stared at the code a bit, and it seems to make sense.  The part
"store a digest + timestamp, and avoid repeating the same message for
<n> hours" is a good idea.

I can see that "echo_msg_clear()" has a bool parameter to clear the
message history but I can not see a call with "true" - what did you 
have in mind?  A button to clear the messages history?  Or "if changing
to a different profile"?

I have not tested the binary.

gert
-- 
"If was one thing all people took for granted, was conviction that if you 
 feed honest figures into a computer, honest figures come out. Never doubted 
 it myself till I met a computer with a sense of humor."
                             Robert A. Heinlein, The Moon is a Harsh Mistress

Gert Doering - Munich, Germany                             gert@...1296...

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 630 bytes --]

Re: [Openvpn-devel] wanted: mechanism to send text messages to client

[Selva Nair]

[-- Attachment #1: Type: text/plain, Size: 1411 bytes --]

Hi

Thanks for the comments.

On Fri, Dec 25, 2020 at 3:03 PM Gert Doering <gert@...1296...> wrote:

> Hi,
>
> On Sun, Dec 20, 2020 at 07:31:42PM -0500, Selva Nair wrote:
> > Here is the link again.
> > https://github.com/selvanair/openvpn-gui/releases/tag/v11-echo-msg
> > I got no feedback then nor now.
>
> I have stared at the code a bit, and it seems to make sense.  The part
> "store a digest + timestamp, and avoid repeating the same message for
> <n> hours" is a good idea.
>
> I can see that "echo_msg_clear()" has a bool parameter to clear the
> message history but I can not see a call with "true" - what did you
> have in mind?  A button to clear the messages history?  Or "if changing
> to a different profile"?
>

It has been a while...

The history needs to be cleared to free up memory when the thread is
terminated on disconnect. Looks like a bug if it's not done during cleanup.
That said, I see that I have newer versions of this echo-msg branch (upto
v4) in my local repo and the latest includes persisting the history in
registry and clearing before disconnect.


> I have not tested the binary.
>

Don't. While we are in this blessed "One True Echo" state, let me rebase
the latest version, do some quick tests and post it as a PR for review &
comments.

Have to do that before I again get stuck in procrastination and the desire
to add more glitter like urls in message text etc..

Selva

[-- Attachment #2: Type: text/html, Size: 2238 bytes --]

Re: [Openvpn-devel] [PATCH] Document common uses of 'echo' directive, re-enable logging for 'echo'.

[Selva Nair]

[-- Attachment #1: Type: text/plain, Size: 9448 bytes --]

Hi,

Some small corrections to the proposed doc below

On Fri, Dec 25, 2020 at 2:28 PM Gert Doering <gert@...1296...> wrote:

> The 'echo' command can be used to signal information to an OpenVPN
> GUI driving the openvpn core via management interface.  Which commands
> exists and their syntax has so far been mostly undocumented.
>
> Condense the long and good discussion between Selva Nair and
> Jonathan K. Bullard into doc/gui-notes.txt (initial draft from
> Jonathan, comments from Selva and Arne), with a pointer added
> to doc/management-notes.txt.
>
> See:
>
>
> https://sourceforge.net/p/openvpn/mailman/openvpn-users/thread/CAEsd45T%2Bd6FUJ9Po0KHwtHjfuL9Q2D-poG8yFtY45Qyh%2BtHjkg%40mail.gmail.com/#msg36136236
>
> and
>
>
> https://sourceforge.net/p/openvpn/mailman/openvpn-devel/thread/CAKuzo_jPThhvXTJAtzhqVUVOLPW1VGu6h2jQhVsHicY8P2WRqA%40mail.gmail.com/#msg36141193
>
> for the details.
>
> Re-enable logging of 'echo' statements, but only for the particular
> class of messages starting with 'echo msg...'.
>
> Signed-off-by: Gert Doering <gert@...1296...>
> ---
>  doc/Makefile.am          |   2 +-
>  doc/gui-notes.txt        | 363 +++++++++++++++++++++++++++++++++++++++
>  doc/management-notes.txt |  10 ++
>  src/openvpn/options.c    |  15 +-
>  4 files changed, 382 insertions(+), 8 deletions(-)
>  create mode 100644 doc/gui-notes.txt
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index df2f54a3..e411f5f9 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -15,7 +15,7 @@ MAINTAINERCLEANFILES = \
>  SUBDIRS = doxygen
>
>  dist_doc_DATA = \
> -       management-notes.txt
> +       management-notes.txt gui-notes.txt
>
>  dist_noinst_DATA = \
>         README.plugins interactive-service-notes.rst \
> diff --git a/doc/gui-notes.txt b/doc/gui-notes.txt
> new file mode 100644
> index 00000000..9715e8f6
> --- /dev/null
> +++ b/doc/gui-notes.txt
> @@ -0,0 +1,363 @@
> +Management Interface "echo" protocol
> +
>
> +================================================================================
> +THIS IS A PRELIMINARY VERSION OF THIS DOCUMENT. ALL INFORMATION IN IT
> +IS SUBJECT TO CHANGE.
>
> +================================================================================
> +
> +
> +    CONTENTS
> +        THE OPENVPN --ECHO OPTION
> +        ENVIRONMENT COMMAND
> +        MESSSAGE COMMANDS
> +        PASSWORD COMMANDS
> +        QUOTING
> +        COMMMAND DETAILS
> +
> +
>
>
...snipped..


> +=======
> +QUOTING
> +=======
> +
> + * In a configuration file, the rest of the line is parsed into
> +separate arguments  and then 'echo' and the arguments are passed, each
> +separated by a single space, through the management interface. For
> +example:
> +
> +    echo     argument1 argument2
> +    echo    "     argument1      argument2"
> +
> +will be sent through the management interface as
> +
> +    >ECHO:timestamp,argument1,argument2
> +    >ECHO:timestamp,     argument1,     argument2
>

Should be
 >ECHO:timestamp,argument1 argument2
 >ECHO:timestamp,     argument1     argument2

(Only a comma after timestamp, no commas added between words)

+
> + * In a command line option, the single argument following "--echo" is
> +parsed similarly, so
> +
> +    --echo   "argument1     argument2"
>

Remove quotes to match with example above


> +    --echo    "'    argument1     argument2'"
>

Extra single quotes above are probably not intended.


> +
> +will be sent through the management interface as
> +
> +    >ECHO:timestamp,argument1,argument2


replace comma after argument1 by space


> +    >ECHO:timestamp,     argument1,     argument2


remove comma after argument1


> +
> + * In a "push" option in a server configuration file, the single
> +option following "push" is parsed similarly, so
> +
> +    push "echo argument1 argument2 argument3   argument4"
> +    push echo "'    argument1 argument2 argument3   argument4'"
>

The opening quote should move to before echo:

 push "echo '    argument1 argument2 argument3   argument4'"


> +will be sent through the management interface as
> +
> +    >ECHO:timestamp,argument1,argument2,argument3 argument4
>

replace commas after first one by space


> +    >ECHO:timestamp,     argument1,argument2 argument3   argument4
>

replace comma after argument1 by space


.. snipped...


> +COMMAND -- msg
> +--------------
> +
> +Syntax: msg text
> +
> +The text is appended to any previous text from "msg" or "msg-n"
> +commands, and a newline is appended after that.
> +
> +A trailing newline will be removed from the completed message before
> +it is displayed to the user.
> +
> +The text may include any UTF-8 character except a comma (","), CR
> +(0x0D), LF (0x0A), or NUL (0x00).

+
> +The text may not contain percent ("%") except in "percent encoding"
> +sequences. To display a percent sign, use %25.
> +
> +The text may not contain commas (",") because of constraints imposed
> +by OpenVPN. Commas should be encoded using "percent encoding" (URL
> +encoding): a '%' character followed by two hexadecimal digits, the
> +high- and then low-nibble of the ASCII code for the character to be
> +shown. Examples: a comma is encoded as %2C or %2c; a percent sign is
> +encoded as %25.


Here we could add:
Text containing comment characters # and ; must be enclosed in quotes to
survive after option parsing by openvpn.


> +
> +The insertion of line endings (CR, LF) in the text is discouraged
> +because it is OS dependent. Instead, use the "msg" command, which
> +appends a line ending appropriate for the OS on which the GUI is
> +running.
> +
> +    Android: ??????
> +
> +    Tunnelblick: Planned.
> +
> +    Windows OpenVPN GUI: Planned.
> +
> +COMMAND -- msg-n
> +----------------
> +
> +Syntax: msg-n text
> +
> +The text is appended to any previous text from "msg"" or "msg-n""
> +commands. (Like "msg" except that no newline is appended.)
> +
> +See "COMMAND -- msg" for details about "text".
> +
> +    Android: ??????
> +
> +    Tunnelblick: Planned.
> +
> +    Windows OpenVPN GUI: Planned.
> +
> +COMMAND -- msg-notify
> +---------------------
> +
> +Syntax: msg-notify title
> +
> +The text from previous "msg" and/or "msg-n" commands is displayed to
> +the user as a notification with title "title" and the previous text is
> +forgotten.
> +
> +    Android: ??????
> +
> +    Tunnelblick: Planned.
> +
> +    Windows OpenVPN GUI: Planned.
> +
> +Note: The max length that will correctly display as a notification
> +message is OS dependent.
> +
> +
> +COMMAND -- msg-window title
> +---------------------------
> +
> +Syntax: msg-window title
> +
> +The text from previous "msg" and/or "msg-n" commands is displayed to
> +the user in a non-modal popup window with title "title" and the
> +previous text is forgotten..
>

How the title is displayed is better left to the implementation. Could be
set as the
window title or as a differently formatted text as the heading of the
message, for example. The latter approach is taken in the proposed OpenVPN
GUI implementation.

+
> +    Android: ??????
> +
> +    Tunnelblick: Planned.
> +
> +    Windows OpenVPN GUI: Planned.
> +
> +
> +COMMAND -- save-passwords
> +-------------------------
> +
> +Syntax: save-passwords
> +
> +The GUI is instructed to allow the user to save usernames, passwords
> +and private keys for the configuration.
> +
> +This command will be effective at startup only if present in the
> +configuration file or as a command line option. If pushed from the
> +server, saving passwords will be allowed in password prompts only
> +after the initial prompt has been shown to the user.
> +
> +This command typically has the effect of presenting the password
> +dialogs to the user with a "save password" checkbox checked. The user
> +may still uncheck it during the dialog.
> +
> +    Android: ??????
> +
> +    Tunnelblick: Planned. Tunnelblick ignores this command. Usernames,
> +passwords, and private keys may be saved by default, and this command
> +will not override the separate Tunnelblick global or per-configuration
> +settings used to disable saving them.
> +
> +    Windows OpenVPN GUI: Supported since release 2.4.1 (GUI version
> 11.5.0)
> +
> +
> +COMMAND -- setenv
> +-----------------
> +
> +Syntax: setenv name value
> +
> +Sets an environment variable that will be available to the scripts run
> +by the GUI.
> +
> +This will set environment variable "OPENVPN_name" to value "value" for
> +the scripts run by the GUI. "name" is changed to "OPENVPN_name" to
> +prevent overwriting sensitive variables such as PATH. Variables are
> +set in the order received, with later values replacing earlier ones
> +for the same "name".
> +
> +Names may include only alphanumeric characters and underscores. A
> +"setenv" command with an invalid name will be ignored.
> +
> +    Android: ??????
> +
> +    Tunnelblick: Planned.
> +
> +    Windows OpenVPN GUI: Planned. When the variables set by "setenv"
> +are merged with those for the process environment, the variables set
> +by "setenv" are listed first, but any duplicates in the process
> +environment are not removed. This means that any variables with the
> +same name will have the value of the variable in the process
> +environment.
>

The GUI supports this since v11.12.0 (release 2.4.7)
Also, the description above is not correct. In case of duplicate names the
one in the  setenv list is chosen. The merged list is sorted as required on
Windows.

The rest looks good to me.

Selva

[-- Attachment #2: Type: text/html, Size: 13962 bytes --]

[Openvpn-devel] [PATCH v2] Document common uses of 'echo' directive, re-enable logging for 'echo'.

[Gert Doering]

The 'echo' command can be used to signal information to an OpenVPN
GUI driving the openvpn core via management interface.  Which commands
exists and their syntax has so far been mostly undocumented.

Condense the long and good discussion between Selva Nair and
Jonathan K. Bullard into doc/gui-notes.txt (initial draft from
Jonathan, comments from Selva and Arne), with a pointer added
to doc/management-notes.txt.

See:

https://sourceforge.net/p/openvpn/mailman/openvpn-users/thread/CAEsd45T%2Bd6FUJ9Po0KHwtHjfuL9Q2D-poG8yFtY45Qyh%2BtHjkg%40mail.gmail.com/#msg36136236

and

https://sourceforge.net/p/openvpn/mailman/openvpn-devel/thread/CAKuzo_jPThhvXTJAtzhqVUVOLPW1VGu6h2jQhVsHicY8P2WRqA%40mail.gmail.com/#msg36141193

for the details.

Re-enable logging of 'echo' statements, but only for the particular
class of messages starting with 'echo msg...'.

v2:
  incorporate feedback from Selva Nair, correct >ECHO examples

Signed-off-by: Gert Doering <gert@...1296...>
---
 doc/Makefile.am          |   2 +-
 doc/gui-notes.txt        | 366 +++++++++++++++++++++++++++++++++++++++
 doc/management-notes.txt |  10 ++
 src/openvpn/options.c    |  15 +-
 4 files changed, 385 insertions(+), 8 deletions(-)
 create mode 100644 doc/gui-notes.txt

diff --git a/doc/Makefile.am b/doc/Makefile.am
index df2f54a3..e411f5f9 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -15,7 +15,7 @@ MAINTAINERCLEANFILES = \
 SUBDIRS = doxygen
 
 dist_doc_DATA = \
-	management-notes.txt
+	management-notes.txt gui-notes.txt
 
 dist_noinst_DATA = \
 	README.plugins interactive-service-notes.rst \
diff --git a/doc/gui-notes.txt b/doc/gui-notes.txt
new file mode 100644
index 00000000..4d993484
--- /dev/null
+++ b/doc/gui-notes.txt
@@ -0,0 +1,366 @@
+Management Interface "echo" protocol
+
+================================================================================
+THIS IS A PRELIMINARY VERSION OF THIS DOCUMENT. ALL INFORMATION IN IT
+IS SUBJECT TO CHANGE.
+================================================================================
+
+
+    CONTENTS
+        THE OPENVPN --ECHO OPTION
+        ENVIRONMENT COMMAND
+        MESSSAGE COMMANDS
+        PASSWORD COMMANDS
+        QUOTING
+        COMMMAND DETAILS
+
+
+=========================
+THE OPENVPN --ECHO OPTION
+=========================
+
+The OpenVPN --echo option causes commands to be sent out through the
+management interface, typically to a Graphic User Interface (GUI) such
+as "OpenVPN for Android", "Tunnelblick" (for macOS), or "Windows
+OpenVPN GUI". It can be included in a configuration file or on a
+command line, or can be pushed from the server.
+
+This document describes the commands that can be sent and how they are
+interpreted by various GUIs.
+
+ * OpenVPN does not process the commands in an --echo option; it only
+sends them out through the management interface.
+
+ * "echo" commands are processed by the GUI if, as, when, and in the
+order they are received. If no GUI is present the processing of
+commands may be delayed, the commands may never be processed, or only
+some commands may be processed. (That can happen if OpenVPN discards
+commands because its buffer for the commands fills up.)
+
+ * There is no mechanism for the GUI to acknowledge the receipt,
+success, or failure of a command.
+
+ * "echo" commands are stored by OpenVPN (within limits, see the next
+point) and sent only when the GUI requests them through the management
+interface. "echo" commands in the configuration file or the command
+line are typically requested and processed at the start of a
+connection attempt. "echo" commands that are pushed by the server are
+also typically asked for at the start of a connection attempt but can
+be sent at any time. They are processed in the middle of a connection
+attempt or after a connection is established, as the "push" options
+are received by the client from the server.
+
+  * OpenVPN's storage for echo commands is limited in size, so a large
+number of commands or commands with long messages may require that
+some commands be removed from the storage. If that happens, some of
+the commands may not be sent through the management interface when a
+GUI does connect to it or asks for the "echo" commands.
+
+ * On SIGUSR1 and SIGHUP connection restarts, "echo" commands that
+were sent through the management interface and have been saved by
+OpenVPN are sent again and will be re-processed by the GUI. (The
+message commands include a mechanism for muting (skipping) duplicate
+messages, see MESSAGE COMMANDS, below.)
+
+ * OpenVPN limits the number of separate arguments in each line of a
+configuration file. Arguments may be quoted to work around this
+limitation, see QUOTING, below.
+
+ * OpenVPN limits the size of each "echo" command sent over the
+management interface to 255 bytes, including overhead characters. To
+allow messages of arbitrary length, several message commands can be
+concatenated together before being displayed to the user, see MESSAGE
+COMMANDS, below.
+
+ * There no indication to the GUI of the source of the command
+(configuration file, command line option, or pushed from a server). It
+might be possible for the GUI to deduce that a command was pushed from
+a server because of timing or other management interface interactions.
+
+
+===================
+ENVIRONMENT COMMAND
+===================
+
+Typically, a GUI allows users to specify shell commands (typically
+scripts) to run at certain points in the connection/disconnection
+process, in addition to those provided by OpenVPN options such as
+"--up" and "--down".
+
+The "setenv" command can be used to set environment variables that are
+available to the scripts run by the GUI. Each "setenv" command
+specifies a value for one environment variable that is available to
+the scripts that the GUI runs.
+
+This is similar to Openvpn's "--setenv" option, which specifies an
+additional environment variable that is included in the environment
+variables that are available to the scripts that OpenVPN runs.
+
+
+=================
+MESSSAGE COMMANDS
+=================
+
+Four commands can be used to display a message to the user from the
+OpenVPN configuration or server:
+
+    msg
+    msg-n
+    msg-window
+    msg-notify
+
+"msg" and "msg-n" commands are concatenated to construct a message.
+When a "msg-window"or "msg-notify" command is received the message is
+displayed to the user.
+
+Identical messages (same title, text, and destination) received during
+one connection may be ignored or muted. Some GUIs may only show the
+first message for a connection, or the first message shown in a window
+and the first message shown as a notification.
+
+
+=================
+PASSWORD COMMANDS
+=================
+
+Three commands can be used to control the GUI's storage of usernames,
+passwords, and private keys:
+
+    disable-save-passwords
+    forget-passwords
+    save-passwords
+
+
+=======
+QUOTING
+=======
+
+ * In a configuration file, the rest of the line is parsed into
+separate arguments  and then 'echo' and the arguments are passed, each
+separated by a single space, through the management interface. For
+example:
+
+    echo     argument1 argument2
+    echo    "     argument1      argument2"
+
+will be sent through the management interface as
+
+    >ECHO:timestamp,argument1 argument2
+    >ECHO:timestamp,     argument1      argument2
+
+ * In a command line option, the single argument following "--echo" is
+parsed similarly, so
+
+    --echo   argument1     argument2
+    --echo   "    argument1     argument2"
+
+will be sent through the management interface as
+
+    >ECHO:timestamp,argument1 argument2
+    >ECHO:timestamp,     argument1      argument2
+
+ * In a "push" option in a server configuration file, the single
+option following "push" is parsed similarly, so
+
+    push "echo argument1 argument2 argument3   argument4"
+    push "echo '    argument1 argument2 argument3   argument4'"
+
+will be sent through the management interface as
+
+    >ECHO:timestamp,argument1 argument2 argument3 argument4
+    >ECHO:timestamp,     argument1 argument2 argument3   argument4
+
+
+================
+COMMMAND DETAILS
+================
+
+
+COMMAND -- disable-save-passwords
+---------------------------------
+
+Syntax: disable-save-passwords
+
+The GUI is instructed to not allow the user to save passwords or
+private keys for the configuration. The user is still allowed to save
+usernames. Any passwords or private keys that have been saved will be
+forgotten.
+
+This command will be effective at startup only if present in the
+configuration file or as a command line option. If pushed from the
+server, saving passwords will be disabled in password prompts only
+after the initial prompt has been shown to the user.
+
+    Android: ??????
+
+    Tunnelblick: Planned. This command will disable saving of
+passwords or private keys and forget any saved usernames, passwords,
+or private keys regardless of the normal (non-forced) global or
+per-configuration settings. A computer administrator can "force" this
+setting, overriding this command.
+
+    Windows OpenVPN GUI: Planned. This command will disable saving of
+passwords or private keys and forget any saved usernames, passwords,
+or private keys regardless of any global settings.
+
+
+COMMAND -- forget-passwords
+---------------------------
+
+Syntax: forget-passwords
+
+The GUI is instructed to forget any usernames, passwords, and private
+keys it has saved for the configuration. Useful when pushed from the
+server so that it is processed after authentication.
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: supported since release 2.4.1 (GUI version 11.5.0)
+
+
+COMMAND -- msg
+--------------
+
+Syntax: msg text
+
+The text is appended to any previous text from "msg" or "msg-n"
+commands, and a newline is appended after that.
+
+A trailing newline will be removed from the completed message before
+it is displayed to the user.
+
+The text may include any UTF-8 character except a comma (","), CR
+(0x0D), LF (0x0A), or NUL (0x00).
+
+The text may not contain percent ("%") except in "percent encoding"
+sequences. To display a percent sign, use %25.
+
+The text may not contain commas (",") because of constraints imposed
+by OpenVPN. Commas should be encoded using "percent encoding" (URL
+encoding): a '%' character followed by two hexadecimal digits, the
+high- and then low-nibble of the ASCII code for the character to be
+shown. Examples: a comma is encoded as %2C or %2c; a percent sign is
+encoded as %25.
+
+Text containing comment characters # and ; must be enclosed in quotes to
+survive after option parsing by openvpn.
+
+The insertion of line endings (CR, LF) in the text is discouraged
+because it is OS dependent. Instead, use the "msg" command, which
+appends a line ending appropriate for the OS on which the GUI is
+running.
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: Planned.
+
+COMMAND -- msg-n
+----------------
+
+Syntax: msg-n text
+
+The text is appended to any previous text from "msg"" or "msg-n""
+commands. (Like "msg" except that no newline is appended.)
+
+See "COMMAND -- msg" for details about "text".
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: Planned.
+
+COMMAND -- msg-notify
+---------------------
+
+Syntax: msg-notify title
+
+The text from previous "msg" and/or "msg-n" commands is displayed to
+the user as a notification with title "title" and the previous text is
+forgotten.
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: Planned.
+
+Note: The max length that will correctly display as a notification
+message is OS dependent.
+
+
+COMMAND -- msg-window title
+---------------------------
+
+Syntax: msg-window title
+
+The text from previous "msg" and/or "msg-n" commands is displayed to
+the user in a non-modal popup window with title "title" and the
+previous text is forgotten.  How the title is displayed exactly is left
+to the implementation. Could be set as the window title or as a
+differently formatted text as the heading of the message, for example.
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: Planned.
+
+
+COMMAND -- save-passwords
+-------------------------
+
+Syntax: save-passwords
+
+The GUI is instructed to allow the user to save usernames, passwords
+and private keys for the configuration.
+
+This command will be effective at startup only if present in the
+configuration file or as a command line option. If pushed from the
+server, saving passwords will be allowed in password prompts only
+after the initial prompt has been shown to the user.
+
+This command typically has the effect of presenting the password
+dialogs to the user with a "save password" checkbox checked. The user
+may still uncheck it during the dialog.
+
+    Android: ??????
+
+    Tunnelblick: Planned. Tunnelblick ignores this command. Usernames,
+passwords, and private keys may be saved by default, and this command
+will not override the separate Tunnelblick global or per-configuration
+settings used to disable saving them.
+
+    Windows OpenVPN GUI: Supported since release 2.4.1 (GUI version 11.5.0)
+
+
+COMMAND -- setenv
+-----------------
+
+Syntax: setenv name value
+
+Sets an environment variable that will be available to the scripts run
+by the GUI.
+
+This will set environment variable "OPENVPN_name" to value "value" for
+the scripts run by the GUI. "name" is changed to "OPENVPN_name" to
+prevent overwriting sensitive variables such as PATH. Variables are
+set in the order received, with later values replacing earlier ones
+for the same "name".
+
+Names may include only alphanumeric characters and underscores. A
+"setenv" command with an invalid name will be ignored.
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: supported since release v2.4.7 (GUI version v11.12.0)
+The variables set by "setenv" are merged with those for the process
+environment.  In case of duplicate names the one in the setenv list is
+chosen.
+
diff --git a/doc/management-notes.txt b/doc/management-notes.txt
index 61daaf07..50f0f567 100644
--- a/doc/management-notes.txt
+++ b/doc/management-notes.txt
@@ -137,6 +137,16 @@ history while simultaneously activating real-time updates:
 The size of the echo buffer is currently hardcoded to 100
 messages.
 
+
+Generally speaking, the OpenVPN Core does not understand echo
+messages at all (so a cooperating GUI and Server can use this
+mechanism for arbitrary information transport).
+
+This said, a few echo commands have been agreed upon between the
+community maintained OpenVPN Windows GUI and Tunnelblick for MacOS,
+and documentation of these can be found in doc/gui-notes.txt.
+
+
 COMMAND -- exit, quit
 ---------------------
 
diff --git a/src/openvpn/options.c b/src/openvpn/options.c
index ff3954d5..36009f4f 100644
--- a/src/openvpn/options.c
+++ b/src/openvpn/options.c
@@ -5306,13 +5306,14 @@ add_option(struct options *options,
         }
         if (good)
         {
-#if 0
-            /* removed for now since ECHO can potentially include
-             * security-sensitive strings */
-            msg(M_INFO, "%s:%s",
-                pull_mode ? "ECHO-PULL" : "ECHO",
-                BSTR(&string));
-#endif
+            /* only message-related ECHO are logged, since other ECHOs
+             * can potentially include security-sensitive strings */
+            if (strncmp(p[1],"msg",3) == 0)
+            {
+                msg(M_INFO, "%s:%s",
+                    pull_mode ? "ECHO-PULL" : "ECHO",
+                    BSTR(&string));
+            }
 #ifdef ENABLE_MANAGEMENT
             if (management)
             {
-- 
2.26.2

Re: [Openvpn-devel] [PATCH v2] Document common uses of 'echo' directive, re-enable logging for 'echo'.

[Gert Doering]

[-- Attachment #1: Type: text/plain, Size: 707 bytes --]

Hi,

On Mon, Jan 18, 2021 at 01:15:29PM +0100, Gert Doering wrote:
> v2:
>   incorporate feedback from Selva Nair, correct >ECHO examples

There will be a v3, as I just added "Android: Planned" to all the
msg stuff.

Selva, which GUI version will be "the one with msg support"?  So I can
have this fixed as well.

gert
-- 
"If was one thing all people took for granted, was conviction that if you 
 feed honest figures into a computer, honest figures come out. Never doubted 
 it myself till I met a computer with a sense of humor."
                             Robert A. Heinlein, The Moon is a Harsh Mistress

Gert Doering - Munich, Germany                             gert@...1296...

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 630 bytes --]

Re: [Openvpn-devel] [PATCH v2] Document common uses of 'echo' directive, re-enable logging for 'echo'.

[Selva Nair]

Hi,

On Mon, Jan 18, 2021 at 8:17 AM Gert Doering <gert@...1296...> wrote:
>
> There will be a v3, as I just added "Android: Planned" to all the
> msg stuff.
>
> Selva, which GUI version will be "the one with msg support"?  So I can
> have this fixed as well.

GUI is at 11.21.0 right now, this will be in 11.22.0 to be released
with 2.4.11 and 2.5.1 onwards, I suppose.

Thanks,

Selva

[Openvpn-devel] [PATCH v3] Document common uses of 'echo' directive, re-enable logging for 'echo'.

[Gert Doering]

The 'echo' command can be used to signal information to an OpenVPN
GUI driving the openvpn core via management interface.  Which commands
exists and their syntax has so far been mostly undocumented.

Condense the long and good discussion between Selva Nair and
Jonathan K. Bullard into doc/gui-notes.txt (initial draft from
Jonathan, comments from Selva and Arne), with a pointer added
to doc/management-notes.txt.

See:

https://sourceforge.net/p/openvpn/mailman/openvpn-users/thread/CAEsd45T%2Bd6FUJ9Po0KHwtHjfuL9Q2D-poG8yFtY45Qyh%2BtHjkg%40mail.gmail.com/#msg36136236

and

https://sourceforge.net/p/openvpn/mailman/openvpn-devel/thread/CAKuzo_jPThhvXTJAtzhqVUVOLPW1VGu6h2jQhVsHicY8P2WRqA%40mail.gmail.com/#msg36141193

for the details.

Re-enable logging of 'echo' statements, but only for the particular
class of messages starting with 'echo msg...'.

v2:
  incorporate feedback from Selva Nair, correct >ECHO examples

v3:
  add "msg*" support status for Windows GUI (11.22.0) and Android (Planned)

Signed-off-by: Gert Doering <gert@...1296...>
---
 doc/Makefile.am          |   2 +-
 doc/gui-notes.txt        | 370 +++++++++++++++++++++++++++++++++++++++
 doc/management-notes.txt |  10 ++
 src/openvpn/options.c    |  15 +-
 4 files changed, 389 insertions(+), 8 deletions(-)
 create mode 100644 doc/gui-notes.txt

diff --git a/doc/Makefile.am b/doc/Makefile.am
index df2f54a3..e411f5f9 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -15,7 +15,7 @@ MAINTAINERCLEANFILES = \
 SUBDIRS = doxygen
 
 dist_doc_DATA = \
-	management-notes.txt
+	management-notes.txt gui-notes.txt
 
 dist_noinst_DATA = \
 	README.plugins interactive-service-notes.rst \
diff --git a/doc/gui-notes.txt b/doc/gui-notes.txt
new file mode 100644
index 00000000..08270f07
--- /dev/null
+++ b/doc/gui-notes.txt
@@ -0,0 +1,370 @@
+Management Interface "echo" protocol
+
+================================================================================
+THIS IS A PRELIMINARY VERSION OF THIS DOCUMENT. ALL INFORMATION IN IT
+IS SUBJECT TO CHANGE.
+================================================================================
+
+
+    CONTENTS
+        THE OPENVPN --ECHO OPTION
+        ENVIRONMENT COMMAND
+        MESSSAGE COMMANDS
+        PASSWORD COMMANDS
+        QUOTING
+        COMMMAND DETAILS
+
+
+=========================
+THE OPENVPN --ECHO OPTION
+=========================
+
+The OpenVPN --echo option causes commands to be sent out through the
+management interface, typically to a Graphic User Interface (GUI) such
+as "OpenVPN for Android", "Tunnelblick" (for macOS), or "Windows
+OpenVPN GUI". It can be included in a configuration file or on a
+command line, or can be pushed from the server.
+
+This document describes the commands that can be sent and how they are
+interpreted by various GUIs.
+
+ * OpenVPN does not process the commands in an --echo option; it only
+sends them out through the management interface.
+
+ * "echo" commands are processed by the GUI if, as, when, and in the
+order they are received. If no GUI is present the processing of
+commands may be delayed, the commands may never be processed, or only
+some commands may be processed. (That can happen if OpenVPN discards
+commands because its buffer for the commands fills up.)
+
+ * There is no mechanism for the GUI to acknowledge the receipt,
+success, or failure of a command.
+
+ * "echo" commands are stored by OpenVPN (within limits, see the next
+point) and sent only when the GUI requests them through the management
+interface. "echo" commands in the configuration file or the command
+line are typically requested and processed at the start of a
+connection attempt. "echo" commands that are pushed by the server are
+also typically asked for at the start of a connection attempt but can
+be sent at any time. They are processed in the middle of a connection
+attempt or after a connection is established, as the "push" options
+are received by the client from the server.
+
+  * OpenVPN's storage for echo commands is limited in size, so a large
+number of commands or commands with long messages may require that
+some commands be removed from the storage. If that happens, some of
+the commands may not be sent through the management interface when a
+GUI does connect to it or asks for the "echo" commands.
+
+ * On SIGUSR1 and SIGHUP connection restarts, "echo" commands that
+were sent through the management interface and have been saved by
+OpenVPN are sent again and will be re-processed by the GUI. (The
+message commands include a mechanism for muting (skipping) duplicate
+messages, see MESSAGE COMMANDS, below.)
+
+ * OpenVPN limits the number of separate arguments in each line of a
+configuration file. Arguments may be quoted to work around this
+limitation, see QUOTING, below.
+
+ * OpenVPN limits the size of each "echo" command sent over the
+management interface to 255 bytes, including overhead characters. To
+allow messages of arbitrary length, several message commands can be
+concatenated together before being displayed to the user, see MESSAGE
+COMMANDS, below.
+
+ * There no indication to the GUI of the source of the command
+(configuration file, command line option, or pushed from a server). It
+might be possible for the GUI to deduce that a command was pushed from
+a server because of timing or other management interface interactions.
+
+
+===================
+ENVIRONMENT COMMAND
+===================
+
+Typically, a GUI allows users to specify shell commands (typically
+scripts) to run at certain points in the connection/disconnection
+process, in addition to those provided by OpenVPN options such as
+"--up" and "--down".
+
+The "setenv" command can be used to set environment variables that are
+available to the scripts run by the GUI. Each "setenv" command
+specifies a value for one environment variable that is available to
+the scripts that the GUI runs.
+
+This is similar to Openvpn's "--setenv" option, which specifies an
+additional environment variable that is included in the environment
+variables that are available to the scripts that OpenVPN runs.
+
+
+=================
+MESSSAGE COMMANDS
+=================
+
+Four commands can be used to display a message to the user from the
+OpenVPN configuration or server:
+
+    msg
+    msg-n
+    msg-window
+    msg-notify
+
+"msg" and "msg-n" commands are concatenated to construct a message.
+When a "msg-window"or "msg-notify" command is received the message is
+displayed to the user.
+
+Identical messages (same title, text, and destination) received during
+one connection may be ignored or muted. Some GUIs may only show the
+first message for a connection, or the first message shown in a window
+and the first message shown as a notification.
+
+
+=================
+PASSWORD COMMANDS
+=================
+
+Three commands can be used to control the GUI's storage of usernames,
+passwords, and private keys:
+
+    disable-save-passwords
+    forget-passwords
+    save-passwords
+
+
+=======
+QUOTING
+=======
+
+ * In a configuration file, the rest of the line is parsed into
+separate arguments  and then 'echo' and the arguments are passed, each
+separated by a single space, through the management interface. For
+example:
+
+    echo     argument1 argument2
+    echo    "     argument1      argument2"
+
+will be sent through the management interface as
+
+    >ECHO:timestamp,argument1 argument2
+    >ECHO:timestamp,     argument1      argument2
+
+ * In a command line option, the single argument following "--echo" is
+parsed similarly, so
+
+    --echo   argument1     argument2
+    --echo   "    argument1     argument2"
+
+will be sent through the management interface as
+
+    >ECHO:timestamp,argument1 argument2
+    >ECHO:timestamp,     argument1      argument2
+
+ * In a "push" option in a server configuration file, the single
+option following "push" is parsed similarly, so
+
+    push "echo argument1 argument2 argument3   argument4"
+    push "echo '    argument1 argument2 argument3   argument4'"
+
+will be sent through the management interface as
+
+    >ECHO:timestamp,argument1 argument2 argument3 argument4
+    >ECHO:timestamp,     argument1 argument2 argument3   argument4
+
+
+================
+COMMMAND DETAILS
+================
+
+
+COMMAND -- disable-save-passwords
+---------------------------------
+
+Syntax: disable-save-passwords
+
+The GUI is instructed to not allow the user to save passwords or
+private keys for the configuration. The user is still allowed to save
+usernames. Any passwords or private keys that have been saved will be
+forgotten.
+
+This command will be effective at startup only if present in the
+configuration file or as a command line option. If pushed from the
+server, saving passwords will be disabled in password prompts only
+after the initial prompt has been shown to the user.
+
+    Android: ??????
+
+    Tunnelblick: Planned. This command will disable saving of
+passwords or private keys and forget any saved usernames, passwords,
+or private keys regardless of the normal (non-forced) global or
+per-configuration settings. A computer administrator can "force" this
+setting, overriding this command.
+
+    Windows OpenVPN GUI: Planned. This command will disable saving of
+passwords or private keys and forget any saved usernames, passwords,
+or private keys regardless of any global settings.
+
+
+COMMAND -- forget-passwords
+---------------------------
+
+Syntax: forget-passwords
+
+The GUI is instructed to forget any usernames, passwords, and private
+keys it has saved for the configuration. Useful when pushed from the
+server so that it is processed after authentication.
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: supported since release 2.4.1 (GUI version 11.5.0)
+
+
+COMMAND -- msg
+--------------
+
+Syntax: msg text
+
+The text is appended to any previous text from "msg" or "msg-n"
+commands, and a newline is appended after that.
+
+A trailing newline will be removed from the completed message before
+it is displayed to the user.
+
+The text may include any UTF-8 character except a comma (","), CR
+(0x0D), LF (0x0A), or NUL (0x00).
+
+The text may not contain percent ("%") except in "percent encoding"
+sequences. To display a percent sign, use %25.
+
+The text may not contain commas (",") because of constraints imposed
+by OpenVPN. Commas should be encoded using "percent encoding" (URL
+encoding): a '%' character followed by two hexadecimal digits, the
+high- and then low-nibble of the ASCII code for the character to be
+shown. Examples: a comma is encoded as %2C or %2c; a percent sign is
+encoded as %25.
+
+Text containing comment characters # and ; must be enclosed in quotes to
+survive after option parsing by openvpn.
+
+The insertion of line endings (CR, LF) in the text is discouraged
+because it is OS dependent. Instead, use the "msg" command, which
+appends a line ending appropriate for the OS on which the GUI is
+running.
+
+    Android: Planned.
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
+			 (GUI version v11.22.0)
+
+COMMAND -- msg-n
+----------------
+
+Syntax: msg-n text
+
+The text is appended to any previous text from "msg"" or "msg-n""
+commands. (Like "msg" except that no newline is appended.)
+
+See "COMMAND -- msg" for details about "text".
+
+    Android: Planned.
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
+			 (GUI version v11.22.0)
+
+COMMAND -- msg-notify
+---------------------
+
+Syntax: msg-notify title
+
+The text from previous "msg" and/or "msg-n" commands is displayed to
+the user as a notification with title "title" and the previous text is
+forgotten.
+
+    Android: Planned.
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
+			 (GUI version v11.22.0)
+
+Note: The max length that will correctly display as a notification
+message is OS dependent.
+
+
+COMMAND -- msg-window title
+---------------------------
+
+Syntax: msg-window title
+
+The text from previous "msg" and/or "msg-n" commands is displayed to
+the user in a non-modal popup window with title "title" and the
+previous text is forgotten.  How the title is displayed exactly is left
+to the implementation. Could be set as the window title or as a
+differently formatted text as the heading of the message, for example.
+
+    Android: Planned.
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
+			 (GUI version v11.22.0)
+
+
+COMMAND -- save-passwords
+-------------------------
+
+Syntax: save-passwords
+
+The GUI is instructed to allow the user to save usernames, passwords
+and private keys for the configuration.
+
+This command will be effective at startup only if present in the
+configuration file or as a command line option. If pushed from the
+server, saving passwords will be allowed in password prompts only
+after the initial prompt has been shown to the user.
+
+This command typically has the effect of presenting the password
+dialogs to the user with a "save password" checkbox checked. The user
+may still uncheck it during the dialog.
+
+    Android: ??????
+
+    Tunnelblick: Planned. Tunnelblick ignores this command. Usernames,
+passwords, and private keys may be saved by default, and this command
+will not override the separate Tunnelblick global or per-configuration
+settings used to disable saving them.
+
+    Windows OpenVPN GUI: Supported since release 2.4.1 (GUI version 11.5.0)
+
+
+COMMAND -- setenv
+-----------------
+
+Syntax: setenv name value
+
+Sets an environment variable that will be available to the scripts run
+by the GUI.
+
+This will set environment variable "OPENVPN_name" to value "value" for
+the scripts run by the GUI. "name" is changed to "OPENVPN_name" to
+prevent overwriting sensitive variables such as PATH. Variables are
+set in the order received, with later values replacing earlier ones
+for the same "name".
+
+Names may include only alphanumeric characters and underscores. A
+"setenv" command with an invalid name will be ignored.
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: supported since release v2.4.7 (GUI version v11.12.0)
+The variables set by "setenv" are merged with those for the process
+environment.  In case of duplicate names the one in the setenv list is
+chosen.
+
diff --git a/doc/management-notes.txt b/doc/management-notes.txt
index 61daaf07..50f0f567 100644
--- a/doc/management-notes.txt
+++ b/doc/management-notes.txt
@@ -137,6 +137,16 @@ history while simultaneously activating real-time updates:
 The size of the echo buffer is currently hardcoded to 100
 messages.
 
+
+Generally speaking, the OpenVPN Core does not understand echo
+messages at all (so a cooperating GUI and Server can use this
+mechanism for arbitrary information transport).
+
+This said, a few echo commands have been agreed upon between the
+community maintained OpenVPN Windows GUI and Tunnelblick for MacOS,
+and documentation of these can be found in doc/gui-notes.txt.
+
+
 COMMAND -- exit, quit
 ---------------------
 
diff --git a/src/openvpn/options.c b/src/openvpn/options.c
index ff3954d5..36009f4f 100644
--- a/src/openvpn/options.c
+++ b/src/openvpn/options.c
@@ -5306,13 +5306,14 @@ add_option(struct options *options,
         }
         if (good)
         {
-#if 0
-            /* removed for now since ECHO can potentially include
-             * security-sensitive strings */
-            msg(M_INFO, "%s:%s",
-                pull_mode ? "ECHO-PULL" : "ECHO",
-                BSTR(&string));
-#endif
+            /* only message-related ECHO are logged, since other ECHOs
+             * can potentially include security-sensitive strings */
+            if (strncmp(p[1],"msg",3) == 0)
+            {
+                msg(M_INFO, "%s:%s",
+                    pull_mode ? "ECHO-PULL" : "ECHO",
+                    BSTR(&string));
+            }
 #ifdef ENABLE_MANAGEMENT
             if (management)
             {
-- 
2.26.2

Re: [Openvpn-devel] [PATCH v3] Document common uses of 'echo' directive, re-enable logging for 'echo'.

[Selva Nair]

Hi.

Looks good to me.

The white- "space police" may object to the formatting in the logging
code (see below). Could be fixed at commit time.

On Mon, Jan 18, 2021 at 11:31 AM Gert Doering <gert@...1296...> wrote:
>
> The 'echo' command can be used to signal information to an OpenVPN
> GUI driving the openvpn core via management interface.  Which commands
> exists and their syntax has so far been mostly undocumented.
>
> Condense the long and good discussion between Selva Nair and
> Jonathan K. Bullard into doc/gui-notes.txt (initial draft from
> Jonathan, comments from Selva and Arne), with a pointer added
> to doc/management-notes.txt.
>
> See:
>
> https://sourceforge.net/p/openvpn/mailman/openvpn-users/thread/CAEsd45T%2Bd6FUJ9Po0KHwtHjfuL9Q2D-poG8yFtY45Qyh%2BtHjkg%40mail.gmail.com/#msg36136236
>
> and
>
> https://sourceforge.net/p/openvpn/mailman/openvpn-devel/thread/CAKuzo_jPThhvXTJAtzhqVUVOLPW1VGu6h2jQhVsHicY8P2WRqA%40mail.gmail.com/#msg36141193
>
> for the details.
>
> Re-enable logging of 'echo' statements, but only for the particular
> class of messages starting with 'echo msg...'.
>
> v2:
>   incorporate feedback from Selva Nair, correct >ECHO examples
>
> v3:
>   add "msg*" support status for Windows GUI (11.22.0) and Android (Planned)
>
> Signed-off-by: Gert Doering <gert@...1296...>
> ---
>  doc/Makefile.am          |   2 +-
>  doc/gui-notes.txt        | 370 +++++++++++++++++++++++++++++++++++++++
>  doc/management-notes.txt |  10 ++
>  src/openvpn/options.c    |  15 +-
>  4 files changed, 389 insertions(+), 8 deletions(-)
>  create mode 100644 doc/gui-notes.txt
>
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index df2f54a3..e411f5f9 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -15,7 +15,7 @@ MAINTAINERCLEANFILES = \
>  SUBDIRS = doxygen
>
>  dist_doc_DATA = \
> -       management-notes.txt
> +       management-notes.txt gui-notes.txt
>
>  dist_noinst_DATA = \
>         README.plugins interactive-service-notes.rst \
> diff --git a/doc/gui-notes.txt b/doc/gui-notes.txt
> new file mode 100644
> index 00000000..08270f07
> --- /dev/null
> +++ b/doc/gui-notes.txt
> @@ -0,0 +1,370 @@
> +Management Interface "echo" protocol
> +
>

snipped...

+COMMAND -- setenv
+-----------------
+
+Syntax: setenv name value
+
+Sets an environment variable that will be available to the scripts run
+by the GUI.
+
+This will set environment variable "OPENVPN_name" to value "value" for
+the scripts run by the GUI. "name" is changed to "OPENVPN_name" to
+prevent overwriting sensitive variables such as PATH. Variables are
+set in the order received, with later values replacing earlier ones
+for the same "name".
+
+Names may include only alphanumeric characters and underscores. A
+"setenv" command with an invalid name will be ignored.
+
+    Android: ??????
+
+    Tunnelblick: Planned.
+
+    Windows OpenVPN GUI: supported since release v2.4.7 (GUI version v11.12.0)
+The variables set by "setenv" are merged with those for the process
+environment.  In case of duplicate names the one in the setenv list is
+chosen.
+

The extra blank line at the end of file is unnecessary (whitespace
error according to git).

> diff --git a/src/openvpn/options.c b/src/openvpn/options.c
> index ff3954d5..36009f4f 100644
> --- a/src/openvpn/options.c
> +++ b/src/openvpn/options.c
> @@ -5306,13 +5306,14 @@ add_option(struct options *options,
>          }
>          if (good)
>          {
> -#if 0
> -            /* removed for now since ECHO can potentially include
> -             * security-sensitive strings */
> -            msg(M_INFO, "%s:%s",
> -                pull_mode ? "ECHO-PULL" : "ECHO",
> -                BSTR(&string));
> -#endif
> +            /* only message-related ECHO are logged, since other ECHOs
> +             * can potentially include security-sensitive strings */
> +            if (strncmp(p[1],"msg",3) == 0)

Missing space between function arguments.

> +            {
> +                msg(M_INFO, "%s:%s",
> +                    pull_mode ? "ECHO-PULL" : "ECHO",
> +                    BSTR(&string));
> +            }
>  #ifdef ENABLE_MANAGEMENT
>              if (management)
>              {
> --
> 2.26.2

I have only compile tested as the code change looks sane and simple.

Acked by: selva.nair@...277...

Thanks,

Selva

[Openvpn-devel] [PATCH applied] Re: Document common uses of 'echo' directive, re-enable logging for 'echo'.

[Gert Doering]

Patch has been applied to the master and release/2.5 branch.

Whitespace added as requested :-)

commit ef2405a6bf5e8159d2e51e45107bc280fd6d0bd3 (master)
commit 4008ce020526f950cb2055ba7effff8f7ceb13e4 (release/2.5)
Author: Gert Doering
Date:   Mon Jan 18 17:28:50 2021 +0100

     Document common uses of 'echo' directive, re-enable logging for 'echo'.

     Signed-off-by: Gert Doering <gert@...1296...>
     Acked-by: Selva Nair <selva.nair@...277...>
     Message-Id: <20210118162850.24214-1-gert@...1296...>
     URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg21443.html
     Signed-off-by: Gert Doering <gert@...1296...>


--
kind regards,

Gert Doering