IPSEC statement

Use the IPSEC statement to define policy for the IPv4 security function that is enabled with the IPCONFIG IPSECURITY parameter. The IPSEC statement is ignored if IPSECURITY is not specified on the IPCONFIG statement. If you also enable IPv6 Security with the IPCONFIG6 IPSECURITY parameter, then use the IPSEC statement to also define policy for IPv6 IP security.

Restriction: Only one IPSEC statement block should appear in the profile. Any subsequent statement blocks are ignored and an informational message is generated. Multiple filter rules can be defined in the IPSEC block.

Syntax

Rule: Specify the parameters in the order shown here.

IP Filter Rule

IPv4 Filter Rule

Protocol

IPv6 Filter Rule

Protocol

Parameters

DVIPSEC

Indicates that IPsec tunnels associated with IPv4 and IPv6 dynamic VIPA addresses are eligible to be distributed if the dynamic VIPA address is being distributed. The IPsec tunnels are also eligible to be moved during dynamic VIPA takeover or giveback.

Restrictions:

The DVIPSEC function can be enabled only in an intial profile. It can not be enabled by using the VARY TCPIP,,OBEYFILE command.
For tunnels that traverse a NAT device, the dynamic VIPA takeover and giveback function is limited to configurations where IKE can act as initiator. IKE cannot act as initiator in the following configurations:
- The remote security endpoint is a security gateway and a NAT is being traversed
- The remote security endpoint is behind an NAPT

For more information about NAT Traversal configuration scenarios, see z/OS Communications Server: IP Configuration Guide.

DVLOCALFLTR

Enables IP filtering and IPSec protection of TCP traffic between a client and an IPv4 dynamic VIPA defined on the same TCP/IP stack, when the traffic is forwarded to another TCP/IP stack. By default, IP filtering is not applied to local traffic.

Guidelines: When DVLOCALFLTR is configured to enable IP filtering:

Ensure that the IPSec policy accounts for all local TCP traffic with an IPv4 dynamic VIPA endpoint. Traffic that does not match a configured IP filter rule is denied.
Use IKEv2 to negotiate the tunnel to protect the traffic. Use HowToInitiate IKEv2 on the KeyExchangePolicy statement or a specific KeyExchangeAction statement to indicate that IKEv2 should be used when key negotiations are initiated by this system.

Restriction: IKEv1 cannot be used to negotiate a tunnel between a client and an IPv4 dynamic VIPA that are defined on the same TCP/IP stack.

LOGDISABLE/LOGENABLE

Indicates whether packet filter logging is enabled or disabled. The following log messages are controlled by this parameter:

EZD0814I
EZD0815I
EZD0821I
EZD0832I
EZD0833I
EZD0836I
EZD0822I

If logging is enabled, messages are written to syslogd by the Traffic Regulation Manager Daemon (TRMD).

If LOGENABLE is specified, then the log setting on the individual default filter rules and the implicit default rules is honored. The log setting for individual default rules is specified with the LOG/NOLOG parameter. The log setting for the implicit default rules is specified with the LOGIMPLICIT/NOLOGIMPLICIT parameter.

If LOGDISABLE is specified, then the log setting on the individual default filter rules and the implicit default rules is ignored and no packet filter logging is done.

LOGIMPLICIT/NOLOGIMPLICIT

Indicates whether packet filter logging is enabled or disabled for packets that are denied by the implicit default rules. IP traffic not explicitly permitted by the default IP filter rules parameters described in the following IP Filter Rule parameters topic, is handled by implicit default rules generated by the stack while default IP filter policy is in effect.

If the IPSEC statement is not specified, packet filter logging is disabled for packets that are handled by the implicit default rules. To turn on packet filter logging for the implicit default rules, IPSEC must be coded with the LOGENABLE and LOGIMPLICIT parameters.

A setting of LOGIMPLICIT is honored only when filter logging is enabled on the IPSEC statement with LOGENABLE.

IP Filter Rule parameters

Default IP filter rules can be defined on the IPSEC statement. The default IP filter policy is used prior to the initial loading of IP security policy into the stack from the Policy Agent. It is also used when the IP security policy has been suspended by the z/OS® UNIX ipsec command (that is, when the ipsec -f default command is issued).

The default IP filter policy consists of the following rules:

Rules defined explicitly with the IPSECRULE and IPSEC6RULE statement
Implicit rules that deny all inbound and outbound data traffic

The explicit rules appear first in the search order and the implicit deny all rules appear last in the search order.

The rules defined explicitly with the IPSECRULE and IPSEC6RULE statements are permit rules. IP traffic not explicitly permitted by one of the defined rules is denied while the default IP filter policy is in effect.

The physical order in which the rules are defined in the profile determines the search order for the rules. The rule parameters are ANDed together to determine whether the IP traffic matches the filter rule.

If you configure an IPSEC6RULE statement but did not specify IPCONFIG6 IPSECURITY, then TCP/IP rejects the IPSEC6RULE statement and issues message EZZ0787I in z/OS Communications Server: IP Messages Volume 4 (EZZ, SNM).

If the IPSEC statement is not specified or if no default IP filter rules are specified, the default IP filter table consists only of the implicitly defined deny all rule.

src_ipaddr

A single IP address. If the source address of an IP packet matches this address, the packet is permitted by this rule.

Specify an asterisk (*) to allow any source IP address to match.

Guidelines:

For IPSECRULE, an asterisk means any IPv4 address. For IPSEC6RULE, an asterisk means any IPv6 address.
For IPSEC6RULE, the src_ipaddr can be any valid IPv6 address in colon-hexadecimal format. IPv4-mapped IPv6 addresses are also allowed.

src_ipaddr/prefix_length

A prefix address specification. If the source address of an IP packet falls within the bounds of this specification, the packet is permitted by this rule. The prefix_length is the number of unmasked leading bits in the ipaddress value. The prefix_length value is in the range 0 - 32 for IPv4 addresses and 0 - 128 for IPv6 addresses. For prefix_length values other than zero (0), an IP packet matches this condition if its source address unmasked bits are identical to the defined unmasked bits. Specifying a prefix_length value of zero (0) is the same as specifying a src_ipaddr value of asterisk (*).

src_ipaddr - src_ipaddr

A range of IP addresses. If the source address of an IP packet falls within this range, inclusive, the packet is permitted by this rule.

Rule: The specification of the IP address range must include blank characters between each IP address and the dash character that separates the beginning and ending range values.

dest_ipaddr

A single IP address. If the destination address of an IP packet matches this address, the packet is permitted by this rule.

Specify an asterisk (*) to allow any destination IP address to match.

Guidelines:

For IPSECRULE, an asterisk means any IPv4 address. For IPSEC6RULE, an asterisk means any IPv6 address.
For IPSEC6RULE, the dest_ipaddr can be any valid IPv6 address in colon-hexadecimal format. IPv4-mapped IPv6 addresses are also allowed.

dest_ipaddr/prefix_length

A prefix address specification. If the destination address of an IP packet falls within the bounds of this specification, the packet is permitted by this rule. The prefix_length is the number of unmasked leading bits in the ipaddress value. The prefix_length value is in the range 0 - 32 for IPv4 addresses and 0 - 128 for IPv6 addresses. For prefix_length values other than zero (0), an IP packet matches this condition if its destination address unmasked bits are identical to the defined unmasked bits. Specifying a prefix_length value of zero (0) is the same as specifying a dest_ipaddr value of asterisk (*).

dest_ipaddr - dest_ipaddr

A range of IP addresses. If the destination address of an IP packet falls within this range, inclusive, the packet is permitted by this rule.

Rule: The specification of the IP address range must include blank characters between each IP address and the dash character that separates the beginning and ending range values.

LOG/NOLOG

Indicates whether packet filter logging is enabled or disabled for the default filter rule. A setting of LOG is honored only when filter logging is enabled on the IPSEC statement with LOGENABLE.

PROTOCOL

The protocol specification for this rule. For IP traffic to be permitted by this rule, the protocol of the traffic must match this parameter.

*

Any protocol specification. IP traffic of any protocol can match this rule. This is the default value.

TCP | 6

TCP protocol specification. For IP traffic to be permitted by this rule, the protocol of the traffic must be TCP.

SRCPORT

A TCP source port or range of TCP source ports. For IP traffic to be permitted by this rule, the source port of the traffic must match this parameter.

Valid values are as follows:

*: Indicates all values in the range 1 - 65535. Any source port matches this parameter value. This is the default.
n: A single value in the range 1 - 65535.
n m: A range of values beginning with n and ending with m, inclusive, where n<m. n and m values must be in the range 1 - 65535.

Restriction: If the ROUTING value is ROUTED or EITHER, SRCPORT must be defined as all ports (*).

DESTPORT

A TCP destination port or range of TCP destination ports. For IP traffic to be permitted by this rule, the destination port of the traffic must match this parameter.

Valid values are as follows:

*: Indicates all values in the range 1 - 65535. Any destination port matches this parameter value. This is the default.
n: A single value in the range 1 - 65535.
n m: A range of values beginning with n and ending with m, inclusive, where n<m. n and m values must be in the range 1 - 65535.

Restriction: If the ROUTING value is ROUTED or EITHER, DESTPORT must be defined as all ports (*).

UDP | 17

UDP protocol specification. For IP traffic to be permitted by this rule, the protocol of the traffic must be UDP.

SRCPORT

A UDP source port or range of UDP source ports. For IP traffic to be permitted by this rule, the source port of the traffic must match this parameter.

Valid values are as follows:

*: Indicates all values in the range 1 - 65535. Any source port matches this parameter value. This is the default.
n: A single value in the range 1 - 65535.
n m: A range of values beginning with n and ending with m, inclusive, where n <m. n and m values must be in the range 1 - 65535.

Restriction: If the ROUTING value is ROUTED or EITHER, SRCPORT must be defined as all ports (*).

DESTPORT

A UDP destination port or range of UDP destination ports. For IP traffic to be permitted by this rule, the destination port of the traffic must match this parameter.

Valid values are as follows:

*: Indicates all values in the range 1 - 65535. Any destination port matches this parameter value. This is the default.
n: A single value in the range 1 - 65535.
n m: A range of values beginning with n and ending with m, inclusive, where n <m. n and m values must be in the range 1 - 65535.

Restriction: If the ROUTING value is ROUTED or EITHER, DESTPORT must be defined as all ports (*).

ICMP | 1

ICMP protocol specification.

Restriction: The ICMP protocol is valid only on an IPSECRULE statement.

Rule: For IP traffic to be permitted by this rule, the protocol of the traffic must be ICMP.

TYPE

An ICMP type or a range of ICMP types. This parameter is applicable when ICMP is specified for the PROTOCOL parameter.

Valid values are as follows:

*: Indicates all values in the range 0 - 255. Any ICMP type matches this parameter value. This is the default.
n: A single value in the range 0 - 255.
n m: A range of values beginning with n and ending with m, inclusive, where n <m. n and m values must be in the range 0 - 255.

Restrictions:

For IP traffic to be permitted by this rule, the ICMP type of the traffic must match this parameter value.
If the ROUTING value is ROUTED or EITHER, TYPE must be defined as all types (*).

CODE

An ICMP code or a range of ICMP codes. This parameter is applicable when ICMP is specified for the PROTOCOL parameter.

Valid values are as follows:

*: Indicates all values in the range 0 - 255. Any ICMP type matches this parameter value. This is the default.
n: A single value in the range 0 - 255.
n m: A range of values beginning with n and ending with m, inclusive, where n <m. n and m values must be in the range 0 - 255.

Restrictions:

For IP traffic to be permitted by this rule, the ICMP code of the traffic must match this parameter value.
If the ROUTING value is ROUTED or EITHER, CODE must be defined as all codes (*).
If the TYPE value is specified as a range of types, CODE must be defined as all codes (*).

ICMPV6 | 58

ICMPv6 protocol specification.

Restriction: The ICMPv6 protocol is valid only on an IPSEC6RULE statement.

Rule: For IP traffic to be permitted by this rule, the protocol of the traffic must be ICMPv6.

TYPE

An ICMPv6 type or a range of ICMPv6 types. This parameter is applicable when ICMPV6 is specified for PROTOCOL.

Valid values are as follows:

*: Indicates all values in the range 0 - 255. Any ICMPv6 type matches this parameter value. This is the default.
n: A single value in the range 0 - 255.
n m: A range of values beginning with n and ending with m, inclusive, where n <m. n and m values must be in the range 0 - 255.

Restrictions:

For IP traffic to be permitted by this rule, the ICMPv6 type of the traffic must match this parameter value.
If the ROUTING value is ROUTED or EITHER, TYPE must be defined as all types (*).

CODE

An ICMPv6 code or a range of ICMPv6 codes. This parameter is applicable when ICMPV6 is specified for PROTOCOL.

Valid values are as follows:

*: Indicates all values in the range 0 - 255. Any ICMPv6 code matches this parameter value. This is the default.
n: A single value in the range 0 - 255.
n m: A range of values beginning with n and ending with m, inclusive, where n <m. n and m values must be in the range 0 - 255.

Restrictions:

For IP traffic to be permitted by this rule, the ICMPv6 type of the traffic must match this parameter value.
If the ROUTING value is ROUTED or EITHER, TYPE must be defined as all types (*).
If the TYPE value is specified as a range of types, CODE must be defined as all codes (*).

OSPF | 89

OSPF protocol specification.

Restriction: For IP traffic to be permitted by this rule, the protocol of the traffic must be OSPF.

TYPE ospftype

OSPF type. This parameter is applicable when OSPF is specified for PROTOCOL. Valid values are * or 0 - 255.

Restrictions:

For IP traffic to be permitted by this rule, the OSPF type of the traffic must match this parameter value. The default is *, which indicates that any OSPF type matches.
If the ROUTING value is ROUTED or EITHER, TYPE must be defined as all types(*).

For a list of the possible IPv4 OSPF types, see RFC 1583 OSPF Version 2. For a list of the possible IPv6 OSPF types, see RFC 2740, OSPF for IPv6. See Related protocol specifications for more information about accessing RFCs.

OPAQUE

The OPAQUE value matches any IPv6 packet for which the upper-layer protocol is not known as a result of fragmentation. This parameter matches non-initial fragments. It also matches initial fragments if the upper-layer protocol value is not included in the first fragment. The OPAQUE value is applicable only to routed fragments because for all local traffic, the stack applies IP filter rules only to fully assembled packets.

Restriction: The OPAQUE protocol is valid only on an IPSEC6RULE statement.

MIPV6 | 135

IPv6 mobility protocol specification.

Restriction: The MIPv6 protocol is valid only on an IPSEC6RULE statement.

Rule: For IP traffic to be permitted by this rule, the protocol of the traffic must be MIPv6.

TYPE

A MIPv6 type or a range of MIPv6 types. This parameter is applicable when MIPV6 is specified for PROTOCOL.

Valid values are as follows:

*: Indicates all values in the range 0 - 255. Any MIPv6 type matches this parameter value. This is the default.
n: A single value in the range 0 - 255.
n m: A range of values beginning with n and ending with m, inclusive, where n <m. n and m values must be in the range 0 - 255.

Restrictions:

For IP traffic to be permitted by this rule, the MIPv6 type of the traffic must match this parameter value.
If the ROUTING value is ROUTED or EITHER, TYPE must be defined as all types (*).

protocol_number

A protocol number in the range 0 - 255.

Restriction: For IP traffic to be permitted by this rule, the protocol of the traffic must match this parameter.

ROUTING

Specifies the type of packet to which this rule applies. Valid values for ROUTING are:

LOCAL

Indicates that this rule applies to packets destined for this stack.

ROUTED

Indicates that this rule applies to packets being forwarded by this stack. When ROUTED is specified, you can further qualify the rule to specify whether the rule applies to only IP packets that are fragmented or all IP packets. If you do not specify FRAGMENTSONLY, the rule applies to all IP packets.

FRAGMENTSONLY: Specifies that the rule applies only to IP packets that are fragmented.
Restriction: The FRAGMENTSONLY parameter is valid only when ROUTING ROUTED is specified.

Tip: Fragments are matched only in routed traffic, because the TCP/IP stack applies IP filter rules for local traffic only to fully reassembled packets.

EITHER

Indicates that this rule applies to forwarded and non-forwarded packets.

The default value is LOCAL.

SECCLASS security_class

A security class value in the range 0 - 255.

Restriction: For IP traffic to be permitted by this rule, the security class of the interface that the traffic is inbound to or outbound from must match this parameter.

For IPv4, the security class for the interface is specified as SECCLASS on the LINK, INTERFACE, or IPCONFIG DYNAMICXCF statement. For IPv6, the security class for the interface is specified as SECCLASS on the INTERFACE or IPCONFIG6 DYNAMICXCF statement. A value of 0 matches any security class value coded on the corresponding profile statement which defines the interface. For more information about security class values, see z/OS Communications Server: IP Configuration Guide.

The default value is 0.

DIRECTION

Specifies the direction of a packet to which this rule applies.

OUTBOUND: This value generates one IP filter. The generated rule permits an outbound packet with the specified source and destination.

INBOUND: This value generates one IP filter. The generated rule permits an inbound packet with the specified source and destination.

BIDIRECTIONAL

This value generates two IP filters. The first generated rule permits an outbound packet with the specified source and destination IP address or port. The second generated rule switches the source and destination specification and permits an inbound packet with the switched source and destination specification.

When BIDIRECTIONAL is specified, you can further qualify the rule to indicate the direction of the packet that can generate a TCP connection. You can do so by specifying the INBCONNECT or OUTBCONNECT parameter.

Restriction: INBCONNECT and OUTBCONNECT are honored only for a rule with a PROTOCOL value of TCP.

INBCONNECT: Indicates that a TCP connection can be initiated only by an inbound packet.
OUTBCONNECT: Indicates that a TCP connection can be initiated only by an outbound packet.

Steps for modifying

To modify most parameters for the IPSEC statement, use a VARY TCPIP,,OBEYFILE command with a data set that contains a new IPSEC statement. Additional actions are required to modify the following parameters:

DVIPSEC

The value of DVIPSEC cannot be modified using the VARY TCPIP,,OBEYFILE command on an active TCP/IP stack.

DVLOCALFLTR

The value of DVLOCALFLTR can be modified by using a VARY TCPIP,,OBEYFILE command with a data set that contains a new IPSEC statement, if the DVIPSEC parameter was specified at TCP/IP initialization. To disable the DVLOCALFLTR function, specify the DVIPSEC parameter without the DVLOCALFLTR subparameter. To enable the DVLOCALFLTR function, specify the DVIPSEC parameter with the DVLOCALFLTR subparameter. The current set of IPSECRULE statements must be included in the data set when you are changing the DVLOCALFLTR setting on the IPSEC statement.

If the DVLOCALFLTR setting is changed, traffic for both new and existing connections are affected. Depending on application behavior, an application might have to be recycled for the new DVLOCALFLTR setting to take effect.

LOGDISABLE/LOGENABLE

The value of LOGDISABLE/LOGENABLE can be modified using a VARY TCPIP,,OBEYFILE command with a data set that contains a new IPSEC statement. The current set of IPSECRULE statements should be included in the data set when changing LOGDISABLE/LOGENABLE on the IPSEC statement.

LOGIMPLICIT/NOLOGIMPLICIT

The value of LOGIMPLICIT/NOLOGIMPLICIT can be modified using a VARY TCPIP,,OBEYFILE command with a data set that contains a new IPSEC statement. The current set of IPSECRULE statements should be included in the data set when changing LOGIMPLICIT/NOLOGIMPLICIT on the IPSEC statement.

IP Filter Rules

To modify the default IP filter rules on the IPSEC statement, use a VARY TCPIP,,OBEYFILE command with a data set that contains a new IPSEC statement. All existing default IP filter rules are deleted and replaced with the default IP filter rules defined on the new IPSEC statement.

To delete all defined default filter rules leaving only the implicit deny all default rule, the data set must contain a new IPSEC statement with no default filter rules defined. If the data set does not contain an IPSEC statement, then the existing default filter rules remain in effect.

If IP filtering is being done based on the default filter rules, then the modified default filter rules are in effect following the VARY TCPIP,,OBEYFILE command. If IP filtering is being done based on the filter rules defined to Policy Agent, then the default filter rules are updated by the VARY TCPIP,,OBEYFILE command, but filter rules defined in Policy Agent remain in effect. The ipsec -f default command must be issued to cause the default filter rules to be used.

For more information about the VARY TCPIP commands, see z/OS Communications Server: IP System Administrator's Commands.

Examples

IPSEC
; Rule   SourceIp      DestIp    Logging   Prot       SrcPort    DestPort   Routing    Secclass
;
; Permit outbound IPv4 TCP traffic from local IP address 1.1.1.1 port 23 to remote IP address 2.2.2.2
; Permit inbound IPv4 TCP  traffic from remote IP address 2.2.2.2 to local IP address 1.1.1.1 port 23
  IPSECR 1.1.1.1       2.2.2.2   NOLOG     PROTO TCP  SRCPORT 23 DESTPORT * ROUTING LOCAL  
;
; Permit outbound IPv4 TCP traffic from local IP address 1.1.1.1 to remote IP address 2.2.2.2 port 23
; Permit inbound IPv4 TCP  traffic from remote IP address 2.2.2.2 port 23 to local IP address 1.1.1.1 
  IPSECR 1.1.1.1       2.2.2.2   NOLOG     PROTO TCP  SRCPORT *  DESTPORT 23 
;
; Permit outbound IPv4 TCP traffic from a range of local IP addresses to any remote IP address port 21
; Permit inbound IPv4 TCP traffic from any remote IP address port 21 to a range of local IP addresses
; Only inbound IPv4 TCP connections are permitted
  IPSECR 1.3.128.200-1.3.128.215 * LOG PROTO TCP DESTPORT 21 DIREC BIDI INBCONNECT
;
; Permit outbound IPv4 ICMP traffic from local IP addresses 1.2.0.0/16
; Permit inbound IPv4 ICMP  traffic to local IP addresses 1.2.0.0/16
  IPSECR 1.2.0.0/16    *         LOG       PROTO ICMP                          
; Permit all routed IPv4 traffic
; IPSECR *             *         LOG       PROTO *                           ROUTING ROUTED
; Permit all local outbound traffic to remote IP address 1.2.3.4
; Permit all local inbound  traffic from remote IP address 1.2.3.4
  IPSECR *             1.2.3.4
; Permit local outbound IPv6 Neighbor Solicitations 
; Permit local inbound IPv6 Neighbor Solicitations 
 IPSEC6R *             *                   LOG       PROTO  ICMPV6  TYPE 135
; Permit local outbound IPv6 Neighbor Advertisements 
; Permit local inbound IPv6 Neighbor Advertisements 
  IPSEC6R *            *                   LOG       PROTO  ICMPV6  TYPE  136
; Permit local inbound IPv6 Router Advertisements from remote IP address 2001::1:2:3:4 
  IPSEC6R *            2001::1:2:3:4/128     LOG      PROTO  ICMPV6  TYPE 134

ENDIPSEC

IPSEC statement

Syntax

Parameters

Steps for modifying

Examples

Related topics