IPSECADM(8)             OpenBSD System Manager's Manual            IPSECADM(8)

NAME
     ipsecadm - interface to setup IPSec

SYNOPSIS
     ipsecadm [command] modifiers ...

NOTE
     Before ipsecadm(8) can be used, IPSec must be enabled by setting one or
     more of the following sysctl(3) variables:

     net.inet.esp.enable    Enable the ESP IPSec protocol

     net.inet.ah.enable     Enable the AH IPSec protocol

     To enable these operations across reboots, see /etc/sysctl.conf.

DESCRIPTION
     The ipsecadm utility sets up security associations in the kernel to be
     used with ipsec(4).  It can be used to specify the encryption and authen-
     tication algorithms and key material for the network layer security pro-
     vided by IPSec.  The possible commands are:

     new esp  Setup a Security Association (SA) which uses the new esp trans-
              forms.  A SA consists of the destination address, a Security Pa-
              rameter Index (SPI) and a security protocol.  Encryption and au-
              thentication algorithms can be applied.  This is the default
              mode.  Allowed modifiers are: -dst, -src, -proxy, -spi, -enc,
              -auth, -authkey, -forcetunnel, and -key.

     old esp  Setup a SA which uses the old esp transforms. Only encryption
              algorithms can be applied. Allowed modifiers are: -dst, -src,
              -proxy, -spi, -enc, -halfiv, -forcetunnel, and -key.

     new ah   Setup a SA which uses the new ah transforms. Authentication will
              be done with HMAC using the specified hash algorithm. Allowed
              modifiers are: -dst, -src, -proxy, -spi, -forcetunnel, -auth,
              and -key.

     old ah   Setup a SA which uses the old ah transforms. Simple keyed hashes
              will be used for authentication. Allowed modifiers are: -dst,
              -src, -proxy, -spi, -forcetunnel, -auth, and -key.

     ip4      Setup an SA which uses the IP-in-IP encapsulation protocol. This
              mode offers no security services by itself, but can be used to
              route other (experimental or otherwise) protocols over an IP
              network.  The SPI value is not used for anything other than ref-
              erencing the information, and does not appear on the wire. Un-
              like other setups, like new esp, there is no necessary setup in
              the receiving side. Allowed modifiers are: -dst, -src, and -spi.

     delspi   The specified SA will be deleted.  Allowed modifiers are: -dst,
              -spi, -proto. and -chain.

     group    Group two SAs together. Allowed modifiers are: -dst, -spi,
              -proto, -dst2, -spi2, and -proto2.

     flow     Create a flow determining which packets are routed via which Se-
              curity Association. Allowed modifiers are: -dst, -spi, -proto,
              -addr, -transport, -sport, -dport, -local, -delete. The net-
              stat(1) command shows the existing flows.

     bind     Associate an incoming Security Association with an outgoing Se-
              curity Association. When a socket receives packets secured by
              the incoming SA all responses will be processed by the outgoing
              SA. Allowed modifiers are: -dst, -spi, -proto, -dst2, -spi2, and
              -proto2. The IP address 0.0.0.0 can be used as wildcard for -src
              and -dst. This can be useful while travelling where the IP ad-
              dress of potential clients is not known.

     flush    Flush SAs from from kernel. This includes flushing any flows and
              routing entries associated with the SAs. Allowed modifiers are:
              -ah, -esp, -oldah, -oldesp, and -ip4. Default action is to flush
              all types of security associations from the kernel.

     If no command is given ipsecadm(1) defaults to new esp mode.

     The modifiers have the following meanings:

           src          The source IP address for the SA. This is necessary
                        for incoming SAs to avoid source address spoofing be-
                        tween mutually suspicious hosts that have established
                        SAs with us. For outgoing SAs, this field is used to
                        slightly speedup packet processing. If this field is
                        zero (0.0.0.0), no spoofing check will be done for in-
                        coming SAs, and an extra routing lookup may be neces-
                        sary for certain classes of packets that originate
                        from the local machine and make use of the SA. If pre-
                        sent, the value of this field is used when doing IP-
                        in-IP encapsulation (e.g., when the forcetunnel option
                        has been specified.

           dst          The destination IP address for the SA.

           proxy        This IP address, if provided, is checked against the
                        inner IP address when doing tunneling to a firewall,
                        to prevent source spoofing attacks. It is strongly
                        recommended that this option is provided when applica-
                        ble. It is applicable in a scenario when host A is us-
                        ing IPsec to communicate with firewall B, and through
                        that to host C. In that case, the proxy address for
                        the incoming SA should be C. This option is not neces-
                        sary for outgoing SAs.

           spi          The Security Parameter Index (SPI).

           tunnel       This option has been deprecated. The arguments are ig-
                        nored, and it otherwise has the same effect as the
                        forcetunnel option.

           newpadding   This option has been deprecated.

           forcetunnel  Force IP-inside-IP encapsulation before ESP or AH pro-
                        cessing is performed for outgoing packets. The
                        source/destination addresses of the outgoing IP packet
                        will be those provided in the src and dst options. No-
                        tice that the IPsec stack will perform IP-inside-IP
                        encapsulation when deemed necessary, even if this flag
                        has not been set.

           enc          The encryption algorithm to be used with the SA. Pos-
                        sible values are:

                        des       This is available for both old and new esp.
                                  Notice that hardware crackers for DES can be
                                  (and have been) built for US$250,000 (in
                                  1998). Use DES for encryption of critical
                                  information at your own risk.  We suggest
                                  using 3DES instead. DES support is kept for
                                  interoperability (with old implementations)

                                  purposes only.  See des_cipher(3).

                        3des      This is available for both old and new esp.
                                  It is considered more secure than straight
                                  DES, since it uses larger keys.

                        blf       Blowfish encryption is available only in new
                                  esp. See blf_key(3).

                        cast      CAST encryption is available only in new
                                  esp.

                        skipjack  SKIPJACK encryption is available only in new
                                  esp.  This algorithm designed by the NSA is
                                  faster than 3DES.  However, since it was de-
                                  signed by the NSA it is a poor choice.

           auth         The authentication algorithm to be used with the SA.
                        Possible values are: md5 and sha1 for both old and new
                        ah and also new esp. Also rmd160 for both new ah and
                        esp.

           key          The secret symmetric key used for encryption and au-
                        thentication. The size for des and 3des is fixed to 8
                        and 24 respectively. For other ciphers like cast or
                        blf the key length can be variable. The key should be
                        given in hexadecimal digits. The key should be chosen
                        in random (ideally, using some true-random source like
                        coin flipping). It is very important that the key is
                        not guessable. One practical way of generating keys is
                        by using the random(4) device (e.g., dd if=/dev/uran-
                        dom bs=1024 count=1 | sha1)

           authkey      The secret key material used for authentication if ad-
                        ditional authentication in new esp mode is required.
                        For old or new ah the key material for authentication
                        is passed with the key option. The key should be given
                        in hexadecimal digits. The key should be chosen in
                        random (ideally, using some true-random source like
                        coin flipping). It is very important that the key is
                        not guessable. One practical way of generating keys is
                        by using the random(4) device (e.g., dd if=/dev/uran-
                        dom bs=1024 count=1 | sha1)

           iv           This option has been deprecated. The argument is ig-
                        nored. When applicable, it has the same behaviour as
                        the halfiv option.

           halfiv       This option causes use of a 4 byte IV in old ESP (as
                        opposed to 8 bytes). It may only be used with old ESP.

           proto        The security protocol needed by delspi, flow, group or
                        bind to uniquely specify the SA.  The default value is
                        50 which means IPPROTO_ESP. Other accepted values are
                        51 (IPPROTO_AH ), and 4 (IPPROTO_IP). One can also
                        specify the symbolic names "esp", "ah", and "ip4",
                        case insensitive.

           chain        Delete the whole SPI chain, otherwise delete only the
                        SPI given.

           dst2         The second IP destination address used by group.



           spi2         The second SPI used by group.

           proto2       The second security protocol used by group. It de-
                        faults to IPPROTO_AH. Other accepted values are 50
                        (IPPROTO_ESP ), and 4 (IPPROTO_IP). One can also spec-
                        ify the symbolic names "esp", "ah", and "ip4", case
                        insensitive.

           addr         The source address, source network mask, destination
                        address and destination network mask against which
                        packets need to match to use the specified Security
                        Association.

           transport    The protocol number which packets need to match to use
                        the specified Security Association. By default the
                        protocol number is not used for matching. Instead of a
                        number, a valid protocol name that appears in proto-
                        cols(5) can be used.

           sport        The source port which packets have to match for the
                        flow.  By default the source port is not used for
                        matching.  Instead of a number, a valid service name
                        that appears in services(5) can be used.

           dport        The destination port which packets have to match for
                        the flow.  By default the source port is not used for
                        matching.  Instead of a number, a valid service name
                        that appears in services(5) can be used.

           local        The flow command also creates a flow which matches lo-
                        cal packets. This is equivalent to using a source ad-
                        dress of 0.0.0.0 and a source network mask of
                        255.255.255.255.

           delete       Instead of creating a flow, an existing flow is delet-
                        ed.

           ah           For flush, only flush SAs of type ah.

           esp          For flush, only flush SAs of type esp.

           oldah        For flush, only flush SAs of type old ah.

           oldesp       For flush, only flush SAs of type old esp.

           ip4          For flush, only flush SAs of type ip4.

EXAMPLE
     Setup a SA which uses new esp with 3des encryption and HMAC-SHA1 authen-
     tication:

     ipsecadm new esp -enc 3des -auth sha1 -spi 1001 -dst 169.20.12.2 \
             -src 169.20.12.3.342 \
             -key 638063806380638063806380638063806380638063806380 \
             -authkey 1234123412341234123412341234123412341234

     Setup a SA for authentication with old ah only:

     ipsecadm old ah -auth md5 -spi 1001 -dst 169.20.12.2 -src 169.20.12.3 \
             -key 12341234deadbeef

     Delete all esp SAs and their flows and routing information:

     ipsecadm flush -esp

SEE ALSO
     netstat(1),  enc(4),  ipsec(4),  protocols(5),  services(5),  isakmpd(8),
      photurisd(8),  vpn(8)

OpenBSD 2.6                     August 26, 1997                              5
