NetBSD IPsec FAQ

This page is developing, and we welcome any comments or suggestions.

IPsec FAQ

Other links

IPsec FAQ

Getting Started

IPsec (IP security protocol) is part of the NetBSD distributions, it provides per-packet authenticity/confidentiality guarantees between peers communicate using IPsec. IPsec is available for both IPv6 and IPv4.

Note that, however, kernel re-configuration is necessary to use IPsec. It is not turned on for default GENERIC kernel.

Userland code includes IPsec support where possible, by default, so no rebuild of userland is necessary even if you switch between kernel with IPsec, and without IPsec.

Note

We sometimes use the word “IP security” in more broader sense, like IP firewalls, packet filtering, and so forth.

IPsec = IKE + ESP || AH

IPsec consists of two parts: the Internet Key Exchange daemon (RFC 7296) that establishes and maintains secure associations between peers, and the ESP/RFC protocols used to secure IP datagrams.

Internet Key Exchange daemon first establishes a secure IKE SA between peers. This involves the following:

Establish a secured channel

A Diffie-Hellman-Merkle exchange is used to establish a secured channel between the peers.

Authenticate, proving the channel is between peers

Using the secured channel established above, each end proves their identity to their the peer. For instance using Public and Private keys, or a pre-shared key.

In IKEv2 this is the IKE_SA_INIT and IKE_AUTH exchanges (IKEv1 referred to this as Phase 1, using either Main or Aggressive Mode).

Note

While IKE is technically optional (you can configure secret keys manually for ESP/AH), it is not recommended. The keys used by ESP/AH have a limited life (both time and byte count) and need to be regularly replaced. The IKE daemon handles this.

The Internet Key Exchange Daemons then use the IKE SA between peers to negotiate, establish, and maintain ESP/AH Child SAs that are used to secure IP Datagrams. Two types of Child SA are supported:

Encapsulating Security Payload (ESP, RFC 4302)

ESP provides both confidentiality and authenticity guarantees for packets. Using a key shared with the peer, each IP datagram is encrypted and then an integrity hash is appended. On receipt, the peer uses the same key to verify the integrity and decrypt the packet.

Note

Combined Algorithms (aka Authenticated Encryption with Associated Data or AEAD), such as AES_GCM and ChaCha20, that combine encryption and integrity have largely replaced separate encryption and integrity algorithms.

Authentication Header (AH, RFC 4303)

AH provides authenticity guarantee for packets. Using a key shared by the peer, an integrity hash is appended to each packet. On receipt, the peer then uses that same key to verify the integrity of the IP datagram.

Unlike other protocols, AH in transport mode (see below), covers the whole packet, from the IP header to the end of the packet. In tunnel mode, however, there's little to differentiate between AH and the ESP combined with NULL encryption.

In IKEv2 this is the CREATE_CHILD_SA exchange (the first Child SA is is typically created by including the CREATE_CHILD_SA exchange contents in the IKE_AUTH exchange, thus avoiding a round trip) (IKEv1 referred to this as Phase 2, Quick Mode).

When establishing ESP or AH additional parameters, such as the following, can be negotiated:

IP compression (IPcomp)

Instead of encapsulating the raw IP datagram, the peers may agree to compress the raw payload. If the compression reduces the size of a given raw IP datagram then it is sent compressed of the uncompressed payload is sent (which typically leads to wasted effort).

NetBSD 10 supports IPcomp (including combinations such as an IPv4 packet being compressed, encapsulated and then sent using IPv6!).

Transport Mode

Instead of tunneling the ESP and/or AH payload inside UDP, the peers may agree to send the packets directly using Transport Mode.

NetBSD 10 supports Transport Mode.

Extended Sequence Numbers

Instead of using a 32-bit sequence counter, peers may agree to use a 64-bit sequence counter (only 32-bits go over the wire). The larger sequence counter means more time between rekeys.

NetBSD 10 does not support Extended Sequence Numbers.

ESP in TCP (RFC 9329)

Instead of transferring ESP packets using UDP, the peers may agree to transfer the encapsulated packets using a TCP data stream. This provides a way to get around firewalls that block UDP traffic.

NetBSD 10 does not support ESP in TCP.

IP Traffic Flow Confidentially (IP-TFC, RFC 9347)
Instead of directly transforming each IP datagram into an ESP packet, peers can agree to aggregate, pad, and fragment traffic obscuring traffic flow.

AH, ESP and IPcomp are implemented in the kernel code. IKE is implemented as daemon process in the userland. Kernel part and userland part will cooperate by using key management table in between.

Note

security of IPsec protocols depend on the secrecy of secret keys. If secret keys are compromised, IPsec protocols can no longer be secure. Take caution about permission mode of configuration files, key database files, or whatever they may lead to information leakage.


        userland programs               IKE daemon
          ^ | AF_INET{,6} socket          ^ | PF_KEY socket
========= | | =========================== | | ======== Kernel/user boundary
          | v                             | v
        transport layer, TCP/UDP        key management table
          ^ |                             ^ | key information
          | |                             | |
          | v                             | v
        IP input/output logic <-------> AH/ESP/IPcomp logic
          ^ |
          | v
        Network drivers (ethernet)

Transport mode and tunnel mode

AH, ESP and IPcomp have two modes of operation: transport mode and tunnel mode. Transport mode encrypts normal communication between peers. Tunnel mode will encapsulate packet into new IPv4/v6 header. Tunnel mode is designed to be used by VPN gateways.

[[transport mode]]
my host ======== peer's host
        transport
        mode

packets: [IP: me->peer] ESP payload
                        <---------> encrypted


[[tunnel mode]]
        (a)                  (b)                        (c)
my host ---- my VPN gateway ======== peer's VPN gateway ---- peer's host
                            tunnel mode

packets on (a): [IP: me->peer] payload
packets on (b): [IP: mygw->peergw] ESP [IP: me->peer] payload
                                   <------------------------> encrypted
packets on (c): [IP: me->peer] payload

IPsec “policy” management

Though the kernel knows how to secure packets, it does not know which packet requires security. We need to tell kernel about which packet needs to be secured. IPsec “policy” configuration allows us to specify it.

IPsec policy can be configured in per-packet, or per-socket manner:

  • Per-packet: configured into the kernel just like packet filters. You can specify like “encrypt outgoing packets if I'm sending to 10.1.1.0/24”. This works well when you are running an IPsec router.
  • Per-socket: configured via setsockopt(2) for a certain socket. You can specify like “encrypt outgoing packets from this socket”. This works well when you would like to run IPsec-aware server program.

IPsec policy decides which IPsec protocols (AH, ESP or IPcomp) to be used against a packet. You can configure kernel to use any combination of AH, ESP and IPcomp against a packet. You can even apply same protocol multiple times, like multiple ESP operation against single packet. It is questionable if multiple ESP operation has any benefit, but certainly interesting for test/debug use.

Configuring IPsec kernel

Refer to tracking NetBSD-current for more details of the build process.

  1. In your kernel configuration file, enable the following portion and build a new kernel. 
    options IPSEC
pseudo-device swcrypto
    Optionally you can also enable debugging: 
    options IPSEC_DEBUG
  2. Build a new kernel as usual.
  3. Replace the kernel and reboot.

Userland tools include IPsec support by default, and no userland rebuild is necessary.

Additionally, you may want to use racoon(8), which comes with NetBSD or install security/isakmpd.

Configuration examples: host-to-host encryption

If you would like to run host-to-host (transport mode) encryption with manually configured secret keys, the following configuration should be enough. We use setkey(8) to configure the manual keys.

#! /bin/sh
#
# packet will look like this: IPv4 ESP payload
# the node is on 10.1.1.1, peer is on 20.1.1.1
setkey -c <<EOF
add 10.1.1.1 20.1.1.1 esp 9876 -E 3des-cbc "hogehogehogehogehogehoge";
add 20.1.1.1 10.1.1.1 esp 10000 -E 3des-cbc 0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef;
spdadd 10.1.1.1 20.1.1.1 any -P out ipsec esp/transport//use;
EOF

The first two lines configure secret keys to be used by ESP. The decimal numbers that appear as the fourth word are called SPI (security parameter index). The value will be attached to ESP packet, and it lets the receiving side lookup the secret key from the packet. The number needs to be unique for a node.

  • From 10.1.1.1 to 20.1.1.1, we'd use the 3DES-CBC algorithm, with secret key "hogehogehogehogehogehoge". The traffic will be identified by SPI 9876.
  • From 20.1.1.1 to 10.1.1.1, we'd use 3DES-CBC algorithm, with secret key 0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef.

The last line configures per-packet IPsec policy for the node. With the configuration, the node (10.1.1.1) to transmit packets to the peer (20.1.1.1) encrypted, whenever secret key is configured into the kernel. The configuration does not prohibit unencrypted packets from 20.1.1.1 to reach 10.1.1.1. If you would like to reject unencrypted packet, add the following line:

spdadd 20.1.1.1 10.1.1.1 any -P in ipsec esp/transport//require;

On the other end (20.1.1.1), the configuration will be like this. Note that the addresses need to be swapped on the “spdadd” line, but not the “add” lines.

#! /bin/sh
#
# packet will look like this: IPv4 ESP payload
# the node is on 20.1.1.1, peer is on 10.1.1.1
setkey -c <<EOF
add 10.1.1.1 20.1.1.1 esp 9876 -E 3des-cbc "hogehogehogehogehogehoge";
add 20.1.1.1 10.1.1.1 esp 10000 -E 3des-cbc 0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef;
spdadd 20.1.1.1 10.1.1.1 any -P out ipsec esp/transport//use;
EOF

The syntax for policy configuration is documented in ipsec_set_policy(3).

Try running tcpdump(8) to see the encrypted packets on the wire - they are encrypted, it is no longer possible to wiretap those packets.

The above example uses human-readable secret keys. However, use of human-readable secret key is discouraged by the specification (since it will have more chance to be compromised, than binary keys). You'd better use binary keys for real operation.

Key length is determined by algorithms. For 3des-cbc, the secret key MUST be 192 bits (= 24 bytes). If you specify shorter/longer key, you will get error from setkey(8).

If you wish to use other algorithms, the configuration is very similar. Here's an example with rijndael-cbc (also known as AES). rijndael-cbc takes 128, 192 or 256 bits of secret keys. Here we use 128bit keys.

#! /bin/sh
#
# packet will look like this: IPv4 ESP payload
# the node is on 10.1.1.1, peer is on 20.1.1.1
# rijndael-cbc with 128bit key
setkey -c <<EOF
add 10.1.1.1 20.1.1.1 esp 9876 -E rijndael-cbc "hogehogehogehoge";
add 20.1.1.1 10.1.1.1 esp 10000 -E rijndael-cbc 0xdeadbeefdeadbeefdeadbeefdeadbeef;
spdadd 10.1.1.1 20.1.1.1 any -P out ipsec esp/transport//use;
EOF

Configuration examples: host-to-host authentication

Just like ESP, you can configure AH.

#! /bin/sh
#
# packet will look like this: IPv4 AH payload
# the node is on 10.1.1.1, peer is on 20.1.1.1
setkey -c <<EOF
add 10.1.1.1 20.1.1.1 ah 9877 -A hmac-md5 "hogehogehogehoge";
add 20.1.1.1 10.1.1.1 ah 10001 -A hmac-md5 "mogamogamogamoga";
spdadd 10.1.1.1 20.1.1.1 any -P out ipsec ah/transport//use;
EOF

Configuration examples: host-to-host encryption+authentication

If you configure secret keys for both AH and ESP, you can use both of them. IPsec document suggests to apply AH after ESP.

#! /bin/sh
#
# packet will look like this: IPv4 AH ESP payload
# the node is on 10.1.1.1, peer is on 20.1.1.1
setkey -c <<EOF
add 10.1.1.1 20.1.1.1 esp 9876 -E 3des-cbc "hogehogehogehogehogehoge";
add 20.1.1.1 10.1.1.1 esp 10000 -E 3des-cbc 0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef;
add 10.1.1.1 20.1.1.1 ah 9877 -A hmac-md5 "hogehogehogehoge";
add 20.1.1.1 10.1.1.1 ah 10001 -A hmac-md5 "mogamogamogamoga";
spdadd 10.1.1.1 20.1.1.1 any -P out ipsec esp/transport//use ah/transport//use;
EOF

Configuration examples: IPsec VPN

First of all, here are couple of issues with IPsec VPN configuration.

  • Routing setup must be done properly.
  • Do not try to use IPsec tunnel device to behave as the NAT box, or filtering firewall, at the same time. IPsec and NAT are inherently not compatible protocol. Also, due to implementation and specification limitations in 1.5, they do not play nice. We are trying to improve this situation. See "Interaction with NPF" for more details.
  • VPN configuration differs from installations to installations. Actually, there's no clear definition of what “VPN” means. If you make questions on mailing lists, you need to clarify your need, your current situation and your network configuration as a whole.

The following example assumes the following network configuration. The goals of the example are:

  • To somehow connect machines inside two private-address cloud (10.0.1.0/24 and 10.0.2.0/24, think of it as Tokyo branch of your company and NY headquarters).
  • The traffic between two cloud needs to be securely exchanged between the gateways.
  • We do not want to pay transpacific leased line charge, so we locally contract with ISP (in Tokyo and in NY) and tunnel traffic between gateways. 
((( 10.0.1.0/24 )))     VPN'ed network, Tokyo branch office
  |10.0.1.1
gateway 1
  |20.0.0.1
  |IPsec tunnel
  |20.0.0.2
gateway 2
  |10.0.2.1
((( 10.0.2.0/24 )))     VPN'ed network, NY headquarters

The following text presents configuration for gateway 1.

#! /bin/sh
#
# Note that routing should be set up in advance, i.e. for this example:
#       route -n add -net 10.0.2.0 10.0.2.1
#       route -n add 10.0.2.1 10.0.1.1
# packet will look like this: IPv4 ESP IPv4 payload
# the node is on 10.0.1.1/20.0.0.1, peer is on 10.0.2.1/20.0.0.2
setkey -c <<EOF
add 20.0.0.1 20.0.0.2 esp 13245 -E blowfish-cbc "blowfishtest.001" ;
add 20.0.0.2 20.0.0.1 esp 13246 -E blowfish-cbc 0xdeadbeefdeadbeefdeadbeefdeadbeef;
spdadd 10.0.1.0/24 10.0.2.0/24 any -P out ipsec esp/tunnel/20.0.0.1-20.0.0.2/require ;
spdadd 10.0.2.0/24 10.0.1.0/24 any -P in ipsec esp/tunnel/20.0.0.2-20.0.0.1/require ;
EOF

(contributed by Per Harald Myrvang)

Configuration examples: Leaf-node tunnel

Tunnel mode can be used in situations where all traffic from a given leaf node is to be encrypted to the next-hop router, and unencrypted from there (for example, a wireless node to a router, because 802.11 WEP is inadequate).

For the leaf node, use:

#! /bin/sh
#
# the node is on 10.0.1.5, router is on 10.0.1.1
setkey -c <<EOF
add 10.0.1.1 10.0.1.5 esp 1011 -E rijndael-cbc "rijndaeltest.001" ;
add 10.0.1.5 10.0.1.1 esp 1012 -E rijndael-cbc 0xdeadbeefdeadbeefdeadbeefdeadbeef;
spdadd 10.0.1.5/32 0.0.0.0/0 any -P out ipsec esp/tunnel/10.0.1.5-10.0.1.1/require;
spdadd 0.0.0.0/0 10.0.1.5/32 any -P in ipsec esp/tunnel/10.0.1.1-10.0.1.5/require;
EOF

For the router, swap the “out” and “in” keywords on the spdadd commands.

Configuring AH/ESP keys by using IKE

Here we describe the following configuration:

  • Node A and B will use transport-mode ESP.
  • It is required for both ends to use ESP to exchange packets, for all protocols.
  • During IKE, node A and B authenticate each other by using shared secret exchange.

Please follow the steps carefully. Run tcpdump(8) to check how the packets are exchanged between two nodes. Statistics by “netstat -sn” is also useful to know how kernel IPsec portion is working.

  1. Copy /usr/share/examples/racoon/racoon.conf.sample into /etc/racoon/racoon.conf. Modify parameters declared in racoon.conf as necessary. It is VERY critical that both ends use the same configuration - you will want less differences in racoon.conf.
  2. racoon will obey the IPsec policy settings in the kernel when it negotiates IPsec keys. Therefore, we need to configure IPsec policy into the kernel by using setkey(8). On node A, configure IPsec policy like this. In the example, “A” and “B” are IPv4/v6 numeric addresses. 
    A# setkey -c
spdadd A B any -P out ipsec esp/transport//require;
spdadd B A any -P in ipsec esp/transport//require;
^D
  3. On node B, configure IPsec policy like this by using setkey(8): 
    B# setkey -c
spdadd B A any -P out ipsec esp/transport//require;
spdadd A B any -P in ipsec esp/transport//require;
^D
  4. On both nodes, prepare pre-shared key file. It is VERY critical to set file permission properly, otherwise it worth nothing to use IPsec - it will do nothing other than wasting your CPU time (racoon(8) will not read files with weak permissions). Again “A” and “B” are numeric IPv4/v6 addresses. 
    A# cat >/etc/racoon/psk.txt
B       spamspamspam
^D
A# chmod 600 /etc/racoon/psk.txt

B# cat >/etc/racoon/psk.txt
A       spamspamspam
^D
B# chmod 600 /etc/racoon/psk.txt
  5. Run racoon. If you wish see the debug trace, arguments would be like below: 
    # racoon -f /etc/racoon/racoon.conf -dddddd
  6. Try to exchange packet between A and B. You will see some messages from racoon to console, and key will be established. 
    A# ping -n B
(with some delay, you will start seeing replies)
^C
A# setkey -D
(you will see keys exchanged by racoon)

racoon will negotiate keys based on the policy definition. By changing policy definition, we can easily configure for other cases. Next example configure keys for the following situation:

  • A is a mail server. A wishes to enforce the use of transport mode AH, to everyone contacts A with POP protocol (TCP port 110). B is a client which wishes to contact A.
    1. The policy configuration on A avoids of AH for local traffic (note that racoon cannot negotiate keys with itself). The order of the policy is highly important. If you reorder them, the configuration will not work. 
      A# setkey -c
spdadd A[110] A tcp -P out none;
spdadd A A[110] tcp -P in none;
spdadd A[110] 0.0.0.0/0 tcp -P out ipsec ah/transport//require;
spdadd 0.0.0.0/0 A[110] tcp -P in ipsec ah/transport//require;
^D

B# setkey -c
spdadd B A[110] tcp -P out ipsec ah/transport//require;
spdadd A[110] B tcp -P in ipsec ah/transport//require;
^D
    2. Other than policy configuration part, configure just like the previous example.

If you have any problem in configuring it, be sure to look at full debug logs (racoon -dddddd) and see where it chokes. Every configuration difference leads to unsuccessful negotiation.

Setting up IPsec manual keys and policies on bootstrap

rc.conf(5) has an entry for IPsec, named “ipsec”. ipsec=YES will run the following command at bootstrap time, before any of the network activities:

/sbin/setkey -f /etc/ipsec.conf

For example, you can perform encrypted NFS mount for /usr. /etc/ipsec.conf should contain valid commands to setkey(8); similar to the configuration examples above without the setkey -c <<EOF ... EOF sections.

Interaction with NPF

NetBSD implements npf(7). NPF filters packets, and IPsec policy processing is inherently similar to packet filter. Therefore, they implement conflicting functionality. NPF/IPsec interaction is specified as: NPF looks at packets in native wire format only. NPF looks at packets before IPsec processing on inbound, and after IPsec processing on outbound.

Even with the processing order, please be aware of the following:

  • If you want IPsec packets to go through NPF, you should not drop them by npf.conf(5) rules. You need to let IP packets with relevant protocol number (50 for ESP, 51 for AH) go through.

    Note

    protocol numbers are completely different thing from TCP/UDP port numbers.

  • Packets coming from tunnel devices (eg gif(4)) will still go through npf(7). You may need to identify these packets by using interface name directive in npf.conf(5).

Processing order

The following diagram summarizes new inbound processing order:

inbound processing:
        userland programs               IKE daemon
          ^ AF_INET{,6} socket            ^ | PF_KEY socket
========= | ============================= | | ======== Kernel/user boundary
          |                               | v
        transport layer, TCP/UDP        key management table
          ^                               ^ | key information
          |                               | |
          |                               | v
  +-----IP input/output logic <-------> AH/ESP/IPcomp logic
  v       ^          ^                      |
tunnel    |          +----------------------+ decapsulated IPsec packets
devices   |
  |     NPF rule
  |       ^
  +------>|
          |
        Network drivers (ethernet)

The following diagram summarizes new outbound processing order:

outbound processing:
        userland programs               IKE daemon
            | AF_INET{,6} socket          ^ | PF_KEY socket
=========== | =========================== | | ======== Kernel/user boundary
            v                             | v
        transport layer, TCP/UDP        key management table
            |                             ^ | key information
            |                             | |
            v                             | v
  +---->IP input/output logic <-------> AH/ESP/IPcomp logic
  |         |                           (incl. IPsec tunnel encapsulation)
tunnel      |
devices     |
  |     NPF rules
  |         |
  +---------+
            v
        Network drivers (ethernet)

Common pitfalls, and debugging techniques

  • Some people mix up the following three items. Take caution if you try to interoperate with other implementations. If you mix them up, you will never be able to make a interoperable configuration. Documentations may be using different words for them (sigh).
    • IPsec with manual key
      In NetBSD case, this way uses setkey(8) to configure IPsec secret key. IPsec secret key will not change over time.
    • IPsec with IKE, with pre-shared secret
      In NetBSD case, this uses racoon(8). We authenticate peer with pre-shared secret. racoon(8) will negotiate IPsec keys dynamically and installs it into the kernel. IPsec secret key changes over time.
    • IPsec with IKE, with certificates
      In NetBSD case, this uses racoon(8). We authenticate peer with certificate files. racoon(8) will negotiate IPsec keys dynamically and installs it into the kernel. IPsec secret key changes over time.
  • The configuration of IPsec is NOT EASY. There are way too many knobs to play with, and debugging is very hard due to wiretap-resistant nature of IPsec. Basically, we can't guess what is going on from packet trace. Try reading some books and standard documents/RFCs, hire consultants or whatever, before you try to configure it.
  • Always run tcpdump while you debug the network. Even though the traffic is encrypted, you can get some idea if the packet is really on the wire or not.
  • netstat(1) is your friend. Run netstat -sn and check the IPsec packet counters.
  • If you have trouble running racoon(8), try running it with maximum debugging output and look at the output. (command line argument -dddddd)
  • You really really need to configure your NetBSD device with peer's device exactly the same to make them interoperate. Your packet needs to be generated by using exactly the same protocol, and encryption algorithm, as the other end is expecting. By failing to do so, you will experience very hard-to-track errors. In IPsec, encryption/authentication failures are modelled as packet drops. So configuration failures will make your packets to be dropped onto the floor with no error indications. tcpdump(8) will not help you much, since the content of packet is now not de-cipherable. Make very very sure that you configure carefully with the other end.
  • On slow machines, you may not be able to negotiate keys with racoon IKE daemon, as IKE negotiation has to finish within net.key.larval_lifetime sysctl MIB, which is 30 seconds by default. Try raising the value if you got a really-slow machines.

Known issues

  • Tunnel mode AH does not work as you might expect, due to restrictions in kernel IPsec policy engine. Do not try to use tunnel mode AH.
  • IPsec and npf(7) code do not play nicely together. See "Interaction with NPF" for detail.
  • IPsec policy rule is not tested enough for explicit protocol specification other than tcp/udp. Use protocol “any” (= address match only) if you would like to take a safer side. The issue here is generic to any packet filters - normal packet filter descriptions do not play nicely with header chains.

Conformance to standard, interoperability

KAME IPsec implementation (which is included in NetBSD tree) conforms to latest set of IPsec standards. KAME's NetBSD Implementation Note has comprehensive list of standard documents to which the implementation conforms.

Interoperability with other implementation has been confirmed in various occasions. KAME's NetBSD Implementation Note includes list of implementations which we have confirmed interoperability in the past. Note that, however, it is possible for both sides to change the code after interoperability tests, and it is possible that they no longer interoperate. It is also possible that NetBSD device and peer's device interoperate in certain configuration only.

If you try to configure NetBSD device with other implementation, please note that IPsec specifications/implementations have too many knobs to play with. You need to configure your NetBSD device with peer's device exactly the same to make them interoperate.

API compatibility with other IPsec stacks

If you write userland code that is aware of IPsec, you may become curious about API compatibility across IPsec platforms.

We have RFC2367 PF_KEY API for manipulating secret key database in the kernel. Basic portion of this API is available on other UNIX-based IPsec stacks as well, and may be compatible to certain degree (for example, OpenBSD implements PF_KEY API as well). KAME IPsec stack extends this in certain way, just like other parties do. Extended portion is not compatible with other (non-KAME) IPsec stacks.

There is no document that specifies IPsec policy management API. Therefore, we can expect no compatibility with (non-KAME) IPsec stacks in IPsec policy management API.

There is no standard for configuration file syntax. You will need to convert them if you would like to copy configuration from/to non-NetBSD IPsec devices.

Since NetBSD and FreeBSD share IPsec codebase from the same origin (KAME), there is a good chance for API compatibility. Note that, however, there are differences in NetBSD IPsec code and FreeBSD IPsec code, since they merged in KAME code of different date. As of writing, normal userland applications do not need to worry about the difference. However, if you plan to implement IPsec key management daemons, you will need to worry about differences in PF_KEY API.

  • NetBSD 1.5 incorporates KAME IPsec stack of early June 2000.
  • FreeBSD 4.0-RELEASE incorporates KAME IPsec stack of early November 1999.
  • There is no difference in manual ipsec key configuration, kernel behavior on AH/ESP operation, or ipsec_set_policy(3) API.
  • There are differences in behavior of PF_KEY socket, libipsec API for PF_KEY wrapper functions and several other locations. The difference may bite you if you want to implement application that manipulates PF_KEY socket directly (i.e. IKE daemon like racoon(8) or key config program like setkey(8)).

During NetBSD-current development between NetBSD 1.4 to NetBSD 1.5, we have imported KAME IPsec portion three times. Those imports contain backward-incompatible changes in the API. Please make sure to use the latest code, if you are on NetBSD-current between 1.4 and 1.5. with NetBSD 1.5 shipped, we will provide complete binary compatibility, or API version number check, to the API present in NetBSD 1.5.

Books and other reading materials?

There are literally tons of books available.

Other links

Miscellaneous links

Back to  NetBSD Documentation: Network