/etc/inet/ike/ikev2.config
The /etc/inet/ike/ikev2.config file contains rules for matching inbound IKE requests and preparing outbound IKEv2 requests. This file is logically part of the peer authentication database (PAD) as described in RFC 4301.
You can test the syntactic correctness of the IKEv2 configuration file and load the configuration file without starting the daemon by using the –c option of in.ikev2d (1M). You might need to use the –f option if it is not in /etc/inet/ike/ikev2.config .
For in.ikev2d to verify the identity of a peer using certificates, it must be able to verify the certificate that contains that identity. In the case of self-signed certificates, the public certificate of the peer must be loaded into the local system's IKEv2 certificate keystore. For CA signed certificates, the public certificate of the signing CA, and any intermediatory certificates, must be loaded into the local system's IKEv2 keystore. See ikev2cert(1M) for examples.
The ikev2.configpolicy file does not define certificate trust or validation policy. Instead, all certificates added to the local system's IKEv2 certificate keystore are trusted implicitly. Trust anchors and certificate validation policy are configured by invoking kmfcfg(1) to modify the IKEv2 specific KMF policy governing usage of the keystore. For additional details, see in.ikev2d(1M) , pktool(1) , and kmfcfg (1).
On any line, an unquoted # character introduces a comment. The remainder of that line is ignored. Additionally, on any line, an unquoted // sequence introduces a comment. The remainder of that line is ignored.
All keywords are case-sensitive.
There are several special types of lexical tokens in the ikev2.config file:
A decimal, hex, or octal number representation is as in C.
An IPv4 or IPv6 address with an optional /NNN suffix, (where NNN is a num) that indicates an address (CIDR) prefix (for example, 10.1.2.0/24). An optional /ADDR suffix (where ADDR is a second IP address) indicates an address/mask pair (for example, 10.1.2.0/255.255.255.0). An optional -ADDR suffix (where ADDR is a second IPv4 address) indicates an inclusive range of addresses (for example, 10.1.2.0-10.1.2.255 ). The / or - can be surrounded by an arbitrary amount of white space.
Either the words XXX, YYY, or ZZZ, for example, { yes | no}.
An IKEv2 identity type. The value of the id-type is checked to ensure that the format matches the type. For example, an EMAIL id-type must contain an @ character. IKEv2 identity types include:
An X.509 distinguished name in text format. For example, "C=US, O=Oracle, CN=Example Name"
A fully qualified domain name. A leading '.' might be used as a wildcard. For example, "myhost.example.com" or ".example.com".
An email address. An empty value before the '@' symbol indicates a wildcard. For example, "joe.example@mail.example.com" or "@example.com".
An IP address. Address ranges or prefixes might be used for wildcard matching. For example, "10.1.2.3", "10.0.1.1 - 10.0.1.15", or "0.0.0.0/0".
An IPv6 address. Address ranges or prefixes might be used for wildcard matching. For example, "fe80::1", "fe80::1 - fe80::12", or "::/0".
A key ID. Typically, this is the 160-bit hash of a certificate's public key. For example, "3f:a0:6a:a1:e6:73:6b:c8:d7:7b:4d:de:b8:b4:3d:5d:ff:26:69:80" .
An IKEv2 authentication method. IKEv2 authentication method values include:
Authenticate using pre-shared keys. Refer to the ikev2.preshared(4) man page.
Authenticate using a certificate signature. The signature method is determined automatically and might be any of the methods described below.
Authenticate using a RSA certificate signature.
Authenticate using a DSS certificate signature.
Authenticate using an ECDSA certificate signature with the SHA256 hash algorithm. The certificate must use a public key from the secp256r1 curve.
Authenticate using an ECDSA certificate signature with the SHA384 hash algorithm. The certificate must use a public key from the secp384r1 curve.
Authenticate using an ECDSA certificate signature with the SHA512 hash algorithm. The certificate must use a public key from the secp521r1 curve.
A quoted string.
Examples include:"Label foo", or "C=US, OU=Sun Microsystems\\, Inc., N=olemcd@eng.example.com"
A backslash (\) is an escape character. If the string needs an actual backslash, two must be specified.
There are four main types of entries:
IKEv2 SA transform defaults
IKEv2 SA transforms
IKEv2 rule defaults
IKEv2 rules
The IKEv2 SA transform defaults are as follows:
These values are used as defaults for all subsequent ikesa_xform entries in the file.
The default lifetime, in seconds, of an IKEv2 security association (SA).
An IKEv2 SA transform specifies a set of methods used to to protect and authenticate traffic for an IKEv2 security association, as well as additional parameters dependent on the security methods chosen.
During establishment of an IKEv2 SA, the initiator might offer several transforms; in this case, the responder will accept one of them, assuming it has at least one matching transform configured. The order of the transforms within this file determines the order of preference when multiple transforms are offered.
IKEv2 SA transforms may be configured globally, outside of any IKEv2 rule, or within an IKEv2 rule. Multiple transform entries at either scope accumulate. However, if any transforms are specified within an IKEv2 rule, that set of transforms overrides the globally defined transforms for that rule only.
Each IKEv2 rule must include at least one transform, either directly within the rule, or inherited from global definitions. Globally defined transforms must appear before any IKEv2 rules to which they should apply.
This is the format of an IKEv2 SA transform:
ikesa_xform { parameter-list }
The parameter-list is an unordered list of attribute value pairs. Unless specified as optional, attributes in the parameter-list must occur exactly once. The following attributes are defined:
The Oakley Diffie-Hellman group is used for IKEv2 SA key derivation. The group numbers are defined in RFC 2409, Appendix A, RFC 3526, RFC 4753, and RFC 5114.
The list of acceptable values may be retrieved by using the following command:
# ikeadm dump groups
An encryption algorithm.
The AES algorithm allows an optional key-size setting, using the syntax (low value to high value), the same as specified in ipsecconf(1M) for the keylenspecifier. To specify a single AES key size, the low value must equal the high value or single number must be used. If no range is specified, all key sizes are allowed.
The list of supported encryption algorithms may be retrieved using the following command:
# ikeadm dump encralgs
Note that the syntax described above uses abbreviated identifiers that omit the –cbc suffix.
An authentication algorithm.
The list of supported authentication algorithms can be retrieved by using the following command:
# ikeadm dump authalgs
Optional. The psuedo-random function to use. The same algorithms available for auth_algs may be used for prf. By default, the value specified for auth_alg will be used.
Optional. The psuedo-random function to use. The same algorithms available for auth_algs may be used for prf. By default, the value specified for auth_alg will be used.
Optional. The lifetime for the IKEv2 SA.
The following IKEv2 rule attributes can be prefigured by using file-level defaults. Values specified within any given rule override global defaults.
|
In each case, the usage and required arguments for these keywords is the same as inside an IKEv2 rule.
An IKEv2 rule describes a set of peer system's with which the IKEv2 service is allowed to establish IKEv2 SAs, along with the local identity and other parameters to be used with that set of peers.
When a new IPsec SA is requested by the kernel, or a peer system attempts to initiate an IKEv2 SA, the set of IKEv2 rules is searched in the order they were added. Initially, a rule is found by matching the IP/IPv6 addresses of the local and peer system's. If multiple matches are possible based on addresses, a different rule may be selected during authentication based on the peer's identity and the contents of any certificate request payloads.
At least one IKEv2 rule must be defined in the configuration file.
This is the format of an IKEv2 rule:
{ parameter-list }
The parameter-list is an unordered list of attributes, each with one or more additional parameters. The following attributes are valid within an IKEv2 rule:
Required parameter. The string is used to identify the IKEv2 rule when using various administrative interfaces, and in debugging output. Only one label parameter is allowed per rule.
Required parameter. The local address, address prefix, or address range for this rule. Multiple local_addr parameters accumulate within a given rule.
Required parameter. The remote address, address prefix, or address range for this rule. Multiple remote_addr parameters accumulate within a given rule.
Identifies the method to be used for both local and remote authentication during establishment of the IKEv2 SA. The values for auth-type are described in the Lexical Components section above. This attribute is required unless both local_auth_method and remote_auth_method are set, in which case it is disallowed.
Similar to auth_method, but identifies the method for authenticating the local system only.
Similar to auth_method, but identifies the method for authenticating the peer system only.
The local ID to use during authentication.
When local_auth_method is preshared, any valid id-type and value may be used. The id-type and value must match one of the remote_id parameters configured on the peer for authentication to succeed.
When local_auth_method uses certificates, local_id value will be used to select which certificate is used during authentication. There must be a certificate matching the value assigned to the id-type and the corresponding private key for this certificate present in the local system's IKEv2 keystore. The private key is used to generate the AUTH value in the IKEv2 protocol.
The receiving system will verify the AUTH value using the certificate identified here. This certificate may be sent to the peer during the IKEv2 protocol exchange (by default) or manually exchanged. See the cert_payload_limit parameter below for details.
The public certificates of the signing CAs and intermediaries also need to be present in the receiving system's IKEv2 keystore in order to verify the identity of the peer's certificate for the receiving system.
This attribute may occur any number of times within a rule. Multiple local_id attributes within a given rule accumulate. When pre-shared key authentication is in use, values beyond the first are not used. When certificate-based authentication is in use, all local_id values are considered. The best local_id is chosen using any certificate request payloads received from the peer and the remaining validity time of the relevant certificates.
If this attribute is omitted, the local IP address of the IKEv2 SA will be used as the local_id. In the case where the local system is behind a NAT, this will result in a local_id derived from the system's internal address, which is undesirable in most cases. For this reason, local_id should always be explicitly configured when NAT is in use.
The possible values for id-type and format of string are described above in the Lexical Components section.
The string values for local_id must not be wildcards.
The remote ID to use during authentication.
When remote_auth_method is preshared, any valid id-type and value may be used. The id-type and value must match one of the local_id parameters configured on the peer for authentication to succeed.
When remote_auth_method uses certificates, the remote ID will be used to select which certificate is used for authentication during IKEv2 SA establishment.
The peer may choose to send the certificate as a payload, in which case the remote ID value must be present in the certificate it sends. The public certificate of the signing CA also needs to be the local system's IKEV2 keystore so that it can verify the certificates signature.
If the peer system chooses not to send its certificate as a payload, the local system's IKEv2 keystore needs a copy of the peer's public certificate and the signing CA's certificate in order to verify its identity.
This attribute may occur any number of times within a rule. If it is omitted, the peer's IP address will be used to compute a default remote_id. Multiple remote_id attributes within a given rule accumulate. The identity asserted by the peer must match one of these values for the authentication to succeed.
The form remote_id ANY will allow any remote ID asserted by the peer. The identity still must be authenticated using certificates or pre-shared keys.
The possible values for id-type and format of string are described above in the Lexical Components section.
Require that the peer's certificate be signed by particular issuer. Self-signed certificates are considered to be their own issuers, and can pass this check. This directive provides an additional verification step. It does not allow self-signed certificates not present in the keystore to be trusted.
If multiple required_issuer attributes are provided, they accumulate with the IKE rule. A peer's certificate is acceptable if it was issued by any of the required_issuers.
This parameter may only be used within IKE rules that employ certificates for remote authentication.
Limit the number of certificate payloads sent during the IKEv2 AUTH exchange. By default, the local end-entity and all intermediate certificates are sent. Setting this attribute to 1 will cause only the end-entity certificate to be sent, while setting it to 0 will disable the sending of certificate payloads entirely. This attribute may be used to significantly reduce the amount of data exchanged during IKEv2 SA creation in the case where it is known that the peer system has some or all of the required certificates installed locally.
This attribute determines whether certificate request payloads are sent to the peer during the AUTH exchange. This parameter is optional, and useful only when the remote authentication method relies on certificates. The default value is yes.
Certificate payloads help the peer select which local identity and certificate to use during authentication. By including this payload, the public key hashes of the trust-anchors in the local keystore are disclosed to the peer before the peer's identity has been authenticated.
Depending on the configuration, enabling certificate request payloads may allow untrusted third parties to gather information about the set of locally configured trust-anchors. This is especially true when this attribute is set to yes.
This attribute determines whether to allow the peer system to use HTTP (aka. hash and URL) certificate payloads during authentication. If this value is set and the peer sends HTTP certificate payloads during authentication, the IKEv2 daemon will retrieve certificates from the URLs specified and cache them locally.
Unlike other credentials exchanged during IKEv2 authentication, certificates downloaded via HTTP are not protected by the encryption mechanism of the IKEv2 SA.
Because certificate payload processing is performed before authentication is complete, enabling this option allows any remote system matching the rule's remote_addr attribute to cause in.ikev2d to download any arbitrary URL. Reasonable size limitations are enforced on the downloaded file.
The default value is no.
This attribute specifies the prefix to prepend to a certificate's SHA1 hash value when generating URLs for HTTP (aka. hash and URL) certificate payloads. If this value is set and the peer system supports HTTP certificate payloads, the IKEv2 daemon will send an HTTP URL and confirmation hash in each certificate payload, rather than embedding the entire certificate. This reduces the size of IKEv2 protocol packets and helps to prevent fragmentation.
It is the administrator's responsibility to make sure that certificates are available for download at the generated URLs. For example, a system using a local cert with label=mycert in the keystore with SHA1 hash "3dc0279b27cd6b2d0bbc01c917d3f03dbed5d352 " and cert_base_url = "http://pki.example.com/certs/" would send a URL that is the concatenation of those two values. It would be necessary to extract the public certificate mycert and store the file on the web server pki.example.com, in the certs subdirectory, with filename equal to the sha1 hash value of the certificate.
Certificates files intended for use with HTTP certificate payloads must be in ASN.1 DER format. Use the outformat=der option when exporting certificates using ikev2cert to produce files in the correct format.
The following command may be used to generate the SHA1 hash of a certificate in the correct format to be used as the certificate's file name. This example uses certificate label=mycert .
ikev2cert list objtype=cert label=mycert | \
@ + nawk 'BEGIN {f=0} /SHA1 Cert/ {f=1;next}; \
@ + {if (f) { gsub(/:/,""); print $1; } f=0}'
Optional. The time in seconds after creation during which this IKEv2 SA may be rekeyed. After this time, a IEv2 SA must be created.
Optional. Determines the lifetime, in seconds or KB, of all IPsec SAs created using IKEv2 SAs established under this rule.
Optional. Determines the soft lifetime, in seconds or KB, of all IPsec SAs created using IKEv2 SAs established under this rule. Once this value is depleted, the IKEv2 service will rekey the IPsec SA if possible.
Optional. Determines the idle time in seconds for all IPsec SAs created using IKEv2 SAs established under this rule. IPsec SAs that are idle will not be rekeyed when their soft lifetime expires.
Optional. Enables perfect forward secrecy for IPsec SA creation. If selected, the Oakley group specified is used for PFS. Acceptable values are the same as for the dh_group parameter listed above. The value of auto may be used, in which case the same dh_group negotiated during IKEv2 SA establishment will be used.
Specifies an IKEv2 SA transform specifically for this IKEv2 rule. Transforms defined within an IKEv2 rule accumulate and override any globally defined transforms. Refer the IKEv2 SA transforms section above for additional details.
The following is an example of an ikev2.config file:
### BEGINNING OF FILE
#
# This default value will apply to all transforms that follow
#
ikesa_lifetime_secs 3600
#
# Global transform definitions. The algorithms choices are
# based on RFC 4921.
#
# Group 20 is 384-bit ECP
ikesa_xform { encr_alg aes(256..256) auth_alg sha384 dh_group 20 }
# Group 19 is 256-bit ECP
ikesa_xform { encr_alg aes(128..128) auth_alg sha256 dh_group 19 }
#
# Basic example rules using pre-shared keys. For these rules to
# function, the file /etc/inet/ike/ikev2.preshared must be
# populated with pre-shared keys for the local and remote
# addresses.
#
# In the next three examples, local_id and remote_id have
# been omitted, and will default to the actual addresses in
# use between the local system and the peer.
#
{
label "IP identities and PSK auth"
auth_method preshared
local_addr 10.0.0.1
remote_addr 10.0.0.2
}
{
label "IP address prefixes and PSK auth"
auth_method preshared
# Any of our IP addresses
local_addr 0.0.0.0/0
# Any peer on either of two subnets
remote_addr 10.0.0.0/24
remote_addr 10.1.0.0/24
}
{
label "IPv6 address prefixes and PSK auth"
auth_method preshared
# Any of our IPv6 addresses
local_addr ::/0
# Any peer on our WAN
remote_addr fd23:0738:dc9d::/48
}
#
# Example rules using certificates and a wide range of ID
# types. For these rules to function, certificates must be
# present in the PKCS#11 softtoken keystore for user
# ikeuser. For local identities, certificate and private
# keys must be present. In order to valididate peer
# identities, the appropriate trust anchors must be
# configured for CA signed certificates. Any self-signed
# end-entity certificates must be present in the keystore or
# they will not be trusted.
#
{
label "Certificate auth with DN identities"
# Any type of certificate signature is allowed
auth_method cert
local_addr 10.0.0.1
remote_addr 10.2.0.0/24
local_id DN = "C=US, O=Oracle, CN=Example IKEv2 Local"
remote_id DN = "C=US, O=Oracle, CN=Example IKEv2 Peer1"
}
{
label "Certificate auth with many peer ID types"
# Any type of certificate signature is allowed
auth_method cert
local_addr 10.0.0.1
remote_addr 10.3.0.0/24
local_id DN = "C=US, O=Oracle, CN=Example IKEv2 Local"
# Certificates will be searched based on which ID the peer
# asserts.
remote_id DN = "C=US, O=Oracle, CN=Example IKEv2 Peer2"
remote_id EMAIL = "jack@example.com"
remote_id EMAIL = "jill@example.com"
remote_id FQDN = "generic.example.com"
remote_id IP = "10.3.200.42"
# The identies used for AUTH are divorced from the type of
# address used to communicate
remote_id IPV6 = "fd23:0738:dc9d:1:1:2:3:4"
remote_id KEYID =
"3f:a0:6a:a1:e6:73:6b:c8:d7:7b:4d:de:b8:b4:3d:5d:ff:26:69:80"
}
{
label "Certificate auth with wildcard peer IDs"
auth_method cert
local_addr 10.0.0.1
remote_addr 10.4.0.0/24
# Wildcard local IDs are not allowed
local_id DN = "C=US, O=Oracle, CN=Example IKEv2 Local"
# Any email address in the example.com domain
remote_id EMAIL = "@example.com"
# Any subdomain of example.com
remote_id FQDN = ".example.com"
# Any IP identity in the 10.4.x.y subnet
remote_id IP = "10.4.0.0/16"
# Any IPv6 address in the fd23:0738:dc9d:2:: subnet
remote_id IPV6 = "fd23:0738:dc9d:2::/64"
}
#
# This example shows how to override the transform list for
# a rule. In this example, the peer doesn't support ECDH so
# we need to fall back. We also want to ensure the use of
# RSA signature authentication.
#
{
label "Override transforms"
auth_method rsa_sig
local_addr 10.0.0.1
remote_addr 10.5.1.13
local_id DN = "C=US, O=Oracle, CN=Example IKEv2 Local"
remote_id DN = "C=US, O=Oracle, CN=Deficient IKEv2 Peer"
# Override the globally defined ikesa_xform list
# Group 16 is 4096-bit MODP
ikesa_xform { encr_alg aes(128..256) auth_alg sha1 dh_group 16 }
# Group 14 is 2048-bit MODP
ikesa_xform { encr_alg aes(128..256) auth_alg sha1 dh_group 14 }
# Group 2 is 1024-bit MODP
ikesa_xform { encr_alg aes(128..256) auth_alg sha1 dh_group 2 }
}
#
# This example shows how to mix authentication types. The
# local system will use a pre-shared key to authenticate to
# the peer, while the peer's identity will be authenticated
# using a DSS certificate signature.
#
{
label "Mixed auth types"
local_auth_method preshared
remote_auth_method dss_sig
local_addr 10.0.0.1
remote_addr 10.6.0.0/16
# Pre-shared key auth can be used with any ID type.
local_id EMAIL = "jack@example.com"
remote_id EMAIL = "jill@example.com"
}
#
# This example shows how to use the generic wildcard ID as well
# as the required_issuer attribute. In this case, we will
# allow any peer on a remote subnet to connect so long as
# that peer presents a certificate issued by the signer.
#
{
label "Wildcard with required signer"
local_auth_method cert
remote_auth_method cert
local_addr 10.0.0.1
remote_addr 10.7.0.0/16
local_id DN = "C=US, O=Oracle, CN=Example IKEv2 Local"
# Match any remote_id regardless of type
remote_id ANY
required_issuer DN = "C=US, O=Oracle, CN=Example IPsec Cert Signer"
}
See attributes(5) for descriptions of the following attributes:
|
cryptoadm(1M) , ikeadm(1M) , ikev2.preshared(4), in.ikev2d(1M) , ipseckey (1M), ipsecalgs(1M) , ipsecconf (1M), pktool(1), kmfcfg(1), svccfg(1M) , attributes (5), labels(5)