diff options
Diffstat (limited to 'ipsec-tools/src/racoon/racoon.conf.5')
| -rw-r--r-- | ipsec-tools/src/racoon/racoon.conf.5 | 1546 |
1 files changed, 1546 insertions, 0 deletions
diff --git a/ipsec-tools/src/racoon/racoon.conf.5 b/ipsec-tools/src/racoon/racoon.conf.5 new file mode 100644 index 00000000..21e499b8 --- /dev/null +++ b/ipsec-tools/src/racoon/racoon.conf.5 @@ -0,0 +1,1546 @@ +.\" $NetBSD: racoon.conf.5,v 1.61.4.1 2012/08/29 08:42:24 tteras Exp $ +.\" +.\" Id: racoon.conf.5,v 1.54 2006/08/22 18:17:17 manubsd Exp +.\" +.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 29, 2012 +.Dt RACOON.CONF 5 +.Os +.\" +.Sh NAME +.Nm racoon.conf +.Nd configuration file for racoon +.\" +.\" .Sh SYNOPSIS +.\" +.Sh DESCRIPTION +.Nm +is the configuration file for the +.Xr racoon 8 +ISAKMP daemon. +.Xr 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 +.Ql { +and +.Ql } . +Lines beginning with +.Ql # +are comments. +.\" +.Ss Meta Syntax +Keywords and special characters that the parser expects exactly are +displayed using +.Ic this +font. +Parameters are specified with +.Ar this +font. +Square brackets +.Po +.Ql \&[ +and +.Ql \&] +.Pc +are used to show optional keywords and parameters. +Note that +you have to pay attention when this manual is describing +.Ar port +numbers. +The +.Ar port +number is always enclosed by +.Ql \&[ +and +.Ql \&] . +In this case, the port number is not an optional keyword. +If it is possible to omit the +.Ar port +number, +the expression becomes +.Bq Bq Ar port . +The vertical bar +.Pq Ql \&| +is used to indicate +a choice between optional parameters. +Parentheses +.Po +.Ql \&( +and +.Ql \&) +.Pc +are used to group keywords and parameters when necessary. +Major parameters are listed below. +.Pp +.Bl -tag -width addressx -compact +.It Ar number +means a hexadecimal or a decimal number. +The former must be prefixed with +.Ql Li 0x . +.It Ar string +.It Ar path +.It Ar file +means any string enclosed in +.Ql \&" +.Pq double quotes . +.It Ar address +means IPv6 and/or IPv4 address. +.It Ar port +means a TCP/UDP port number. +The port number is always enclosed by +.Ql \&[ +and +.Ql \&] . +.It Ar timeunit +is one of following: +.Ic sec , secs , second , seconds , +.Ic min , mins , minute , minutes , +.Ic hour , hours . +.El +.\" +.Ss Privilege separation +.Bl -tag -width Ds -compact +.It Ic privsep { Ar statements Ic } +Specifies privilege separation parameters. +When enabled, these enable +.Xr racoon 8 +to operate with an unprivileged instance doing most of the work, while +a privileged instance takes care of performing the following operations +as root: reading PSK and private keys, launching hook scripts, and +validating passwords against system databases or against PAM. +Please note that using privilege separation makes changes to the +.Ar listen +and +.Ar paths +sections ignored upon configuration reloads. +A +.Xr racoon 8 +restart is required if you want such changes to be taken into account. +.Pp +.Bl -tag -width Ds -compact +.It Ic user Ar user ; +The user to which the unprivileged instance of +.Xr racoon 8 , +should switch. +This can be a quoted user name or a numeric UID. +.It Ic group Ar group ; +The group the unprivileged instance of +.Xr racoon 8 , +should switch. +This can be a quoted group name or a numeric GID. +.It Ic chroot Ar path ; +A directory to which the unprivileged instance of +.Xr racoon 8 +should +.Xr chroot 2 . +This directory should hold a tree where the following files must be +reachable: +.Bl -tag -width Ds -compact +.It Pa /dev/random +.It Pa /dev/urandom +.It The certificates +.It The file containing the Xauth banner +.El +.Pp +The PSK file, the private keys, and the hook scripts are accessed through the +privileged instance of +.Xr racoon 8 +and do not need to be reachable in the +.Xr chroot 2 Ap ed +tree. +.El +.El +.Ss Path Specification +This section specifies various paths used by racoon. +When running in privilege separation mode, +.Ic certificate +and +.Ic script +paths are mandatory. +A +.Xr racoon 8 +restart is required if you want path changes to be taken into account. +.Bl -tag -width Ds -compact +.It Ic path include Ar path ; +Specifies a path to include a file. +See +.Sx File Inclusion . +.It Ic path pre_shared_key Ar file ; +Specifies a file containing pre-shared key(s) for various ID(s). +See +.Sx Pre-shared key File . +.It Ic path certificate Ar path ; +.Xr racoon 8 +will search this directory if a certificate or certificate request is received. +If you run with privilege separation, +.Xr racoon 8 +will refuse to use a certificate stored outside of this directory. +.It Ic path backupsa Ar file ; +Specifies a file to which SA information negotiated by +racoon should be stored. +.Xr racoon 8 +will install SA(s) from the file when started with the +.Fl B +flag. +The file is growing because +.Xr racoon 8 +simply adds SAs to it. +You should maintain the file manually. +.It Ic path script Ar path ; +.Xr racoon 8 +will search this directory for scripts hooks. +If you run with privilege separation, +.Xr racoon 8 +will refuse to execute a script stored outside of this directory. +.It Ic path pidfile Ar file ; +Specifies file where to store PID of process. +If path starts with +.Pa / +it is treated as an absolute path. +Otherwise, it is treated as a relative +path to the VARRUN directory specified at compilation time. +Default is +.Pa racoon.pid . +.El +.\" +.Ss File Inclusion +.Bl -tag -width Ds -compact +.It Ic include Ar file +Specifies other configuration files to be included. +.El +.\" +.Ss Timer Specification +.Bl -tag -width Ds -compact +.It Ic timer { Ar statements Ic } +This section specifies various timer values used by racoon. +.Pp +.Bl -tag -width Ds -compact +.It Ic counter Ar number ; +The maximum number of retries to send. +The default is 5. +.It Ic interval Ar number Ar timeunit ; +The interval to resend, in seconds. +The default time is 10 seconds. +.It Ic persend Ar number ; +The number of packets per send. +The default is 1. +.It Ic phase1 Ar number Ar timeunit ; +The maximum time it should take to complete phase 1. +The default time is 15 seconds. +.It Ic phase2 Ar number Ar timeunit ; +The maximum time it should take to complete phase 2. +The default time is 10 seconds. +.It Ic natt_keepalive Ar number Ar timeunit ; +The interval between sending NAT-Traversal keep-alive packets. +The default time is 20 seconds. +Set to 0s to disable keep-alive packets. +.El +.El +.\" +.Ss Listening Port Specification +.Bl -tag -width Ds -compact +.It Ic listen { Ar statements Ic } +If no +.Ar listen +directive is specified, +.Xr racoon 8 +will listen on all available interface addresses. +The following is the list of valid statements: +.Pp +.Bl -tag -width Ds -compact +.\" How do I express bold brackets; `[' and `]' . +.\" Answer: For bold brackets, do "Ic \&[ foo \&]". +.\" Is the "Bq Ic [ Ar port ] ;" buggy ? +.It Ic isakmp Ar address Bq Bq Ar port ; +If this is specified, +.Xr racoon 8 +will only listen on the defined +.Ar address . +The default port is 500, which is specified by IANA. +You can provide more than one address definition. +.It Ic isakmp_natt Ar address Bq Ar port ; +Same as +.Ic isakmp +but also sets the socket options to accept UDP-encapsulated ESP traffic for +NAT-Traversal. +If you plan to use NAT-T, you should provide at least one address +with port 4500, which is specified by IANA. +There is no default. +.It Ic strict_address ; +Requires that all addresses for ISAKMP be bound. +This statement will be ignored if you do not specify address definitions. +.El +When running in privilege separation mode, you need to restart +.Xr racoon 8 +to have changes to the +.Ar listen +section taken into account. +.Pp +The +.Ar listen +section can also be used to specify the admin socket mode and ownership +if racoon was built with support for admin port. +.Bl -tag -width Ds -compact +.It Ic adminsock Ar path Op Ar owner\ group\ mode ; +The +.Ar path , +.Ar owner , +and +.Ar group +values specify the socket path, owner, and group. +They must be quoted. +The defaults are +.Pa /var/racoon/racoon.sock , +UID 0, and GID 0. +.Ar mode +is the access mode in octal. +The default is 0600. +.It Ic adminsock disabled ; +This directive tells racoon to not listen on the admin socket. +.El +.El +.\" +.Ss Miscellaneous Global Parameters +.Bl -tag -width Ds -compact +.It Ic gss_id_enc Ar enctype ; +Older versions of +.Xr racoon 8 +used ISO-Latin-1 as the encoding of the GSS-API identifier attribute. +For interoperability with Microsoft Windows' GSS-API authentication +scheme, the default encoding has been changed to UTF-16LE. +The +.Ic gss_id_enc +parameter allows +.Xr racoon 8 +to be configured to use the old encoding for compatibility with existing +.Xr racoon 8 +installations. +The following are valid values for +.Ar enctype : +.Pp +.Bl -tag -width Ds -compact +.It Ic utf-16le +Use UTF-16LE to encode the GSS-API identifier attribute. +This is the default encoding. +This encoding is compatible with Microsoft Windows. +.It Ic latin1 +Use ISO-Latin-1 to encode the GSS-API identifier attribute. +This is the encoding used by older versions of +.Xr racoon 8 . +.El +.El +.\" +.Pp +.Bl -tag -width Ds -compact +.It Ic pfkey_buffer Ar kBytes +Specifies the socket send/receive buffer size in kilobytes. +Numerous kernel PF_KEY implementations have problems with dumping +SAD/SDP with large amount of entries (this happens when 100s to +1000s of tunnels are configured). +.Pp +The default value of 0 leaves everything at the OS-specific default value. +If the default buffer size is greater than what is specified here racoon +will not decrease it. +.Pp +This problem is known to be fixed in Linux 2.6.25 and later. +.El +.\" +.Ss Remote Nodes Specifications +.Bl -tag -width Ds -compact +.It Ic remote Ar name Bo Ic inherit Ar parent_name Bc Ic ({ Ar statements Ic } | ;) +Specifies the IKE phase 1 parameters for each remote node. +.Pp +If connection is initiated using racoonctl, a unique match using the +remote IP must be found or the remote block name has to be given. +For received acquires (kernel notices traffic requiring a new SA) the +remote IP and remoteid from matching sainfo block are used to decide +the remoteblock. +If no uniquely matching remoteblock is found using +these criteria, no connection attempt is done. +.Pp +When acting as responder, racoon picks the first proposal that has one +or more acceptable remote configurations. +When determining if a remote +specification is matching the following information is checked: +.Bl -bullet -width Ds -compact +.It +The remote IP is checked against +.Ic remote_address . +.It +ISAKMP exchange type is checked against +.Ic exchange_mode . +.It +ISAKMP SA attributes must match a +.Ic proposal +block. +.It +The remote identity is matched against +.Ic peers_identifier +if +.Ic verify_identifier +is on. +.It +If a certificate request was received, it must match the issuer of +.Ic "certificate_type x509" +certificate. +If certificate request without issuer name was sent, the +.Ic match_empty_cr +parameter specifies whether or not remote block matches. +.El +.Pp +Similarly, NAT-T is enabled if any of the initial remote configuration +candidates allow NAT-T. +.Pp +Sections with +.Ic inherit Ar parent +statements (where +.Ar parent +is either +.Ar address +or a keyword +.Ic anonymous ) +that have all values predefined to those of a given +.Ar parent . +In these sections it is enough to redefine only the changed parameters. +.Pp +The following are valid statements. +.Pp +.Bl -tag -width Ds -compact +.\" +.It Ic remote_address Ar address ; +Defines the IP address of the peer. +.\" +.It Ic exchange_mode ( main | aggressive | base ) ; +Defines the exchange mode for phase 1 when racoon is the initiator. +It also means the acceptable exchange mode when racoon is the 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. +.\" +.It Ic doi Ic ipsec_doi ; +Means to use IPsec DOI as specified in RFC 2407. +You can omit this statement. +.\" +.It Ic situation Ic identity_only ; +Means to use SIT_IDENTITY_ONLY as specified in RFC 2407. +You can omit this statement. +.\" +.It Ic my_identifier Bo Ar qualifier Bc Ar idtype ... ; +Specifies the identifier sent to the remote host +and the type to use in the phase 1 negotiation. +.Ic address, fqdn , user_fqdn , keyid , +and +.Ic asn1dn +can be used as an +.Ar idtype . +The +.Ar qualifier +is currently only used for +.Ic keyid , +and can be either +.Ic file +or +.Ic tag . +The possible values are : +.Bl -tag -width Ds -compact +.It Ic my_identifier Ic address Bq Ar address ; +The type is the IP address. +This is the default type if you do not specify an identifier to use. +.It Ic my_identifier Ic user_fqdn Ar string ; +The type is a USER_FQDN (user fully-qualified domain name). +.It Ic my_identifier Ic fqdn Ar string ; +The type is a FQDN (fully-qualified domain name). +.It Ic my_identifier Ic keyid Bo Ic file Bc Ar file ; +The type is a KEY_ID, read from the file. +.It Ic my_identifier Ic keyid Ic tag Ar string ; +The type is a KEY_ID, specified in the quoted string. +.It Ic my_identifier Ic asn1dn Bq Ar string ; +The type is an ASN.1 distinguished name. +If +.Ar string +is omitted, +.Xr racoon 8 +will get the DN from the Subject field in the certificate. +.El +.\" +.It Ic xauth_login Bq Ar string ; +Specifies the login to use in client-side Hybrid authentication. +It is available only if +.Xr racoon 8 +has been built with this option. +The associated password is looked up in the pre-shared key files, +using the login +.Ic string +as the key id. +.\" +.It Ic peers_identifier Ar idtype ... ; +Specifies the peer's identifier to be received. +If it is not defined then +.Xr racoon 8 +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 +.Ic verify_identifier . +The usage of +.Ar idtype +is the same as +.Ic my_identifier +except that the individual component values of an +.Ic asn1dn +identifier may specified as +.Ic * +to match any value (e.g. "C=XX, O=MyOrg, OU=*, CN=Mine"). +The format of the +specification should correspond to RFC 2253; in particular, commas and certain +other characters - +.Ic ,=+\*[Lt]\*[Gt]#; +- may be included in a name by preceeding them with a backslash "\e", and +arbitrary characters may be inserted in a name with the "\enn" escape, where +nn is the hex representation of the ascii value of the desired character. +Alternative acceptable peer identifiers may be specified by repeating the +.Ic peers_identifier +statement. +.\" +.It Ic 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 +.Ic peers_identifier +is not the same as the peer's identifier in the ID payload, +the negotiation will fail. +The default is off. +.\" +.It Ic certificate_type Ar certspec ; +Specifies a certificate specification. +.Ar certspec +is one of followings: +.Bl -tag -width Ds -compact +.It Ic x509 Ar certfile Ar privkeyfile ; +.Ar certfile +means a file name of a certificate. +.Ar privkeyfile +means a file name of a secret key. +.El +.Bl -tag -width Ds -compact +.It Ic plain_rsa Ar privkeyfile ; +.Ar privkeyfile +means a file name of a private key generated by +.Xr plainrsa-gen 8 . +Required +for RSA authentication. +.El +.It Ic ca_type Ar cacertspec ; +Specifies a root certificate authority specification. +.Ar cacertspec +is one of followings: +.Bl -tag -width Ds -compact +.It Ic x509 Ar cacertfile ; +.Ar cacertfile +means a file name of the root certificate authority. +Default is +.Pa /etc/openssl/cert.pem +.El +.\" +.It Ic mode_cfg (on | off) ; +Gather network information through ISAKMP mode configuration. +Default is off. +.\" +.It Ic weak_phase1_check (on | off) ; +Tells racoon to act on unencrypted deletion messages during phase 1. +This is a small security risk, so the default is off, meaning that +racoon will keep on trying to establish a connection even if the +user credentials are wrong, for instance. +.\" +.It Ic peers_certfile ( dnssec | Ar certfile | Ic plain_rsa Ar pubkeyfile ) ; +If +.Ic dnssec +is defined, +.Xr racoon 8 +will ignore the CERT payload from the peer, +and try to get the peer's certificate from DNS instead. +If +.Ar certfile +is defined, +.Xr racoon 8 +will ignore the CERT payload from the peer, +and will use this certificate as the peer's certificate. +If +.Ic plain_rsa +is defined, +.Xr racoon 8 +will expect +.Ar pubkeyfile +to be the peer's public key that was generated by +.Xr plainrsa-gen 8 . +.\" +.It Ic script Ar script Ic phase1_up +.It Ic script Ar script Ic phase1_down +.It Ic script Ar script Ic phase1_dead +Shell scripts that get executed when a phase 1 SA goes up or down, or +when it is detected as dead by DPD. +All scripts get either +.Ic phase1_up +, +.Ic phase1_down +or +.Ic phase1_dead +as first argument, and the following +variables are set in their environment: +.Bl -tag -width Ds -compact +.It Ev LOCAL_ADDR +The local address of the phase 1 SA. +.It Ev LOCAL_PORT +The local port used for IKE for the phase 1 SA. +.It Ev REMOTE_ADDR +The remote address of the phase 1 SA. +.It Ev REMOTE_PORT +The remote port used for IKE for the phase 1 SA. +.It Ev REMOTE_ID +The remote identity received in IKE for the phase 1 SA. +.El +The following variables are only set if +.Ic mode_cfg +was enabled: +.Bl -tag -width Ds -compact +.It INTERNAL_ADDR4 +An IPv4 internal address obtained by ISAKMP mode config. +.It INTERNAL_NETMASK4 +An IPv4 internal netmask obtained by ISAKMP mode config. +.It INTERNAL_CIDR4 +An IPv4 internal netmask obtained by ISAKMP mode config, in CIDR notation. +.It INTERNAL_DNS4 +The first internal DNS server IPv4 address obtained by ISAKMP mode config. +.It INTERNAL_DNS4_LIST +A list of internal DNS servers IPv4 address obtained by ISAKMP mode config, +separated by spaces. +.It INTERNAL_WINS4 +The first internal WINS server IPv4 address obtained by ISAKMP mode config. +.It INTERNAL_WINS4_LIST +A list of internal WINS servers IPv4 address obtained by ISAKMP mode config, +separated by spaces. +.It SPLIT_INCLUDE +The space separated list of IPv4 addresses and masks (address slash mask) +that define the networks to be encrypted (as opposed to the default where +all the traffic should be encrypted) ; obtained by ISAKMP mode config ; +SPLIT_INCLUDE and SPLIT_LOCAL are mutually exclusive. +.It SPLIT_LOCAL +The space separated list of IPv4 addresses and masks (address slash mask) +that define the networks to be considered local, and thus excluded from the +tunnels ; obtained by ISAKMP mode config. +.It SPLIT_INCLUDE_CIDR +Same as SPLIT_INCLUDE, with netmasks in CIDR notation. +.It SPLIT_LOCAL_CIDR +Same as SPLIT_LOCAL, with netmasks in CIDR notation. +.It DEFAULT_DOMAIN +The DNS default domain name obtained by ISAKMP mode config. +.El +.\" +.\" +.It Ic send_cert (on | off) ; +If you do not want to send a certificate, set this to off. +The default is on. +.\" +.It Ic send_cr (on | off) ; +If you do not want to send a certificate request, set this to off. +The default is on. +.\" +.It Ic match_empty_cr (on | off) ; +Specifies whether this remote block is a valid match when a non-specific +certificate request is received. +The default is on. +.\" +.It Ic verify_cert (on | off) ; +By default, the identifier sent by the remote host (as specified in its +.Ic my_identifier +statement) is compared with the credentials in the certificate +used to authenticate the remote host as follows: +.Bl -tag -width Ds -compact +.It Type Ic asn1dn : +The entire certificate subject name is compared with the identifier, +e.g. "C=XX, O=YY, ...". +.It Type Ic address, fqdn, or user_fqdn : +The certificate's subjectAltName is compared with the identifier. +.El +If the two do not match the negotiation will fail. +If you do not want to verify the identifier using the peer's certificate, +set this to off. +.\" +.It Ic lifetime time Ar number Ar 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 not be proposed to +the peer if you do not specify it (them). +They can be individually specified in each proposal. +.\" +.It Ic ike_frag (on | off | force) ; +Enable receiver-side IKE fragmentation if +.Xr racoon 8 +has been built with this feature. +If set to on, racoon will advertise +itself as being capable of receiving packets split by IKE fragmentation. +This extension is there to work around broken firewalls that do not +work with fragmented UDP packets. +IKE fragmentation is always enabled on the sender-side, and it is +used if the peer advertises itself as IKE fragmentation capable. +By selecting force, IKE Fragmentation will +be used when racoon is acting as the initiator even before the remote +peer has advertised itself as IKE fragmentation capable. +.\" +.It Ic esp_frag Ar fraglen ; +This option is only relevant if you use NAT traversal in tunnel mode. +Its purpose is to work around broken DSL routers that reject UDP +fragments, by fragmenting the IP packets before ESP encapsulation. +The result is ESP over UDP of fragmented packets instead of fragmented +ESP over UDP packets (i.e., IP:UDP:ESP:frag(IP) instead of +frag(IP:UDP:ESP:IP)). +.Ar fraglen +is the maximum size of the fragments. +552 should work anywhere, +but the higher +.Ar fraglen +is, the better the performance. +.Pp +Note that because PMTU discovery is broken on many sites, you will +have to use MSS clamping if you want TCP to work correctly. +.\" +.It Ic initial_contact (on | off) ; +Enable this to send an INITIAL-CONTACT message. +The default value is +.Ic on . +This message is useful only when the responder implementation chooses an +old SA when there are multiple SAs with different established time and the +initiator reboots. +If racoon did not send the message, +the responder would use an old SA even when a new SA was established. +For systems that use a KAME derived IPSEC stack, the +.Xr sysctl 8 +variable net.key.preferred_oldsa can be used to control this preference. +When the value is zero, the stack always uses a new SA. +.\" +.It Ic passive (on | off) ; +If you do not want to initiate the negotiation, set this to on. +The default value is +.Ic off . +It is useful for a server. +.\" +.It Ic proposal_check Ar level ; +Specifies the action of lifetime length, key length, and PFS of the phase 2 +selection on the responder side, and the action of lifetime check in +phase 1. +The default level is +.Ic strict . +If the +.Ar level +is: +.Bl -tag -width Ds -compact +.It Ic obey +The responder will obey the initiator anytime. +.It Ic strict +If the responder's lifetime length is longer than the initiator's or +the responder's key length is shorter than the initiator's, +the responder will use the initiator's value. +Otherwise, the proposal will be rejected. +If PFS is not required by the responder, the responder will obey the proposal. +If PFS is required by both sides and the responder's group is not equal to +the initiator's, then the responder will reject the proposal. +.It Ic claim +If the responder's lifetime length is longer than the initiator's or +the responder's key length is shorter than the initiator's, +the responder will use the initiator's value. +If the responder's lifetime length is shorter than the initiator's, +the responder uses its own length AND sends a RESPONDER-LIFETIME notify +message to an initiator in the case of lifetime (phase 2 only). +For PFS, this directive behaves the same as +.Ic strict . +.It Ic exact +If the initiator's lifetime or key length is not equal to the responder's, +the responder will reject the proposal. +If PFS is required by both sides and the responder's group is not equal to +the initiator's, then the responder will reject the proposal. +.El +.\" +.It Ic support_proxy (on | off) ; +If this value is set to on, then both values of ID payloads in the +phase 2 exchange are always used as the addresses of end-point of +IPsec-SAs. +The default is off. +.\" +.It Ic generate_policy (on | off | require | unique) ; +This directive is for the responder. +Therefore you should set +.Ic passive +to on in order that +.Xr racoon 8 +only becomes a responder. +If the responder does not have any policy in SPD during phase 2 +negotiation, and the directive is set to on, then +.Xr racoon 8 +will choose the first proposal in the +SA payload from the initiator, and generate policy entries from the proposal. +It is useful to negotiate with clients whose IP address is allocated +dynamically. +Note that an inappropriate policy might be installed into the responder's SPD +by the initiator, +so other communications might fail if such policies are installed +due to a policy mismatch between the initiator and the responder. +.Ic on +and +.Ic require +values mean the same thing (generate a require policy). +.Ic unique +tells racoon to set up unique policies, with a monotoning increasing +reqid number (between 1 and IPSEC_MANUAL_REQID_MAX). +This directive is ignored in the initiator case. +The default value is +.Ic off . +.\" +.\" +.It Ic nat_traversal (on | off | force) ; +This directive enables use of the NAT-Traversal IPsec extension +(NAT-T). +NAT-T allows one or both peers to reside behind a NAT gateway (i.e., +doing address- or port-translation). +If a NAT gateway is detected during the phase 1 handshake, racoon will +attempt to negotiate the use of NAT-T with the remote peer. +If the negotiation succeeds, all ESP and AH packets for the given connection +will be encapsulated into UDP datagrams (port 4500, by default). +Possible values are: +.Bl -tag -width Ds -compact +.It Ic on +NAT-T is used when a NAT gateway is detected between the peers. +.It Ic off +NAT-T is not proposed/accepted. +This is the default. +.It Ic force +NAT-T is used regardless of whether a NAT gateway is detected between the +peers or not. +.El +Please note that NAT-T support is a compile-time option. +Although it is enabled in the source distribution by default, it +may not be available in your particular build. +In that case you will get a +warning when using any NAT-T related config options. +.\" +.It Ic dpd_delay Ar delay ; +This option activates the DPD and sets the time (in seconds) allowed +between 2 proof of liveliness requests. +The default value is +.Ic 0 , +which disables DPD monitoring, but still negotiates DPD support. +.\" +.It Ic dpd_retry Ar delay ; +If +.Ic dpd_delay +is set, this sets the delay (in seconds) to wait for a proof of +liveliness before considering it as failed and send another request. +The default value is +.Ic 5 . +.\" +.It Ic dpd_maxfail Ar number ; +If +.Ic dpd_delay +is set, this sets the maximum number of liveliness proofs to request +(without reply) before considering the peer is dead. +The default value is +.Ic 5 . +.\" +.It Ic rekey (on | off | force) ; +Enable automatic renegotiation of expired phase1 when there are non-dying +phase2 SAs. +Possible values are: +.Bl -tag -width Ds -compact +.It Ic force +Rekeying is done unconditionally. +.It Ic on +Rekeying is done only if DPD monitoring is active. +This is the default. +.It Ic off +No automatic rekeying. +Do note that turning off automatic rekeying will +result in inaccurate DPD monitoring. +.El +.\" +.It Ic nonce_size Ar 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. +.\" +.It Ic ph1id Ar number ; +An optional number to identify the remote proposal and to link it +only with sainfos who have the same number. +Defaults to 0. +.\" +.It Ic proposal { Ar sub-substatements Ic } +.Bl -tag -width Ds -compact +.\" +.It Ic encryption_algorithm Ar algorithm ; +Specifies the encryption algorithm used for the phase 1 negotiation. +This directive must be defined. +.Ar algorithm +is one of following: +.Ic des, 3des, blowfish, cast128, aes, camellia +.\".Ic rc5 , idea +for Oakley. +For other transforms, this statement should not be used. +.\" +.It Ic hash_algorithm Ar algorithm ; +Defines the hash algorithm used for the phase 1 negotiation. +This directive must be defined. +.Ar algorithm +is one of following: +.Ic md5, sha1, sha256, sha384, sha512 +for Oakley. +.\" +.It Ic authentication_method Ar type ; +Defines the authentication method used for the phase 1 negotiation. +This directive must be defined. +.Ar type +is one of: +.Ic pre_shared_key , rsasig +(for plain RSA authentication), +.Ic gssapi_krb , hybrid_rsa_server , +.Ic hybrid_rsa_client , xauth_rsa_server , xauth_rsa_client , xauth_psk_server +or +.Ic xauth_psk_client . +.\" +.It Ic dh_group Ar group ; +Defines the group used for the Diffie-Hellman exponentiations. +This directive must be defined. +.Ar group +is one of following: +.Ic modp768 , modp1024 , modp1536 , +.Ic modp2048 , modp3072 , modp4096 , +.Ic modp6144 , modp8192 . +Or you can define 1, 2, 5, 14, 15, 16, 17, or 18 as the DH group number. +When you want to use aggressive mode, +you must define the same DH group in each proposal. +.It Ic lifetime time Ar number Ar timeunit ; +Defines the lifetime of the phase 1 SA proposal. +Refer to the description of the +.Ic lifetime +directive defined in the +.Ic remote +directive. +.It Ic gss_id Ar string ; +Defines the GSS-API endpoint name, to be included as an attribute in the SA, +if the +.Ic gssapi_krb +authentication method is used. +If this is not defined, the default value of +.Ql host/hostname +is used, where hostname is the value returned by the +.Xr hostname 1 +command. +.El +.El +.Pp +.It Ic remote Po Ar address | Ic anonymous Pc Bo Bo Ar port Bc Bc \ +Bo Ic inherit Ar parent Bc Ic { Ar statements Ic } +Deprecated format of specifying a remote block. +This will be removed in future. +It is a remnant from time when remote block was decided +solely based on the peers IP address. +.Pp +This is equivalent to: +.Bd -literal -offset +remote "address" [inherit "parent-address"] { + remote_address address; +} +.Ed +.El +.\" +.Ss Sainfo Specifications +.Bl -tag -width Ds -compact +.It Ic sainfo Po Ar local_id | Ic anonymous Pc \ +Po Ar remote_id | Ic clientaddr | Ic anonymous Pc \ +Bo Ic from Ar idtype Bo Ar string Bc Bc Bo Ic group Ar string Bc \ +Ic { Ar statements Ic } +Defines the parameters of the IKE phase 2 (IPsec-SA establishment). +.Pp +The +.Ar local_id +and +.Ar remote_id +strings are constructed like: +.Pp +.Ic address Ar address +.Bq Ic / Ar prefix +.Bq Ic [ Ar port ] +.Ar ul_proto +.Pp +or +.Pp +.Ic subnet Ar address +.Bq Ic / Ar prefix +.Bq Ic [ Ar port ] +.Ar ul_proto +.Pp +An id string should be expressed to match the exact value of an ID payload. +This is not like a filter rule. +For example, if you define 3ffe:501:4819::/48 as +.Ar local_id . +3ffe:501:4819:1000:/64 will not match. +In the case of a longest prefix (selecting a single host), +.Ar address +instructs to send ID type of ADDRESS while +.Ar subnet +instructs to send ID type of SUBNET. +Otherwise, these instructions are identical. +.Pp +The +.Ic anonymous +keyword can be used to match any id. +The +.Ic clientaddr +keyword can be used to match a remote id that is equal to either the peer +ip address or the mode_cfg ip address (if assigned). +This can be useful +to restrict policy generation when racoon is acting as a client gateway +for peers with dynamic ip addresses. +.Pp +The +.Ic from +keyword allows an sainfo to only match for peers that use a specific phase1 +id value during authentication. +The +.Ic group +keyword allows an XAuth group membership check to be performed +for this sainfo section. +When the mode_cfg auth source is set to +.Ic system +or +.Ic ldap , +the XAuth user is verified to be a member of the specified group +before allowing a matching SA to be negotiated. +.Pp +.Bl -tag -width Ds -compact +.\" +.It Ic pfs_group Ar 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. +.Ar group +is one of following: +.Ic modp768 , modp1024 , modp1536 , +.Ic modp2048 , modp3072 , modp4096 , +.Ic modp6144 , modp8192 . +Or you can define 1, 2, 5, 14, 15, 16, 17, or 18 as the DH group number. +.\" +.It Ic lifetime time Ar number Ar timeunit ; +define how long an IPsec-SA will be used, in timeunits. +Any proposal will be accepted, and no attribute(s) will be proposed to +the peer if you do not specify it(them). +See the +.Ic proposal_check +directive. +.\" +.It Ic remoteid Ar number ; +Sainfos will only be used if their remoteid matches the ph1id of the +remote section used for phase 1. +Defaults to 0, which is also the default for ph1id. +.El +.\" +.Pp +.Xr racoon 8 +does not have a 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 are algorithms which will not be used. +These algorithms are define by using the following three directives, +with a single comma as the separator. +For algorithms that can take variable-length keys, algorithm names +can be followed by a key length, like +.Dq Li blowfish 448 . +.Xr racoon 8 +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 +.Ic des , 3des , hmac_md5 , +and +.Ic hmac_sha1 +are specified as algorithms, we have four combinations for use with ESP, +and two for AH. +Then, based on the SPD settings, +.Xr racoon 8 +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. +.\" +.Bl -tag -width Ds -compact +.It Ic encryption_algorithm Ar algorithms ; +.Ic des , 3des , des_iv64 , des_iv32 , +.Ic rc5 , rc4 , idea , 3idea , +.Ic cast128 , blowfish , null_enc , +.Ic twofish , rijndael , aes , camellia +.Pq used with ESP +.\" +.It Ic authentication_algorithm Ar algorithms ; +.Ic des , 3des , des_iv64 , des_iv32 , +.Ic hmac_md5 , hmac_sha1 , hmac_sha256, hmac_sha384, hmac_sha512, non_auth +.Pq used with ESP authentication and AH +.\" +.It Ic compression_algorithm Ar algorithms ; +.Ic deflate +.Pq used with IPComp +.El +.El +.\" +.Ss Logging level +.Bl -tag -width Ds -compact +.It Ic log Ar level ; +Defines the logging level. +.Ar level +is one of following: +.Ic error , warning , notify , info , debug +or +.Ic debug2 . +The default is +.Ic info . +If you set the logging level too high on slower machines, +IKE negotiation can fail due to timing constraint changes. +.El +.\" +.Ss Specifies the way to pad +.Bl -tag -width Ds -compact +.It Ic padding { Ar statements Ic } +specifies the padding format. +The following are valid statements: +.Bl -tag -width Ds -compact +.It Ic randomize (on | off) ; +Enables the use of a randomized value for padding. +The default is on. +.It Ic randomize_length (on | off) ; +The pad length will be random. +The default is off. +.It Ic maximum_length Ar number ; +Defines a maximum padding length. +If +.Ic randomize_length +is off, this is ignored. +The default is 20 bytes. +.It Ic exclusive_tail (on | off) ; +Means to put the number of pad bytes minus one into the last part +of the padding. +The default is on. +.It Ic strict_check (on | off) ; +Means to constrain the peer to set the number of pad bytes. +The default is off. +.El +.El +.Ss ISAKMP mode configuration settings +.Bl -tag -width Ds -compact +.It Ic mode_cfg { Ar statements Ic } +Defines the information to return for remote hosts' ISAKMP mode config +requests. +Also defines the authentication source for remote peers +authenticating through Xauth. +.Pp +The following are valid statements: +.Bl -tag -width Ds -compact +.It Ic auth_source (system | radius | pam | ldap) ; +Specifies the source for authentication of users through Xauth. +.Ar system +means to use the Unix user database. +This is the default. +.Ar radius +means to use a RADIUS server. +It works only if +.Xr racoon 8 +was built with libradius support. +Radius configuration is handled by statements in the +.Ic radiuscfg +section. +.Ar pam +means to use PAM. +It works only if +.Xr racoon 8 +was built with libpam support. +.Ar ldap +means to use LDAP. +It works only if +.Xr racoon 8 +was built with libldap support. +LDAP configuration is handled by statements in the +.Ic ldapcfg +section. +.It Ic auth_groups Ar "group1", ... ; +Specifies the group memberships for Xauth in quoted group name strings. +When defined, the authenticating user must be a member of at least one +group for Xauth to succeed. +.It Ic group_source (system | ldap) ; +Specifies the source for group validation of users through Xauth. +.Ar system +means to use the Unix user database. +This is the default. +.Ar ldap +means to use LDAP. +It works only if +.Xr racoon 8 +was built with libldap support and requires LDAP authentication. +LDAP configuration is handled by statements in the +.Ic ldapcfg +section. +.It Ic conf_source (local | radius | ldap) ; +Specifies the source for IP addresses and netmask allocated through ISAKMP +mode config. +.Ar local +means to use the local IP pool defined by the +.Ic network4 +and +.Ic pool_size +statements. +This is the default. +.Ar radius +means to use a RADIUS server. +It works only if +.Xr racoon 8 +was built with libradius support and requires RADIUS authentication. +RADIUS configuration is handled by statements in the +.Ic radiuscfg +section. +.Ar ldap +means to use an LDAP server. +It works only if +.Xr racoon 8 +was built with libldap support and requires LDAP authentication. +LDAP configuration is handled by +statements in the +.Ic ldapcfg +section. +.It Ic accounting (none | system | radius | pam) ; +Enables or disables accounting for Xauth logins and logouts. +The default is +.Ar none +which disable accounting. +Specifying +.Ar system +enables system accounting through +.Xr utmp 5 . +Specifying +.Ar radius +enables RADIUS accounting. +It works only if +.Xr racoon 8 +was built with libradius support and requires RADIUS authentication. +RADIUS configuration is handled by statements in the +.Ic radiuscfg +section. +Specifying +.Ar pam +enables PAM accounting. +It works only if +.Xr racoon 8 +was build with libpam support and requires PAM authentication. +.It Ic pool_size Ar size +Specify the size of the IP address pool, either local or allocated +through RADIUS. +.Ic conf_source +selects the local pool or the RADIUS configuration, but in both +configurations, you cannot have more than +.Ar size +users connected at the same time. +The default is 255. +.It Ic network4 Ar address ; +.It Ic netmask4 Ar address ; +The local IP pool base address and network mask from which dynamically +allocated IPv4 addresses should be taken. +This is used if +.Ic conf_source +is set to +.Ar local +or if the RADIUS server returned +.Ar 255.255.255.254 . +Default is +.Ar 0.0.0.0/0.0.0.0 . +.It Ic dns4 Ar addresses ; +A list of IPv4 addresses for DNS servers, separated by commas, or on multiple +.Ic dns4 +lines. +.It Ic wins4 Ar addresses ; +A list of IPv4 address for WINS servers. +The keyword +.It nbns4 +can also be used as an alias for +.It wins4 . +.It Ic split_network (include | local_lan) Ar network/mask, ... +The network configuration to send, in CIDR notation (e.g. 192.168.1.0/24). +If +.Ic include +is specified, the tunnel should be only used to encrypt the indicated +destinations ; otherwise, if +.Ic local_lan +is used, everything will pass through the tunnel but those destinations. +.It Ic default_domain Ar domain ; +The default DNS domain to send. +.It Ic split_dns Ar "domain", ... +The split dns configuration to send, in quoted domain name strings. +This list can be used to describe a list of domain names for which +a peer should query a modecfg assigned dns server. +DNS queries for all other domains would be handled locally. +(Cisco VPN client only). +.It Ic banner Ar path ; +The path of a file displayed on the client at connection time. +Default is +.Ar /etc/motd . +.It Ic auth_throttle Ar delay ; +On each failed Xauth authentication attempt, refuse new attempts for a set +.Ar delay +of seconds. +This is to avoid dictionary attacks on Xauth passwords. +Default is one second. +Set to zero to disable authentication delay. +.It Ic pfs_group Ar group ; +Sets the PFS group used in the client proposal (Cisco VPN client only). +Default is 0. +.It Ic save_passwd (on | off) ; +Allow the client to save the Xauth password (Cisco VPN client only). +Default is off. +.El +.El +.Ss Ldap configuration settings +.Bl -tag -width Ds -compact +.It Ic ldapcfg { Ar statements Ic } +Defines the parameters that will be used to communicate with an ldap +server for +.Ic xauth +authentication. +.Pp +The following are valid statements: +.Bl -tag -width Ds -compact +.It Ic version (2 | 3) ; +The ldap protocol version used to communicate with the server. +The default is +.Ic 3 . +.It Ic host Ar (hostname | address) ; +The host name or ip address of the ldap server. +The default is +.Ic localhost . +.It Ic port Ar number ; +The port that the ldap server is configured to listen on. +The default is +.Ic 389 . +.It Ic base Ar distinguished name ; +The ldap search base. +This option has no default value. +.It Ic subtree (on | off) ; +Use the subtree ldap search scope. +Otherwise, use the one level search scope. +The default is +.Ic off . +.It Ic bind_dn Ar distinguished name ; +The user dn used to optionally bind as before performing ldap search operations. +If this option is not specified, anonymous binds are used. +.It Ic bind_pw Ar string ; +The password used when binding as +.Ic bind_dn . +.It Ic attr_user Ar attribute name ; +The attribute used to specify a users name in an ldap directory. +For example, +if a user dn is "cn=jdoe,dc=my,dc=net" then the attribute would be "cn". +The default value is +.Ic cn . +.It Ic attr_addr Ar attribute name ; +.It Ic attr_mask Ar attribute name ; +The attributes used to specify a users network address and subnet mask in an +ldap directory. +These values are forwarded during mode_cfg negotiation when +the conf_source is set to ldap. +The default values are +.Ic racoon-address +and +.Ic racoon-netmask . +.It Ic attr_group Ar attribute name ; +The attribute used to specify a group name in an ldap directory. +For example, +if a group dn is "cn=users,dc=my,dc=net" then the attribute would be "cn". +The default value is +.Ic cn . +.It Ic attr_member Ar attribute name ; +The attribute used to specify group membership in an ldap directory. +The default value is +.Ic member . +.El +.El +.Ss Radius configuration settings +.Bl -tag -width Ds -compact +.It Ic radiuscfg { Ar statements Ic } +Defines the parameters that will be used to communicate with radius +servers for +.Ic xauth +authentication. +If radius is selected as the xauth authentication or accounting +source and no servers are defined in this section, settings from +the system +.Xr radius.conf 5 +configuration file will be used instead. +.Pp +The following are valid statements: +.Bl -tag -width Ds -compact +.It Ic auth Ar (hostname | address) [port] sharedsecret ; +The host name or ip address, optional port value and shared secret value +of a radius authentication server. +Up to 5 radius authentication servers +may be specified using multiple lines. +.It Ic acct Ar (hostname | address) [port] sharedsecret ; +The host name or ip address, optional port value and shared secret value +of a radius accounting server. +Up to 5 radius accounting servers may be +specified using multiple lines. +.It Ic timeout Ar seconds ; +The timeout for receiving replies from radius servers. +The default is +.Ic 3 . +.It Ic retries Ar count ; +The maximum number of repeated requests to make before giving up +on a radius server. +The default is +.Ic 3 . +.El +.El +.Ss Special directives +.Bl -tag -width Ds -compact +.It Ic complex_bundle (on | off) ; +defines the interpretation of proposal in the case of SA bundle. +Normally +.Dq IP AH ESP IP payload +is proposed as +.Dq 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 proposed as +.Dq AH transport and ESP tunnel . +The default value is +.Ic off . +.El +.\" +.Ss Pre-shared key File +The pre-shared key file defines pairs of identifiers and corresponding +shared secret keys which are used in the pre-shared key authentication +method in phase 1. +The pair in each line is separated by some number of blanks and/or tab +characters like in the +.Xr hosts 5 +file. +Key can include blanks because everything after the first blanks +is interpreted as the secret key. +Lines starting with +.Ql # +are ignored. +Keys which start with +.Ql 0x +are interpreted as hexadecimal strings. +Note that the file must be owned by the user ID running +.Xr racoon 8 +.Pq usually the privileged user , +and must not be accessible by others. +.\" +.Sh EXAMPLES +The following shows how the remote directive should be configured. +.Bd -literal -offset +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 ; +} +.Ed +.Pp +If you are configuring plain RSA authentication, the remote directive +should look like the following: +.Bd -literal -offset +path certificate "/usr/local/v6/etc" ; +remote anonymous +{ + exchange_mode main,base ; + lifetime time 12 hour ; + certificate_type plain_rsa "/usr/local/v6/etc/myrsakey.priv"; + peers_certfile plain_rsa "/usr/local/v6/etc/yourrsakey.pub"; + proposal { + encryption_algorithm aes ; + hash_algorithm sha1 ; + authentication_method rsasig ; + dh_group 2 ; + } +} +.Ed +.Pp +The following is a sample for the pre-shared key file. +.Bd -literal -offset +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 +.Ed +.\" +.Sh SEE ALSO +.Xr racoon 8 , +.Xr racoonctl 8 , +.Xr setkey 8 +.\" +.Sh HISTORY +The +.Nm +configuration file first appeared in the +.Dq YIPS +Yokogawa IPsec implementation. +.\" +.Sh BUGS +Some statements may not be handled by +.Xr racoon 8 +yet. +.Pp +Diffie-Hellman computation can take a very long time, and may cause +unwanted timeouts, specifically when a large D-H group is used. +.\" +.Sh SECURITY CONSIDERATIONS +The use of IKE phase 1 aggressive mode is not recommended, +as described in +.Li http://www.kb.cert.org/vuls/id/886601 . |