IkeConfig statement

If you code more than one IkeConfig statement, the last statement is used. Likewise, if a parameter other than SMF119 or SupportedCertAuth in the IkeConfig statement is specified more than once, the value from the last statement is used. SMF119 adds to, but does not replace, the types of SMF records to be written. SupportedCertAuth is used to define a set of certificate authorities (CAs) this value adds to, but does not replace, the list of CAs supported by a local security endpoint.

Parameters

IkeSyslogLevel

Specifies the level of logging to obtain from the IKE daemon. The following levels are supported:

0 - IKE_SYSLOG_LEVEL_NONE

Disable IKE daemon syslog messages

1 - IKE_SYSLOG_LEVEL_MINIMUM

Minimal IKE daemon syslog output

2 - IKE_SYSLOG_LEVEL_SADETAIL

Always output detailed Security Association (SA) information when available

4 - IKE_SYSLOG_LEVEL_DEBUGSA

Debug for SA negotiations

8 - IKE_SYSLOG_LEVEL_FMTPKTTRC

Formatted packet trace

16 - IKE_SYSLOG_LEVEL_UNFPKTTRC

Unformatted packet trace

32 - IKE_SYSLOG_LEVEL_VERBOSE

Show cascaded error messages

64 - IKE_SYSLOG_LEVEL_CERTINFO

Show certificates in CA cache when cache is initially built or rebuilt

128

Reserved

To specify a combination of log levels, add the level numbers. For example, to request FMTPKTTRC (8) messages and VERBOSE (32) messages, specify IkeSyslogLevel 40. Use the MODIFY IKED,REFRESH command to change this value. Level values greater than 1 are intended for diagnostic purposes only. A non-zero PagentSyslogLevel will take effect only if IkeSyslogLevel is also set to a non-zero value, otherwise no debug trace records are generated.

Rules:

• The default IkeSyslogLevel is in effect until the parameter is read from the configuration file.
• Any level higher than 1 automatically includes 1.

PagentSyslogLevel

Specifies the level of diagnostic logging to obtain for the interaction between the IKE daemon and the Policy Agent. The following levels are supported:

0 - PAGENT_SYSLOG_LEVEL_NONE

No logging of IKE daemon interactions with the Policy Agent.

1 - PAGENT_SYSLOG_LEVEL_EMERG

A panic condition

2 - PAGENT_SYSLOG_LEVEL_ALERT

Requires immediate action

4 - PAGENT_SYSLOG_LEVEL_CRIT

Critical condition

8 - PAGENT_SYSLOG_LEVEL_ERR

Error messages

16 - PAGENT_SYSLOG_LEVEL_WARNING

Warning messages

32 - PAGENT_SYSLOG_LEVEL_NOTICE

Conditions that are not error conditions, but might require special handling

64 - PAGENT_SYSLOG_LEVEL_INFO

Informational messages

128 - PAGENT_SYSLOG_LEVEL_DEBUG

Messages that contain information normally of use only when debugging a program

To specify a combination of log levels, add the level numbers. For example, to request LEVEL_EMERG (1) messages and LEVEL_WARNING (16) messages, specify PagentSyslogLevel 17. Use the MODIFY IKED,REFRESH command to change this value. Level values greater than 0 are intended for diagnostic purposes only. A non-zero PagentSyslogLevel will take effect only if IkeSyslogLevel is also set to a non-zero value, otherwise no debug trace records will be generated.

SMF119

Specifies the types of SMF 119 records to be written to the MVS™ SMF data sets. The following levels are supported:

None

No SMF 119 records should be written to the MVS SMF data sets. This is the default.

IKEAll

All SMF 119 records should be written to the MVS SMF data sets. This setting includes all of the SMF 119 record types listed in this topic.

IKETunnel

SMF record type 119 subtypes related to phase 1 SA events should be written (subtypes 73 and 74) to the MVS SMF data sets.

DynTunnel

SMF record type 119 subtypes related to phase 2 SA events should be written (subtypes 75 and 76) to the MVS SMF data sets.

To specify a combination of records to be written, specify multiple SMF119 statements. Use the MODIFY IKED,REFRESH command to change this value.

KeyRing

The owning userid and ringname used by the IKE server when performing RSA signature mode of authentication. When using a key ring owned by IKE server, specify the ring name as ringname. When using a key ring owned by another user, specify the ring name as userid/ringname.

The KeyRing parameter is not used by NSS client TCP/IP stacks.

IkeRetries

Specifies the number of times that an unanswered IKE negotiation message is retransmitted before the negotiation is terminated. The value of n can be in the range 1 - 8. The default is six retransmissions (254 seconds before dropping the message exchange if the default IkeInitWait value of two seconds is used). The IKE server uses an exponentially increasing wait interval between each retransmission. The initial wait interval is specified by the IkeInitWait parameter, and each subsequent wait interval is doubled from there. For example, if the IkeInitWait value is two, the first retransmission comes after two seconds, the second comes four seconds after the first, the fourth eight seconds after the third, and so on. Use the MODIFY IKED,REFRESH command to change this value.

Table 1 illustrates how a retransmission scenario would occur using the default values of IkeRetries 6 and IkeInitWait 2. The following scenario assumes that the IKE partner never responds to the IKE message in question.

Table 1. Example of an IkeRetries retransmission scenario

Event	Seconds since last event	Elapsed time in seconds
Send initial message	0	0
1st wait interval expires: message retransmitted	2	2
2nd wait interval expires: message retransmitted	4	6
3rd wait interval expires: message retransmitted	8	14
4th wait interval expires: message retransmitted	16	30
5th wait interval expires: message retransmitted	32	62
6th wait interval expires: message retransmitted	64	126
7th wait interval expires: message exchange is dropped	128	254 (See note)
Note: * 4 minutes, 14 seconds

Table 2 illustrates how retransmission scenario would occur using the maximum values of IkeRetries 8 and IkeInitWait 15. This scenario assumes that the IKE partner never responds to the IKE message in question.

Table 2. Example of an IkeRetries retransmission using maximum values scenario

Event	Seconds since last event	Elapsed time in seconds
Send initial message	0	0
1st wait interval expires: message retransmitted	15	15
2nd wait interval expires: message retransmitted	30	45
3rd wait interval expires: message retransmitted	60	105
4th wait interval expires: message retransmitted	120	225
5th wait interval expires: message retransmitted	240	465
6th wait interval expires: message retransmitted	480	945
7th wait interval expires: message retransmitted	960	1905
8th wait interval expires: message retransmitted	1920	3825
9th wait interval expires: message exchange is dropped	3840	7665
Note: * 2 hours, 7 minutes, 45 seconds

Table 3 illustrates how retransmission scenario would occur using the minimum values of IkeRetries 1 and IkeInitWait 1. This scenario assumes that the IKE partner never responds to the IKE message in question:

Table 3. Example of an IkeRetries retransmission using minimum values scenario

Event	Seconds since last event	Elapsed time in seconds
Send initial message	0	0
1st wait interval expires: message retransmitted	1	1
2nd wait interval expires: message exchange is dropped	2	3

IkeInitWait

Specifies the number of seconds to wait before the first retransmission of an unanswered IKE message. The value of n can be in the range 1 - 15. The default is 2 seconds. Use the MODIFY IKED,REFRESH command to change this value.

FIPS140

Specifies whether the IKE daemon should perform cryptographic operations by invoking cryptographic modules that are designed to meet the Level 1 security requirements documented in the Federal Information Processing Standard (FIPS) publication 140 (FIPS 140).

yes

Perform all IKE daemon cryptographic operations using cryptographic modules that are designed to meet FIPS 140 requirements. When the value of yes is specified, the IKE daemon server is running in FIPS 140 mode.

no

IKE daemon might perform some cryptographic operations using cryptographic modules that do not adhere to the FIPS 140 requirements. When the value of no is specified, the IKE daemon is not running in FIPS 140 mode.

Requirement: ICSF must be active before starting the IKE daemon when FIPS140 YES is specified. For information about configuring ICSF to support FIPS 140-2, see Operating in compliance with FIPS 140-2 in z/OS Cryptographic Services ICSF Writing PKCS #11 Applications.

Rule: This parameter cannot be modified while the IKED is running. Attempts to modify the value while the IKED is running are ignored and a warning message is issued.

Tip: Enabling FIPS 140 mode provides a higher degree of assurance of the integrity of the cryptographic modules that IKE uses, including ICSF and System SSL. However, enabling FIPS 140 mode might require additional setup and configuration, it will restrict the available set of cryptographic algorithms, and it might result in a reduction in performance. See Cryptographic standards and FIPS 140 in z/OS Communications Server: IP Configuration Guide for more information.

Echo

Echoes all IKE daemon log messages to the job output file, specified by the IKEDOUT DD (JCL) statement. Use the MODIFY IKED,REFRESH command to change this value.

NetworkSecurityServer

Identifies the primary NSS server for IKE NSS client TCP/IP stacks.

A single server is used for all of the TCP/IP stacks configured as NSS clients. Stacks can be configured individually as NSS clients. Stacks with a corresponding NssStackConfig statement are treated as NSS clients; stacks without a corresponding NssStackConfig statement rely solely on local IKE resources.

Tip: The NetworkSecurityServer parameter is optional. However, if both the NetworkSecurityServer and NetworkSecurityServerBackup parameters are not specified, none of the TCP/IP stacks can function as an NSS client.

Use the MODIFY IKED,REFRESH command to change this value. If you change the NetworkSecurityServer value, the changes take effect for new connections, but existing connections are not dropped. If you want the old connections to be dropped, perform the following steps:

1. Comment out the following statements:
   • NetworkSecurityServer statement (if present)
   • NetworkSecurityServerBackup statement (if present)
   • NssStackConfig statements (if present)
2. Issue a MODIFY IKED, REFRESH command to reread the IKED configuration file.
3. Uncomment the following statements:
   • NetworkSecurityServer statement (if present)
   • NetworkSecurityServerBackup statement (if present)
   • NssStackConfig statements (if present)
4. Issue a MODIFY IKED,REFRESH command to re-read the IKED configuration file.

host

The address of the NSS server can be specified either as a host name, a numeric IPv4 address, or a numeric IPv6 address. This is a required parameter. If a host name is specified, the maximum length accepted is 255 characters. The host name value should conform to the naming standards set forth by RFC 1035. For information about RFC, see Related protocol specifications.

Examples of supported host identifiers are as follows:

163.44.212.11
1080:0:0:0:8:800:200C:417A
norton.nycsanitation.gov

Port port

The TCP port on which the NSS server is listening for connections from the IKE daemon. The default value is 4159. Valid values are in the range 1 - 65535.

This parameter is optional.

Identity

The identity of the NSS Server. This is a required parameter.

The IKE daemon requires that communication with an NSS Server be protected using AT-TLS. During the AT-TLS handshake, the NSS server provides a certificate that is used to authenticate its identity. The IKE daemon interrogates this certificate and verifies that the identity in the certificate matches the identity specified on the NetworkSecurityServer parameter of the IkeConfig statement.

The following identity types (for idtype) and formats (for authid) are supported:

IpAddr

Indicates that the authid value is a numeric IPv4 address or a numeric IPv6 address. For example, 1.2.3.4.

Fqdn

Indicates that the authid value is a fully qualified domain name or host name. For example, vnet.ibm.com. The maximum length accepted is 255 characters. The Fqdn value should conform to the naming standards set forth by RFC 1035.

UserAtFqdn

Indicates that the authid value is a user at a fully qualified domain name or host name. The user name cannot contain a blank. For example, ibm@vnet.ibm.com. The maximum length accepted is 512 characters. The UserAtFqdn value should conform to the naming standards set forth by RFC 822.

X500dn

Indicates that the authid value is an X.500 distinguished name (DN). The DN must be specified in accordance with RFC 2253. A double-byte character is represented using the escaped UTF-8 encoding of the double-byte character in the Unicode character set. Attribute types can be specified using either attribute names or numeric object identifiers. Attribute values must represent string values.

Any distinguished name that contains an imbedded blank must be enclosed in double quotes. For example, X500dn "CN=R. Kramden,T=Driver,O=Gotham Bus Company,C=US".

Table 4 lists the DN attribute names that are recognized by the System SSL run time. An error is returned if the DN contains an unrecognized attribute name.

Table 4. DN attribute names

Abbreviation	Meaning
C	Country
CN	Common name
DC	Domain component
E	E-mail address
EMAIL	E-mail address (preferred)
EMAILADDRESS	E-mail address
L	Locality
O	Organization name
OU	Organizational unit name
PC	Postal code
S	State or province
SN	Surname
SP	State or province
ST	State or province (preferred)
STREET	Street
T	Title

The following code is an example of a DN using attribute names and string values:

CN=Hoffman,OU=Endicott,O=IBM,C=US

The following code is the same DN using object identifiers and encoded string values. The encoded string values represent the ASN.1 DER encoding of the string. The System SSL run time supports the following ASN.1 string types: PRINTABLE, VISIBLE, TELETEX, IA5, UTF8, BMP, and UCS.

2.5.4.3=#130E526F6E616C6420486F66666D616E,2.5.4.11=
#1308456E6469636F7474, 2.5.4.10=#130349424D,2.5.4.6=#13025553

Individual characters can be represented using escape sequences. This is useful when the character cannot be represented in a single-byte character set. The hexadecimal value for the escape sequence is the UTF-8 encoding of the character in the Unicode character set. Table 5 shows some Unicode example letter descriptions.

Table 5. Unicode letter descriptions

Unicode letter description	10646 code	UTF-8	Quoted
LATIN CAPITAL LETTER L	U0000004C	0x4C	L
LATIN SMALL LETTER U	U00000075	0x75	u
LATIN SMALL LETTER C WITH CARON	U0000010D	0xC48D	\C4\8D
LATIN SMALL LETTER I	U00000069	0x69	i
LATIN SMALL LETTER C WITH ACUTE	U00000107	0xC487	\C4\87

Guideline: The letters in the Quoted column in Table 5 can be used to encode a surname as follows:

SN=Lu\C4\8Di\C4\87

An escape sequence can also be used for special characters that are part of the name and are not to be interpreted as delimiters. The following special characters must be represented as an escape sequence (prefixed with a backslash [\]) when used as part of the name:

• A space or number sign (#) character occurring at the beginning of the string
• A space occurring at the end of the string
• One of the following characters , + " \ < >

This correct escape sequence is shown in the following example:

"CN=L. Eagle,OU=Jones\, Dale and Mian,O=IBM,C=US"

In this example, the enclosing double quotes are required because of the imbedded blanks, not because of the escaped characters.

Rule: When an X500dn type identity is specified, the DN attributes must have the same order as those of the corresponding certificate subject name.

NetworkSecurityServerBackup

Identifies the backup NSS server for the IKE daemon. The NSS server (or its backup) supplies certificate and remote management services for managed stacks.

A single backup server is used for all of the TCP/IP stacks configured as NSS clients.

The NetworkSecurityServerBackup parameter is optional. It allows network security clients to connect to a backup NSS server at a different address or port from the primary. Alternatively, in a sysplex configuration, the primary NSS server can be configured on a dynamic VIPA to use the recovery capabilities of dynamic addressing. If no backup server is available when the primary server is not responsive, certificate and remote management services are unavailable to network security clients. However, if a NetworkSecurityServerBackup parameter is not specified, then certificate services are unavailable to Network Security clients if the primary NSS server becomes unresponsive.

Network Security clients switch between the primary and the backup NSS servers whenever their current server becomes unresponsive. If both the primary and the backup become unresponsive, the Network Security client attempts to connect to the primary and the backup in a round-robin fashion until a successful connection is made. It is possible to have a situation where one NSS client is being managed by the primary server and another NSS client is being managed by the backup server. It is also possible to specify a backup server without specifying a primary server, in which case, the backup server is treated as if it is the primary server.

Use the MODIFY IKED,REFRESH command to change this value. If you change the NetworkSecurityServerBackup value, then the changes take effect for new connections, but existing connections are not dropped. If you want the old connections to be dropped, follow this following sequence:

1. Comment out all of the following statements:
   • NetworkSecurityServer statement (if present)
   • NetworkSecurityServerBackup statement (if present)
   • NssStackConfig statements (if present)
2. Issue a MODIFY IKED, REFRESH command to re-read the IKED configuration file.
3. Uncomment out all of the following statements:
   • NetworkSecurityServer statement (if present)
   • NetworkSecurityServerBackup statement (if present)
   • NssStackConfig statements (if present)
4. Issue a MODIFY IKED, REFRESH command to re-read the IKED configuration file.

host

The address of the NSS server can be specified either as a host name, a numeric IPv4 address, or a numeric IPv6 address. This is a required parameter. If a host name is specified, the maximum length accepted is 255 characters. The host name value should conform to the naming standards set forth by RFC 1035.

Examples of supported host identifiers are as follows:

163.44.212.11
1080:0:0:0:8:800:200C:417A
norton.nycsanitation.gov

Port port

The TCP port on which the backup NSS server is listening for connections from the IKE daemon. The default value is 4159. Valid values are in the range 1 - 65535. This parameter is optional.

Identity

The identity of the backup NSS server. This is a required parameter.

The IKE daemon requires that communication with an NSS server be protected using AT-TLS. During the AT-TLS handshake the NSS server provides a certificate that is used to authenticate its identify. The IKE daemon interrogates this certificate and verifies that the identity in the certificate matches the identity specified on the NetworkSecurityServer parameter of the IkeConfig statement.

The following identity types (idtype) and formats (authid) are supported:

IpAddr

Indicates that the authid value is a numeric IPv4 address or a numeric IPv6 address. For example, 1.2.3.4.

Fqdn

Indicates that the authid value is a fully qualified domain name or host name. For example, vnet.ibm.com. The maximum length accepted is 255 characters. The Fqdn value should conform to the naming standards set forth by RFC 1035.

UserAtFqdn

Indicates that the authid value is a user at a fully qualified domain name or host name. The user name cannot contain a blank. For example, ibm@vnet.ibm.com. The maximum length accepted is 512 characters. The UserAtFqdn value cannot begin or end with a dot (.) or contain consecutive dots. The UserAtFqdn value should conform to the naming standards set forth by RFC 822.

X500dn

Indicates that authid is an X.500 distinguished name (DN). See the NetworkSecurityServer parameter description in this topic for the DN specification.

NssWaitLimit

Specifies the number of seconds (1-300) that an NSS client waits between connection attempts when trying to establish a connection with an NSS server.

The product of the NssWaitLimit value multiplied by the NssWaitRetries value defines the maximum number of seconds that an NSS client attempts to connect to an NSS server before switching to another server. For example, if the NssWaitLimit value is 60, and the NssWaitRetries value is 3, then an NSS client waits at most for a total of 180 seconds for a successful connection with a given server. See the description of the NetworkSecurityServerBackup parameter for a discussion of how NSS clients switch between the primary and backup NSS servers.

The default value is 60 seconds. Use the MODIFY IKED,REFRESH command to change this value. The new value takes effect immediately.

NssWaitRetries

Specifies the number of times (1-10) that an NSS client attempts to establish a connection with an NSS server.

The product of the NssWaitLimit value multiplied by the NssWaitRetries value defines the maximum number of seconds that an NSS client attempts to connect to an NSS server before switching to another server. For example, if the NssWaitLimit value is 60, and the NssWaitRetries value is 3, then an NSS client waits at most for a total of 180 seconds for a successful connection with a given server. See the description of the NetworkSecurityServerBackup parameter for a discussion of how NSS clients switch between the primary and backup NSS servers.

The default value is 3 retries. Use the MODIFY IKED,REFRESH command to change this value. The new value takes effect immediately.

PagentWait

The time limit in seconds to wait for connection to the Policy Agent. The value of n can be 0-9999. A value of 0 indicates retry forever. The default is 0.

SupportedCertAuth

Specifies the label of a certificate on the IKE server's key ring. This label corresponds to the certificate of a certificate authority supported by the local security endpoint when using RSA signature mode of authentication. RSA signature authentication is a certificate-based authentication method used by the IKE server to authenticate a remote security endpoint's identify. The SupportedCertAuth parameter can be specified multiple times to identify a set of supported certificate authorities.

Use the SupportedCertAuth parameter to define a set of certificate authorities (CAs) supported by the local security endpoint. This list is provided to the remote security endpoint to request that it choose a certificate signed by an acceptable CA. The remote security endpoint is not constrained to choose certificates signed by CAs accepted by the local security endpoint. However, if the remote security endpoint chooses a certificate signed by a CA that is not on the IKE server's key ring, the key exchange fails.

The CaLabel parameter of the RemoteSecurityEndpoint IPSec policy statement can be used to further restrict the set of certificate authorities that can sign the certificate used by a particular remote security endpoint. The advantage of further restricting the set of certificate authorities that might sign the certificate used by a particular remote security endpoint is a reduction in the size of the IKE key exchange messages transmitted between the local security endpoint and the remote security endpoint.

The number of specified labels is limited to a maximum of 128. The maximum length of a label is 32 characters, which corresponds to the maximum length of a RACF® label. The default is an empty list containing no labels.

Use the MODIFY IKED,REFRESH command to change this value.

The SupportedCertAuth parameter is not used by NSS server client TCP/IP stacks.