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 can protect traffic in either one direction (requiring a pair of entries) or by a single policy entry which installs the needed symmetric sadb rules.

When the command is issued without any arguments, the list of (file policy entries) loaded are shown. To display the (spd p.e.s) use the -l option. Both will display the index number for the entry.

Note, since one file policy entry (FPE) can generate multiple SPD pol entries (SPEs), the list of FPEs may not show all the actual entries. However, it is still useful in determining what what rules have been added to get the spd into its current state.

You can use the -d option with the index to delete a given policy in the system. If the -d option removes an FPE entry that produces multiple SPEs, only then SPD with the same policy index as the FPE will be removed. This can produce a situation where there may be SPEs when there are no FPEs

With no options, 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 the -l option. The rules are ordered such that all bypass rules are checked first, then ESP rules, then AH rules. After that, they are checked in the order entered.

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 for issues in securing this file.

ipsecconf supports the following option:

-a file

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, the addition of new policy entries may not affect such endpoints or sockets. However, the policy will be latched for a socket with an existing non-null policy. Thus, make sure that there are no preexisting connections that will 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 invoking ipsecconf without any arguments, or with the -l option. See DESCRIPTION for more information. 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 with connections for which the policy has been latched, packets will continue to go out with the same policy, even if it has been deleted. It is advisable to use the -l option to find the correct policy index.

-f

Flush all the policies in the system. Constraints are similar to the -d option with respect to latching.

-l

Listing of the internal system policy table. When ipsecconf is invoked without any arguments, a complete list of policy entries with indexes added by the user since boot is displayed. The current table can differ from the previous one if, for example, a multi-homed entry was added or policy reordering occurred, or if a single rule entry generates two spd rules In the case of a multi-homed entry, all the addresses are listed explicitly. If a 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. Suppresses the warning message generated when adding policies.

Each policy entry contains 3 parts specified as follows:

{pattern} action {properties}

or

{pattern} action {properties} ["or" action {properties}]*

Every policy entry begins on a new line and can span multiple lines. pattern specifies the traffic pattern that should be matched against the outbound and inbound datagrams. If there is a match, a specific action determined by the second argument will be taken, depending upon the properties of the policy entry.

If there is an or in the rule (multiple action-properties for a given pattern), a transmitter will use the first action-property pair that works, while a receiver will use any that are acceptable.

pattern and properties are name-value pairs where name and value are separated by a <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 a wildcard. Wildcard entries match any corresponding entry in the datagram.

One thing to remember is that UDP port 500 is always bypassed regardless of any policy entries. This is a requirement for in.iked(1M) to work.

File can be commented by using a # 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 ::= { <pattern1> } <action1> { <properties1> } |
     { <pattern2> } <action2> { <properties2> } 
     [ 'or' <action2> { <properties2>} ]*

     pattern1 ::=  <pattern_name_value_pair1>*

     pattern2 ::=  <pattern_name_value_pair2>*
 
     action1 ::= apply | permit | bypass | pass
     action2 ::=  bypass | pass | drop | ipsec

     properties1 ::=   {<prop_name_value_pair1>}
     properties2 ::=   {<prop_name_value_pair2>}


     pattern_name_value_pair1 ::=
        saddr <address>/<prefix> |
        src  <address>/<prefix> |
        srcaddr <address>/<prefix> |      
        smask <mask> |
        sport <port> |
        daddr <address>/<prefix> |
        dst <address>/<prefix> |
        dstaddr <address>/<prefix> |
        dmask <mask> |
        dport <port> |
        ulp <protocol> |
        proto <protocol>

     pattern_name_value_pair2 ::=
        raddr <address>/<prefix> |
        remote  <address>/<prefix> |
        rport <port> |
        laddr <address>/<prefix> |
        local <address>/<prefix> |
        lport <port> |
        ulp <protocol> |
        proto <protocol>  |
        dir <dir_val2>

     address ::=  <IPv4 dot notation> | <IPv6 colon notation> |
                  <String recognized by gethostbyname>|
                  <String recognized by getnetbyname>

     prefix ::=  <number>

     mask ::= <0xhexdigit[hexdigit]> | <0Xhexdigit[hexdigit]> |
              <IPv4 dot notation>

     port ::= <number>| <String recognized by getservbyname>

     protocol ::=  <number>| <String recognized by getprotobyname>

     prop_name_value_pair1 ::=
          auth_algs <auth_alg> |
          encr_algs <encr_alg> |
          encr_auth_algs <auth_alg> |
          sa <sa_val> |
          dir <dir_val1>

     prop_name_value_pair2 ::=
          auth_algs <auth_alg> |
          encr_algs <encr_alg> |
          encr_auth_algs <auth_alg> |
          sa <sa_val>

     auth_alg ::=  <auth_algname> ['(' <keylen> ')']
     auth_algname ::= any | md5 | hmac-md5 | sha | sha1 | hmac-sha | 
                      hmac-sha1 | <number>

     encr_alg ::= <encr_algname> ['(' <keylen> ')']
     encr_algname ::= any | aes | aes-cbc | des | des-cbc | 3des | 
                      3des-cbc | blowfish | blowfish-cbc | <number>
     
     keylen ::= <number> | <number>'..' | '..'<number> | <number>'..'<number>

     sa_val ::= shared | unique

     dir_val1 ::= out | in
     dir_val2 ::= out | in | both

     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.

laddr/plen

local/plen

The value that follows is the local 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. Local means destination on incoming and source on outgoing packets. The source address value can be a hostname as described in getaddrinfo(3XSOCKET) or a network 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 getaddrinfo(3XSOCKET) returns multiple addresses for the host, then policy will be added for each of the addresses with other entries remaining the same.

raddr/plen

remote/plen

The value that follows is the remote address of the datagram with the prefix length. Only plen leading bits of the remote address of the packet will be matched. plen is optional. Remote means source on incoming packets and destination on outgoing packets. The remote address value can be a hostname as described in getaddrinfo(3SOCKET) or a network 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 getaddrinfo(3SOCKET) returns multiple addresses for the host, then policy will be added for each of the addresses with other entries remaining the same.

src/plen

srcaddr/plen

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 getaddrinfo(3xsocket) or a network 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 getaddrinfo(3xsocket) returns multiple addresses for the host, then policy will be added for each of the addresses with other entries remaining the same.

daddr/plen

dest/plen

dstaddr/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 a policy entry that covers each source address-destination address pair will be added to the system.

smask

For IPv4 only. 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 Internet 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.

For both IPv4 and IPv6 addresses, the same information can be specified as a slen value attached to the saddr parameter.

dmask

Analogous to smask.

lport

The value that follows is the local 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 the datagram. This can be either a port number or a string searched with a NULL proto argument, as described in getservbyname(3XNET)

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 the datagram. This can be either a port number or a string as described in getservbyname(3XNET) searched with NULL proto argument.

proto

ulp

The value that follows is the Upper Layer Protocol that this entry should be matched against. It could be a number or a string as described in getprotobyname(3XNET)If no smask or plen is specified, a plen of 32 for IPv4 or 128 for IPv6 will be used.

If no smask or plen is specified, a plen of 32 for IPv4 or 128 for IPv6 will be used, meaning a host.

Policy entries may contain the following (name value) pairs in the properties field. Each (name value) pair may appear only once in a given 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 algorithm. 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.

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 verified 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 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 algorithm. 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.

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 outbound 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.

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 verified for inbound datagrams.

For encr_algs, encr_auth_algs, and auth_algs a key length specification may be present. This is either a single value specifying the only valid key length for the algorithm or a range specifying the valid minimum and/or maximum key lengths. Minimum or maximum lengths may be omitted.

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.

both

This means that this policy entry should be considered for both inbound and outbound datagrams

This entry is not needed when the action is "apply", "permit" or "ipsec". 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 a unique security association should be used or any existing SA can be used. If there is a policy requirement, SAs are created dynamically on the first outbound 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:

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 association 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 the default.

This is mandatory only for outbound policy entries and should not be given for entries whose action is "bypass". If this entry 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 properties. It should be one of the following and this field is mandatory.

ipsec

Use IPsec for the datagram as described by the properties, if the pattern matches the datagram. If ipsec is given without a dir spec , the pattern is matched to incoming and outgoing datagrams.

apply

Apply IPsec to the datagram as described by the properties, 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 incoming datagram and satisfies the constraints described by the properties. If it does not satisfy the properties, discard the datagram. If permit is given, the pattern is matched only for inbound datagrams.

bypass

pass

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.

drop

Drop any packets that match the pattern.

If the file contains multiple policy entries, for example, they are assumed to be listed in the order in which they are to be applied. In cases of multiple entries matching the outbound and inbound datagram, the first match will be taken. The system will reorder 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 ranking 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 daemons 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.

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 effect on them. This feature of latching may change in the future. It is not advisable to depend upon this feature.

Make sure to set up the policies before starting any communications, as existing connections may be affected by the addition of new policy entries. Similarly, do not change policies in the middle of a communication.

Note that certain ndd tunables affect how policies configured with this tool are enforced; see ipsecesp(7P) for more details.

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.

/var/run/ipsecpolicy.conf

Cache of IPsec policies currently configured for the system, maintained by ipsecconf command. Do not edit this file.

/etc/inet/ipsecinit.conf

File containing IPsec policies to be installed at the time the system transitions from run-level 2 or 3. If present, these policies are loaded after /usr is mounted but before any non-boot-time routing information is processed and before any Internet services are started, including naming services.

/etc/inet/ipsecinit.sample

Sample input file for ipseconf.

See attributes(5) for descriptions of the following attributes:

in.iked(1M), init(1M), ifconfig(1M), ipseckey(1M), accept(3SOCKET), connect(3SOCKET), gethostbyname(3XNET), getnetbyname(3XNET), getprotobyname(3XNET), getservbyname(3XNET), getaddrinfo(3SOCKET), socket(3SOCKET), attributes(5), ipsecah(7P) , ipsecesp(7P), tun(7M)

Glenn, R. and Kent, S. RFC 2410, The NULL Encryption Algorithm 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.

Frankel, S. and Kelly, R. Glenn, The AES Cipher Algorithm and Its Use With IPsec, 2001.

Bad "string" on line N.

Duplicate "string" on line N.

string refers to one of the names in pattern or properties. A Bad string indicates that an argument is malformed; a Duplicate string indicates that there are multiple arguments of a similar type, for example, multiple Source Address arguments..

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.

spd_msg return: File exists

Reported when there is already a policy entry that matches the traffic of this new entry.