/usr/sbin/ipsecconf

/usr/sbin/ipsecconf -a file [-q]

/usr/sbin/ipsecconf -c file

/usr/sbin/ipsecconf -d [-i tunnel-name] {index, tunnel-name, index}

/usr/sbin/ipsecconf -f [-i tunnel-name]

/usr/sbin/ipsecconf -F

/usr/sbin/ipsecconf -l [-i tunnel-name] [-n]

/usr/sbin/ipsecconf -L [-n]

The ipsecconf utility configures the IPsec policy for a host or for one of its tunnels. Once the policy is configured, all outbound and inbound datagrams are subject to policy checks as they exit and enter the host or tunnel. For the host policy, if no entry is found, no policy checks will be completed, and all the traffic will pass through. For a tunnel, if no entry is found and there is at least one entry for the tunnel, the traffic will automatically drop. The difference in behavior is because of the assumptions about IPsec tunnels made in many implementations. Datagrams that are being forwarded will not be subjected to policy checks that are added using this command. See ifconfig(8) and dladm(8) 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. To specify a single tunnel's SPD, use the -i option in combination with -l. To specify all SPDs, both host and for all tunnels, use -L.

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.

As with -l, -d can use the -i flag to indicate a tunnel. An alternate syntax is to specify a tunnel name, followed by a comma (,), followed by an index. For example, ip.tun0,1.

With no options, the entries are displayed in the order that they were added, which is not necessarily the order in which the traffic match takes 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 system restarts. Permanent policy entries should be added to /etc/inet/ipsecinit.conf. This file is read by the following smf(7) service:

svc:/network/ipsec/policy

See NOTES for more information on managing IPsec security policy and SECURITY for issues in securing /etc/inet/ipsecinit.conf.

ipsecconf supports the following options: -a file

Each policy entry contains three 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. If an entry exceeds the length of a line, you should split it only within a "braced" section or immediately before the first (left-hand) brace of a braced section. Avoid using the backslash character (\e). See EXAMPLES.

The pattern section, as shown in the syntax above, 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(8) 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> |
 type <icmp-type> |
 type <number>-<number> |
 code <icmp-code>
 code <number>-<number>
 tunnel <interface-name> |
 negotiate <tunnel,transport>

 pattern_name_value_pair2 ::=
 raddr <address>/<prefix> |
 remote <address>/<prefix> |
 rport <port> |
 laddr <address>/<prefix> |
 local <address>/<prefix> |
 lport <port> |
 ulp <protocol> |
 type <icmp-type> |
 type <number>-<number> |
 code <icmp-code> |
 code <number>-<number>
 proto <protocol> |
 tunnel <interface-name> |
 negotiate <tunnel,transport> |
 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 | hmac-sha256 | hmac-sha384 |
 hmac-sha512 |<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>'..' \e
 <number>

 sa_val ::= shared | unique

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

 number ::= < 0 | 1 | 2 ... 9> <number>
 icmp-type ::= <number> | unreach | echo | echorep | squench |
 redir | timex | paramprob | timest | timestrep |
 inforeq | inforep | maskreq | maskrep | unreach6 |
 pkttoobig6 | timex6 | paramprob6 | echo6 | echorep6 |
 router-sol6 | router-ad6 | neigh-sol6 | neigh-ad6 |
 redir6

 icmp-code ::= <number> | net-unr | host-unr | proto-unr | port-unr |
 needfrag | srcfail | net-unk | host-unk | isolate |
 net-prohib | host-prohib | net-tos | host-tos |
 filter-prohib | host-preced | cutoff-preced |
 no-route6 | adm-prohib6 | addr-unr6 | port-unr6 |
 hop-limex6 | frag-re-timex6 | err-head6 | unrec-head6 |
 unreq-opt6

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

remote/plen

srcaddr/plen

saddr/plen

dest/plen

dstaddr/plen

negotiate transport

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

Action follows the pattern and should be given before properties. It should be one of the following and this field is mandatory. ipsec

pass

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(4P) 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 .

A new entry is considered duplicate of the old entry if an old entry matches the same traffic pattern as the new entry. See 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.

To prevent non-privileged users from modifying the security policy, ensure that the configuration file is writable only by trusted users.

The configuration file is defined by a property of the policy smf(7) service. The default configuration file, is /etc/inet/ipsecinit.conf. This can be changed using the svcprop(1) command. See NOTES for more details.

The policy description language supports the use of tokens that can be resolved by means of a name service, using functions such as gethostbyname(3NSL). While convenient, these functions are only secure as the name service the system is configured to use. Great care should be taken to secure the name service if it is used to resolve elements of the security policy.

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.

If the name switch is configured to use a name service that is not local to the system, bypass policy entries might be required to prevent the policy from preventing communication to the name service. See nsswitch.conf(5).

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.

The ipsecconf command can only be run by a user who has sufficient privilege to open the pf_key(4P) socket. The appropriate privilege can be assigned to a user with the Network IPsec Management profile. See profiles(1), rbac(7), prof_attr(5).

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(4P) for more details.

Example 1 Protecting Outbound TCP Traffic With ESP and the AES Algorithm

The following example specified that any TCP packet from spiderweb to arachnid should be encrypted with AES, and the SA could be a shared one. It does not verify whether or not the inbound traffic is encrypted.

#
# Protect the outbound TCP traffic between hosts spiderweb
# and arachnid with ESP and use AES algorithm.
#
{
 laddr spiderweb
 raddr arachnid
 ulp tcp
 dir out
} ipsec {
 encr_algs AES
}

Example 2 Verifying Whether or Not Inbound Traffic is Encrypted

Example 1 does not verify whether or not the inbound traffic is encrypted. The entry in this example protects inbound traffic:

#
# Protect the TCP traffic on inbound with ESP/DES from arachnid
# to spiderweb
#
{
 laddr spiderweb
 raddr arachnid
 ulp tcp
 dir in
} ipsec {
 encr_algs AES
}

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 specified, the system will still use an ESP SA with encr_auth_alg specified, if it was found in the SA tables.

Example 3 Protecting All Traffic Between Two Hosts

The following example protects both directions at once:

{
 laddr spiderweb
 raddr arachnid
 ulp tcp
} ipsec {
 encr_algs AES
}

Example 4 Authenticating All Inbound Traffic to the Telnet Port

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. 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, remove the dir.

#
# All the inbound traffic to the telnet port should be
# authenticated.
#
{
 lport telnet
 dir in
} ipsec {
 auth_algs sha1
}

Example 5 Verifying Inbound Traffic is Null-Encrypted

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 algorithm 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 precedence. Thus any inbound traffic will be matched against all bypass entries before any other policy entries.

#
# 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.
{
raddr host-B
 dir in 
} bypass {}

# Now add for network-B.
{
 raddr network-B/16
 dir in
} ipsec {
encr_algs NULL
encr_auth_algs md5
}

Example 6 Entries to Bypass Traffic from IPsec

The first two entries provide that any datagram leaving the machine with source port 53 or coming into port number 53 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 53.

#
# Bypass traffic for port no 53
 #
{lport 53} bypass {}
{rport 53} bypass {}
{raddr spiderweb } ipsec {encr_algs any sa unique}

Example 7 Protecting Outbound Traffic

 #
 # Protect the outbound traffic from all interfaces.
 #
{raddr spiderweb dir out} ipsec {auth_algs any sa unique}

If the gethostbyname(3XNET) call for spiderweb yields multiple addresses, multiple policy entries will be added for all the source address with the same properties.

{
 laddr arachnid
 raddr spiderweb
 dir in
} ipsec {auth_algs any sa unique}

If the gethostbyname(3XNET) call for spiderweb and the gethostbyname(3XNET) call for arachnid 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.

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
#
{raddr network-b/16 dir out} ipsec {auth_algs any}
{dir out} ipsec {encr_algs any}
{raddr network-c/16 dir out} bypass {} # NULL properties

Note that bypass can be given anywhere and it will take precedence over all other entries. NULL pattern matches all the traffic.

Example 9 Encrypting IPv6 Traffic with 3DES and MD5

The following entry on the host with the link local address fe80::a00:20ff:fe21:4483 specifies that any outbound traffic between the hosts with IPv6 link-local addresses fe80::a00:20ff:fe21:4483 and fe80::a00:20ff:felf:e346 must be encrypted with 3DES and MD5.

{
 laddr fe80::a00:20ff:fe21:4483
 raddr fe80::a00:20ff:felf:e346
 dir out
} ipsec {
 encr_algs 3DES
 encr_auth_algs MD5
}

Example 10 Verifying IPv6 Traffic is Authenticated with SHA1

The following two entries require that all IPv6 traffic to and from the IPv6 site-local network fec0:abcd::0/32 be authenticated with SHA1.

{raddr fec0:abcd::0/32} ipsec { auth_algs SHA1 }

Example 11 Key Lengths

# use aes at any key length
{raddr spiderweb} ipsec {encr_algs aes}

# use aes with a 192 bit key
{raddr spiderweb} ipsec {encr_algs aes(192)}

# use aes with any key length up to 192 bits
# i.e. 192 bits or less
{raddr spiderweb} ipsec {encr_algs aes(..192)}

# use aes with any key length of 192 or more
# i.e. 192 bits or more
{raddr spiderweb} ipsec {encr_algs aes(192..)}

#use aes with any key from 192 to 256 bits
{raddr spiderweb} ipsec {encr_algs aes(192..256)}

#use any algorithm with a key of 192 bits or longer
{raddr spiderweb} ipsec {encr_algs any(192..)}

Example 12 Correct and Incorrect Policy Entries

The following are examples of correctly formed policy entries:

{ raddr that_system rport telnet } ipsec { encr_algs 3des encr_auth_algs
sha1 sa shared}

{
 raddr that_system
 rport telnet
} ipsec {
 encr_algs 3des
 encr_auth_algs sha1
 sa shared
}

{ raddr that_system rport telnet } ipsec
 { encr_algs 3des encr_auth_algs sha1 sa shared}

{ raddr that_system rport telnet } ipsec
 { encr_algs 3des encr_auth_algs sha1 sa shared} or ipsec
 { encr_algs aes encr_auth_algs sha1 sa shared}

...and the following is an incorrectly formed entry:

{ raddr that_system rport telnet } ipsec
 { encr_algs 3des encr_auth_algs sha1 sa shared}
 or ipsec { encr_algs aes encr_auth_algs sha1 sa shared}

In the preceding, incorrect entry, note that the third line begins with "or ipsec". Such an entry causes ipsecconf to return an error.

Example 13 Allowing Neighbor Discovery to Occur in the Clear

The following two entries require that all IPv6 traffic to and from the IPv6 site-local network fec0:abcd::0/32 be authenticated with SHA1. The second entry allows neighbor discovery to operate correctly.

{raddr fec0:abcd::0/32} ipsec { auth_algs SHA1 }
{raddr fec0:abcd::0/32 ulp ipv6-icmp type 133-137 dir both }
 pass { }

Example 14 Using "or"

The following entry allows traffic using the AES or Blowfish algorithms from the remote machine spiderweb:

{raddr spiderweb} ipsec {encr_algs aes} or ipsec {encr_algs blowfish}

Example 15 Configuring a Tunnel to be Backward-Compatible with Solaris 9

The following example is equivalent to "encr_algs aes encr_auth_algs md5" in ifconfig(8):

{tunnel ip.tun0 negotiate transport} ipsec {encr_algs aes
 encr_auth_algs md5}

Example 16 Configuring a Tunnel to a VPN client with an Assigned Address

The following example assumes a distinct "inside" network with its own topology, such that a client's default route goes "inside".

# Unlike route(8), the default route has to be spelled-out.
{tunnel ip.tun0 negotiate tunnel raddr client-inside/32
laddr 0.0.0.0/0} ipsec {encr_algs aes encr_auth_algs sha1}

Example 17 Transit VPN router between Two Tunnelled Subnets and a Third

The following example specifies a configuration for a VPN router that routes between two tunnelled subnets and a third subnet that is on-link. Consider remote-site A, remote-site B, and local site C, each with a /24 address allocation.

# ip.tun0 between me (C) and remote-site A.
# Cover remote-site A to remote-side B.
{tunnel ip.tun0 negotiate tunnel raddr A-prefix/24 laddr
B-prefix/24} ipsec {encr_algs 3des encr_auth_algs md5}

# Cover remote-site A traffic to my subnet.
{tunnel ip.tun0 negotiate tunnel raddr A-prefix/24 laddr
C-prefix/24} ipsec {encr_algs 3des encr_auth_algs md5}

# ip.tun1 between me (C) and remote-site B.
# Cover remote-site B to remote-site A.
{tunnel ip.tun1 negotiate tunnel raddr B-prefix/24 laddr
A-prefix/24} ipsec {encr_algs aes encr_auth_algs sha1}

# Cover remote-site B traffic to my subnet.
{tunnel ip.tun1 negotiate tunnel raddr B-prefix/24 laddr
C-prefix/24} ipsec {encr_algs aes encr_auth_algs md5}

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

auths (1), profiles (1), svcprop (1), svcs (1), gethostbyname (3NSL), accept (3SOCKET), connect (3SOCKET), getaddrinfo (3SOCKET), socket (3SOCKET), gethostbyname (3XNET), getnetbyname (3XNET), getprotobyname (3XNET), getservbyname (3XNET), ipsecah (4P), ipsecesp (4P), pf_key (4P), ike.config (5), nsswitch.conf (5), prof_attr (5), user_attr (5), attributes (7), rbac (7), smf (7), ifconfig (8), in.iked (8), init (8), ipsecalgs (8), ipseckey (8), svcadm (8), svccfg (8)

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.

Duplicate "string" on line N.

IPsec manual keys are managed by the service management facility, smf(7). The services listed below manage the components of IPsec. These services are delivered as follows:

svc:/network/ipsec/policy:default (enabled)
svc:/network/ipsec/ipsecalgs:default (enabled)
svc:/network/ipsec/manual-key:default (disabled)
svc:/network/ipsec/ike:default (disabled)

The manual-key service is delivered disabled. The system administrator must create manual IPsec Security Associations (SAs), as described in ipseckey(8), before enabling that service.

The policy service is delivered enabled, but without a configuration file, so that, as a starting condition, packets are not protected by IPsec. After you create the configuration file /etc/inet/ipsecinit.conf, as described in this man page, and refresh the service (svcadm refresh, see below), the policy contained in the configuration file is applied. If there is an error in this file, the service enters maintenance mode.

Services that are delivered disabled are delivered that way because the system administrator must create configuration files for those services before enabling them. See ike.config(5) for the ike service.

See ipsecalgs(8) for the ipsecalgs service.

The correct administrative procedure is to create the configuration file for each service, then enable each service using svcadm(8).

If the configuration needs to be changed, edit the configuration file then refresh the service, as follows:

example# svcadm refresh policy

The smf(7) framework will record any errors in the service-specific log file. Use any of the following commands to examine the logfile property:

example# svcs -l policy
example# svcprop policy
example# svccfg -s policy listprop

The following property is defined for the policy service:

config/config_file

This property can be modified using svccfg(8) by users who have been assigned the following authorization:

solaris.smf.value.ipsec

See auths(1), user_attr(5), rbac(7).

The service needs to be refreshed using svcadm(8) before the new property is effective. General non-modifiable properties can be viewed with the svcprop(1) command.

# svccfg -s ipsec/policy setprop config/config_file = /new/config_file
# svcadm refresh policy

Administrative actions on this service, such as enabling, disabling, refreshing, and requesting restart can be performed using svcadm(8). A user who has been assigned the authorization shown below can perform these actions:

solaris.smf.manage.ipsec

The service's status can be queried using the svcs(1) command.

The ipsecconf command is designed to be managed by the policy smf(7) service. While the ipsecconf command can be run from the command line, this is discouraged. If the ipsecconf command is to be run from the command line, the policy smf(7) service should be disabled first. See svcadm(8).