This chapter describes how to configure the IP Security (IPSEC) and SETKEY protocols. IPSEC provides per-packet authenticity/confidentiality guarantees between peers that communicate using IPSEC.
IPSEC provides security for transmission of sensitive information over unprotected networks such as the Internet. IPEC acts at the network layer, protecting and authenticating IP packets between participating IPSEC devices.
IPSEC consists of a couple of separate protocols that are listed below:
Authentication Header (AH): Provides authenticity guarantee for packets, by attaching strong crypto checksums to packets. Unlike other protocols, AH covers the whole packet, from the IP header to the end of the packet.
If you receive a packet with AH and the checksum operation was successful, you can be sure about two things if you and the peer share a secret key, and no other party knows the key:
• The packet was originated by the expected peer. The packet was not generated by impersonator.
• The packet was not modified in transit.
Encapsulating Security Payload (ESP): Provides confidentiality guarantee for packets, by encrypting packets with encryption algorithms. If you receive a packet with ESP and have successfully decrypted it, you can be sure that the packet was not wiretapped in the middle, provided that you and the peer share a secret key, and no other party knows the key.
IP payload compression (IPcomp): ESP provides encryption service to the packets. However, encryption tends to give negative impact to compression on the wire (such as ppp compression). IPcomp provides a way to compress packets before encryption by ESP. (Of course, you can use IPcomp alone if you wish to).
Internet Key Exchange (IKE): An alternate form of keying is called Internet Key Exchange.
Note! Security of IPSEC protocols depends on the secrecy of secret keys. If secret keys are compromised, IPSEC protocols can no longer be secure. Take precautions about permission modes of configuration files, key database files, or whatever may lead to information leakage.
Both ESP and AH rely on security associations. A security association (SA) consists of a source, destination and an instruction. The collection of all SA’s maintained by the network kernel for a system is termed the security association database (SAD). A sample authentication SA may look like this:
add 10.0.0.11 10.0.0.216 ah 15700 -A hmac-md5 "1234567890123456";
This says "traffic going from 10.0.0.11 to 10.0.0.216 that needs an AH can be signed using HMAC-MD5 using secret 1234567890123456". This instruction is labelled with SPI ("Security Parameter Index") id "15700" (SPI’s will be covered later). SAs are symmetrical; both sides of a conversation share exactly the same SA, it is not mirrored on the other side. Note that there is no ‘autoreverse’ rule - this SA only describes a possible authentication from 10.0.0.11 to 10.0.0.216. For two-way traffic, two SAs are needed.
Following is a sample SA:
add 10.0.0.11 10.0.0.216 esp 15701 -E 3des-cbc "123456789012123456789012";
This says "traffic going from 10.0.0.11 to 10.0.0.216 that needs encryption can be encyphered using 3des-cbc with key 123456789012123456789012". The SPI id is "15701".
SAs describe possible instructions, but do not in fact describe policy as to when these need to be used. In fact, there could be an arbitrary number of nearly identical SAs with only differing SPI ids. To do actual cryptography, we need to describe a security policy (SP). This policy can include things such as "use ipsec if available" or "drop traffic unless we have ipsec". The collection of SPs for a system is termed the security policy database (SPD).
A typical simple Security Policy (SP) looks like this:
spdadd 10.0.0.216 10.0.0.11 any -P out ipsec esp/transport//require ah/transport//require;
If entered on host 10.0.0.216, this means that all traffic going out to 10.0.0.11 must be encrypted and be wrapped in an AH authenticating header. Note that this does not describe which SA is to be used, that is left as an exercise for the kernel to determine.
In other words, a Security Policy specifies what we want; a Security Association describes how we want it.
Outgoing packets are labelled with the SA SPI ("the how") which the kernel used for encryption and authentication so the remote can look up the corresponding verification and decryption instruction.
The configuration file for IPSEC is loaded by the SETKEY program. The default name and location of this file is MULTINET:IPSEC.CONF, but other filenames may be used when specifying the -f switch for SETKEY.
The configuration file describes all the Security Associations (SA) and Security Policies (SP) for the system. Lines starting with the "#" character are treated as comment lines. Configuration descriptions can be spread over multiple lines in the file. Each description must end with a semicolon.
add [-4n] src dst protocol spi [extensions] algorithm ...;
Add an SAD entry. This can fail with multiple reasons, including when the key length does not match the specified algorithm.
get [-4n] src dst protocol spi;
Show an SAD entry.
delete [-4n] src dst protocol;
Remove all SAD entries that match the specification.
deleteall [-4n] src dst protocol;
Removes all SAD entries that match the specification.
flush [protocol];
Clears all SAD entries matched by the options. -F on the command line achieves the same functionality.
dump [protocol];
Dumps all SAD entries matched by the options. -D on the command line achieves the same functionality.
spdadd [-4n] src_range dst_range upperspec policy;
Adds an SPD entry.
spdflush ;
Clears all SPD entries. -FP on the command line achieves the same functionality.
spddump ;
Dumps all SPD entries. -DP on the command line achieves the same functionality.
Arguments for the configuration file operations are as follows:
src/dst
Source/destination of the secure communication is specified as IPv4/v6 addresses. SETKEY can resolve a FQDN into numeric addresses. If the FQDN resolves into multiple addresses, SETKEY will install multiple SAD/SPD entries into the kernel by trying all possible combinations. -4 and -n restricts the address resolution of FQDN in certain ways. -4 restricts results into IPv4/v6 addresses only. -n avoids FQDN resolution and requires addresses to be numeric addresses.
Protocol (where protocol is one of the following):
• esp ESP based on RFC 2406
• esp-old ESP based on RFC 1827
• ah AH based on RFC 2402
• ah-old AH based on RFC 1826
• ipcomp IPComp
spi
Security Parameter Index (SPI) for the SAD and the SPD. spi must be a decimal number or a hexadecimal number prefixed by ‘0x’.
SPI values between 0 and 255 are reserved for future use by IANA.
Extensions
May take the following values:
-m mode
Specify a security protocol mode for use. Mode is one of the following: transport, tunnel or any. The default value is any.
-r size
Specify window size in bytes for replay prevention. size must be a decimal number in 32-bit word. If size is zero or not specified, replay checks don’t take place.
-u id
Specify the identifier of the policy entry in SPD. See policy.
-f pad_option
Defines the content of the ESP padding, and must be one of the following:
• zero-pad All of the padding are zero.
• random-pad A series of randomized values are set.
• seq-pad A series of sequential increasing numbers started from 1 are set.
-f nocyclic-seq
Don’t allow cyclic sequence number.
-ls time in seconds
Specify the soft lifetime duration of the SA.
-lh time in seconds
Specify the hard lifetime duration of the SA.
-E ealgo key
Specify an encryption algorithm for ESP.
-E ealgo key -A aalgo key
Specify an encryption algorithm ealgo, as well as a payload authentication algorithm aalgo, for ESP.
-A aalgo key
Specify an authentication algorithm for AH.
-C calgo [-R]
Specify a compression algorithm for IPComp. If -R is specified, the spi field value will be used
as the IPComp CPI (compression parameter index). If -R is not specified, the kernel
will use well-known CPI, and the spi field will be used only as an index for kernel internal
usage.
key must be a double-quoted character string, or a series of hexadecimal digits preceded by "0x".
Possible values for ealgo, aalgo, and calgo are specified in Table 31-1 and Table 31-2.
src_range
dst_range
These are selections of the secure communication specified as an IPv4/v6 address or an IPv4/v6
address range, and it may also include a TCP/UDP port specification. The addresses may take one of the following forms (an example of each is shown):
Address 192.168.0.15
Address/prefixlen 192.168.0.15/24
Address[port] 192.168.0.15[1234]
Address/prefixlen[port] 192.168.0.15/24[1234]
Note that prefixlen and port must be decimal numbers. The square brackets around port are necessary. For FQDN resolution, the rules applicable to src and dst apply here as well.
upperspec
Upper-layer protocol to be used. icmp6, ip4, and any can be specified, where any indicates "any
protocol." The protocol number may also be used.
policy
Policy is one of the following three formats:
-P direction discard protocol/mode/src-dst/level[...]
-P direction none protocol/mode/src-dst/level[...]
-P direction ipsec protocol/mode/src-dst/level[...]
• direction must be out or in.
• discard means the packet matching indexes will be discarded.
• none means that IPsec operations will not take place on the packet.
• ipsec means that IPsec operations will take place on the packet.
• protocol/mode/src-dst/level specifies the rule as to how the packet will be processed:
• protocol must be one of ah, esp or ipcomp.
• mode must be transport. Note that only transport is valid for the implementation of MultiNet, as tunneling isn’t supported.
• Both src and dst can be omitted.
level must be one of the following:
• default means the kernel consults the system-wide default against the protocol specified.
• use means that the kernel uses a SA if one is available.
• require means SA is required whenever the kernel sends a packet matched with the policy.
• unique is the same as require; in addition, it allows the policy to bind with the unique outbound
SA.
The following table shows the supported algorithms that can be used as aalgo in a -A aalgo protocol parameter:
Table 31-1 Authentication Algorithms
|
Algorithm |
Key Length in Bits |
|
hmac-md5 |
128 |
|
hmac-sha1 |
160 |
|
keyed-md5 |
128 |
|
keyed-sha1 |
160 |
|
null |
0 to 2048 |
The following table shows the supported algorithms that can be used as ealgo in a -E ealgo protocol
parameter:
Table 31-2 Encryption Algorithms
|
Algorithm |
Key Length in Bits |
|
blowfish-cbc |
40 to 448 |
|
cast128-cbc |
40 to 128 |
|
des-cbc |
64 |
|
3des-cbc |
192 |
|
des-deriv |
64 |
|
rijndael-cbc |
128/192/256 |
Only deflate may be used as calgo in a -C ealgo protocol parameter.
What follows is a very simple configuration for talking from host 10.0.0.216 to 10.0.0.11 using encryption and authentication.
On host 10.0.0.216:
add 10.0.0.216 10.0.0.11 ah 24500 -A hmac-md5 "1234567890123456";
add 10.0.0.216 10.0.0.11 esp 24501 -E 3des-cbc "12345678901212345678901222";
spdadd 10.0.0.216 10.0.0.11 any -P out ipsec esp/transport//require ah/transport//require;
On host 10.0.0.11, the same Security Associations, no Security Policy:
add 10.0.0.216 10.0.0.11 ah 24500 -A hmac-md5 "1234567890123456";
add 10.0.0.216 10.0.0.11 esp 24501 -E 3des-cbc "12345678901212345678901222";
With the above configuration in place, $ mu ping 10.0.0.11 from 10.0.0.216 looks like this using tcpdump:
22:37:52 10.0.0.216>10.0.0.11:AH(spi=0x00005fb4,seq=0xa):ESP(spi=0x00005fb5,seq=0xa)(DF)
23:37:52 10.0.0.11>10.0.0.216:icmp:echo reply
Note how the ping back from 10.0.0.11 is plainly visible. The forward ping cannot be read by tcpdump (as the packet is encrypted), but it does show the Security Parameter Index of AH and ESP, which tells 10.0.0.11 how to verify the authenticity of our packet and how to decrypt it.
A problem with the previous example is that it specifies a policy on how 10.0.0.216 should treat packets going to 10.0.0.11, and that it specifies how 10.0.0.11 should treat those packets. However it does not instruct 10.0.0.11 to discard unauthenticated or unencrypted traffic. Hence, anybody could insert spoofed and completely unencrypted data and 10.0.0.11 will accept it. To remedy the above, we need an incoming Security Policy on 10.0.0.11, as follows:
spdadd 10.0.0.216 10.0.0.11 any -P in ipsec esp/transport//require ah/transport//require;
This instructs 10.0.0.11 that any traffic coming in to it from 10.0.0.216 is required to have valid ESP and AH.
To complete this configuration, the return traffic needs to be encrypted and authenticated as well. Therefore, the following configurations will be required:
On 10.0.0.216:
flush;
spdflush;
# AH
add 10.0.0.11 10.0.0.216 ah 15700 -A hmac-md5 "1234567890123456";
add 10.0.0.11 10.0.0.11 ah 24500 -A hmac-md5 "1234567890123456";
# ESP
add 10.0.0.11 10.0.0.216 esp 15701 -E 3des-cbc "1234567890123456789012";
add 10.0.0.11 10.0.0.216 esp 24501 -E 3des-cbc "1234567890123456789012";
spdadd 10.0.0.216 10.0.0.11 any -P out ipsec esp/transport//require ah/transport//require;
spdadd 10.0.0.11 10.0.0.216 any -P in ipsec esp/transport//require ah/transport//require;
And on 10.0.0.11:
flush;
spdflush;
# AH
add 10.0.0.11 10.0.0.216 ah 15700 -A hmac-md5 "1234567890123456";
add 10.0.0.11 10.0.0.11 ah 24500 -A hmac-md5 "1234567890123456";
# ESP
add 10.0.0.11 10.0.0.216 esp 15701 -E 3des-cbc "1234567890123456789012";
add 10.0.0.11 10.0.0.216 esp 24501 -E 3des-cbc "1234567890123456789012";
spdadd 10.0.0.216 10.0.0.11 any -P out ipsec esp/transport//require ah/transport//require;
spdadd 10.0.0.11 10.0.0.216 any -P in ipsec esp/transport//require ah/transport//require;
Note that in this example, identical keys were used for both directions of traffic. However, it’s not required to use identical keys for both directions.
The configuration file for IPSEC is loaded by the SETKEY program. A foreign command must be defined to invoke SETKEY:
$ setkey :== $multinet:setkey
$ setkey [-v] -f filename
$ setkey ["-aPlv"] "-D"
$ setkey ["-Pv"] "-F"
$ setkey [-h] -x
The possible command options for SETKEY are:
|
-D |
Dump the SAD entries. If with -P, the SPD entries are dumped.If with -a, the dead SAD entries will be displayed as well. |
|
-f filename |
Read the configuration commands from the specified file. |
|
-F |
Flush the SAD entries. If with -P, the SPD entries are flushed. |
|
-a |
A dead SAD entry means that it has been expired but remains in the system because it is referenced by some SPD entries. |
|
-h |
Add hexadecimal dump on -x mode. |
|
-l |
Loop forever with short output on -D. |
|
-v |
Be verbose. The program will dump messages exchanged on PF_KEY socket, including messages sent from other processes to the kernel. |
|
-x |
Loop forever and dump all the messages transmitted to PF_KEY socket. |
Example 1: Parse and load the policies in the file MULTINET:IPSEC.CONF into the kernel (note that the output from parsing can be quite verbose, so part of the output has been deleted from the middle this example to keep it to a reasonable size):
$ setkey "-f" multinet:ipsec.conf
Starting parse
Entering state 0
Reducing via rule 1 (line 126), -> commands
state stack now 0
Entering state 1
Reading a token: Next token is 261 (ADD)
Shifting token 261 (ADD), Entering state 2
Reducing via rule 57 (line 537), -> ipaddropts
state stack now 0 1 2
entering state 23
Reading a token: Next token is 292 (STRING)
Shifting token 292 (STRING), Entering state 36
Reducing via rule 61 (line 568), STRING -> ipaddr
state stack now 0 1 2 23
Entering state 39
...
Entering state 19
Reducing via rule 9 (line 141),spdadd_command -> command
state stack now 0 1
Entering state 12
Reducing via rule 2 (line 127), commands command -> commands
state stack now 0
Entering state 1
Reading a token: Now at end of input.
Shifting token 0 ($), Entering state 137
Now at end of input.
Example 2: Dump out the policies in the kernel:
$ setkey "-PD"
192.168.154.10/24[any] 192.168.228.100/24[any]any
out ipsec
esp/transport//use
ah/transport//use
spid=1 seq=0 pid=149
refcnt=1
Example 3: Dump out the SAD entries in the kernel:
$ setkey "-D"
192.168.228.100 192.168.154.10
ah mode=any spi=1000(0x00002711)reqid=0(0x00000000)
A:hmac -sha1 6d6f6761 6d6f6761 6d6f6761 6d6f6761
replay=0 flags=0x00000040 state=mature seq=3 pid=149
created: Dec 22 15:52:49 2003 current: Dec 22 15:54:30 2003
diff: 101(s) hard:0(s) soft:0(s)
last: hard:0(s) soft:0(s)
current:0(bytes) hard:0(bytes) soft:0(bytes)
allocated:0 hard:0 soft:0
refcnt=1
192.168.154.10.192 168.228.100
ah mode=any spi=9877(0x00002695)reqid=0(0x00000000)
A:hmac -sha1 686f6765 686f6765 686f6765 686f6765
replay=0 flags=0x00000040 state=mature seq=2 pid=149
created: Dec 22 15:52:49 2003 current: Dec 22 15:54:30 2003
diff: 101(s) hard:0(s) soft:0(s)
last: hard:0(s) soft:0(s)
current:0(bytes) hard:0(bytes) soft:0(bytes)
allocated:0 hard:0 soft:0
refcnt=1
192.168.228.100.192 168.154.10
ah mode=transport spi=10000(0x00002710)reqid=0(0x00000000)
E:3des-cbc deadbeef deadbeef deadbeef deadbeef deadbeef
replay=0 flags=0x00000040 state=mature seq=1 pid=149
created: Dec 22 15:52:49 2003 current: Dec 22 15:54:30 2003
diff: 101(s) hard:0(s) soft:0(s)
last: hard:0(s) soft:0(s)
current:0(bytes) hard:0(bytes) soft:0(bytes)
allocated:0 hard:0 soft:0
refcnt=1
192.168.154.10 192.168.228.100
ah mode=transport spi=9876(0x00002694)reqid=0(0x00000000)
E:3des-cbc 686f6765 686f6765 686f6765 686f6765 686f6765
replay=0 flags=0x00000040 state=mature seq=0 pid=149
created: Dec 22 15:52:49 2003 current: Dec 22 15:54:30 2003
diff: 101(s) hard:0(s) soft:0(s)
last: hard:0(s) soft:0(s)
current:0(bytes) hard:0(bytes) soft:0(bytes)
allocated:0 hard:0 soft:0
refcnt=1
Example 4: Dump the messages out on the PF_KEY socket.
$ setkey "-hx"
14:38:47.009961
00000000:02 0b 00 00 06 00 00 00 00 00 00 00 00 00 00 00
0000000010:02 0b 00 01 02 00 00 00 00 00 00 95 00 00 00
sadb_msg { version=2 type=1 1 errno=0 satype=1
len=2 reserved=0 seq=0 pid=149
14:38:47 057809
00000000:02 0b 00 01 02 00 00 00 00 00 00 00 95 00 00 00
Example 5: Flush all of the entries from the kernel.
$ setkey "-F"
$ setkey "-D"
No SAD entries.
If you want to run host-to-host (transport mode) encryption with manually configured secret keys, the following configuration should be sufficient:
# multinet:ipsec.conf
#
# packet will look like this: IPv4 ESP payload
# the node is on 10.1.1.1, peer is on 20.1.1.1
add 10.1.1.1 10.2.1.1 esp 9876 -E 3des-cbc "hogehogehogehogehogehoge";
add 10.2.1.1 10.1.1.1 esp 10000 -E 3des-cbc
0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef;
spdadd 10.1.1.1 10.2.1.1 any -P out ipsec esp/transport//use;
From 10.1.1.1 to 10.2.1.1, use the 3DES-CBC algorithm with SPI 9876, with secret key "hogehogehogehhogehogehoge".The traffic will be identified by SPI 9876.
From 10.2.1.1 to 10.1.1.1, use 3DES-CBC algorithm with SPI 10000, with secret key
0xdeadbeefdeadbeefdeadbeefdeadbeef.
The last line configures per-packet IPSEC policy for the node. Using this configuration, the transmit node (10.1.1.1) used to send packets to the peer (20.1.1.1), is encrypted whenever a secret key is configured in to the kernel. The configuration does not prohibit unencrypted packets from 20.1.1.1 to reach 10.1.1.1. To reject unencrypted packets, the following line would be added to the configuration file:
spdadd 10.2.1.1 10.1.1.1 any -P in ipsec esp/transport//require;
On the peer’s node (10.2.1.1), the configuration will look similar to what is shown in the following example. Note that the addresses need to be swapped on the "spdadd" line, but "add" lines do not need to be swapped.
# multinet:ipsec.conf
#
# packet will look like this: IPv4 ESP payload
# the node is on 10.2.1.1, peer is on 10.1.1.1
add 10.1.1.1 10.2.1.1 esp 9876 -E 3des-cbc "hogehogehogehogehogehoge";
add 10.2.1.1 10.1.1.1 esp 10000 -E 3des-cbc
0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef
spdadd 10.2.1.1 10.1.1.1 any -P out ipsec esp/transport//use;
The previous example uses human-readable secret keys. However, using human-readable secret keys is discouraged by the IPSEC policy specification, since they are more likely to be compromised than binary keys. Binary keys should be used for normal operations.
Key length is determined by algorithms. See Tables 31-1 and 31-2 for the required key lengths. For 3des-cbc, the secret key must be 192 bits (24 bytes). If a shorter or longer key is specified, SETKEY will return an error when parsing the line.
The following is an example of rijndael-cbc (also known as AES) using 128-bit keys.
# multinet:ipsec.conf
#
# the packet will look like this: IPv4 ESP payload
# the node is on 10.1.1.1, peer is on 10.2.1.1
# rijndael -cbc with 128bit key
add 10.1.1.1 10.2.1.1 esp 9876 -E rijndael -cbc "hogehogehogehoge";
add 10.2.1.1 10.1.1.1 esp 10000 -E rijndael -cbc
0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef;
spdadd 10.1.1.1 10.2.1.1 any -P out ipsec esp/transport//use;
The following example shows a sample configuration for host-to-host authentication:
# multinet:ipsec.conf
#
# packet will look like this: IPv4 AH payload
# the node is on 10.1.1.1, peer is on 10.2.1.1
add 10.1.1.1 10.2.1.1 ah 9877 -A hmac-md5 "hogehogehogehoge";
add 10.2.1.1 10.1.1.1 ah 10001 -A hmac-md5 "mogamogamogamoga";
spdadd 10.1.1.1 10.2.1.1 any -P out ipsec ah/transport//use;
The following example shows sample keys that are configured for both AH and ESP.
Note! It is recommended that you apply AH after ESP.
# multinet:ipsec.conf
#
# packet will look like this: IPv4 AH ESP payload
# the node is on 10.1.1.1, peer is on 10.2.1.1
add 10.1.1.1 10.2.1.1 esp 9876 -E 3des-cbc "hogehogehogehogehogehoge";
add 10.2.1.1 10.1.1.1 esp 10000 -E 3des-cbc
0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef;
add 10.1.1.1 10.2.1.1 ah 9877 -A hmac-md5 "mogamogamogamoga";
spdadd 10.1.1.1 10.2.1.1 any -P out ipsec esp/transport//use
ah/transport//use;
The MultiNet 5.2 IPSEC implementation conforms to the latest set of IPSEC standards.
The RACOON service performs the task of securely creating security associations for participating systems. When a security policy senses the need of a security association, RACOON is notified and securely communicates with an Internet Key Exchange daemon on the other system to establish the security association. Security Policies must still be configured manually with the SETKEY program.
The RACOON service can be controlled through the following MULTINET NETCONTROL commands:
• DEBUG - set the debug level for a currently running Racoon IKE daemon.
• ESTABLISH remote-ip-address [local-ip-address] – initiate key exchange protocol communication between the remote ip-address and the local ip-address. If local-ip-address is not specified then the value of MULTINET_HOST_NAME is used. This does not install Security Associations, but does the initial negotiation necessary to allow Security Associations to be established when necessary. It is not necessary to manually establish the negotiation information – RACOON will do it automatically when necessary.
• FLUSH – flush all existing keys
• NOOP - No Operation
• SHOW – show existing key associations
• SHUTDOWN – Shutdown the Racoon IKE Daemon. All established keys are flushed as part of this process.
• START – Start the Racoon IKE Daemon
• STOP – Same as SHUTDOWN
• VERSION – Display control interface version
The configuration file (MULTINET:RACOON.CONF) can be configured to handle all systems in general, or specific systems.
RACOON negotiates security associations for itself (ISAKMP SA, or phase 1 SA) and for kernel IPsec (IPsec SA, or phase 2 SA). The file consists of a sequence of directives and statements. Each directive is composed by a tag, and statements are enclosed by ‘{‘ and ‘}’. Lines beginning with ‘#’ are comments.
Keywords and special characters that the parser expects exactly are displayed using this font. Parameters are specified with this font. Square brackets ‘[‘ and ‘]’ are used to show optional keywords and parameters. Note that you have to pay attention when this manual is describing port numbers. The port number is always enclosed by ‘[‘ and ‘]’. In this case, the port number is not an optional keyword. If it is possible to omit port number, the expression becomes [[port]]. The vertical bar (‘|’) is used to indicate a choice between optional parameters. Parentheses ‘(‘ and ‘)’ are used to group keywords and parameters when necessary. Major parameters are listed below.
Number means a hexadecimal or a decimal number. The former must be prefixed with `0x'.
string path file means any string enclosed in ‘"‘ (double quote).
Address means IPv4 address.
Port means a TCP/UDP port number. The port number is always enclosed by ‘[‘ and ‘]’.
Timeunit is one of following: sec, secs, second, seconds, min, mins, minute, minutes, hour, hours.
Path Specification
path include path;
specifies a path to include a file. See File Inclusion.
path pre_shared_key file;
specifies a file containing pre-shared key(s) for various ID(s). See Pre-shared key File.
path certificate path;
racoon will search this directory if a certificate or certificate request is received.
path backupsa file;
specifies a file to be stored a SA information which is negotiated by racoon. racoon will install SA(s) from the file with a boot option -B. The file is increasing because racoon simply adds a SA to the file at the moment. You should maintain the file manually.
File Inclusion
include file
other configuration files can be included.
Timer Specification
timer { statements }
specifies various timer values.
counter number;
the maximum number of retries to send. The default is 5.
interval number timeunit;
the interval to resend, in seconds. The default time is 10 seconds.
persend number;
the number of packets per send. The default is 1.
phase1 number timeunit;
the maximum time it should take to complete phase 1. The default time is 15 seconds.
phase2 number timeuni;
the maximum time it should take to complete phase 2. The default time is 10 seconds.
Listening Port Specification
listen { statements }
If no listen directive is specified, racoon will listen on all of the available interface addresses. The following is the list of valid statements:
isakmp address [[port]];
If this is specified, racoon will only listen on address. The default port is 500, which is specified by IANA. You can provide more than one address definition.
strict_address;
require that all addresses for ISAKMP must be bound. This statement will be ignored if you do not specify any addresses.
Remote Nodes Specifications
remote (address | anonymous) [[port]] { statements }
specifies the parameters for IKE phase 1 for each remote node. The default port is 500. If anonymous is specified, the statements apply to all peers which do not match any other remote directive.
The following are valid statements:
exchange_mode (main | aggressive | base);
defines the exchange mode for phase 1 when racoon is the initiator. Also it means the acceptable exchange mode when racoon is responder. More than one mode can be specified by separating them with a comma. All of the modes are acceptable. The first exchange mode is what racoon uses when it is the initiator.
doi ipsec_doi;
means to use IPSEC-DOI as specified RFC 2407. You can omit this statement.
situation identity_only;
means to use SIT_IDENTITY_ONLY as specified RFC 2407. You can omit this statement.
my_identifier idtype ...;
specifies the identifier sent to the remote host and the type to use in the phase 1 negotiation. address, fqdn, user_fqdn, keyid and asn1dn can be used as an idtype. they are used like:
my_identifier address [address];
the type is the IP address. This is the default type if you do not specify an identifier to use.
my_identifier user_fqdn string;
the type is a USER_FQDN (user fully-qualified domain name).
my_identifier fqdn string;
the type is a FQDN (fully-qualified domain name).
my_identifier keyid file;
the type is a KEY_ID. my_identifier asn1dn [string]; the type is an ASN.1 distinguished name. If string is omitted, racoon will get DN from Subject field in the certificate.
peers_identifier idtype ...;
specifies the peer's identifier to be received. If it is not defined then racoon will not verify the peer's identifier in ID payload transmitted from the peer. If it is defined, the behavior of the verification depends on the flag of verify_identifier. The usage of idtype is same to my_identifier.
verify_identifier (on | off);
If you want to verify the peer's identifier, set this to on. In this case, if the value defined by peers_identifier is not same to the peer's identifier in the ID payload, the negotiation will failed. The default is off.
certificate_type certspec;
specifies a certificate specification. certspec is one of followings:
x509 certfile privkeyfile;
certfile means a file name of certificate. privkeyfile means a file name of secret key.
peers_certfile (dnssec | certfile);
If dnssec is defined, racoon will ignore the CERT pay- load from the peer, and try to get the peer's certificate from DNS instead. If certfile is defined, racoon will ignore the CERT payload from the peer, and will use this certificate as the peer's certificate.
send_cert (on | off);
If you do not want to send a certificate for some reason, set this to off. The default is on.
send_cr (on | off);
If you do not want to send a certificate request for some reason, set this to off. The default is on.
verify_cert (on | off);
If you do not want to verify the peer's certificate for some reason, set this to off. The default is on.
lifetime time number timeunit;
define a lifetime of a certain time which will be proposed in the phase 1 negotiations. Any proposal will be accepted, and the attribute(s) will be not proposed to the peer if you do not specify it(them). They can be individually specified in each proposal.
initial_contact (on | off);
enable this to send an INITIAL-CONTACT message. The default value is on. This message is useful only when the implementation of the responder choices an old SA when there are multiple SAs which are different established time, and the initiator reboots. If racoon did not use the message, the responder would use an old SA even when a new SA was established. The KAME stack has the switch in the system wide value, net.key.preferred_oldsa. when the value is zero, the stack always use a new SA.
passive (on | off);
If you do not want to initiate the negotiation, set this to on. The default value is off. It is useful for a server.
proposal_check level;
specifies the action of lifetime length and PFS of the phase 2 selection on the responder side. The default level is strict. If the level is:
• obey the responder will obey the initiator anytime.
• Strict If the responder's length is longer than the initiator's one, the responder uses the initiator's one. Otherwise it rejects the proposal. If PFS is not required by the responder, the responder will obey the proposal. If PFS is required by both sides and if the responder's group is not equal to the initiator's one, then the responder will reject the proposal.
• Claim If the responder's length is longer than the initiator's one, the responder will use the initiator's one. If the responder's length is shorter than the initiator's one, the responder uses its own length AND sends a RESPONDER-LIFETIME notify message to an initiator in the case of lifetime. About PFS, this directive is same as strict.
• exact If the initiator's length is not equal to the responder's one, the responder will reject the proposal. If PFS is required by both sides and if the responder's group is not equal to the initiator's one, then the responder will reject the proposal.
support_mip6 (on | off);
If this value is set on then both values of ID payloads in phase 2 exchange are always used as the addresses of end-point of IPsec-SAs. The default is off.
generate_policy (on | off);
This directive is for the responder. Therefore you should set passive on in order that racoon only becomes a responder. If the responder does not have any policy in SPD during phase 2 negotiation, and the directive is set on, then racoon will choice the first proposal in the SA payload from the initiator, and generate policy entries from the proposal. It is useful to negotiate with the client which is allocated IP address dynamically. Note that inappropriate policy might be installed by the initiator because the responder just installs policies as the initiator proposes. So that other communication might fail if such policies installed. This directive is ignored in the initiator case. The default value is off.
nonce_size number;
define the byte size of nonce value. Racoon can send any value although RFC2409 specifies that the value MUST be between 8 and 256 bytes. The default size is 16 bytes.
proposal { sub-substatements }
encryption_algorithm algorithm;
specify the encryption algorithm used for the phase 1 negotiation. This directive must be defined. algorithm is one of following: des, 3des, blowfish, cast128 for Oakley. For other transforms, this statement should not be used.
hash_algorithm algorithm;
define the hash algorithm used for the phase 1 negotiation. This directive must be defined. algorithm is one of following: md5, sha1 for Oakley.
authentication_method type;
defines the authentication method used for the phase 1 negotiation. This directive must be defined. type is one of: pre_shared_key, rsasig, gssapi_krb.
dh_group group;
define the group used for the Diffie-Hellman exponentiations. This directive must be defined. group is one of following: modp768, modp1024, modp1536. Or you can define 1, 2, or 5 as the DH group number. When you want to use aggressive mode, you must define same DH group in each proposal.
lifetime time number timeunit;
define lifetime of the phase 1 SA proposal. Refer to the description of lifetime directive immediately defined in remote directive.
gssapi_id string;
define the GSS-API endpoint name, to be included as an attribute in the SA, if the gssapi_krb authentication method is used. If this is not defined, the default value of `ike/hostname' is used, where hostname is the FQDN of the interface being used.
Policy Specifications
The policy directive is obsolete, policies are now in the SPD. racoon will obey the policy configured into the kernel by setkey, and will construct phase 2 proposals by combining sainfo specifications in racoon.conf, and policies in the kernel.
Sainfo Specifications
sainfo (source_id destination_id | anonymous) { statements }
defines the parameters of the IKE phase 2 (IPsec-SA establishment). source_id and destination_id are constructed like:
address address [/ prefix] [[port]] ul_proto
or
idtype string
It means exactly the content of ID payload. This is not like a filter rule. For example, if you define 3ffe:501:4819::/48 as source_id. 3ffe:501:4819:1000:/64 will not match.
pfs_group group;
define the group of Diffie-Hellman exponentiations. If you do not require PFS then you can omit this directive. Any proposal will be accepted if you do not specify one. group is one of following: modp768, modp1024, modp1536. Or you can define 1, 2, or 5 as the DH group number.
lifetime time number timeunit;
define the lifetime of amount of time which are to be used IPsec-SA. Any proposal will be accepted, and no attribute(s) will be proposed to the peer if you do not specify it(them). See the proposal_check directive.
racoon does not have the list of security protocols to be negotiated. The list of security protocols are passed by SPD in the kernel. Therefore you have to define all of the potential algorithms in the phase 2 proposals even if there is a algorithm which will not be used. These algorithms are define by using the following three directives, and they are lined with single comma as the separator. For algorithms that can take variable-length keys, algorithm names can be followed by a key length, like ``blowfish 448''. racoon will compute the actual phase 2 proposals by computing the permutation of the specified algorithms, and then combining them with the security protocol specified by the SPD. For example, if des, 3des, hmac_md5, and hmac_sha1 are specified as algorithms, we have four combinations for use with ESP, and two for AH. Then, based on the SPD settings, racoon will construct the actual proposals. If the SPD entry asks for ESP only, there will be 4 proposals. If it asks for both AH and ESP, there will be 8 proposals. Note that the kernel may not support the algorithm you have specified.
encryption_algorithm algorithms;
des, 3des, des_iv64, des_iv32, rc5, rc4, idea, 3idea, cast128, blowfish, null_enc, twofish, rijndael (used with ESP)
authentication_algorithm algorithms;
des, 3des, des_iv64, des_iv32, hmac_md5, hmac_sha1, non_auth (used with ESP authentication and AH)
compression_algorithm algorithms;
deflate (used with IPComp)
Logging level
log level;
define logging level. level is one of following: notify, debug and debug2. The default is notify. If you put too high logging level on slower machines, IKE negotiation can fail due to timing constraint changes.
Specifying the way to pad
padding { statements }
specified padding format. The following are valid statements:
randomize (on | off);
enable using a randomized value for padding. The default is on.
randomize_length (on | off);
the pad length is random. The default is off.
maximum_length number;
define a maximum padding length. If randomize_length is off, this is ignored. The default is 20 bytes.
exclusive_tail (on | off);
means to put the number of pad bytes minus one into last part of the padding. The default is on.
strict_check (on | off);
means to be constrained the peer to set the number of pad bytes. The default is off.
Special directives
complex_bundle (on | off);
defines the interpretation of proposal in the case of SA bundle. Normally ``IP AH ESP IP payload'' is proposed as ``AH tunnel and ESP tunnel''. The interpretation is more common to other IKE implementations, however, it allows very limited set of combinations for proposals. With the option enabled, it will be pro- posed as ``AH transport and ESP tunnel''. The default value is off.
Pre-shared key File
Pre-shared key file defines a pair of the identifier and the shared secret key which are used at Pre-shared key authentication method in phase 1. The pair in each lines are separated by some number of blanks and/or tab characters like hosts(5). Key can be included any blanks because all of the words after 2nd column are interpreted as a secret key. Lines start with `#' are ignored. Keys which start with `0x' are hexadecimal strings. Note that the file must be owned by the user ID running racoon (usually the privileged user), and must not be accessible by others.
#
# Basic Racoon configuration file
#
path pre_shared_key "multinet:psk.txt" ;
remote anonymous
{
exchange_mode aggressive, main, base ;
lifetime time 24 hour ;
proposal {
encryption_algorithm blowfish 448;
hash_algorithm md5; #sha1;
authentication_method pre_shared_key ;
dh_group 5 ;
}
}
sainfo anonymous
{
pfs_group 2;
lifetime time 12 hour ;
encryption_algorithm blowfish 448;
authentication_algorithm hmac_sha1, hmac_md5 ;
compression_algorithm deflate ;
}
192.168.1.2 deadbeef
192.168.1.3 deadbeef
192.168.1.4 deadbeef
192.168.1.5 face0ff0
The following restrictions exist regarding the use of IPSEC in MultiNet V5.2. These restrictions may be lifted in future releases of MultiNet.
• Security may not be set on a socket-by-socket basis via the use of setsockopt().
• Only transport mode is supported to both AH and ESP. Tunnel mode (primarily used for VPN’s) is not supported in any mode (AH or ESP).
• IPcomp is not currently implemented.
