te
Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
ipseckey - manually manipulate an IPsec Security Association Database (SADB)

ipseckey [-nvp]

ipseckey [-nvp] -f filename

ipseckey -c filename

ipseckey [-nvp] [delete | delete-pair | get] SA_TYPE {EXTENSION value...}

ipseckey [-np] [monitor | passive_monitor | pmonitor]

ipseckey [-nvp] flush {SA_TYPE}

ipseckey [-nvp] dump {SA_TYPE}

ipseckey [-nvp] save SA_TYPE {filename}

ipseckey [-nvp] -s filename

The ipseckey command is used to manually manipulate the security association databases of the network security services, ipsecah(7P) and ipsecesp(7P). You can use the ipseckey command to set up security associations between communicating parties when automated key management is not available.

While the ipseckey utility has only a limited number of general options, it supports a rich command language. The user may specify requests to be delivered by means of a programmatic interface specific for manual keying. See pf_key(7P). When ipseckey is invoked with no arguments, it will enter an interactive mode which prints a prompt to the standard output and accepts commands from the standard input until the end-of-file is reached. Some commands require an explicit security association ("SA") type, while others permit the SA type to be unspecified and act on all SA types.

ipseckey uses a PF_KEY socket and the message types SADB_ADD, SADB_DELETE, SADB_GET, SADB_UPDATE, SADB_FLUSH, and SADB_X_PROMISC. Thus, you must be a superuser to use this command.

ipseckey handles sensitive cryptographic keying information. Please read the Security section for details on how to use this command securely.

-c [filename]

-f [filename]

-n

-p

-s [filename]

-v

add

update

update-pair

delete

delete-pair

get

flush

monitor

passive_monitor

pmonitor

dump

save

help

all

ah

esp

Commands like add, delete, get, and update require that certain extensions and associated values be specified. The extensions will be listed here, followed by the commands that use them, and the commands that require them. Requirements are currently documented based upon the IPsec definitions of an SA. Required extensions may change in the future. <number> can be in either hex (0xnnn), decimal (nnn) or octal (0nnn).<string> is a text string. <hexstr> is a long hexadecimal number with a bit-length. Extensions are usually paired with values; however, some extensions require two values after them.

spi <number>

pair-spi <number>

inbound | outbound

replay <number>

replay_value <number>

state <string>|<number>

auth_alg <string>|<number>

authalg <string>|<number>

encr_alg <string>|<number>

encralg <string>|<number>

The next six extensions are lifetime extensions. There are two varieties, "hard" and "soft". If a hard lifetime expires, the SA will be deleted automatically by the system. If a soft lifetime expires, an SADB_EXPIRE message will be transmitted by the system, and its state will be downgraded to dying from mature. See pf_key(7P). The monitor command to key allows you to view SADB_EXPIRE messages.

idle_addtime <number>

idle_usetime <number>

soft_bytes <number>

hard_bytes <number>

soft_addtime <number>

hard_addtime <number>

soft_usetime <number>

hard_usetime <number>

saddr address | name

srcaddr address | name

saddr6 IPv6 address

srcaddr6 IPv6 address

src address | name

src6 IPv6 address

daddr <address>|<name>

dstaddr <address>|<name>

daddr6 <IPv6 address>|<name>

dstaddr6 <IPv6 address>|<name>

dst <addr>|<name>

dst6 <IPv6 address>|<name>

sport <portnum>

dport <portnum>

encap <protocol>

proto <protocol number>

ulp <protocol number>

nat_loc <address>|<name>

nat_rem <address>|<name>

nat_lport <portnum>

nat_rport <portnum>

isrc <address> | <name>[/<prefix>]

innersrc <address> | <name>[/<prefix>]

isrc6 <address> | <name>[/<prefix>]

innersrc6 <address> | <name>[/<prefix>]

proxyaddr <address> | <name>[/<prefix>]

proxy <address> | <name>[/<prefix>]

idst <address> | <name>[/<prefix>]

innerdst <address> | <name>[/<prefix>]

idst6 <address> | <name>[/<prefix>]

innerdst6 <address> | <name>[/<prefix>]

innersport <portnum>

isport <portnum>

innerdport <portnum>

idport <portnum>

iproto <protocol number>iulp <protocol number>

authkey <hexstring>

encrkey <hexstring>

Certificate identities are very useful in the context of automated key management, as they tie the SA to the public key certificates used in most automated key management protocols. They are less useful for manually added SAs. Unlike other extensions, srcidtype takes two values, a type, and an actual value. The type can be one of the following:

prefix

fqdn

domain

user_fqdn

mailbox

The value is an arbitrary text string that should identify the certificate.

srcidtype <type, value>

dstidtype <type, value>

An IPsec SA is a Tunnel Mode SA if the "proto" value is either 4 (ipip) or 41 (ipv6) and there is an inner-address or inner-port value specified. Otherwise, the SA is a Transport Mode SA.

Keying material is very sensitive and should be generated as randomly as possible. Some algorithms have known weak keys. IPsec algorithms have built-in weak key checks, so that if a weak key is in a newly added SA, the add command will fail with an invalid value.

The ipseckey command allows a privileged user to enter cryptographic keying information. If an adversary gains access to such information, the security of IPsec traffic is compromised. The following issues should be taken into account when using the ipseckey command.

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 not be trustworthy.

Security weaknesses often lie in misapplication of tools, not in the tools themselves. Administrators are urged to be cautious when using ipseckey. The safest mode of operation is probably on a console or other hard-connected TTY.

For further thoughts on this subject, see the afterward by Matt Blaze in Bruce Schneier's Applied Cryptography: Protocols, Algorithms, and Source Code in C.

IPsec manual keys are managed by the service management facility, smf(5). 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 this man page, 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 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. See ipsecconf(1M).

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(4) for the ike service.

See ipsecalgs(1M) for the ipsecalgs service.

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

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

example# svcadm refresh manual-key

Warning: To prevent ipseckey complaining about duplicate Associations, the ipseckey command flushes the Security Association Data Base (SADB) when the ipseckey command is run from smf(5), before adding any new Security Associations defined in the configuration file. This differs from the command line behavior where the SADB is not flushed before adding new Security Associations.

The smf(5) 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 manual-key
example# svcprop manual-key
example# svccfg -s manual-key listprop

The following property is defined for the manual-key service:

config/config_file

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

solaris.smf.value.ipsec

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

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

# svccfg -s ipsec/manual-key setprop config/config_file = \e
/new/config_file
# svcadm refresh manual-key

Administrative actions on this service, such as enabling, disabling, refreshing, and requesting restart can be performed using svcadm(1M). 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 ipseckey command is designed to be run under smf(5) management. While the ipsecconf command can be run from the command line, this is discouraged. If the ipseckey command is to be run from the command line, the manual-key smf(5) service should be disabled first. See svcadm(1M).

Example 1 Emptying Out All SAs

To empty out all SA:

example# ipseckey flush

Example 2 Flushing Out IPsec AH SAs Only

To flush out only IPsec AH SAs:

example# ipseckey flush ah

Example 3 Saving All SAs To Standard Output

To save all SAs to the standard output:

example# ipseckey save all

Example 4 Saving ESP SAs To The File /tmp/snapshot

To save ESP SAs to the file /tmp/snapshot:

example# ipseckey save esp /tmp/snapshot

Example 5 Deleting an IPsec SA

To delete an IPsec SA, only the SPI and the destination address are needed:

example# ipseckey delete esp spi 0x2112 dst 224.0.0.1

An alternative would be to delete the SA and the SAs pair if it has one:

example# ipseckey delete-pair esp spi 0x2112 dst 224.0.0.1

Example 6 Getting Information on an IPsec SA

Likewise, getting information on a SA only requires the destination address and SPI:

example# ipseckey get ah spi 0x5150 dst mypeer

Example 7 Adding or Updating IPsec SAs

Adding or updating SAs requires entering interactive mode:

example# ipseckey
ipseckey> add ah spi 0x90125 src me.domain.com dst you.domain.com \e
 authalg md5 authkey 1234567890abcdef1234567890abcdef
ipseckey> update ah spi 0x90125 dst you.domain.com hard_bytes \e
 16000000
ipseckey> exit

Adding two SAs that are linked together as a pair:

example# ipseckey
ipseckey> add esp spi 0x2345 src me.domain.com dst you.domain.com \e
 authalg md5 authkey bde359723576fdea08e56cbe876e24ad \e
 encralg des encrkey be02938e7def2839
ipseckey> add esp spi 0x5432 src me.domain.com dst you.domain.com \e
 authalg md5 authkey bde359723576fdea08e56cbe876e24ad \e
 encralg des encrkey be02938e7def2839 pair-spi 0x2345
ipseckey> exit

Example 8 Adding an SA in the Opposite Direction

In the case of IPsec, SAs are unidirectional. To communicate securely, a second SA needs to be added in the opposite direction. The peer machine also needs to add both SAs.

example# ipseckey 
ipseckey> add ah spi 0x2112 src you.domain.com dst me.domain.com \e
 authalg md5 authkey bde359723576fdea08e56cbe876e24ad \e
 hard_bytes 16000000
ipseckey> exit

Example 9 Monitoring PF_KEY Messages

Monitoring for PF_KEY messages is straightforward:

example# ipseckey monitor

Example 10 Using Commands in a File

Commands can be placed in a file that can be parsed with the -f option. This file may contain comment lines that begin with the "#" symbol. For example:

# This is a sample file for flushing out the ESP table and 
# adding a pair of SAs. 

flush esp 

### Watch out! I have keying material in this file. See the 
### SECURITY section in this manual page for why this can be 
### dangerous .

add esp spi 0x2112 src me.domain.com dst you.domain.com \e
 authalg md5 authkey bde359723576fdea08e56cbe876e24ad \e
 encralg des encrkey be02938e7def2839 hard_usetime 28800 
add esp spi 0x5150 src you.domain.com dst me.domain.com \e
 authalg md5 authkey 930987dbe09743ade09d92b4097d9e93 \e
 encralg des encrkey 8bd4a52e10127deb hard_usetime 28800

## End of file - This is a gratuitous comment

Example 11 Adding SAs for IPv6 Addresses

The following commands from the interactive-mode create an SA to protect IPv6 traffic between the site-local addresses

example # ipseckey
ipseckey> add esp spi 0x6789 src6 fec0:bbbb::4483 dst6 fec0:bbbb::7843\e
 authalg md5 authkey bde359723576fdea08e56cbe876e24ad \e
 encralg des encrkey be02938e7def2839 hard_usetime 28800
ipseckey>exit

Example 12 Linking Two SAs as a Pair

The following command links two SAs together, as a pair:

example# ipseckey update esp spi 0x123456 dst 192.168.99.2 \e
pair-spi 0x654321

/etc/inet/secret/ipseckeys

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Committed

ps(1), svcprop(1), svcs(1), ipsecconf(1M), ipsecalgs(1M), route(1M), svcadm(1M), svccfg(1M), ike.config(4), attributes(5), smf(5), ipsec(7P), ipsecah(7P), ipsecesp(7P), pf_key(7P)

Schneier, B., Applied Cryptography: Protocols, Algorithms, and Source Code in C. Second ed. New York, New York: John Wiley & Sons, 1996.

The ipseckey command parses the configuration file and reports any errors. In the case of multiple errors, ipseckey reports as many of these as possible.

The ipseckey command does not attempt to use a COMMAND that has a syntax error. A COMMAND might be syntactically correct but can nevertheless generate an error because the kernel rejected the request made to pf_key(7P). This might occur because a key had an invalid length or because an unsupported algorithm was specified.

If there are any errors in the configuration file, ipseckey reports the number of valid COMMANDS and the total number of COMMANDS parsed.

Parse error on line N.

Unexpected end of command line.

Unknown

Address type N not supported.

N is not a bit specifier

bit length N is too big for

string is not a hex string

Can only specify single

Don't use extension for <string> for <command>.

One of the entered values is incorrect: Diagnostic code NN: <msg>

In spite of its IPsec-specific name, ipseckey is analogous to route(1M), in that it is a command-line interface to a socket-based administration engine, in this case, PF_KEY. PF_KEY was originally developed at the United States Naval Research Laboratory.

To have machines communicate securely with manual keying, SAs need to be added by all communicating parties. If two nodes wish to communicate securely, both nodes need the appropriate SAs added.

In the future ipseckey may be invoked under additional names as other security protocols become available to PF_KEY.

This command requires sys_ip_config privilege to operate and thus can run in the global zone and in exclusive-IP zones. The global zone can set up security associations with ipseckey to protect traffic for shared-IP zones on the system.