ipsecconf

 


 
 
 
 Maintenance Commands                                ipsecconf(1M)
 
 
 


NAME

ipsecconf - configure system wide IPSEC policy

SYNOPSIS

/usr/sbin/ipsecconf /usr/sbin/ipsecconf -a file [ -q ] /usr/sbin/ipsecconf -d index /usr/sbin/ipsecconf -f /usr/sbin/ipsecconf -l [ -n ]

DESCRIPTION

The ipsecconf utility configures the IPsec policy for a host. Once the policy is configured, all outbound and inbound datagrams are subject to policy checks as they exit and enter the host. If no entry is found, no policy checks will be completed, and all the traffic will pass through. Datagrams that are being forwarded will not be subjected to policy checks that are added using this command. See ifconfig(1M) and tun(7M) for information on how to protect forwarded packets. Depending upon the match of the policy entry, a specific action will be taken. This command can be run only by superuser. Each entry pro- tects traffic only in one direction, that is, either out- bound or inbound. Thus to protect traffic in both direc- tions, you need to have one entry in each direction. When the command is issued without any arguments, the poli- cies configured in the system are shown. Each entry is displayed with an index followed by a number. You can use the -d option with the index to delete a given policy in the system. The entries are displayed in the order that they were added, which is not necessarily the order that the traffic match will take place. To view the order in which the traffic match will take place, use -l option. Policy entries are not preserved across reboot. Thus the policy needs to be added everytime the machine reboots. To configure policies early in the boot, one can setup policies in the /etc/inet/ipsecinit.conf file, which are then read from the inetinit startup script. See SECURITY CONSIDERATIONS.

OPTIONS

ipsecconf supports the following options: -a file SunOS 5.8 Last change: 13 Oct 1999 1 Maintenance Commands ipsecconf(1M) Add the IPSEC policy to the system as specified by each entry in the file. An IPsec configuration file contains one or more entries that specify the configuration. Once the policy is added, all outbound and inbound datagrams are subject to policy checks. Entries in the files are described in the OPERANDS section below. Examples can be found in the EXAMPLES section below. Policy is latched for TCP/UDP sockets on which a connect(3SOCKET) or accept(3SOCKET) is issued. So, addition of new policy entries may not affect such endpoints/sockets. Also, an old connection that was not subject to any policy, may be sub- ject to policy checks by the addition of new pol- icy entries. This could disrupt the old communi- cation if the other end is not expecting similar policy. Thus, make sure that there are not any pre-existing connections that would be subject to checks by the new policy entries. The feature of policy latching explained above may change in the future. It is not advisable to depend upon this feature. -d index Delete the policy denoted by the index. The index is obtained by viewing the policy config- ured in the system. Once the entry is deleted, all outbound and inbound datagrams affected by this policy entry will not be subjected to policy checks. Be advised that for connections whose policy has been latched, packets will continue to go out with the same policy even it has been delelted. -f Flush all the policies in the system. Constraints are similar to the -d option with respect to latching . -l Long listing of the policy entries. When ipsec- conf is invoked without any arguments, it shows the complete list ofpolicy entries added by the user since the boot. The -l option displays the current kernel table. The current table can differ from the previous one if, for example, a multi-homed entry was added or policy re-ordering occurred. In the case of a multi-homed entry, all the addresses are listed explicitly. If a SunOS 5.8 Last change: 13 Oct 1999 2 Maintenance Commands ipsecconf(1M) mask was not specified earlier but was instead inferred from the address, it will be explicitly listed here. This option is used to view policy entries in the correct order. The outbound and inbound policy entries are listed separately. -n Show network addresses, ports, protocols in numbers. The -n option may only be used with the -l option. -q Quiet mode. Supresses the warning message gen- erated when adding policies.

OPERANDS

Each policy entry contains 3 parts specified as follows : {pattern} action {properties} Every policy entry begins on a new line and can span multi- ple lines. "pattern" specifies the traffic pattern that should be matched against the outbound and inbound datagrams. If there is a match, a specific "action" deter- mined by the second argument will be taken, depending upon the "properties" of the policy entry. Pattern and properties are name-value pairs where name and value are separated by <space>, <tab> or <newline>. Multiple name-value pairs should be separated by <space>, <tab> or <newline>. The beginning and end of the pattern and properties are marked by "{" and "}" respectively. Files can contain multiple policy entries. An unspecified name-value pair in the "pattern" will be considered as wild- card. Wildcard entries matches any corresponding entry in the datagram. File can be commented by using "#" as the first character. Comments may be inserted either at the beginning or the end of a line. The complete syntax of a policy entry is: policy ::= {pattern} action {properties} pattern ::= <pattern_name_value_pair>| <pattern_name_value_pair>, <pattern> action ::= apply | permit | bypass properties ::= <prop_name_value_pair>| SunOS 5.8 Last change: 13 Oct 1999 3 Maintenance Commands ipsecconf(1M) <prop_name_value_pair>, <properties> pattern_name_value_pair ::= <saddr/prefix address>| <smask mask>| <sport part>| <daddr/prefix address>| <dmask mask>| <dport port>| <ulp protocol> address ::= <Internet dot notation> | <String recognized by gethostbyname> | <String recongnized by getnetbyname> prefix ::= <number> mask ::= <0xhexdigit[hexdigit]> | <0Xhexdigit[hexdigit]> | <Internet dot notation> port ::= <number>| <String recognized by getservbyname> protocol ::= <number>| <String recognized by getprotobyname> prop_name_value_pair ::= <auth_algs auth_alg>| <encr_algs encr_alg| <encr_auth_algs auth_alg| <sa sa_val| <dir dir_val> auth_alg ::= <md5 | hmac-md5 | sha | sha1 | hmac-sha | hmac-sha1 | number> encr_alg ::= <des | des-cbc | 3des | 3des-cbc | number> sa_val ::= shared | unique dir_val ::= out | in number ::= < 0 | 1 | 2 ... 9> <number> Policy entries may contain the following (name value) pairs in the pattern field. Each (name value) pair may appear only once in given policy entry. saddr/plen The value that follows is the source address of the datagram with the prefix length. Only plen leading bits of the source address of the packet will be matched. plen is optional. The source address value can be a hostname as described in gethostbyname(3XNET) or a network SunOS 5.8 Last change: 13 Oct 1999 4 Maintenance Commands ipsecconf(1M) name as described in getnetbyname(3XNET) or a host address or network address in the Internet standard dot notation. See inet_addr(3XNET). If a hostname is given and gethostbyname(3XNET) returns multiple addresses for the host, then policy will be added for each of the addresses with other entries remaining the same. daddr/plen The value that follows is the destination address of the datagram with the prefix length. Only plen leading bits of the destination address of the packet will be matched. plen is optional. See saddr for valid values that can be given. If multiple source and destination addresses are found, then policy entry covering each (source address - destination address) pair will be added to the system. smask The value that follows is the source mask. If prefix length is given with saddr, this should not be given. This can be represented either in hexadecimal number with a leading 0x or 0X, for example, 0xffff0000, 0Xffff0000 or in the Inter- net decimal dot notation, for example, 255.255.0.0 and 255.255.255.0. The mask should be contiguous and the behavior is not defined for non-contiguous masks. smask is considered only when saddr is given. dmask The value that follows is the destination mask. If prefix length is given with daddr, this should not be given. This can be represented either in hexadecimal number with a leading 0x or 0X, for example, 0xffff0000, 0Xffff0000 or in the Internet decimal dot nontation, for example, 255.255.0.0 and 255.255.255.0. The mask should be contiguous and the behavior is not defined for non-contiguous masks. dmask is considered only when daddr is given. sport The value that follows is the source port of the datagram. This can be either a port number or a string searched with a NULL proto argument, as described in getservbyname(3XNET) dport The value that follows is the destination port of SunOS 5.8 Last change: 13 Oct 1999 5 Maintenance Commands ipsecconf(1M) the datagram. This can be either a port number or a string as described in getservbyname(3XNET) searched with NULL proto argument. ulp The value that follows is the Upper Layer Proto- col that this entry should be matched against. It could be a number or a string as described in getprotobyname(3XNET) If any component of the entry is not given, it will be con- sidered as a wildcard entry. Thus, if pattern is null, all packets will match the policy entry. If neither the prefix length nor the mask is given for the address, a mask will be inferred For example, if a.b.c.d is the address and + b, c and d are zeroes, the mask is 0xff000000. + only c and d are zeroes, the mask is 0xffff0000. + only d is zero, the mask is 0xffffff00. + neither a, b ,c nor d are zeroes, the mask is 0xffffffff.To avoid ambiguities, it is advisable to explicitly give either the prefix length or the mask. Policy entries may contain the following (name value) pairs in teh properties filed. Each (name value) pair may appear only once in a give policy entry. auth_algs An acceptable value following this implies that IPsec AH header will be present in the outbound datagram. Values following this describe the authentication algorithms that will be used while applying the IPsec AH on outbound datagrams and verified to be present on inbound datagrams. See RFC 2402. This entry can contain either a string or a decimal number. string This should be either MD5 or HMAC-MD5 denoting the HMAC-MD5 algorithm as described in RFC 2403, and SHA1, or HMAC-SHA1 or SHA or HMAC-SHA denoting the HMAC-SHA algorithm described in RFC 2404. The string can also be ANY, which denotes no-preference for the algo- rithm. Default algorithms will be chosen based upon the SAs available at this time for manual SAs and the key negotiating daemon for automatic SAs. Strings are not case-sensitive. SunOS 5.8 Last change: 13 Oct 1999 6 Maintenance Commands ipsecconf(1M) number A number in the range 1-255. This is useful when new algorithms can be dynamically loaded. If auth_algs is not present, the AH header will not be present in the outbound datagram, and the same will be veri- fied for the inbound datagram. encr_algs An acceptable value following this implies that IPsec ESP header will be present in the outbound datagram. The value following this describes the encryption algorithms that will be used to apply the IPsec ESP protocol to outbound datagrams and verify it to be present on inbound datagrams. See RFC 2406. This entry can contain either a string or a decimal number. Strings are not case-sensitive. string This should be either DES or DES-CBC, to denote the algorithm described in RFC 2405 or 3DES or 3DES-CBC, to denote the used of 3DES in a manner consistent with RFC 2451. The value can be NULL which implies a NULL encryption pursuant to RFC 2410. This means that the payload will not be encrypted.The string can be ANY, which denotes no-preference for the algorithm. Default algo- rithms will be chosen depending upon the SAs available at this time for manual SAs and upon the key negotating daemon for automatic SAs. number A decimal number in the range 1-255. This is useful when new algorithms can be dynamically loaded. encr_auth_algs An acceptable value following encr_auth_algs implies that the IPsec ESP header will be present in the out- bound datagram. The values following encr_auth_algs describe the authentication algorithms that will be used while applying the IPsec ESP protocol on outbound datagrams and verified to be present on inbound datagrams. See RFC 2406. This entry can contain either a string or a number. Strings are case-insensitive. string Valid values are the same as the ones described for auth_algs above. SunOS 5.8 Last change: 13 Oct 1999 7 Maintenance Commands ipsecconf(1M) number This should be a decimal number in the range 1-255. This is useful when new algorithms can be dynamically loaded. If encr_algs is present and encr_auth_algs is not present in a policy entry, the system will use an ESP SA regardless of whether the SA has an authentication algorithm or not. If encr_algs is not present and encr_auth_algs is present in a policy entry, null encryption will be provided, which is equivalent to encr_algs with NULL, for outbound and inbound datagrams. If both encr_algs and encr_auth_algs are not present in a policy entry, ESP header will not be present for outbound datagrams and the same will be verified for inbound datagrams. If both encr_algs and encr_auth_algs are present in a policy entry, ESP header with integrity checksum will be present on outbound datagrams and the same will be veri- fied for inbound datagrams. dir Values following this decides whether this entry is for outbound or inbound datagram. Valid values are strings that should be one of the following. out This means that this policy entry should be considered only for outbound datagrams. in This means that this policy entry should be considered only for inbound datagrams. This entry is not needed when the action is "apply" or "permit". But if it is given while the action is "apply" or "permit", it should be "out" or "in" respectively. This is mandatory when the action is "bypass". sa Values following this decide the attribute of the security association. Value indicates whether an unique security association should be used or any existing SA can be used. If there is a policy require- ment, SAs are created dynamically on the first out- bound datagram using the key management daemon. Static SAs can be created using ipseckey(1M). The values used here determine whether a new SA will be used/obtained. Valid values are strings that could be one of the following: SunOS 5.8 Last change: 13 Oct 1999 8 Maintenance Commands ipsecconf(1M) unique Unique Association. A new/unused association will be obtained/used for packets matching this policy entry. If an SA that was previously used by the same 5 tuples, that is, {Source address, Destination address, Source port, Destination Port, Protocol (for example, TCP/UDP)} exists, it will be reused. Thus uniqueness is expressed by the 5 tuples given above. The security asso- ciation used by the above 5 tuples will not be used by any other socket. For inbound datagrams, uniqueness will not be verified. shared Shared association. If an SA exists already for this source-destination pair, it will be used. Otherwise a new SA will be obtained. This is mandatory only for outbound policy entries and should not be given for entries whose action is "bypass". If this enty is not given for inbound entries, for example, when "dir" is in or "action" is permit, it will be assumed to be shared. Action follows the pattern and should be given before pro- perties. It should be one of the following and this field is mandatory. apply Apply IPSEC to the datagram as described by the pro- perties, if the pattern matches the datagram. If apply is given, the pattern is matched only on the outbound datagram. permit Permit the datagram if the pattern matches the incom- ing datagram and satisfies the constraints described by the properties. If it does not satisfy the proper- ties, discard the datagram. If permit is given, the pattern is matched only for inbound datagrams. bypass Bypass any policy checks if the pattern matches the datagram. dir in the properties decides whether the check is done on outbound or inbound datagrams. All the bypass entries are checked before checking with any other policy entry in the system. This has the highest precedence over any other entries. dir is the only field that should be present when action is bypass. If the file contains multiple policy entries, for example, they are assumed to be listed in the orderd in which they SunOS 5.8 Last change: 13 Oct 1999 9 Maintenance Commands ipsecconf(1M) are to be applied. In cases of multiple entries matching the outbound and inbound datagram, the first match will be taken. The system will re-order the policy entry, that is, add the new entry before the old entry, only when: + The level of protection is "stronger" than the old level of protection. Currently, strength is defined as: AH and ESP > ESP > AH The standard uses of AH and ESP were what drove this rank- ing of "stronger". There are flaws with this. ESP can be used either without authentication, which will allow cut- and-paste or replay attacks, or without encryption, which makes it equivalent or slightly weaker than AH. An administrator should take care to use ESP properly. See ipsecesp(7P) for more details. + If the new entry has bypass as action.bypass has the highest precedence. It can be added in any order, and the system will still match all the bypass entries before matching any other entries. This is useful for key management demons which can use this feature to bypass IPSEC as it protects its own traffic. Entries with both AH (auth_algs present in the policy entry) and ESP (encr_auth_algs or encr_auth_algs present in the policy entry) protection are ordered after all the entries with AH and ESP and before any AH-only and ESP-only entries. In all other cases the order specified by the user is not modified, that is,newer entries are added at the end of all the old entries. See EXAMPLES. A new entry is considered duplicate of the old entry if an old entry matches the same traffic pattern as the new entry. See EXAMPLES for information on duplicates. SECURITY CONSIDERATIONS If, for example, the policy file comes over the wire from an NFS mounted file system, an adversary can modify the data contained in the file, thus changing the policy configured on the machine to suit his needs. Administrators should be cautious about transmitting a copy of the policy file over a network. Policy is latched for TCP/UDP sockets on which a connect(3SOCKET) or accept(3SOCKET) has been issued. Adding new policy entries will not have any effects on them. This SunOS 5.8 Last change: 13 Oct 1999 10 Maintenance Commands ipsecconf(1M) feature of latching may change in the future. It is advis- able not to depend upon this feature. Make sure to set up the policies before starting any commun- ications, as existing connections may be affected by the addition of new policy entries. Similarly, do not change policies in the middle of a communication. If your source address is a host that can be looked up over the network, and your naming system itself is compromised, then any names used will no longer be trustworthy. EXAMPLES Example 1: Protecting Outbound TCP Traffic With ESP and the DES Algorithm # # Protect the outbound TCP traffic between hosts spiderweb # and arachnid with ESP and use DES algorithm. # { saddr spiderweb daddr arachnid ulp tcp #only TCP datagrams. } apply { encr_algs DES } This entry specifies that for any TCP packet from spiderweb to arachnid should be encrypted with DES and the SA could be a shared one. As no prefix len or mask is given, a mask will be inferred. To look at the mask, use the ipsecconf command with the -l option.. Note that dir is not given in properties as apply implies that only outbound packets will be matched with the pattern. Example 2: Verifying Whether or Not Inbound Traffic is Encrypted The above entry will not verify whether or not the inbound traffic is encrypted. Thus you need the following entry to protect inbound traffic.. # # Protect the TCP traffic on inbound with ESP/DES from arachnid # to spiderweb # { saddr arachnid daddr spiderweb SunOS 5.8 Last change: 13 Oct 1999 11 Maintenance Commands ipsecconf(1M) ulp tcp } permit { encr_algs DES } "sa" can be absent for inbound policy entries as it implies that it can be a shared one. Uniqueness is not verified on inbound. Note that in both the above entries, authentication was never specified..This can lead to cut and paste attacks. As mentioned previously, though the authentication is not specfied, the system will still use an ESP SA with encr_auth_alg specified, if it was found in the SA tables. Example 3: Authenticating All Inbound Traffic to the Telnet Port # # All the inbound traffic to the telnet port should be # authenticated. # { dport telnet # telnet is 23 } permit { auth_algs SHA1 dir in } This entry specifies that any inbound datagram to telnet port should come in authenticated with the SHA1 algorithm. Otherwise the datagram should not be permitted. Without this entry, traffic destined to port number 23 can come in clear. Note that dir as given is optional, as permit implies that this policy entry will be checked only on inbound. "sa" is not specified, which implies that it is shared. This can be done only for inbound entries. You need to have an equivalent entry to protect outbound traffic so that the outbound traffic is authenticated as well. Example 4: Verifying Inbound Traffic is Null-Encrypted # # Make sure that all inbound traffic from network-B is NULL # encrypted, but bypass for host-B alone from that network. # Add the bypass first. { saddr host-B } bypass { dir in } # Now add for network-B. { saddr network-B/16 SunOS 5.8 Last change: 13 Oct 1999 12 Maintenance Commands ipsecconf(1M) } permit { encr_algs ENUL encr_auth_algs md5 } The first entry specifies that any packet with address host-B should not be checked against any policies. The second entry specifies that all inbound traffic from network-B should be encrypted with a NULL encryption algo- rithm and the MD5 authentication algorithm. NULL encryption implies that ESP header will be used without encrypting the datagram. As the first entry is bypass it need not be given first in order, as bypass entries have the highest pre- cedence. Thus any inbound traffic will be matched against all bypass entries before any other policy entries.. Example 5: Encrypting a Packet with 3DES and SHA1 The following entry on host-B specifies that that any packet from hostA to hostB should be encrypted with 3DES and SHA1. { saddr hostA daddr hostB } permit { encr_algs 3DES encr_auth_algs SHA1 } If you try to add an entry { saddr hostA daddr hostB dport 23 } permit { encr_algs DES } it will fail with "ioctl:File exists". But if you change the order, that is, give the second entry first, and first entry second, it will succeed. This is because traffic to port number 23 from hostB to hostA will be protected with DES and the remainder will be protected with 3DES and SHA1. If you modify the second entry as follows, { saddr hostA daddr hostB dport 23 } permit { SunOS 5.8 Last change: 13 Oct 1999 13 Maintenance Commands ipsecconf(1M) encr_algs DES auth_algs SHA1 } it will not fail. This entry gets ordered first in the list, as the entry is protected with AH and ESP, which has pre- cedence before the prior entry that has only ESP. You can add a bypass entry in any order and it will always have the highest precedence. But, all other entries are subject to the check as explained above. The following entry { daddr 134.56.0.0 # Network address dmask 0xffff0000 } permit { auth_algs any} expects any traffic originating from 134.56.0.0 to be authenticated. You cannot add the following entry after the above entry has been added, { daddr 134.56.123.0 dmask 0xffffff00 } permit { encr_algs any} as the previous entry would match the traffic from 134.56.0.0. But you can add this entry before adding the previous entry, or you can add it with AH and ESP protec- tion. It will be reordered and considered before the previ- ous one. Example 6: Entries to Bypass Traffic from IPsec The first two entries provide that any datagram leaving the machine with source port 500 or coming into port number 500 should not be subjected to IPsec policy checks, irrespective of any other policy entry in the system. Thus the latter two entries will be considered only for ports other than port number 500. # # Bypass traffic for port no 500 # {sport 500} bypass {dir out} {dport 500} bypass {dir in} {saddr spiderweb} apply { encr_algs any sa unique} {daddr spiderweb} permit { encr_algs any} Example 7: Protecting Outbound Traffic SunOS 5.8 Last change: 13 Oct 1999 14 Maintenance Commands ipsecconf(1M) # # Protect the outbound traffic from all interfaces. # { saddr spiderweb} apply {auth_algs any sa unique} If gethostbyname ("spiderweb") yields multiple addresses, multiple policy entries will be added for all the source address with the same properties. { saddr spiderweb daddr arachnid } apply { auth_algs any sa unique} If gethostbyname ("spiderweb") and gethostbyname ("ara- chnid") yield multiple addresses, multiple policy entries will be added for each (saddr daddr) pair with the same properties. Use ipsecconf-l to view all the policy entries added here. Example 8: Bypassing Unauthenticated Traffic # # Protect all the outbound traffic with ESP except any traffic # to network-b which should be authenticated and bypass anything # to network-c # {daddr network-b/16} apply { auth_algs any } {} apply { encr_algs any sa shared} # NULL pattern {daddr network-c/16} bypass {dir out} Note that bypass can be given anywhere and it will take pre- cedence over all other entries. NULL pattern matches all the traffic. .

FILES

/etc/inet/ipsecpolicy.conf File containing IPSEC policies configured in the system. Maintained by ipsecconf command. Do not manually edit this file. /etc/inet/ipsecinit.conf File containting IPsec policies that are configured early in the boot. If present, it is read from /etc/initd.d/inetinitafter /usr is mounted.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes: SunOS 5.8 Last change: 13 Oct 1999 15 Maintenance Commands ipsecconf(1M) ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsu | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________|

SEE ALSO

init(1M),ifconfig(1M),ipseckey(1M),accept(3SOCKET),connect(3SOCKET),gethostbyname(3XNET), getnetbyname(3XNET),getprotobyname(3XNET), getservbyname(3XNET), socket(3SOCKET),attributes(5),ipsecah(7P),ipsecesp(7P),tun(7M) Glenn, R. and Kent, S.RFC 2410, The NULL Encryption Algo- rithm and Its Use With IPsec, The Internet Society, 1998. Kent, S. and Atkinson, R.RFC 2402, IP Authentication Header, The Internet Society, 1998. Kent, S. and Atkinson, R.RFC 2406, IP Encapsulating Security Payload (ESP), The Internet Society, 1998. Madsen, C. and Glenn, R., RFC 2403, The Use of HMAC-MD5-96 within ESP and AH, The Internet Society, 1998. Madsen, C. and Glenn, R., RFC 2404, The Use of HMAC-SHA-1-96 within ESP and AH, The Internet Society, 1998. Madsen, C. and Doraswamy, N., RFC 2405, The ESP DES-CBC Cipher Algorithm With Explicit IV, The Internet Society, 1998. Pereira, R. and Adams, R., RFC 2451, The ESP CBC-Mode Cipher Algorithms, The Internet Society, 1998.

DIAGNOSTICS

Bad "string" on line N." 6 Duplicate "string" on line N. String reflects one of the names in pattern or proper- ties is wrong. Bad indicates a malformed argument, and Duplicate indicates that there are multiple arguments of similar type. for example, multiple saddr. Error before or at line N. Indicates parsing error before or at line N. Non-existent index Reported when the index for delete is not a valid one. SunOS 5.8 Last change: 13 Oct 1999 16 Maintenance Commands ipsecconf(1M) ioctl: File exists Reported when there is already a policy entry that matches the traffic of this new entry. SunOS 5.8 Last change: 13 Oct 1999 17