IPSEC.CONF(5)             OpenBSD Programmer's Manual            IPSEC.CONF(5)

NAME
     ipsec.conf - IPsec configuration file

DESCRIPTION
     The ipsec.conf file specifies rules and definitions for IPsec, which pro-
     vides security services for IP datagrams.  IPsec itself is a pair of pro-
     tocols: Encapsulating Security Payload (ESP), which provides integrity
     and confidentiality; and Authentication Header (AH), which provides in-
     tegrity.  The IPsec protocol itself is described in ipsec(4).

     In its most basic form, a flow is established between hosts and/or net-
     works, and then Security Associations (SA) are established, which detail
     how the desired protection will be achieved.  IPsec uses flows to deter-
     mine whether to apply security services to an IP packet or not.  Flows
     and SAs can be loaded, viewed, and modified using the ipsecctl(8) utili-
     ty.

     Generally speaking an automated keying daemon, such as isakmpd(8), is
     used to set up flows and establish SAs, by specifying an `ike' line in
     ipsec.conf (see AUTOMATIC KEYING, below).  An authentication method, such
     as public key authentication, will also have to be set up: see the PKI
     section of isakmpd(8) for information on the types of authentication
     available, and the procedures for setting them up.  After that it's sim-
     ply a case of running the daemon.  Note that isakmpd(8) will probably
     need to be run with at least the -K option, to avoid keynote(4) policy
     checking.

     An alternative method of setting up SAs is also possible using manual
     keying.  Manual keying can be convenient for quick setups and testing.
     These procedures are documented within this page.

     Lines beginning with `#' and empty lines are regarded as comments, and
     ignored.  Lines may be split using the `\' character.

     Addresses can be specified in CIDR notation (matching netblocks), as sym-
     bolic host names, interface names, or interface group names.

     Certain parameters can be expressed as lists, in which case ipsecctl(8)
     generates all the necessary combinations.  For example:

           ike esp from {192.168.1.1, 192.168.1.2} to \
                   {10.0.0.17, 10.0.0.18} peer 192.168.10.1

     Will expand to:

           ike esp from 192.168.1.1 to 10.0.0.17 peer 192.168.10.1
           ike esp from 192.168.1.1 to 10.0.0.18 peer 192.168.10.1
           ike esp from 192.168.1.2 to 10.0.0.17 peer 192.168.10.1
           ike esp from 192.168.1.2 to 10.0.0.18 peer 192.168.10.1

     Macros can be defined that will later be expanded in context.  Macro
     names must start with a letter, and may contain letters, digits and un-
     derscores.  Macro names may not be reserved words (for example flow,
     from, esp).  Macros are not expanded inside quotes.

     For example:

           remote_gw = "192.168.3.12"
           flow esp from 192.168.7.0/24 to 192.168.8.0/24 peer $remote_gw

AUTOMATIC KEYING
     In this scenario, ipsec.conf is used to set up flows and SAs automatical-
     ly using isakmpd(8).  Some examples of setting up automatic keying:

        # Set up two tunnels:
        # First between the machines 192.168.3.1 and 192.168.3.2
        # Second between the networks 10.1.1.0/24 and 10.1.2.0/24
        ike esp from 192.168.3.1 to 192.168.3.2
        ike esp from 10.1.1.0/24 to 10.1.2.0/24 peer 192.168.3.2

     The commands are as follows:

     ike [mode] [encap] [tmode]
           mode specifies the IKE mode to use: one of passive, active, or
           dynamic.  When passive is specified, isakmpd(8) will not immediate-
           ly start negotiation of this tunnel, but wait for an incoming re-
           quest from the remote peer.  When active or dynamic is specified,
           negotiation will be started at once.  The dynamic mode will addi-
           tionally enable Dead Peer Detection (DPD) and use the local host-
           name as the identity of the local peer, if not specified by the
           srcid parameter.  dynamic mode should be used for hosts with dynam-
           ic IP addresses like road warriors or dialup hosts.  If omitted,
           active mode will be used.

           encap specifies the encapsulation protocol to be used.  Possible
           protocols are esp and ah; the default is esp.

           tmode describes the encapsulation mode to be used.  Possible modes
           are tunnel and transport; the default is tunnel.

     proto protocol
           The optional proto parameter restricts the flow to a specific IP
           protocol.  Common protocols are icmp(4), tcp(4), and udp(4).  For a
           list of all the protocol name to number mappings used by
           ipsecctl(8), see the file /etc/protocols.

     from src [port sport] to dst [port dport]
           This rule applies for packets with source address src and destina-
           tion address dst.  The keyword any will match any address (i.e.
           0.0.0.0/0).  The optional port modifiers restrict the flows to the
           specified ports.  They are only valid in conjunction with the
           tcp(4) and udp(4) protocols.  Ports can be specified by number or
           by name.  For a list of all port name to number mappings used by
           ipsecctl(8), see the file /etc/services.

     local localip peer remote
           The local parameter specifies the address or FQDN of the local end-
           point.  Unless we are multi-homed or have aliases, this option is
           generally not needed.

           The peer parameter specifies the address or FQDN of the remote end-
           point.  For host-to-host connections where dst is identical to
           remote, this option is generally not needed.

     main auth algorithm enc algorithm group group
           These parameters define the cryptographic transforms to be used for
           main mode.  Possible values for auth, enc, and group are described
           below in CRYPTO TRANSFORMS.

           If omitted, ipsecctl(8) will use the default values hmac-sha1, aes,
           and modp1024.

     quick auth algorithm enc algorithm group group
           These parameters define the cryptographic transforms to be used for
           quick mode.  Possible values for auth, enc, and group are described
           below in CRYPTO TRANSFORMS.  If group is specified, Perfect Forward
           Security (PFS) is used.  If the value none is used, PFS is dis-
           abled.

           If omitted, ipsecctl(8) will use the default values hmac-sha2-256
           and aes; PFS will only be used if the remote side requests it.

     srcid string dstid string
           srcid defines an ID of type ``USER_FQDN'' or ``FQDN'' that will be
           used by isakmpd(8) as the identity of the local peer.  If the argu-
           ment is an email address (bob@example.com), ipsecctl(8) will use
           USER_FQDN as the ID type.  Anything else is considered to be an
           FQDN.  If srcid is omitted, the default is to use the IP address of
           the connecting machine.

           dstid is similar to srcid, but instead specifies the ID to be used
           by the remote peer.

     psk string
           Use a pre-shared key string for authentication.  If this option is
           not specified, public key authentication is used (see isakmpd(8)).

PACKET FILTERING
     IPsec traffic appears unencrypted on the enc(4) interface and can be fil-
     tered accordingly using the OpenBSD packet filter, pf(4).  The grammar
     for the packet filter is described in pf.conf(5).

     If the filtering rules specify to block everything by default, the fol-
     lowing rule would ensure that IPsec traffic never hits the packet filter-
     ing engine, and is therefore passed:

           set skip on enc0

     In the following example, all traffic is blocked by default.  IPsec traf-
     fic from gateways {192.168.3.1, 192.168.3.2} and networks {10.0.1.0/24,
     10.0.2.0/24} is permitted.  The external interface, sk0, has to allow the
     keying daemons to talk to each other.

           block on sk0
           block on enc0

           pass  in on sk0 proto esp from 192.168.3.2 to 192.168.3.1
           pass out on sk0 proto esp from 192.168.3.1 to 192.168.3.2
           pass  in on sk0 proto udp from 192.168.3.2 to 192.168.3.1 \
                   port {500, 4500}
           pass out on sk0 proto udp from 192.168.3.1 to 192.168.3.2 \
                   port {500, 4500}

           pass  in on enc0 proto ipencap from 192.168.3.2 to 192.168.3.1
           pass out on enc0 proto ipencap from 192.168.3.1 to 192.168.3.2
           pass  in on enc0 from 10.0.2.0/24 to 10.0.1.0/24
           pass out on enc0 from 10.0.1.0/24 to 10.0.2.0/24

     Connections on enc0 for which state is being kept should be interface
     bound, to avoid permitting unencrypted traffic should isakmpd(8) exit.
     For example:

           pass on enc0 from 192.168.3.1 to any keep state (if-bound)

CRYPTO TRANSFORMS
     It is very important that keys are not guessable.  One practical way of
     generating keys is to use openssl(1).  The following generates a 160-bit
     (20-byte) key:

           $ openssl rand 20 | hexdump -e '20/1 "%02x"'

     The following authentication types are permitted with the auth keyword:

           Authentication      Key Length
           hmac-md5            128 bits
           hmac-ripemd160      160 bits      [quick mode only]
           hmac-sha1           160 bits
           hmac-sha2-256       256 bits
           hmac-sha2-384       384 bits
           hmac-sha2-512       512 bits

     The following cipher types are permitted with the enc keyword:

           Cipher              Key Length
           des                 56 bits
           3des                168 bits
           aes                 128 bits
           aesctr              160 bits      [quick mode only]
           blowfish            160 bits
           cast                128 bits
           skipjack            80 bits

     Use of DES or Skipjack as an encryption algorithm is not recommended (ex-
     cept for backwards compatibility) due to their short key length.  Fur-
     thermore, attacks on Skipjack have shown severe weaknesses in its struc-
     ture.

     Note that DES requires 8 bytes to form a 56-bit key and 3DES requires 24
     bytes to form its 168-bit key.  This is because the most significant bit
     of each byte is used for parity.

     The following group types are permitted with the group keyword:

           Group               Size
           modp768             768
           modp1024            1024
           modp1536            1536
           modp2048            2048
           modp3072            3072
           modp4096            4096
           modp6144            6144
           modp8192            8192
           none                0             [quick mode only]

MANUAL FLOWS
     In this scenario, ipsec.conf is used to set up flows manually.  IPsec us-
     es flows to determine whether to apply security services to an IP packet
     or not.  Some examples of setting up flows:

        # Set up two flows:
        # First between the machines 192.168.3.14 and 192.168.3.100
        # Second between the networks 192.168.7.0/24 and 192.168.8.0/24
        flow esp from 192.168.3.14 to 192.168.3.100
        flow esp from 192.168.7.0/24 to 192.168.8.0/24 peer 192.168.3.12

     The following types of flow are available:

     flow esp
           ESP can provide the following properties: authentication, integri-
           ty, replay protection, and confidentiality of the data.  If no flow
           type is specified, this is the default.

     flow ah
           AH provides authentication, integrity, and replay protection, but
           not confidentiality.

     flow ipip
           IPIP does not provide authentication, integrity, replay protection,
           or confidentiality.  However, it does allow tunnelling of IP traf-
           fic over IP, without setting up gif(4) interfaces.

     The commands are as follows:

     in or out
           This rule applies to incoming or outgoing packets.  If neither in
           nor out are specified, ipsecctl(8) will assume the direction out
           for this rule and will construct a proper in rule.  Thus packets in
           both directions will be matched.

     proto protocol
           The optional proto parameter restricts the flow to a specific IP
           protocol.  Common protocols are icmp(4), tcp(4), and udp(4).  For a
           list of all the protocol name to number mappings used by
           ipsecctl(8), see the file /etc/protocols.

     from src [port sport] to dst [port dport]
           This rule applies for packets with source address src and destina-
           tion address dst.  The keyword any will match any address (i.e.
           0.0.0.0/0).  The optional port modifiers restrict the flows to the
           specified ports.  They are only valid in conjunction with the
           tcp(4) and udp(4) protocols.  Ports can be specified by number or
           by name.  For a list of all port name to number mappings used by
           ipsecctl(8), see the file /etc/services.

     local localip
           The local parameter specifies the address or FQDN of the local end-
           point of this flow and can be usually left out.

     peer remote
           The peer parameter specifies the address or FQDN of the remote end-
           point of this flow.  For host-to-host connections where dst is
           identical to remote, the peer specification can be left out.

     type modifier
           This optional parameter sets up special flows using the modifiers
           require, use, acquire, dontacq, bypass or deny.  A bypass flow is
           used to specify a flow for which security processing will be by-
           passed: matching packets will not be processed by any other flows
           and handled in normal operation.  A deny flow is used to drop any
           matching packets.  By default, ipsecctl(8) will automatically set
           up normal flows with the corresponding type.

MANUAL SECURITY ASSOCIATIONS (SAs)
     In this scenario, ipsec.conf is used to set up SAs manually.  The securi-
     ty parameters for a flow are stored in the Security Association Database
     (SAD).  An example of setting up an SA:

        # Set up an IPsec SA for flows between 192.168.3.14 and 192.168.3.12
        esp from 192.168.3.14 to 192.168.3.12 spi 0xdeadbeef:0xbeefdead \
                authkey file "auth14:auth12" enckey file "enc14:enc12"

     Parameters specify the peers, Security Parameter Index (SPI), crypto-
     graphic transforms, and key material to be used.  The following rules en-
     ter SAs in the SADB:

           esp       Enter an ESP SA.
           ah        Enter an AH SA.
           ipip      Enter an IPIP pseudo SA.
           tcpmd5    Enter a TCP MD5 SA.

     The commands are as follows:

     mode  For ESP and AH the encapsulation mode can be specified.  Possible
           modes are tunnel and transport.  When left out, tunnel is chosen.
           For details on modes see ipsec(4).

     from src to dst
           This SA is for a flow between the peers src and dst.

     spi number
           The SPI identifies a specific SA.  number is a 32-bit value and
           needs to be unique.

     auth algorithm
           For ESP and AH an authentication algorithm can be specified.  Pos-
           sible values are described above in CRYPTO TRANSFORMS.

           If no algorithm is specified, ipsecctl(8) will choose hmac-sha2-256
           by default.

     enc algorithm
           For ESP an encryption algorithm can be specified.  Possible values
           are described above in CRYPTO TRANSFORMS.

           If no algorithm is specified, ipsecctl(8) will choose aes by de-
           fault.

     authkey keyspec
           keyspec defines the authentication key to be used.  It is either a
           hexadecimal string or a path to a file containing the key.  The
           filename may be given as either an absolute path to the file or a
           relative pathname, and is specified as follows:

                  authkey file "filename"

           It is also possible to specify two values separated by a colon.
           ipsecctl(8) will then generate the matching incoming SA using the
           second value specified.

     enckey keyspec
           The encryption key is defined similarly to authkey.

     tcpmd5 from src to dst spi number authkey keyspec
           TCP MD5 signatures are generally used between BGP daemons, such as
           bgpd(8).  Since bgpd(8) itself already provides this functionality,
           this option is generally not needed.  More information on TCP MD5
           signatures can be found in tcp(4), bgpd.conf(5), and RFC 2385.

           This rule applies for packets with source address src and destina-
           tion address dst.  The parameter spi is a 32-bit value defining the
           Security Parameter Index (SPI) for this SA.  The encryption key is
           defined similarly to authkey.

SEE ALSO
     openssl(1), enc(4), ipsec(4), tcp(4), pf.conf(5), ipsecctl(8), isakmpd(8)

HISTORY
     The ipsec.conf file format first appeared in OpenBSD 3.8.

OpenBSD 4.0                      April 9, 2005                               6
