mirror of
https://github.com/OpenVPN/openvpn.git
synced 2024-09-19 19:42:30 +02:00
13ee7f902f
The certificate selection process for the Crypto API certificates is currently fixed to match on subject or identifier. Especially if certificates that are used for OpenVPN are managed by a Windows CA, it is appropriate to select the certificate to use by the template that it is generated from, especially on domain-joined clients which automatically acquire/renew the corresponding certificate. The attached match implements the match on TMPL: with either a template name (which is looked up through CryptFindOIDInfo) or by specifying the OID of the template directly, which then is matched against the corresponding X509 extensions specifying the template that the certificate was generated from. The logic requires to walk all certificates in the underlying store and to match the certificate extensions directly. The hook which is implemented in the certificate selection logic is generic to allow other Crypto-API certificate matches to also be implemented at some point in the future. The logic to match the certificate template is taken from the implementation in the .NET core runtime, see Pal.Windows/FindPal.cs in in the implementation of System.Security.Cryptography.X509Certificates. Change-Id: Ia2c3e4c5c83ecccce1618c43b489dbe811de5351 Signed-off-by: Heiko Wundram <heiko.wundram@gehrkens.it> Signed-off-by: Hannes Domani <ssbssa@yahoo.de> Acked-by: Selva Nair <selva.nair@gmail.com> Message-Id: <20240606103441.26598-1-gert@greenie.muc.de> URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg28726.html Signed-off-by: Gert Doering <gert@greenie.muc.de>
261 lines
11 KiB
ReStructuredText
261 lines
11 KiB
ReStructuredText
Windows-Specific Options
|
|
-------------------------
|
|
|
|
--allow-nonadmin TAP-adapter
|
|
(Standalone) Set ``TAP-adapter`` to allow access from non-administrative
|
|
accounts. If ``TAP-adapter`` is omitted, all TAP adapters on the system
|
|
will be configured to allow non-admin access. The non-admin access
|
|
setting will only persist for the length of time that the TAP-Win32
|
|
device object and driver remain loaded, and will need to be re-enabled
|
|
after a reboot, or if the driver is unloaded and reloaded. This
|
|
directive can only be used by an administrator.
|
|
|
|
--block-outside-dns
|
|
Block DNS servers on other network adapters to prevent DNS leaks. This
|
|
option prevents any application from accessing TCP or UDP port 53 except
|
|
one inside the tunnel. It uses Windows Filtering Platform (WFP) and
|
|
works on Windows Vista or later.
|
|
|
|
This option is considered unknown on non-Windows platforms and
|
|
unsupported on Windows XP, resulting in fatal error. You may want to use
|
|
``--setenv opt`` or ``--ignore-unknown-option`` (not suitable for
|
|
Windows XP) to ignore said error. Note that pushing unknown options from
|
|
server does not trigger fatal errors.
|
|
|
|
--cryptoapicert select-string
|
|
*(Windows/OpenSSL Only)* Load the certificate and private key from the
|
|
Windows Certificate System Store.
|
|
|
|
Use this option instead of ``--cert`` and ``--key``.
|
|
|
|
This makes it possible to use any smart card, supported by Windows, but
|
|
also any kind of certificate, residing in the Cert Store, where you have
|
|
access to the private key. This option has been tested with a couple of
|
|
different smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID)
|
|
on the client side, and also an imported PKCS12 software certificate on
|
|
the server side.
|
|
|
|
To select a certificate, based on a substring search in the
|
|
certificate's subject:
|
|
::
|
|
|
|
cryptoapicert "SUBJ:Peter Runestig"
|
|
|
|
To select a certificate, based on certificate's thumbprint (SHA1 hash):
|
|
::
|
|
|
|
cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
|
|
|
|
The thumbprint hex string can easily be copy-and-pasted from the Windows
|
|
Certificate Store GUI. The embedded spaces in the hex string are optional.
|
|
|
|
To select a certificate based on a substring in certificate's
|
|
issuer name:
|
|
::
|
|
|
|
cryptoapicert "ISSUER:Sample CA"
|
|
|
|
To select a certificate based on a certificate's template name or
|
|
OID of the template:
|
|
::
|
|
|
|
cryptoapicert "TMPL:Name of Template"
|
|
cryptoapicert "TMPL:1.3.6.1.4..."
|
|
|
|
The first non-expired certificate found in the user's store or the
|
|
machine store that matches the select-string is used.
|
|
|
|
--dhcp-release
|
|
Ask Windows to release the TAP adapter lease on shutdown. This option
|
|
has no effect now, as it is enabled by default starting with
|
|
OpenVPN 2.4.1.
|
|
|
|
--dhcp-renew
|
|
Ask Windows to renew the TAP adapter lease on startup. This option is
|
|
normally unnecessary, as Windows automatically triggers a DHCP
|
|
renegotiation on the TAP adapter when it comes up, however if you set
|
|
the TAP-Win32 adapter Media Status property to "Always Connected", you
|
|
may need this flag.
|
|
|
|
--ip-win32 method
|
|
When using ``--ifconfig`` on Windows, set the TAP-Win32 adapter IP
|
|
address and netmask using ``method``. Don't use this option unless you
|
|
are also using ``--ifconfig``.
|
|
|
|
:code:`manual`
|
|
Don't set the IP address or netmask automatically. Instead
|
|
output a message to the console telling the user to configure the
|
|
adapter manually and indicating the IP/netmask which OpenVPN
|
|
expects the adapter to be set to.
|
|
|
|
:code:`dynamic [offset] [lease-time]`
|
|
Automatically set the IP address and netmask by replying to DHCP
|
|
query messages generated by the kernel. This mode is probably the
|
|
"cleanest" solution for setting the TCP/IP properties since it
|
|
uses the well-known DHCP protocol. There are, however, two
|
|
prerequisites for using this mode:
|
|
|
|
(1) The TCP/IP properties for the TAP-Win32 adapter must be set
|
|
to "Obtain an IP address automatically", and
|
|
|
|
(2) OpenVPN needs to claim an IP address in the subnet for use
|
|
as the virtual DHCP server address.
|
|
|
|
By default in ``--dev tap`` mode, OpenVPN will take the normally
|
|
unused first address in the subnet. For example, if your subnet is
|
|
:code:`192.168.4.0 netmask 255.255.255.0`, then OpenVPN will take
|
|
the IP address :code:`192.168.4.0` to use as the virtual DHCP
|
|
server address. In ``--dev tun`` mode, OpenVPN will cause the DHCP
|
|
server to masquerade as if it were coming from the remote endpoint.
|
|
|
|
The optional offset parameter is an integer which is > :code:`-256`
|
|
and < :code:`256` and which defaults to 0. If offset is positive,
|
|
the DHCP server will masquerade as the IP address at network
|
|
address + offset. If offset is negative, the DHCP server will
|
|
masquerade as the IP address at broadcast address + offset.
|
|
|
|
The Windows :code:`ipconfig /all` command can be used to show what
|
|
Windows thinks the DHCP server address is. OpenVPN will "claim"
|
|
this address, so make sure to use a free address. Having said that,
|
|
different OpenVPN instantiations, including different ends of
|
|
the same connection, can share the same virtual DHCP server
|
|
address.
|
|
|
|
The ``lease-time`` parameter controls the lease time of the DHCP
|
|
assignment given to the TAP-Win32 adapter, and is denoted in
|
|
seconds. Normally a very long lease time is preferred because it
|
|
prevents routes involving the TAP-Win32 adapter from being lost
|
|
when the system goes to sleep. The default lease time is one year.
|
|
|
|
:code:`netsh`
|
|
Automatically set the IP address and netmask using the Windows
|
|
command-line "netsh" command. This method appears to work correctly
|
|
on Windows XP but not Windows 2000.
|
|
|
|
:code:`ipapi`
|
|
Automatically set the IP address and netmask using the Windows IP
|
|
Helper API. This approach does not have ideal semantics, though
|
|
testing has indicated that it works okay in practice. If you use
|
|
this option, it is best to leave the TCP/IP properties for the
|
|
TAP-Win32 adapter in their default state, i.e. "Obtain an IP
|
|
address automatically."
|
|
|
|
:code:`adaptive` (Default)
|
|
Try :code:`dynamic` method initially and fail over to :code:`netsh`
|
|
if the DHCP negotiation with the TAP-Win32 adapter does not succeed
|
|
in 20 seconds. Such failures have been known to occur when certain
|
|
third-party firewall packages installed on the client machine block
|
|
the DHCP negotiation used by the TAP-Win32 adapter. Note that if
|
|
the :code:`netsh` failover occurs, the TAP-Win32 adapter TCP/IP
|
|
properties will be reset from DHCP to static, and this will cause
|
|
future OpenVPN startups using the :code:`adaptive` mode to use
|
|
:code:`netsh` immediately, rather than trying :code:`dynamic` first.
|
|
|
|
To "unstick" the :code:`adaptive` mode from using :code:`netsh`,
|
|
run OpenVPN at least once using the :code:`dynamic` mode to restore
|
|
the TAP-Win32 adapter TCP/IP properties to a DHCP configuration.
|
|
|
|
--pause-exit
|
|
Put up a "press any key to continue" message on the console prior to
|
|
OpenVPN program exit. This option is automatically used by the Windows
|
|
explorer when OpenVPN is run on a configuration file using the
|
|
right-click explorer menu.
|
|
|
|
--register-dns
|
|
Run :code:`ipconfig /flushdns` and :code:`ipconfig /registerdns` on
|
|
connection initiation. This is known to kick Windows into recognizing
|
|
pushed DNS servers.
|
|
|
|
--route-method m
|
|
Which method ``m`` to use for adding routes on Windows?
|
|
|
|
:code:`adaptive` (default)
|
|
Try IP helper API first. If that fails, fall back to the route.exe
|
|
shell command.
|
|
|
|
:code:`ipapi`
|
|
Use IP helper API.
|
|
|
|
:code:`exe`
|
|
Call the route.exe shell command.
|
|
|
|
--service args
|
|
Should be used when OpenVPN is being automatically executed by another
|
|
program in such a context that no interaction with the user via display
|
|
or keyboard is possible.
|
|
|
|
Valid syntax:
|
|
::
|
|
|
|
service exit-event [0|1]
|
|
|
|
In general, end-users should never need to explicitly use this option,
|
|
as it is automatically added by the OpenVPN service wrapper when a given
|
|
OpenVPN configuration is being run as a service.
|
|
|
|
``exit-event`` is the name of a Windows global event object, and OpenVPN
|
|
will continuously monitor the state of this event object and exit when
|
|
it becomes signaled.
|
|
|
|
The second parameter indicates the initial state of ``exit-event`` and
|
|
normally defaults to 0.
|
|
|
|
Multiple OpenVPN processes can be simultaneously executed with the same
|
|
``exit-event`` parameter. In any case, the controlling process can
|
|
signal ``exit-event``, causing all such OpenVPN processes to exit.
|
|
|
|
When executing an OpenVPN process using the ``--service`` directive,
|
|
OpenVPN will probably not have a console window to output status/error
|
|
messages, therefore it is useful to use ``--log`` or ``--log-append`` to
|
|
write these messages to a file.
|
|
|
|
--show-adapters
|
|
(Standalone) Show available TAP-Win32 adapters which can be selected
|
|
using the ``--dev-node`` option. On non-Windows systems, the
|
|
``ifconfig``\(8) command provides similar functionality.
|
|
|
|
--show-net
|
|
(Standalone) Show OpenVPN's view of the system routing table and network
|
|
adapter list.
|
|
|
|
--show-net-up
|
|
Output OpenVPN's view of the system routing table and network adapter
|
|
list to the syslog or log file after the TUN/TAP adapter has been
|
|
brought up and any routes have been added.
|
|
|
|
--show-valid-subnets
|
|
(Standalone) Show valid subnets for ``--dev tun`` emulation. Since the
|
|
TAP-Win32 driver exports an ethernet interface to Windows, and since TUN
|
|
devices are point-to-point in nature, it is necessary for the TAP-Win32
|
|
driver to impose certain constraints on TUN endpoint address selection.
|
|
|
|
Namely, the point-to-point endpoints used in TUN device emulation must
|
|
be the middle two addresses of a /30 subnet (netmask 255.255.255.252).
|
|
|
|
--tap-sleep n
|
|
Cause OpenVPN to sleep for ``n`` seconds immediately after the TAP-Win32
|
|
adapter state is set to "connected".
|
|
|
|
This option is intended to be used to troubleshoot problems with the
|
|
``--ifconfig`` and ``--ip-win32`` options, and is used to give the
|
|
TAP-Win32 adapter time to come up before Windows IP Helper API
|
|
operations are applied to it.
|
|
|
|
--win-sys path
|
|
Set the Windows system directory pathname to use when looking for system
|
|
executables such as ``route.exe`` and ``netsh.exe``. By default, if this
|
|
directive is not specified, OpenVPN will use the SystemRoot environment
|
|
variable.
|
|
|
|
This option has changed behaviour since OpenVPN 2.3. Earlier you had to
|
|
define ``--win-sys env`` to use the SystemRoot environment variable,
|
|
otherwise it defaulted to :code:`C:\\WINDOWS`. It is not needed to use
|
|
the ``env`` keyword any more, and it will just be ignored. A warning is
|
|
logged when this is found in the configuration file.
|
|
|
|
--windows-driver drv
|
|
Specifies which tun driver to use. Values are :code:`ovpn-dco` (default),
|
|
:code:`tap-windows6` and :code:`wintun`. :code:`ovpn-dco` and :code:`wintun`
|
|
require ``--dev tun``. :code:`wintun` also requires OpenVPN process to run
|
|
elevated, or be invoked using the Interactive Service.
|