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

     net.inet.ipcomp.enable  Enable the IPComp 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,
              -srcid_type, -srcid, -dstid_type, -dstid, -auth, -authkey,
              -authkeyfile, -forcetunnel, -key, and -keyfile.

     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, -srcid_type, -srcid, -dstid_type, -dstid,
              -halfiv, -forcetunnel, -key, and -keyfile.

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

     old ah   Setup a SA which uses the old ah transforms.  Simple keyed hash-
              es will be used for authentication.  Allowed modifiers are:
              -dst, -src, -proxy, -spi, -srcid_type, -srcid, -dstid_type,
              -dstid, -forcetunnel, -auth, -key, and -keyfile.

     group    Group two SAs together, such that whenever the first one is ap-
              plied, the second one will be applied as well (SA bundle).  Ar-
              bitrarily long SA bundles can thus be created.  Note that the
              last SA in the bundle is the one that is applied last.  Thus, if
              an ESP and an AH SA are bundled together (in that order), then
              the resulting packet will have an AH header, followed by an ESP
              header, followed by the encrypted payload.  Allowed modifiers
              are: -dst, -spi, -proto, -dst2, -spi2, and -proto2.

     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, and -proto.

     flow     Create a flow determining what security parameters a packet
              should have (input or output).  Allowed modifiers are: -src,
              -dst, -proto, -addr, -transport, -sport, -dport, -delete, -in,
              -out, -deny, -srcid, -dstid, -srcid_type, -dstid_type, -use,
              -acquire, -require, -dontacq, -permit, and -bypass. The net-
              stat(1) command shows all specified flows.  Flows are direction-
              al, and the -in and -out modifiers are used to specify the di-
              rection.  By default, flows are assumed to apply to outgoing
              packets.  The kernel will attempt to find an appropriate Securi-
              ty Association from those already present (an SA that matches
              the destination address, if set, and the security protocol).  If
              the destination address is set to all zeroes (0.0.0.0) or left
              unspecified, the destination address from the packet will be
              used to locate an SA (the source address is used for incoming
              flows).  For incoming flows, the destination address (if speci-
              fied) should point to the expected source of the SA (the remote
              SA peer).  If no such SA exists, key management daemons will be
              used to generate them if -acquire or -require were used.  If
              -acquire was used, traffic will be allowed out (or in) and IPsec
              will be used when the relevant SAs have been established.  If
              -require was used, traffic will not be allowed in or out until
              it is protected by IPsec.  If -dontacq was used, traffic will
              not be allowed in or out until it is protected by IPsec, but key
              management will not be asked to provide such an SA.  The -proto
              argument (by default set to esp) will be used to determine what
              type of SA should be established.  A bypass or permit flow is
              used to specify a flow for which IPsec processing will be by-
              passed, i.e packets will/need not be processed by any SAs.  For
              permit flows, additional modifiers are restricted to: -addr,
              -transport, -sport, -dport, -in, -out, and -delete. A deny flow
              is used to specify classes of packets that must be dropped (ei-
              ther on output or input) without further processing.  deny takes
              the same additional modifiers as bypass.

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

     ipcomp   Setup an IP Compression Association (IPCA) which will use the
              IPcomp transforms. Just like an SA, an IPCA consists of the des-
              tination address, a Compression Parameter Index (CPI) and a pro-
              tocol (which is fixed to IPcomp). Compression algorithms are ap-
              plied. Allowed modifiers are: -dst, -src, -cpi, -comp, and
              -forcetunnel. To create an IPsec SA using compression, an IPCA
              and an SA must first be created. After this a IPCA/SA bundle
              must be created using the group keyword. The IPCA must be ap-
              plied first.

     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 in-
                 coming SAs to avoid source address spoofing between mutually
                 suspicious hosts that have established SAs with us.  For out-
                 going SAs, this field is used to fill in the source address
                 when doing tunneling.


           -dst  The destination IP address for the SA.

           -dst2
                 The second IP address used by group.

           -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 op-
                 tion is provided when applicable.  It is applicable in a sce-
                 nario when host A is using IPsec to communicate with firewall
                 B, and through that to host C.  In that case, the proxy ad-
                 dress for the incoming SA should be C.  This option is not
                 necessary for outgoing SAs.

           -spi  The Security Parameter Index (SPI), given as a hexadecimal
                 number.

           -spi2
                 The second SPI used by group.

           -cpi  The Compression Parameter Index (CPI), given as a hexadecimal
                 number.

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

           -newpadding
                 This option has been deprecated.

           -forcetunnel
                 Force IP-inside-IP encapsulation before ESP or AH processing
                 is performed for outgoing packets.  The source/destination
                 addresses of the outgoing IP packet will be those provided in
                 the src and dst options.  Notice 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.  Possible
                 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 or AES instead.  DES
                           support is kept for interoperability (with old im-
                           plementations) 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.

                 aes       Rijndael encryption is available only in new esp.

                 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 and is faster
                           than 3DES.  However, since it was designed by the
                           NSA it is a poor choice.

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

           -comp
                 The compression algorithm to be used with the IPCA. The only
                 possible value currently is: deflate.

           -key  The secret symmetric key used for encryption and authentica-
                 tion.  The size for des and 3des is fixed to 8 and 24 respec-
                 tively.  For other ciphers like cast, aes, or blf the key
                 length can vary (depending on the algorithm).  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 guess-
                 able.  One practical way of generating keys is by using the
                 random(4) device (e.g., dd if=/dev/urandom bs=1024 count=1 |
                 sha1)

           -keyfile
                 Read the key from a file.  May be used instead of the -key
                 flag, and has the same syntax considerations.

           -authkey
                 The secret key material used for authentication if additional
                 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-ran-
                 dom 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)

           -authkeyfile
                 Read the authkey from a file.  May be used instead of the
                 -authkey flag, and has the same syntax considerations.

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

           -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 or flow, 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.

           -proto2
                 The second security protocol used by group. It defaults to
                 IPPROTO_AH, otherwise takes the same values as -proto.

           -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.  Alterna-
                 tively, addresses and masks can be specified as
                 ``source/prefixlen destination/prefixlen''. All addresses

                 must be of the same address family (IPv4 or IPv6).

           -transport
                 The protocol number which packets need to match to use the
                 specified Security Association.  By default the protocol num-
                 ber is not used for matching.  Instead of a number, a valid
                 protocol name that appears in protocols(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.

           -srcid
                 For flow, used to specify what local identity key management
                 should use when negotiating the SAs.  If left unspecified,
                 the source address of the flow is used (see the discussion on
                 flow above, with regard to source address).

           -dstid
                 For flow, used to specify what the remote identity key man-
                 agement should expect is.  If left unspecified, the destina-
                 tion address of the flow is used (see the discussion on flow
                 above, with regard to destination address).

           -srcid_type
                 For flow, used to specify the type of identity given by
                 -srcid. Valid values are prefix, fqdn, and ufqdn. The prefix
                 type implies an IPv4 or IPv6 address followed by a forward
                 slash character and a decimal number indicating the number of
                 important bits in the address (equivalent to a netmask, in
                 IPv4 terms).  Key management then has to pick a local identi-
                 ty that falls within the address space indicated.  The fqdn
                 and ufqdn types are DNS-style host names and mailbox-format
                 user addresses, respectively, and are especially useful for
                 mobile user scenarios.  Note that no validity checking on the
                 identities is done.

           -dstid_type
                 See -srcid_type.

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

           -bypass
                 For flow, create or delete a bypass flow.  Packets matching
                 this flow will not be processed by IPsec.

           -deny
                 For flow, create or delete a deny flow.  Packets matching
                 this flow will be dropped.

           -use  For flow, specify that packets matching this flow should try
                 to use IPsec if possible.

           -acquire
                 For flow, specify that packets matching this flow should try
                 to use IPsec and establish SAs dynamically if possible, but

                 permit unencrypted traffic.

           -require
                 For flow, specify that packets matching this flow must use
                 IPsec, and establish SAs dynamically as needed. If no SAs are
                 established, traffic is not allowed through.

           -dontacq
                 For flow, specify that packets matching this flow must use
                 IPsec.  If such SAs are not present, simply drop the packets.
                 Such a policy may be used to demand peers to establish SAs
                 before they can communicate with us, without going through
                 the burden of initiating the SA ourselves (thus allowing for
                 some denial of service attacks).  This flow type is particu-
                 larly suitable for security gateways.

           -in   For flow, specify that it should be used to match incoming
                 packets only.

           -out  For flow, specify that it should be used to match outgoing
                 packets only.

           -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.

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

     ipsecadm new esp -enc 3des -auth sha1 -spi 100a -dst 169.20.12.2 \
             -src 169.20.12.3 \
             -key 638063806380638063806380638063806380638063806380 \
             -authkey 1234123412341234123412341234123412341234

     Setup a SA for authentication with old ah only:

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

     Setup a flow requiring use of AH:

     ipsecadm flow -dst 169.20.12.2 -proto ah \
             -addr 10.1.1.0 255.255.255.0 10.0.0.0 255.0.0.0 -out -require

     Setup an inbound SA:

     ipsecadm new esp -enc blf -auth md5 -spi 1002 -dst 169.20.12.3 \
             -src 169.20.12.2 \
             -key abadbeef15deadbeefabadbeef15deadbeefabadbeef15deadbeef \
             -authkey 12349876432167890192837465098273

     Setup an ingress flow on for the inbound SA:

     ipsecadm flow -addr 10.0.0.0 255.0.0.0 10.1.1.0 255.255.255.0 \
             -dst 169.20.12.2 -proto esp -in -require

     Setup a bypass flow:

     ipsecadm flow -bypass -out \
             -addr 10.1.1.0 255.255.255.0 10.1.1.0 255.255.255.0

     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 3.0                     August 26, 1997                              7
