2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
5 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH IKE.CONFIG 4 "Apr 27, 2009"
8 ike.config \- configuration file for IKE policy
12 \fB/etc/inet/ike/config\fR
18 The \fB/etc/inet/ike/config\fR file contains rules for matching inbound IKE
19 requests. It also contains rules for preparing outbound \fBIKE\fR requests.
22 You can test the syntactic correctness of an \fB/etc/inet/ike/config\fR file by
23 using the \fB-c\fR or \fB-f\fR options of \fBin.iked\fR(1M). You must use the
24 \fB-c\fR option to test a \fBconfig\fR file. You might need to use the \fB-f\fR
25 option if it is not in \fB/etc/inet/ike/config\fR.
26 .SS "Lexical Components"
29 On any line, an unquoted \fB#\fR character introduces a comment. The remainder
30 of that line is ignored. Additionally, on any line, an unquoted \fB//\fR
31 sequence introduces a comment. The remainder of that line is ignored.
34 There are several types of lexical tokens in the \fBike.config\fR file:
42 A decimal, hex, or octal number representation is as in 'C'.
48 \fB\fIIPaddr\fR/\fIprefix\fR/\fIrange\fR\fR
52 An IPv4 or IPv6 address with an optional /\fINNN\fR suffix, (where \fINNN\fR is
53 a \fInum\fR) that indicates an address (\fBCIDR\fR) prefix (for example,
54 \fB10.1.2.0/24\fR). An optional /\fIADDR\fR suffix (where \fIADDR\fR is a
55 second IP address) indicates an address/mask pair (for example,
56 \fB10.1.2.0/255.255.255.0\fR). An optional -\fIADDR\fR suffix (where \fIADDR\fR
57 is a second IPv4 address) indicates an inclusive range of addresses (for
58 example, \fB10.1.2.0-10.1.2.255\fR). The \fB/\fR or \fB-\fR can be surrounded
59 by an arbitrary amount of white space.
65 \fB\fBXXX\fR | \fBYYY\fR | \fBZZZ\fR\fR
69 Either the words \fBXX\fRX, \fBYYY\fR, or \fBZZZ\fR, for example, {yes,no}.
79 An IKE phase 1 identity type. IKE phase 1 identity types include:
137 \fB\fB"\fR\fIstring\fR\fB"\fR\fR
143 Examples include:\fB"Label foo"\fR, or \fB"C=US, OU=Sun Microsystems\\, Inc.,
144 N=olemcd@eng.example.com"\fR
146 A backslash (\fB\e\fR) is an escape character. If the string needs an actual
147 backslash, two must be specified.
157 A certificate selector, a \fIstring\fR which specifies the identities of zero
158 or more certificates. The specifiers can conform to \fBX.509\fR naming
161 A \fIcert-sel\fR can also use various shortcuts to match either subject
162 alternative names, the filename or \fBslot\fR of a certificate in
163 \fB/etc/inet/ike/publickeys\fR, or even the \fBISSUER\fR. For example:
168 "EMAIL=postmaster@domain.org"
169 "webmaster@domain.org" # Some just work w/o TYPE=
171 "10.21.11.11" # Some just work w/o TYPE=
173 "mailhost.domain.org" # Some just work w/o TYPE=
174 "ISSUER=C=US, O=Sun Microsystems\\, Inc., CN=Sun CA"
179 Any \fIcert-sel\fR preceded by the character \fB!\fR indicates a negative
180 match, that is, not matching this specifier. These are the same kind of strings
181 used in \fBikecert\fR(1M).
187 \fB\fIldap-list\fR\fR
191 A quoted, comma-separated list of LDAP servers and ports.
193 For example, \fB"ldap1.example.com"\fR, \fB"ldap1.example.com:389"\fR,
194 \fB"ldap1.example.com:389,ldap2.example.com"\fR.
196 The default port for LDAP is \fB389\fR.
202 \fB\fIparameter-list\fR\fR
206 A list of parameters.
209 .SS "File Body Entries"
212 There are four main types of entries:
223 IKE phase 1 transform defaults
239 The global parameter entries are as follows:
243 \fBcert_root \fIcert-sel\fR\fR
247 The X.509 distinguished name of a certificate that is a trusted root CA
248 certificate.It must be encoded in a file in the \fB/etc/inet/ike/publickeys\fR
249 directory. It must have a CRL in \fB/etc/inet/ike/crl\fRs. Multiple
250 \fBcert_root\fR parameters aggregate.
256 \fBcert_trust \fIcert-sel\fR\fR
260 Specifies an X.509 distinguished name of a certificate that is self-signed, or
261 has otherwise been verified as trustworthy for signing IKE exchanges. It must
262 be encoded in a file in \fB/etc/inet/ike/publickeys\fR. Multiple
263 \fBcert_trust\fR parameters aggregate.
269 \fBexpire_timer \fIinteger\fR\fR
273 The number of seconds to let a not-yet-complete IKE Phase I (Main Mode)
274 negotiation linger before deleting it. Default value: 300 seconds.
284 If this keyword is present in the file, \fBin.iked\fR(1M) ignores Certificate
285 Revocation Lists (\fBCRL\fRs) for root \fBCA\fRs (as given in \fBcert_root\fR)
291 \fBldap_server \fIldap-list\fR\fR
295 A list of LDAP servers to query for certificates. The list can be additive.
301 \fBpkcs11_path \fIstring\fR\fR
305 The string that follows is a name of a shared object (\fB\&.so\fR) that
306 implements the PKCS#11 standard. The name is passed directly into
307 \fBdlopen\fR(3C) for linking, with all of the semantics of that library call.
308 By default, \fBin.iked\fR(1M) runs the same ISA as the running kernel, so a
309 library specified using \fBpkcs11_path\fR and an absolute pathname \fBmust\fR
310 match the same ISA as the kernel. One can use the start/exec SMF property (see
311 \fBsvccfg\fR(1M)) to change \fBin.iked\fR's ISA, but it is not recommended.
313 If this setting is not present, the default value is set to \fBlibpkcs11.so\fR.
314 Most cryptographic providers go through the default library, and this parameter
315 should only be used if a specialized provider of IKE-useful cryptographic
316 services cannot interface with the Solaris Cryptographic Framework. See
319 This option is now deprecated, and may be removed in a future release.
325 \fBretry_limit \fIinteger\fR\fR
329 The number of retransmits before any IKE negotiation is aborted. Default value:
336 \fBretry_timer_init \fIinteger\fR or \fIfloat\fR\fR
340 The initial interval (in seconds) between retransmits. This interval is doubled
341 until the \fBretry_timer_max\fR value (see below) is reached. Default value:
348 \fBretry_timer_max \fIinteger\fR or \fIfloat\fR\fR
352 The maximum interval (in seconds) between retransmits. The doubling retransmit
353 interval stops growing at this limit. Default value: 30 seconds.
358 This value is never reached with the default configuration. The longest
359 interval is 8 (0.5 * 2 ^ (5 - 1)) seconds.
366 \fBproxy \fIstring\fR\fR
370 The string following this keyword must be a URL for an HTTP proxy, for example,
371 \fBhttp://proxy:8080\fR.
377 \fBsocks \fIstring\fR\fR
381 The string following this keyword must be a URL for a SOCKS proxy, for example,
382 \fBsocks://socks-proxy\fR.
392 If this keyword is present in the file, \fBin.iked\fR(1M) uses HTTP to retrieve
393 Certificate Revocation Lists (\fBCRL\fRs).
398 The following IKE phase 1 transform parameters can be prefigured using
399 file-level defaults. Values specified within any given transform override these
403 The IKE phase 1 transform defaults are as follows:
407 \fBp1_lifetime_secs \fInum\fR\fR
411 The proposed default lifetime, in seconds, of an IKE phase 1 security
412 association (\fBSA\fR).
418 \fBp1_nonce_len \fInum\fR\fR
422 The length in bytes of the phase 1 (quick mode) nonce data. This cannot be
423 specified on a per-rule basis.
428 The following IKE rule parameters can be prefigured using file-level defaults.
429 Values specified within any given rule override these defaults, unless a rule
434 \fBp2_lifetime_secs \fInum\fR\fR
438 The proposed default lifetime, in seconds, of an IKE phase 2 security
439 association (SA). This value is optional. If omitted, a default value is used.
445 \fBp2_softlife_secs \fInum\fR\fR
449 The soft lifetime of a phase 2 SA, in seconds. If this value is specified, the
450 SA soft expires after the number of seconds specified by
451 \fBp2_softlife_secs\fR. This causes \fBin.iked\fR to renegotiate a new phase 2
452 SA before the original SA expires.
454 This value is optional, if omitted soft expiry occurs after 90% of the lifetime
455 specified by \fBp2_lifetime_secs\fR. The value specified by
456 \fBp2_softlife_secs\fR is ignored if \fBp2_lifetime_secs\fR is not specified.
458 Setting \fBp2_softlife_secs\fR to the same value as \fBp2_lifetime_secs\fR
459 disables soft expires.
465 \fBp2_idletime_secs \fInum\fR\fR
469 The idle lifetime of a phase 2 SA, in seconds. If the value is specified, the
470 value specifies the lifetime of the SA, if the security association is not used
471 before the SA is revalidated.
477 \fBp2_lifetime_kb \fInum\fR\fR
481 The lifetime of an SA can optionally be specified in kilobytes. This parameter
482 specifies the default value. If lifetimes are specified in both seconds and
483 kilobytes, the SA expires when either the seconds or kilobyte threshholds are
490 \fBp2_softlife_kb \fInum\fR\fR
494 This value is the number of kilobytes that can be protected by an SA before a
495 soft expire occurs (see \fBp2_softlife_secs\fR, above).
497 This value is optional. If omitted, soft expiry occurs after 90% of the
498 lifetime specified by \fBp2_lifetime_kb\fR. The value specified by
499 \fBp2_softlife_kb\fR is ignored if \fBp2_lifetime_kb\fR is not specified.
505 \fBp2_nonce_len \fInum\fR\fR
509 The length in bytes of the phase 2 (quick mode) nonce data. This cannot be
510 specified on a per-rule basis.
516 \fBlocal_id_type \fIp1-id-type\fR\fR
520 The local identity for IKE requires a type. This identity type is reflected in
521 the IKE exchange. The type can be one of the following:
526 an IP address (for example, \fB10.1.1.2\fR)
532 DNS name (for example, \fBtest.domain.com\fR)
538 MBOX RFC 822 name (for example, \fBroot@domain.com\fR)
544 DNX.509 distinguished name (for example, \fBC=US, O=Sun Microsystems\, Inc.,
552 \fBp1_xform '{' parameter-list '}\fR
556 A phase 1 transform specifies a method for protecting an IKE phase 1 exchange.
557 An initiator offers up lists of phase 1 transforms, and a receiver is expected
558 to only accept such an entry if it matches one in a phase 1 rule. There can be
559 several of these, and they are additive. There must be either at least one
560 phase 1 transform in a rule or a global default phase 1 transform list. In a
561 configuration file without a global default phase 1 transform list \fBand\fR a
562 rule without a phase, transform list is an invalid file. Unless specified as
563 optional, elements in the parameter-list must occur exactly once within a given
564 transform's parameter-list:
568 \fBoakley_group \fInumber\fR\fR
572 The Oakley Diffie-Hellman group used for IKE SA key derivation. The group
573 numbers are defined in RFC 2409, Appendix A, and RFC 3526. Acceptable values
604 \fBencr_alg {3des, 3des-cbc, blowfish, blowfish-cdc, des, des-cbc, aes,
609 An encryption algorithm, as in \fBipsecconf\fR(1M). However, of the ciphers
610 listed above, only \fBaes\fR and \fBaes-cbc\fR allow optional key-size setting,
611 using the "low value-to-high value" syntax. To specify a single AES key size,
612 the low value must equal the high value. If no range is specified, all three
613 AES key sizes are allowed.
619 \fBauth_alg {md5, sha, sha1, sha256, sha384, sha512}\fR
623 An authentication algorithm.
625 Use \fBipsecalgs\fR(1M) with the \fB-l\fR option to list the IPsec protocols
626 and algorithms currently defined on a system. The \fBcryptoadm list\fR command
627 diplays a list of installed providers and their mechanisms. See
634 \fBauth_method {preshared, rsa_sig, rsa_encrypt, dss_sig}\fR
638 The authentication method used for IKE phase 1.
644 \fBp1_lifetime_secs \fInum\fR\fR
648 Optional. The lifetime for a phase 1 SA.
656 \fBp2_lifetime_secs \fInum\fR\fR
660 If configuring the kernel defaults is not sufficient for different tasks, this
661 parameter can be used on a per-rule basis to set the IPsec \fBSA\fR lifetimes
668 \fBp2_pfs \fInum\fR\fR
672 Use perfect forward secrecy for phase 2 (quick mode). If selected, the oakley
673 group specified is used for phase 2 PFS. Acceptable values are:
676 0 (do not use Perfect Forward Secrecy for IPsec SAs)
706 An IKE rule starts with a right-curly-brace (\fB{\fR), ends with a
707 left-curly-brace (\fB}\fR), and has the following parameters in between:
711 \fBlabel \fIstring\fR\fR
715 Required parameter. The administrative interface to \fBin.iked\fR looks up
716 phase 1 policy rules with the label as the search string. The administrative
717 interface also converts the label into an index, suitable for an extended
718 ACQUIRE message from PF_KEY - effectively tying IPsec policy to IKE policy in
719 the case of a node initiating traffic. Only one \fBlabel\fR parameter is
726 \fBlocal_addr <\fIIPaddr\fR/\fIprefix\fR/\fIrange\fR>\fR
730 Required parameter. The local address, address prefix, or address range for
731 this phase 1 rule. Multiple \fBlocal_addr\fR parameters accumulate within a
738 \fBremote_addr <\fIIPaddr\fR/\fIprefix\fR/\fIrang\fRe>\fR
742 Required parameter. The remote address, address prefix, or address range for
743 this phase 1 rule. Multiple \fBremote_addr\fR parameters accumulate within a
750 \fBlocal_id_type \fIp1-id-type\fR\fR
754 Which phase 1 identity type I uses. This is needed because a single certificate
755 can contain multiple values for use in IKE phase 1. Within a given rule, all
756 phase 1 transforms must either use preshared or non-preshared authentication
757 (they cannot be mixed). For rules with preshared authentication, the
758 \fBlocal_id_type\fR parameter is optional, and defaults to \fBIP\fR. For rules
759 which use non-preshared authentication, the 'local_id_type' parameter is
760 required. Multiple 'local_id_type' parameters within a rule are not allowed.
766 \fBlocal_id \fIcert-sel\fR\fR
770 Disallowed for preshared authentication method; required parameter for
771 non-preshared authentication method. The local identity string or certificate
772 selector. Only one local identity per rule is used, the first one stated.
778 \fBremote_id \fIcert-sel\fR\fR
782 Disallowed for preshared authentication method; required parameter for
783 non-preshared authentication method. Selector for which remote phase 1
784 identities are allowed by this rule. Multiple \fBremote_id\fR parameters
785 accumulate within a given rule. If a single empty string (\fB""\fR) is given,
786 then this accepts any remote \fBID\fR for phase 1. It is recommended that
787 certificate trust chains or address enforcement be configured strictly to
788 prevent a breakdown in security if this value for \fBremote_id\fR is used.
794 \fBp2_lifetime_secs \fInum\fR\fR
798 If configuring the kernel defaults is not sufficient for different tasks, this
799 parameter can be used on a per-rule basis to set the IPsec \fBSA\fR lifetimes
806 \fBp2_pfs \fInum\fR\fR
810 Use perfect forward secrecy for phase 2 (quick mode). If selected, the oakley
811 group specified is used for phase 2 PFS. Acceptable values are:
814 0 (do not use Perfect Forward Secrecy for IPsec SAs)
845 \fBp1_xform \fB{\fR \fIparameter-list\fR \fB}\fR\fR
849 A phase 1 transform specifies a method for protecting an IKE phase 1 exchange.
850 An initiator offers up lists of phase 1 transforms, and a receiver is expected
851 to only accept such an entry if it matches one in a phase 1 rule. There can be
852 several of these, and they are additive. There must be either at least one
853 phase 1 transform in a rule or a global default phase 1 transform list. A
854 \fBike.config\fR file without a global default phase 1transform list \fBand\fR
855 a rule without a phase 1 transform list is an invalid file. Elements within the
856 parameter-list; unless specified as optional, must occur exactly once within a
857 given transform's parameter-list:
861 \fBoakley_group \fInumber\fR\fR
865 The Oakley Diffie-Hellman group used for \fBIKE SA\fR key derivation.
866 Acceptable values are currently:
896 \fBencr_alg {3des, 3des-cbc, blowfish, blowfish-cdc, des, des-cbc, aes,
901 An encryption algorithm, as in \fBipsecconf\fR(1M). However, of the ciphers
902 listed above, only \fBaes\fR and \fBaes-cbc\fR allow optional key-size setting,
903 using the "low value-to-high value" syntax. To specify a single AES key size,
904 the low value must equal the high value. If no range is specified, all three
905 AES key sizes are allowed.
911 \fBauth_alg {md5, sha, sha1}\fR
915 An authentication algorithm, as specified in \fBipseckey\fR(1M).
921 \fBauth_method {preshared, rsa_sig, rsa_encrypt, dss_sig}\fR
925 The authentication method used for IKE phase 1.
931 \fBp1_lifetime_secs \fInum\fR\fR
935 Optional. The lifetime for a phase 1 SA.
942 \fBExample 1 \fRA Sample \fBike.config\fR File
945 The following is an example of an \fBike.config\fR file:
951 ### BEGINNING OF FILE
953 ### First some global parameters...
955 ### certificate parameters...
957 # Root certificates. I SHOULD use a full Distinguished Name.
958 # I must have this certificate in my local filesystem, see ikecert(1m).
959 cert_root "C=US, O=Sun Microsystems\\, Inc., CN=Sun CA"
961 # Explicitly trusted certs that need no signatures, or perhaps
962 # self-signed ones. Like root certificates, use full DNs for them
964 cert_trust "EMAIL=root@domain.org"
966 # Where do I send LDAP requests?
967 ldap_server "ldap1.domain.org,ldap2.domain.org:389"
969 ## phase 1 transform defaults...
971 p1_lifetime_secs 14400
974 ## Parameters that might also show up in rules.
976 p1_xform { auth_method preshared oakley_group 5 auth_alg sha
982 ### Now some rules...
985 label "simple inheritor"
991 label "simple inheritor IPv6"
993 local_addr fe80::a00:20ff:fe7d:6
994 remote_addr fe80::a00:20ff:fefb:3780
998 # an index-only rule. If I'm a receiver, and all I
999 # have are index-only rules, what do I do about inbound IKE requests?
1000 # Answer: Take them all!
1002 label "default rule"
1003 # Use whatever "host" (e.g. IP address) identity is appropriate
1006 local_addr 0.0.0.0/0
1007 remote_addr 0.0.0.0/0
1011 # Now I'm going to have the p1_xforms
1013 {auth_method preshared oakley_group 5 auth_alg md5 encr_alg \e
1015 {auth_method preshared oakley_group 5 auth_alg md5 encr_alg 3des }
1017 # After said list, another keyword (or a '}') stops xform
1022 # Let's try something a little more conventional.
1024 label "host to .80 subnet"
1026 local_id "10.1.86.51"
1028 remote_id "" # Take any, use remote_addr for access control.
1030 local_addr 10.1.86.51
1031 remote_addr 10.1.80.0/24
1034 { auth_method rsa_sig oakley_group 5 auth_alg md5 encr_alg 3des }
1036 { auth_method rsa_sig oakley_group 5 auth_alg md5 encr_alg \e
1039 { auth_method rsa_sig oakley_group 5 auth_alg sha1 encr_alg 3des }
1041 { auth_method rsa_sig oakley_group 5 auth_alg sha1 encr_alg \e
1046 # Let's try something a little more conventional, but with ipv6.
1048 label "host to fe80::/10 subnet"
1050 local_id "fe80::a00:20ff:fe7d:6"
1052 remote_id "" # Take any, use remote_addr for access control.
1054 local_addr fe80::a00:20ff:fe7d:6
1055 remote_addr fe80::/10
1058 { auth_method rsa_sig oakley_group 5 auth_alg md5 encr_alg 3des }
1060 { auth_method rsa_sig oakley_group 5 auth_alg md5 encr_alg \e
1063 { auth_method rsa_sig oakley_group 5 auth_alg sha1 encr_alg \e
1066 { auth_method rsa_sig oakley_group 5 auth_alg sha1 encr_alg \e
1071 # How 'bout something with a different cert type and name?
1073 label "punchin-point"
1075 local_id "ipsec-wizard@domain.org"
1077 remote_id "10.5.5.128"
1079 local_addr 0.0.0.0/0
1080 remote_addr 10.5.5.128
1083 { auth_method rsa_sig oakley_group 5 auth_alg md5 encr_alg \e
1088 label "receiver side"
1090 remote_id "ipsec-wizard@domain.org"
1093 local_id "10.5.5.128"
1095 local_addr 10.5.5.128
1096 remote_addr 0.0.0.0/0
1099 { auth_method rsa_sig oakley_group 5 auth_alg md5 encr_alg blowfish }
1100 # NOTE: Specifying preshared null-and-voids the remote_id/local_id
1103 { auth_method preshared oakley_group 5 auth_alg md5 encr_alg \e
1113 See \fBattributes\fR(5) for descriptions of the following attributes:
1121 ATTRIBUTE TYPE ATTRIBUTE VALUE
1123 Interface Stability Committed
1129 \fBcryptoadm\fR(1M), \fBikeadm\fR(1M), \fBin.iked\fR(1M), \fBikecert\fR(1M),
1130 \fBipseckey\fR(1M), \fBipsecalgs\fR(1M), \fBipsecconf\fR(1M), \fBsvccfg\fR(1M),
1131 \fBdlopen\fR(3C), \fBattributes\fR(5), \fBrandom\fR(7D)
1134 Harkins, Dan and Carrel, Dave. \fIRFC 2409, Internet Key Exchange (IKE)\fR.
1135 Cisco Systems, November 1998.
1138 Maughan, Douglas et. al. \fIRFC 2408, Internet Security Association and Key
1139 Management Protocol (ISAKMP)\fR. National Security Agency, Ft. Meade, MD.
1143 Piper, Derrell. \fIRFC 2407, The Internet IP Security Domain of Interpretation
1144 for ISAKMP\fR. Network Alchemy. Santa Cruz, California. November 1998.
1147 Kivinen, T. \fIRFC 3526, More Modular Exponential (MODP) Diffie-Hellman Groups
1148 for Internet Key Exchange (IKE)\fR. The Internet Society, Network Working