openvpn.8

OpenVPN -- A Secure tunneling daemon

for an attacker with access to a signed string to find another string
which would sign to the same signature or generate a valid signature
for his own string.

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 --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-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 will start with a random IV and carry forward
the residuals across datagrams in a manner similar
to that used by IPSec (see RFC 2405 for more information). 

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 require a peer to function,
and therefore can be specified without
.B --dev
or
.B --remote.

The typical usage of
.B --test-crypto
would be something like this:

.B openvpn --test-crypto --secret key

or

.B openvpn --test-crypto --secret key --verb 9

This option is very useful to test OpenVPN after it has been ported to
a new platform, or to isolate problems in the compiler, OpenSSL
crypto library, or OpenVPN's crypto code.  Since it is a self-test mode,
problems with encryption and authentication can be debugged independently
of network and tunnel issues.
.SS TLS Mode Options:
TLS mode is the most powerful mode of OpenVPN in both security and flexibility.
TLS mode works by establishing control and
data channels which are multiplexed over a single UDP port.  OpenVPN initiates
a TLS session over the control channel and uses it to exchange cipher
and HMAC keys to protect the data channel.  TLS mode uses a robust reliability
layer over the UDP connection for all control channel communication, while
the data channel, over which encrypted tunnel data passes, is forwarded without
any mediation.  The result is the best of both worlds: a fast data channel
that forwards over UDP with only the overhead of encrypt,
decrypt, and HMAC functions,
and a control channel that provides all of the security features of TLS,
including certificate-based authentication and perfect forward security.

To use TLS mode, each peer that runs OpenVPN should have its own local
certificate/key pair (
.B --cert
and
.B --key
), signed by the root certificate which is specified
in
.B --ca.

When two OpenVPN peers connect, each presents its local certificate to the
other.  Each peer will then check that its partner peer presented a
certificate which was signed by the master root certificate as specified in
.B --ca.

If that check on both peers succeeds, then the TLS negotiation will succeed, both OpenVPN
peers will exchange temporary session keys, and the tunnel will begin
passing data.

The OpenVPN distribution contains a set of scripts for managing RSA certificates & keys,
located in the
.I easy-rsa
subdirectory.

The easy-rsa package is also rendered in web form here:
.I http://openvpn.sourceforge.net/easyrsa.html
.TP
.B --tls-server
Enable TLS and assume server role during TLS handshake.  Note that
OpenVPN is designed as a peer-to-peer application.  The designation
of client or server is only for the purpose of negotiating the TLS
control channel.
.TP
.B --tls-client
Enable TLS and assume client role during TLS handshake.
.TP
.B --ca file
Certificate authority (CA) file in .pem format, also referred to as the
.I root
certificate.  This file can have multiple
certificates in .pem format, concatenated together.  You can construct your own
certificate authority certificate and private key by using a command such as:

.B openssl req -nodes -new -x509 -keyout tmp-ca.key -out tmp-ca.crt

Then edit your openssl.cnf file and edit the
.B certificate
variable to point to your new root certificate
.B tmp-ca.crt.

For testing purposes only, the OpenVPN distribution includes a sample
CA certificate (tmp-ca.crt).
Of course you should never use
the test certificates and test keys distributed with OpenVPN in a
production environment, since by virtue of the fact that
they are distributed with OpenVPN, they are totally insecure.
.TP
.B --dh file
File containing Diffie Hellman parameters
in .pem format (required for
.B --tls-server
only). Use

.B openssl dhparam -out dh1024.pem 1024

to generate your own, or use the existing dh1024.pem file
included with the OpenVPN distribution.  Diffie Hellman parameters
may be considered public.
.TP
.B --cert file
Local peer's signed certificate in .pem format -- must be signed
by a certificate authority whose certificate is in
.B --ca file.
Each peer in an OpenVPN link running in TLS mode should have its own
certificate and private key file.  In addition, each certificate should
have been signed by the key of a certificate
authority whose public key resides in the
.B --ca
certificate authority file.
You can easily make your own certificate authority (see above) or pay money
to use a commercial service such as thawte.com (in which case you will be
helping to finance the world's second space tourist :).
To generate a certificate,
you can use a command such as:

.B openssl req -nodes -new -keyout mycert.key -out mycert.csr

If your certificate authority private key lives on another machine, copy
the certificate signing request (mycert.csr) to this other machine (this can
be done over an insecure channel such as email).  Now sign the certificate
with a command such as:

.B openssl ca -out mycert.crt -in mycert.csr

Now copy the certificate (mycert.crt)
back to the peer which initially generated the .csr file (this
can be over a public medium).
Note that the
.B openssl ca
command reads the location of the certificate authority key from its
configuration file such as
.B /usr/share/ssl/openssl.cnf
-- note also
that for certificate authority functions, you must set up the files
.B index.txt
(may be empty) and
.B serial
(initialize to
.B 
01
).
.TP
.B --key file
Local peer's private key in .pem format.  Use the private key which was generated
when you built your peer's certificate (see
.B -cert file
above).
.TP
.B --tls-cipher l
A list l of allowable TLS ciphers separated by
.B |
(optional).  If you require a high level of security,
you may want to set this parameter manually, to prevent a
version rollback attack where a man-in-the-middle attacker tries
to force two peers to negotiate to the lowest level
of security they both support.
Use
.B --show-tls
to see a list of supported TLS ciphers.
.TP
.B --tls-timeout n
Packet retransmit timeout on TLS control channel
if no acknowledgment from remote within
.B n
seconds (default=2).  When OpenVPN sends a control
packet to its peer, it will expect to receive an
acknowledgement within
.B n
seconds or it will retransmit the packet, subject
to a TCP-like exponential backoff algorithm.  This parameter
only applies to control channel packets.  Data channel
packets (which carry encrypted tunnel data) are never
acknowledged, sequenced, or retransmitted by OpenVPN because
the higher level network protocols running on top of the tunnel
such as TCP expect this role to be left to them.
.TP
.B --reneg-bytes n
Renegotiate data channel key after
.B n
bytes sent or received (disabled by default).
OpenVPN allows the lifetime of a key
to expressed as a number of bytes encrypted/decrypted, a number of packets, or
a number of seconds.  A key renegotiation will be forced
if any of these three criteria are met by either peer.
.TP
.B --reneg-pkts n
Renegotiate data channel key after
.B n
packets sent and received (disabled by default).
.TP
.B --reneg-sec n
Renegotiate data channel key after
.B n
seconds (default=3600).
.TP
.B --hand-window n
Handshake Window -- the TLS-based key exchange must finalize within
.B n
seconds
of handshake initiation by any peer (default = 60 seconds).
If the handshake fails
we will attempt to reset our connection with our peer and try again.
Even in the event of handshake failure we will still use
our expiring key for up to
.B --tran-window
seconds to maintain continuity of transmission of tunnel
data.
.TP
.B --tran-window n
Transition window -- our old key can live this many seconds
after new a key renegotiation begins (default = 3600 seconds).
This is a powerful feature that contributes to the robustness
of the OpenVPN key negotiation protocol.  Even during periods
of extremely poor network connectivity between peers, with
significant dropped packets, OpenVPN
will never let the failure of a key exchange handshake interfere with
the continuing transmission of tunnel data.
.TP
.B --single-session
After initially connecting to a remote peer, disallow any new connections.
Using this
option means that a remote peer cannot connect, disconnect, and then
reconnect.

If the daemon is reset by a signal or
.B --ping-restart,
it will allow one new connection.

.B --single-session
can be used with
.B --ping-exit
or
.B --inactive
to create a single dynamic session that will exit when finished.
.TP
.B --tls-auth f
Add an additional layer of authentication on top of the TLS
control channel to protect against DoS attacks.
.B f
(required) is a shared-secret passphrase file.

.B --tls-auth
is recommended when you are running OpenVPN in a mode where
it is listening for packets from any IP address such as when
.B --remote
is not specified, or
.B --remote
is specified with
.B --float.

The rationale for
this feature is as follows.  TLS requires a multi-packet exchange
before it is able to authenticate a peer.  During this time
before authentication, OpenVPN is allocating resources (memory
and CPU) to this potential peer.  The potential peer is also
exposing many parts of OpenVPN and the OpenSSL library to the packets
it is sending.  Most successful network attacks today seek
to either exploit bugs in programs (such as buffer overflow attacks) or
force a program to consume so many resources that it becomes unusable.
Of course the first line of defense is always to produce clean,
well-audited code.  OpenVPN has been written with buffer overflow
attack prevention as a top priority.
But as history has shown, many of the most widely used
network applications have, from time to time,
fallen to buffer overflow attacks.

So as a second line of defense, OpenVPN offers
this special layer of authentication on top of the TLS control channel so that