racoon.conf(5) - Linux man page
Name
racoon.conf - configuration file for racoon
Description
racoon.conf is the configuration file for the racoon(8) ISAKMP daemon. racoon(8) 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, enclosed by '{' and '}'. Lines beginning with '#' are comments.
Meta Syntax
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 andparameters. Note that you have to pay attention when this manual isdescribing port numbers. The port number is always enclosed by '[' and']'. In this case, the port number is not an optional keyword. If it ispossible to omit the port number, the expression becomes [[port]]. Thevertical bar ('|') is used to indicate a choice between optionalparameters. Parentheses ( '(' and ')') are used to group keywords andparameters when necessary. Major parameters are listed below.
number' means a hexadecimal or a decimal number. The formermust be prefixed with '0x'. string' path' file' means any string enclosed in '"' (double quotes). address means IPv6 and/or IPv4 address. port' means a TCP/UDP port number. The port number is alwaysenclosed by '[' and ']'. timeunit is one of following: sec, secs, second, seconds, min, mins,minute, minutes, hour, hours.
Privilege separation privsep { statements } specifies privilege separation parameters. When enabled, theseenable racoon(8) to operate with an unprivileged instance doingmost of the work, while a privileged instance takes care ofperforming the following operations as root: reading PSK andprivate keys, launching hook scripts, and validating passwordsagainst system databases or against PAM.
user user; The user to which the unprivileged instance of racoon(8),should switch. This can be a quoted user name or anumeric UID. group group; The group to which the unprivileged instance ofracoon(8), should switch. This can be a quoted groupname or a numeric GID. chroot path; A directory to which the unprivileged instance ofracoon(8) should chroot(2). This directory should hold atree where the following files must be reachable: /dev/random /dev/urandom the certificates the file containing the Xauth banner
The PSK file, the private keys, and the hook scripts areaccessed through the privileged instance of racoon(8) anddo not need to be reachable in the chroot(2)'ed tree.
Path Specification This section specify various paths used by racoon. When running inprivilege separation mode, certificate and script paths are mandatory. 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(8) will search this directory if a certificate orcertificate request is received. If you run with privilegeseparation, racoon(8) will refuse to use a certificate storedoutside of this directory. path backupsa file; specifies a file to which SA information which is negotiated byracoon should be stored. racoon(8) will install SA(s) from thefile when started with the -B flag. The file is growing becauseracoon(8) simply adds SAs to it. You should maintain the filemanually. path script path; racoon(8) will search this directory for scripts hooks. If yourun with privilege separation, racoon(8) will refuse to execute ascript stored outside of this directory. path pidfile file; specifies file where to store PID of process. If path startswith / it is treated as an absolute path, otherwise relative toVARRUN directory specified at compilation time. Default isracoon.pid.
File Inclusion include file other configuration files can be included.
Identifier Specification is obsolete. It must be defined at each remote directive.
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 is10 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. Thedefault time is 15 seconds. phase2 number timeunit; the maximum time it should take to complete phase 2. Thedefault time is 10 seconds. natt_keepalive number timeunit; interval between sending NAT-Traversal keep-alivepackets. The default time is 20 seconds. Set to 0s todisable keep-alive packets.
Listening Port Specification listen { statements } If no listen directive is specified, racoon(8) will listen on allavailable interface addresses. The following is the list ofvalid statements:
isakmp address [[port]]; If this is specified, racoon(8) will only listen onaddress. The default port is 500, which is specified byIANA. You can provide more than one address definition. isakmp_natt address [port]; Same as isakmp but also sets the socket options to acceptUDP-encapsulated ESP traffic for NAT-Traversal. If youplan to use NAT-T, you should provide at least oneaddress with port 4500, which is specified by IANA.There is no default. strict_address; require that all addresses for ISAKMP must be bound.This statement will be ignored if you do not specify anyaddress. The listen section can also be used to specify the admin socketmode and ownership, if racoon was built with support for adminport. adminsock path [owner group mode]; path, owner, and group are the socket path, owner, andgroup; they must be quoted. Defaults are/var/racoon/racoon.sock, UID 0, and GID 0. mode is theaccess mode in octal, default is 0600. adminsock disabled; This directive tells racoon to not listen on the adminsocket.
Miscellaneous Global Parameters gss_id_enc enctype; Older versions of racoon(8) used ISO-Latin-1 as the encoding ofthe GSS-API identifier attribute. For interoperability withMicrosoft Windows' GSS-API authentication scheme, the defaultencoding has been changed to UTF-16LE. The gss_id_enc parameterallows racoon(8) to be configured to use the old encoding forcompatibility with existing racoon(8) installations. Thefollowing are valid values for enctype:
utf-16le Use UTF-16LE to encode the GSS-API identifier attribute.This is the default encoding. This encoding iscompatible with Microsoft Windows. latin1 Use ISO-Latin-1 to encode the GSS-API identifierattribute. This is the encoding used by older versionsof racoon(8).
pfkey_buffer kBytes Specifies the soket send/receive buffer size in kilobytes.Numerous kernel PF_KEY implementations have problems with dumpingSAD/SDP with large amount of entries (this happens when 100s to1000s of tunnels are configured).
The default value of 0 leaves everything at the OS-specificdefault value. If the default buffer size is greater than whatis specified here racoon will not decrease it.
This problem is known to be fixed in Linux 2.6.25 and later.
Remote Nodes Specifications remote (address | anonymous) [[port]] [inherit parent] { statements } specifies the parameters for IKE phase 1 for each remote node.The default port is 500. If anonymous is specified, thestatements apply to all peers which do not match any other remotedirective.
Sections with inherit parent statements (where parent is eitheraddress or a keyword anonymous) have all values predefined tothose of a given parent. In these sections it is enough toredefine only the changed parameters.
The following are valid statements.
exchange_mode (main | aggressive | base); defines the exchange mode for phase 1 when racoon is theinitiator. It also means the acceptable exchange modewhen racoon is responder. More than one mode can bespecified by separating them with a comma. All of themodes are acceptable. The first exchange mode is whatracoon uses when it is the initiator. doi ipsec_doi; means to use IPsec DOI as specified in RFC 2407. You canomit this statement. situation identity_only; means to use SIT_IDENTITY_ONLY as specified in RFC 2407.You can omit this statement. identifier idtype; is obsolete. Instead, use my_identifier. my_identifier idtype ...; specifies the identifier sent to the remote host and thetype to use in the phase 1 negotiation. address, fqdn,user_fqdn, keyid, and asn1dn can be used as an idtype.Use them in the following way: my_identifier address [address]; the type is the IP address. This is the defaulttype if you do not specify an identifier to use. my_identifier user_fqdn string; the type is a USER_FQDN (user fully-qualifieddomain 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. Ifstring is omitted, racoon(8) will get the DN fromthe Subject field in the certificate. xauth_login [string]; specifies the login to use in client-side Hybridauthentication. It is available only if racoon(8) hasbeen built with this option. The associated password islooked up in the pre-shared key files, using the loginstring as the key id. peers_identifier idtype ...; specifies the peer's identifier to be received. If it isnot defined then racoon(8) will not verify the peer'sidentifier in ID payload transmitted from the peer. Ifit is defined, the behavior of the verification dependson the flag of verify_identifier. The usage of idtype isthe same as my_identifier except that the individualcomponent values of an asn1dn identifier may specified as* to match any value (e.g. "C=XX, O=MyOrg, OU=*,CN=Mine"). Alternative acceptable peer identifiers maybe specified by repeating the peers_identifier statement. verify_identifier (on | off); If you want to verify the peer's identifier, set this toon. In this case, if the value defined bypeers_identifier is not the same as the peer's identifierin the ID payload, the negotiation will failed. Thedefault is off. certificate_type certspec; specifies a certificate specification. certspec is oneof followings: x509 certfile privkeyfile; certfile means a file name of a certificate.privkeyfile means a file name of a secret key. ca_type cacertspec; specifies a root certificate authority specification.cacertspec is one of followings: x509 cacertfile; cacertfile means a file name of the rootcertificate authority. Default is/etc/openssl/cert.pem mode_cfg (on | off); Gather network information through ISAKMP modeconfiguration. Default is off. peers_certfile (dnssec | certfile); If dnssec is defined, racoon(8) will ignore the CERTpayload from the peer, and try to get the peer'scertificate from DNS instead. If certfile is defined,racoon(8) will ignore the CERT payload from the peer, andwill use this certificate as the peer's certificate. script script phase1_up script script phase1_down Shell scripts that get executed when a phase 1 SA goes upor down. Both scripts get either phase1_up orphase1_down as first argument, and the followingvariables are set in their environment: LOCAL_ADDR The local address of the phase 1 SA. LOCAL_PORT The local port used for IKE for the phase 1 SA. REMOTE_ADDR The remote address of the phase 1 SA. REMOTE_PORT The remote port used for IKE for the phase 1 SA. The following variables are only set if mode_cfg wasenabled: INTERNAL_ADDR4 An IPv4 internal address obtained by ISAKMP modeconfig. INTERNAL_NETMASK4 An IPv4 internal netmask obtained by ISAKMP modeconfig. INTERNAL_DNS4 Internal DNS server IPv4 address obtained byISAKMP mode config. INTERNAL_NBNS4 Internal WINS server IPv4 address obtained byISAKMP mode config. 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 somereason, set this to off. The default is on. verify_cert (on | off); If you do not want to verify the peer's certificate forsome reason, set this to off. The default is on. lifetime time number timeunit; Define a lifetime of a certain time which will beproposed in the phase 1 negotiations. Any proposal willbe accepted, and the attribute(s) will be not proposed tothe peer if you do not specify it (them). They can beindividually specified in each proposal. ike_frag (on | off); Enable receiver-side IKE fragmentation, if racoon(8) hasbeen built with this feature. This extension is there towork around broken firewalls that do not work withfragmented UDP packets. IKE fragmentation is alwaysenabled on the sender-side, and it is used if the peeradvertises itself as IKE fragmentation capable. esp_frag fraglen; This option is only relevant if you use NAT traversal intunnel mode. Its purpose is to work around broken DSLrouters that reject UDP fragments, by fragmenting the IPpackets before ESP encapsulation. The result is ESP overUDP of fragmented packets instead of fragmented ESP overUDP packets (i.e., IP:UDP:ESP:frag(IP) instead offrag(IP:UDP:ESP:IP)). fraglen is the maximum size of thefragments. 552 should work anywhere, but the higherfraglen is, the better is the performance.
Note that because PMTU discovery is broken on many sites,you will have to use MSS clamping if you want TCP to workcorrectly. initial_contact (on | off); enable this to send an INITIAL-CONTACT message. Thedefault value is on. This message is useful only whenthe implementation of the responder chooses an old SAwhen there are multiple SAs with different establishedtime, and the initiator reboots. If racoon did not sendthe message, the responder would use an old SA even whena new SA was established. The KAME stack has the switchin the system wide value net.key.preferred_oldsa. whenthe value is zero, the stack always uses a new SA. passive (on | off); If you do not want to initiate the negotiation, set thisto on. The default value is off. It is useful for aserver. proposal_check level; specifies the action of lifetime length and PFS of thephase 2 selection on the responder side, and the actionof lifetime check in phase 1. The default level isstrict. If the level is: obey' the responder will obey the initiatoranytime. strict If the responder's length is longer than theinitiator's one, the responder uses theinitiator's one. Otherwise it rejects theproposal. If PFS is not required by theresponder, the responder will obey the proposal.If PFS is required by both sides and if theresponder's group is not equal to the initiator'sone, then the responder will reject the proposal. claim If the responder's length is longer than theinitiator's one, the responder will use theinitiator's one. If the responder's length isshorter than the initiator's one, the responderuses its own length AND sends aRESPONDER-LIFETIME notify message to an initiatorin the case of lifetime (phase 2 only). For PFS,this directive behaves the same as strict. exact If the initiator's length is not equal to theresponder's one, the responder will reject theproposal. If PFS is required by both sides andif the responder's group is not equal to theinitiator's one, then the responder will rejectthe proposal. support_proxy (on | off); If this value is set to on, then both values of IDpayloads in the phase 2 exchange are always used as theaddresses of end-point of IPsec-SAs. The default is off. generate_policy (on | off); This directive is for the responder. Therefore youshould set passive to on in order that racoon(8) onlybecomes a responder. If the responder does not have anypolicy in SPD during phase 2 negotiation, and thedirective is set to on, then racoon(8) will choose thefirst proposal in the SA payload from the initiator, andgenerate policy entries from the proposal. It is usefulto negotiate with clients whose IP address is allocateddynamically. Note that an inappropriate policy might beinstalled into the responder's SPD by the initiator, soother communications might fail if such policies areinstalled due to a policy mismatch between the initiatorand the responder. This directive is ignored in theinitiator case. The default value is off. nat_traversal (on | off | force); This directive enables use of the NAT-Traversal IPsecextension (NAT-T). NAT-T allows one or both peers toreside behind a NAT gateway (i.e., doing address- orport-translation). Presence of NAT gateways along thepath is discovered during phase 1 handshake and if found,NAT-T is negotiated. When NAT-T is in charge, all ESPand AH packets of a given connection are encapsulatedinto UDP datagrams (port 4500, by default). Possiblevalues are: on' NAT-T is used when a NAT gateway is detectedbetween the peers. off' NAT-T is not proposed/accepted. This is thedefault. force NAT-T is used regardless if a NAT is detectedbetween the peers or not. Please note that NAT-T support is a compile-time option.Although it is enabled in the source distribution bydefault, it may not be available in your particularbuild. In that case you will get a warning when usingany NAT-T related config options. dpd_delay delay; This option activates the DPD and sets the time (inseconds) allowed between 2 proof of liveness requests.The default value is 0, which disables DPD monitoring,but still negotiates DPD support. dpd_retry delay; If dpd_delay is set, this sets the delay (in seconds) towait for a proof of liveness before considering it asfailed and send another request. The default value is 5. dpd_maxfail number; If dpd_delay is set, this sets the maximum number ofproof of liveness to request (without reply) beforeconsidering the peer is dead. The default value is 5. nonce_size number; define the byte size of nonce value. Racoon can send anyvalue although RFC2409 specifies that the value MUST bebetween 8 and 256 bytes. The default size is 16 bytes. proposal { sub-substatements } encryption_algorithm algorithm; specify the encryption algorithm used for thephase 1 negotiation. This directive must bedefined. algorithm is one of following: des,3des, blowfish, cast128, aes for Oakley. Forother transforms, this statement should not beused. hash_algorithm algorithm; define the hash algorithm used for the phase 1negotiation. This directive must be defined.algorithm is one of following: md5, sha1, sha256,sha384, sha512 for Oakley. authentication_method type; defines the authentication method used for thephase 1 negotiation. This directive must bedefined. type is one of: pre_shared_key, rsasig,gssapi_krb, hybrid_rsa_server, orhybrid_rsa_client. dh_group group; define the group used for the Diffie-Hellmanexponentiations. This directive must be defined.group is one of following: modp768, modp1024,modp1536, modp2048, modp3072, modp4096, modp6144,modp8192. Or you can define 1, 2, 5, 14, 15, 16,17, or 18 as the DH group number. When you wantto use aggressive mode, you must define the sameDH group in each proposal. lifetime time number timeunit; define lifetime of the phase 1 SA proposal.Refer to the description of the lifetimedirective defined in the remote directive. gss_id string; define the GSS-API endpoint name, to be includedas an attribute in the SA, if the gssapi_krbauthentication method is used. If this is notdefined, the default value of 'host/hostname' isused, where hostname is the value returned by thehostname(1) command.
Policy Specifications The policy directive is obsolete, policies are now in the SPD. racoon(8)will obey the policy configured into the kernel by setkey(8), and willconstruct phase 2 proposals by combining sainfo specifications inracoon.conf, and policies in the kernel.
Sainfo Specifications sainfo (source_id destination_id | anonymous) [from idtype [string]]{ statements } defines the parameters of the IKE phase 2 (IPsec-SAestablishment). source_id and destination_id are constructedlike:
address address [/ prefix] [[port]] ul_proto
or
subnet address [/ prefix] [[port]] ul_proto
or
idtype string
It means exactly the content of ID payload. This is not like afilter rule. For example, if you define 3ffe:501:4819::/48 assource_id. 3ffe:501:4819:1000:/64 will not match.
In case of longest prefix (selecting single host) addressinstructs to send ID type of ADDRESS, while subnet instructs tosend ID type of SUBNET. Otherwise these instructions areidentical.
pfs_group group; define the group of Diffie-Hellman exponentiations. Ifyou 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,modp2048, modp3072, modp4096, modp6144, modp8192. Or youcan define 1, 2, 5, 14, 15, 16, 17, or 18 as the DH groupnumber. lifetime time number timeunit; define how long an IPsec-SA will be used, in timeunits.Any proposal will be accepted, and no attribute(s) willbe proposed to the peer if you do not specify it(them).See the proposal_check directive. my_identifier idtype ...; is obsolete. It does not make sense to specify anidentifier in the phase 2.
racoon(8) does not have a list of security protocols to benegotiated. The list of security protocols are passed by SPD inthe kernel. Therefore you have to define all of the potentialalgorithms in the phase 2 proposals even if there are algorithmswhich will not be used. These algorithms are define by using thefollowing three directives, with a single comma as the separator.For algorithms that can take variable-length keys, algorithmnames can be followed by a key length, like ''blowfish 448''.racoon(8) will compute the actual phase 2 proposals by computingthe permutation of the specified algorithms, and then combiningthem with the security protocol specified by the SPD. Forexample, if des, 3des, hmac_md5, and hmac_sha1 are specified asalgorithms, we have four combinations for use with ESP, and twofor AH. Then, based on the SPD settings, racoon(8) willconstruct the actual proposals. If the SPD entry asks for ESPonly, there will be 4 proposals. If it asks for both AH and ESP,there will be 8 proposals. Note that the kernel may not supportthe algorithm you have specified. encryption_algorithm algorithms; des, 3des, des_iv64, des_iv32, rc5, rc4, idea, 3idea,cast128, blowfish, null_enc, twofish, rijndael, aes (usedwith ESP) authentication_algorithm algorithms; des, 3des, des_iv64, des_iv32, hmac_md5, hmac_sha1,hmac_sha256, hmac_sha384, hmac_sha512, non_auth (usedwith 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 set the logging leveltoo high on slower machines, IKE negotiation can fail due totiming 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 defaultis 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 isoff, this is ignored. The default is 20 bytes. exclusive_tail (on | off); means to put the number of pad bytes minus one into thelast part of the padding. The default is on. strict_check (on | off); means to constrain the peer to set the number of padbytes. The default is off.
ISAKMP mode configuration settings mode_cfg { statements } Defines the information to return for remote hosts' ISAKMP modeconfig requests. Also defines the authentication source forremote peers authenticating through hybrid auth.
The following are valid statements: auth_source (system | radius | pam); Specify the source for authentication of users throughhybrid auth. system means to use the Unix user database.This is the default. radius means to use a RADIUSserver. It works only if racoon(8) was built withlibradius support, and the configuration is done inradius.conf(5). pam means to use PAM. It works only ifracoon(8) was built with libpam support. conf_source (local | radius); Specify the source for IP addresses and netmask allocatedthrough ISAKMP mode config. local means to use the localIP pool defined by the network4 and pool_size keywords.This is the default. radius means to use a RADIUSserver. It works only if racoon(8) was built withlibradius support, and the configuration is done inradius.conf(5). RADIUS configuration requires RADIUSauthentication. accounting (none | radius | pam); Enable or disable accounting for Xauth logins andlogouts. Default is none, which disable accounting.radius enable RADIUS accounting. It works only ifracoon(8) was built with libradius support, and theconfiguration is done in radius.conf(5). RADIUSaccounting require RADIUS authentication. pam enable PAMaccounting. It works only if racoon(8) was built withlibpam support. PAM accounting requires PAMauthentication. pool_size size Specify the size of the IP address pool, either local orallocated through RADIUS. conf_source selects the localpool or the RADIUS configuration, but in bothconfigurations, you cannot have more than size usersconnected at the same time. The default is 255. network4 address; netmask4 address; The local IP pool base address and network mask fromwhich dynamically allocated IPv4 addresses should betaken. This is used if conf_source is set to local or ifthe RADIUS server returned 255.255.255.254. Default is0.0.0.0/0.0.0.0. dns4 address; The IPv4 address for a DNS server. nbns4 address; The IPv4 address for a WINS server. banner path; The path of a file displayed on the client at connectiontime. Default is /etc/motd. auth_throttle delay; On each failed Xauth authentication attempt, refuse newattempts for delay more seconds. This is to avoiddictionary attacks on Xauth passwords. Default is onesecond. Set to zero to disable authentication delay. pfs_group group; Sets the PFS group used in the client proposal (Cisco VPNclient only). Default is 0. save_passwd (on | off); Allow the client to save the Xauth password (Cisco VPNclient only). 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 andESP tunnel''. The interpretation is more common to other IKEimplementations, however, it allows very limited set ofcombinations for proposals. With the option enabled, it will beproposed as ''AH transport and ESP tunnel''. The default valueis off.
Pre-shared key File The pre-shared key file defines pairs of identifiers and correspondingshared secret keys which are used in the pre-shared key authenticationmethod in phase 1. The pair in each line is separated by some number ofblanks and/or tab characters like in the hosts(5) file. Key can includeblanks because everything after the first blanks is interpreted as thesecret key. Lines starting with '#' are ignored. Keys which start with'0x' are interpreted as hexadecimal strings. Note that the file must beowned by the user ID running racoon(8) (usually the privileged user), andmust not be accessible by others.
Examples
The following shows how the remote directive should be configured.
path pre_shared_key "/usr/local/v6/etc/psk.txt" ;
remote anonymous
{
- exchange_mode aggressive,main,base;
lifetime time 24 hour;
proposal {
encryption_algorithm 3des;
hash_algorithm sha1;
authentication_method pre_shared_key;
dh_group 2;
}
}
sainfo anonymous
{
- pfs_group 2;
lifetime time 12 hour ;
encryption_algorithm 3des, blowfish 448, twofish, rijndael ;
authentication_algorithm hmac_sha1, hmac_md5 ;
compression_algorithm deflate ;
}
The following is a sample for the pre-shared key file.
10.160.94.3 mekmitasdigoat 172.16.1.133 0x12345678 194.100.55.1 whatcertificatereally 3ffe:501:410:ffff:200:86ff:fe05:80fa mekmitasdigoat 3ffe:501:410:ffff:210:4bff:fea2:8baa mekmitasdigoat foo@kame.net mekmitasdigoat foo.kame.net hoge
See Also
racoon(8), racoonctl(8), setkey(8)
History
The racoon.conf configuration file first appeared in the ''YIPS'' Yokogawa IPsec implementation.
Bugs
Some statements may not be handled by racoon(8) yet.
Diffie-Hellman computation can take a very long time, and may cause unwanted timeouts, specifically when a large D-H group is used.
Security Considerations
The use of IKE phase 1 aggressive mode is not recommended, as described in http://www.kb.cert.org/vuls/id/886601.
BSD November 23, 2004 BSD
