openvpn.8

OpenVPN is a robust and highly flexible tunneling application that uses all of the encryption, authe

of where the client is connecting from.  Remember
that you must also add the route to the system
routing table as well (such as by using the
.B --route
directive).  The reason why two routes are needed
is that the
.B --route
directive routes the packet from the system
to OpenVPN.  Once in OpenVPN, the
.B --iroute
directive routes to the specific client.

This option must be specified either in a client
instance config file using
.B --client-config-dir
or dynamically generated using a
.B --client-connect
script.
.TP
.B --client-to-client
Because the OpenVPN server mode handles multiple clients
through a single tun or tap interface, it is effectively
a router.  The
.B --client-to-client
flag tells OpenVPN to internally route client-to-client
traffic rather than pushing all client-originating traffic
to the tun/tap interface.

When this option is used, each client will "see" the other
clients which are currently connected.  Otherwise, each
client will only see the server.  Don't use this option
if you want to firewall tunnel traffic using
custom, per-client rules.
.TP
.B --duplicate-cn
Allow multiple clients with the same common name to concurrently connect.
In the absence of this option, OpenVPN will disconnect a client instance
upon connection of a new client having the same common name.
.TP
.B --client-connect script
Run
.B script
on client connection.  The script is passed the common name
and IP address of the just-authenticated client
as environmental variables.  The script is also passed
a single argument which is the filename of a temporary file.
If the script wants to generate client-instance-specific
options, it can write them to this file.  See the
.B --client-config-dir
option below for options which
can be legally used in a client-specific context.
.TP
.B --client-disconnect
Like
.B --client-connect
but called on client instance shutdown.
.TP
.B --client-config-dir dir
Specify a directory
.B dir
for custom client config files.  After
a connecting client has been authenticated, OpenVPN will
look in this directory for a file having the same name
as the client's X509 common name.  If a matching file
exists, it will be opened and processed for client-specific
configuration options.

One of the useful properties of this option is that it
allows client configuration files to be conveniently
created, edited, or removed while the server is live,
without needing to restart the server.

The following
options are legal in a client-specific context:
.B --push, --push-reset, --iroute, --ifconfig-push,
and
.B --config.
.TP
.B --tmp-dir dir
Specify a directory
.B dir
for temporary files.  This directory will be used by
.B --client-connect
scripts to dynamically generate client-specific
configuration files.
.TP
.B --hash-size r v
Set the size of the real address hash table to
.B r
and the virtual address table to
.B v.
By default, both tables are sized at 256 buckets.
.TP
.B --bcast-buffers n
Allocate
.B n
buffers for broadcast datagrams (default=256).
.TP
.B --connect-freq n sec
Allow a maximum of
.B n
new connections per
.B sec 
seconds from clients.  This is designed to contain DoS attacks which flood
the server with connection requests using certificates which
will ultimately fail to authenticate.

This is an imperfect solution however, because in a real
DoS scenario, legitimate connections might also be refused.
.TP
.B --learn-address cmd
Run script or shell command
.B cmd
to validate client virtual addresses.

.B cmd
will be executed with 3 parameters:

.B [1] operation --
"add", "update", or "delete" based on whether or not
the address is being added to, modified, or deleted from
OpenVPN's internal routing table.
.br
.B [2] address --
The address being learned or unlearned.  This can be
an IPv4 address such as "198.162.10.14", an IPv4 subnet
such as "198.162.10.0/24", or an ethernet MAC address (when
.B --dev tap
is being used) such as "00:FF:01:02:03:04".
.br
.B [3] common name --
The common name on the certificate associated with the
client linked to this address.  Only present for "add"
or "update" operations, not "delete".

Normally, the
.B cmd
script will use the information provided above to set
appropriate firewall entries on the VPN tun/tap interface.
Since OpenVPN provides the association between virtual IP
or MAC address and the client's authenticated common name,
it allows a user-defined script to configure firewall access
policies with regard to the client's high-level common name,
rather than the low level client virtual addresses.
.SS Data Channel Encryption Options:
These options are meaningful for both Static & TLS-negotiated key modes
(must be compatible between peers).
.TP
.B --secret file [direction]
Enable Static Key encryption mode (non-TLS).
Use pre-shared secret
.B file
which was generated with
.B --genkey.

The optional
.B direction
parameter enables the use of 4 distinct keys
(HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that
each data flow direction has a different set of HMAC and cipher keys.
This has a number of desirable security properties including
eliminating certain kinds of DoS and message replay attacks.

When the
.B direction
parameter is omitted, 2 keys are used bidirectionally, one for HMAC
and the other for encryption/decryption.

The
.B direction
parameter should always be complementary on either side of the connection,
i.e. one side should use "0" and the other should use "1", or both sides
should omit it altogether.

The
.B direction
parameter requires that
.B file
contains a 2048 bit key.  While pre-1.5 versions of OpenVPN
generate 1024 bit key files, any version of OpenVPN which
supports the
.B direction
parameter, will also support 2048 bit key file generation
using the
.B --genkey
option.

Static key encryption mode has certain advantages,
the primary being ease of configuration.

There are no certificates
or certificate authorities or complicated negotiation handshakes and protocols.
The only requirement is that you have a pre-existing secure channel with
your peer (such as
.B ssh
) to initially copy the key.  This requirement, along with the
fact that your key never changes unless you manually generate a new one,
makes it somewhat less secure than TLS mode (see below).  If an attacker
manages to steal your key, everything that was ever encrypted with
it is compromised.  Contrast that to the perfect forward secrecy features of
TLS mode (using Diffie Hellman key exchange), where even if an attacker
was able to steal your private key, he would gain no information to help
him decrypt past sessions.

Another advantageous aspect of Static Key encryption mode is that
it is a handshake-free protocol 
without any distinguishing signature or feature
(such as a header or protocol handshake sequence) 
that would mark the ciphertext packets as being
generated by OpenVPN.  Anyone eavesdropping on the wire
would see nothing
but random-looking data.
.TP
.B --auth alg
Authenticate packets with HMAC using message
digest algorithm
.B alg.
(The default is
.B SHA1
).
HMAC is a commonly used message authentication algorithm (MAC) that uses
a data string, a secure hash algorithm, and a key, to produce
a digital signature.

OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC the resulting ciphertext.

In static-key encryption mode, the HMAC key
is included in the key file generated by
.B --genkey.
In TLS mode, the HMAC key is dynamically generated and shared
between peers via the TLS control channel.  If OpenVPN receives a packet with
a bad HMAC it will drop the packet.
HMAC usually adds 16 or 20 bytes per packet.
Set
.B alg=none
to disable authentication.

For more information on HMAC see
.I http://www.cs.ucsd.edu/users/mihir/papers/hmac.html
.TP
.B --cipher alg
Encrypt packets with cipher algorithm
.B alg.
The default is
.B BF-CBC,
an abbreviation for Blowfish in Cipher Block Chaining mode.
Blowfish has the advantages of being fast, very secure, and allowing key sizes
of up to 448 bits.  Blowfish is designed to be used in situations where
keys are changed infrequently.

For more information on blowfish, see
.I http://www.counterpane.com/blowfish.html

To see other ciphers that are available with
OpenVPN, use the
.B --show-ciphers
option.

OpenVPN supports the CBC, CFB, and OFB cipher modes.

Set
.B alg=none
to disable encryption.
.TP
.B --keysize n
Size of cipher key in bits (optional).
If unspecified, defaults to cipher-specific default.  The
.B --show-ciphers
option (see below) shows all available OpenSSL ciphers,
their default key sizes, and whether the key size can
be changed.  Use care in changing a cipher's default
key size.  Many ciphers have not been extensively
cryptanalyzed with non-standard key lengths, and a
larger key may offer no real guarantee of greater
security, or may even reduce security.
.TP
.B --engine
Enable OpenSSL hardware crypto engine functionality.
.TP
.B --no-replay
Disable OpenVPN's protection against replay attacks.
Don't use this option unless you are prepared to make
a tradeoff of greater efficiency in exchange for less
security.

OpenVPN provides datagram replay protection by default.

Replay protection is accomplished
by tagging each outgoing datagram with an identifier
that is guaranteed to be unique for the key being used.
The peer that receives the datagram will check for
the uniqueness of the identifier.  If the identifier
was already received in a previous datagram, OpenVPN
will drop the packet.  Replay protection is important
to defeat attacks such as a SYN flood attack, where
the attacker listens in the wire, intercepts a TCP
SYN packet (identifying it by the context in which
it occurs in relation to other packets), then floods
the receiving peer with copies of this packet.

OpenVPN's replay protection is implemented in slightly
different ways, depending on the key management mode
you have selected.

In Static Key mode
or when using an CFB or OFB mode cipher, OpenVPN uses a
64 bit unique identifier that combines a time stamp with
an incrementing sequence number.

When using TLS mode for key exchange and a CBC cipher
mode, OpenVPN uses only a 32 bit sequence number without
a time stamp, since OpenVPN can guarantee the uniqueness
of this value for each key.  As in IPSec, if the sequence number is
close to wrapping back to zero, OpenVPN will trigger
a new key exchange.

To check for replays, OpenVPN uses
the
.I sliding window
algorithm used
by IPSec.
.TP
.B --replay-window n [t]
Use a replay protection sliding-window of size
.B n
and a time window of
.B t
seconds.

By default
.B n
is 64 (the IPSec default) and
.B t
is 15 seconds.

This option is only relevant in UDP mode, i.e.
when either
.B --proto udp
is specifed, or no
.B --proto
option is specified.

When OpenVPN tunnels IP packets over UDP, there is the possibility that
packets might be dropped or delivered out of order.  Because OpenVPN, like IPSec,
is emulating the physical network layer,
it will accept an out-of-order packet sequence, and
will deliver such packets in the same order they were received to
the TCP/IP protocol stack, provided they satisfy several constraints.

.B (a)
The packet cannot be a replay (unless
.B --no-replay
is specified, which disables replay protection altogether).

.B (b)
If a packet arrives out of order, it will only be accepted if the difference
between its sequence number and the highest sequence number received
so far is less than
.B n.

.B (c)
If a packet arrives out of order, it will only be accepted if it arrives no later
than
.B t
seconds after any packet containing a higher sequence number.

If you are using a network link with a large pipeline (meaning that
the product of bandwidth and latency is high), you may want to use
a larger value for
.B n.
Satellite links in particular often require this.

If you run OpenVPN at
.B --verb 4,
you will see the message "Replay-window backtrack occurred [x]"
every time the maximum sequence number backtrack seen thus far
increases.  This can be used to calibrate
.B n.

There is some controversy on the appropriate method of handling packet
reordering at the security layer.

Namely, to what extent should the
security layer protect the encapsulated protocol from attacks which masquerade
as the kinds of normal packet loss and reordering that occur over IP networks?

The IPSec and OpenVPN approach is to allow packet reordering within a certain
fixed sequence number window.

OpenVPN adds to the IPSec model by limiting the window size in time as well as
sequence space.

OpenVPN also adds TCP transport as an option (not offered by IPSec) in which
case OpenVPN can adopt a very strict attitude towards message deletion and
reordering:  Don't allow it.  Since TCP guarantees reliability, any packet
loss or reordering event can be assumed to be an attack.

In this sense, it could be argued that TCP tunnel transport is preferred when
tunneling non-IP or UDP application protocols which might be vulnerable to a
message deletion or reordering attack which falls within the normal
operational parameters of IP networks.

So I would make the statement that one should never tunnel a non-IP protocol
or UDP application protocol over UDP, if the protocol might be vulnerable to a
message deletion or reordering attack that falls within the normal operating
parameters of what is to be expected from the physical IP layer.  The problem
is easily fixed by simply using TCP as the VPN transport layer.
.TP
.B --replay-persist file
Persist replay-protection state across sessions using
.B file
to save and reload the state.

This option will strengthen protection against replay attacks,
especially when you are using OpenVPN in a dynamic context (such
as with
.B --inetd)
when OpenVPN sessions are frequently started and stopped. 

This option will keep a disk copy of the current replay protection
state (i.e. the most recent packet timestamp and sequence number
received from the remote peer), so that if an OpenVPN session
is stopped and restarted, it will reject any replays of packets
which were already received by the prior session.

This option only makes sense when replay protection is enabled
(the default) and you are using either
.B --secret
(shared-secret key mode) or TLS mode with
.B --tls-auth.
.TP
.B --no-iv
Disable OpenVPN's use of IV (cipher initialization vector).
Don't use this option unless you are prepared to make
a tradeoff of greater efficiency in exchange for less
security.

OpenVPN uses an IV by default, and requires it for CFB and
OFB cipher modes (which are totally insecure without it).
Using an IV is important for security when multiple
messages are being encrypted/decrypted with the same key.

IV is implemented differently depending on the cipher mode used.

In CBC mode, OpenVPN uses a pseudo-random IV for each packet.

In CFB/OFB mode, OpenVPN uses a unique sequence number and time stamp
as the IV.  In fact, in CFB/OFB mode, OpenVPN uses a datagram
space-saving optimization that uses the unique identifier for
datagram replay protection as the IV.
.TP
.B --test-crypto
Do a self-test of OpenVPN's crypto options by encrypting and
decrypting test packets using the data channel encryption options
specified above.  This option does not re