ipseckey(1M)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | COMMANDS | SECURITY ASSOCIATION TYPES | EXTENSION VALUE TYPES | SECURITY CONSIDERATIONS | EXAMPLES | ATTRIBUTES | SEE ALSO | DIAGNOSTICS | NOTES

NAME

ipseckey- manually manipulate an IPsec Security Association Database (SADB)

SYNOPSIS

ipseckey [-nvp]
ipseckey [-nvp] -f filename
ipseckey [-nvp] [delete| 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

DESCRIPTION

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_PROMISE. Thus, you must be a superuser to use this command.

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

OPTIONS

-f [filename]

Read commands from an input file, filename. The lines of the input file are identical to the command line language. The load command provides similar functionality. The -s option or the save command can generate files readable by the -f argument.

-n

Prevent attempts to print host and network names symbolically when reporting actions. This is useful, for example, when all name servers are down or are otherwise unreachable.

-p

Paranoid. Do not print any keying material, even if saving SAs. Instead of an actual hexadecimal digit, print an X when this flag is turned on.

-s [filename]

The opposite of the -f option. If '-' is given for a filename, then the output goes to the standard output. A snapshot of all current SA tables will be output in a form readable by the -f option. The output will be a series of add commands.

-v

Verbose. Print the messages being sent into the PF_KEY socket, and print raw seconds values for lifetimes.

COMMANDS

add

Add an SA. Because it involves the transfer of keying material, it cannot be invoked from the command line. The add command accepts all extension-value pairs described below.

update

Update SA lifetime, and in the cases of larval SAs (leftover from faulty automated key management), keying material and other extensions. Like add, this command cannot be invoked from the command line because keying material could be seen by the ps(1) command. The update command accepts all extension-value pairs, but normally is only used for SA lifetime updates.

delete

Delete a specific SA from a specific SADB. This command requires the spi extension, and the dest extension for IPsec SAs. Other extension-value pairs are superfluous for a delete message.

get

Lookup and display a security association from a specifc SADB. Like delete, this command only requires spi and dest for IPsec.

flush

Remove all SA for a given SA_TYPE, or all SA for all types.

monitor

Continuously report on any PF_KEY messages. This uses the SADB_X_PROMISC message to enable messages that a normal PF_KEY socket would not receive to be received.. See pf_key(7P).

passive_monitor

Like monitor, except that it does not use the SADB_X_PROMISC message.

pmonitor

Synonym for passive_monitor.

dump

Will display all SAs for a given SA type, or will display all SAs. Because of the large amount of data generated by this command, there is no guarantee that all SA information will be sucessfully delivered, or that this command will even complete.

save

Is the command analog of the -s option. It is included as a command to provide a way to snapshot a particular SA type, for example, esp or ah.

help

Prints a brief summary of commands.

SECURITY ASSOCIATION TYPES

all

Specifies all known SA types. This type is only used for the flush and dump commands. This is equivalent to having no SA type for these commands.

ah

Specifies the IPsec Authentication Header ("AH") SA.

esp

Specifies the IPsec Encapsulating Security Payload ("ESP") SA).

EXTENSION VALUE TYPES

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 hexidecmal number with a bit-length. Extensions are usually paired with values; however, some extensions require two values after them.

spi <number>

Specifies the security parameters index of the SA. This extension is required for the add, delete, get and update commands.

replay <number>

Specifies the replay window size. If not specified, the replay window size is assumed to be zero. It is not recommended that manually added SAs have a replay window. This extension is used by the add and update commands.

state <string> | <number>

Specifies the SA state, either by numeric value or by the strings "larval", "mature", "dying" or "dead". If not specified, the value defaults to mature. This extension is used by the add and update commands.

auth_alg <string> | <number>
authalg <string> | <number>

Specifies the authentication algorithm for an SA, either by numeric value, or by strings indicating an algorithm name. Current authentication algorithms include:

HMAC-MD5

md5, hmac-md5

HMAC-SH-1

sha, sha-1, hmac-sha1, hmac-sha

Often, algorithm names will have several synonyms. This extension is required by the add command for certain SA types. It is also used by the update command.

encr_alg <string> | <number>
encralg <string> | <number>

Specifies the encryption algorithm for an SA, either by numeric value, or by strings indicating an algorithm name. Current encryption algorithms include DES ("des")and Triple-DES ("3des"). This extension is required by the add command for certain SA types. It is also used by the update command.

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.

soft_bytes <number>
hard_bytes <number>

Specifies the number of bytes that this SA can protect. If <number> is not specified, the default value is zero, which means that the SA will not expire based on the number of bytes protected. This extension is used by the add and update commands.

soft_addtime <number>
hard_addtime <number>

Specifies the number of seconds that this SA can exist after being added or updated from a larval SA. An update of a mature SA does not reset the initial time that it was added. If <number> is not specified, the default value is zero, which means the SA will not expire based on how long it has been since it was added. This extension is used by the add and update commands.

soft_usetime <number>
hard_usetime <number>

Specifies the number of seconds this SA can exist after first being used. If <number> is not specified, the default value is zero, which means the SA will not expire based on how long it has been since it was added. This extension is used by the add and update commands.

srcaddr <address>
src <address>

srcaddr <address> and src <address> are synonyms that indicate the source address of the SA. If unspecified, the source address will either remain unset, or it will be set to a wildcard address if a destination address was supplied. This is valid for IPsec SAs. Future SA types may alter this assumption. This extension is used by the add, update, get and delete commands.

dstaddr <addr>
dst <addr>

dstaddr <addr> and dst <addr> are synonyms that indicate the destination address of the SA. If unspecified, the destination address will remain unset. Because IPsec SAs require a specified destination address and spi for identification, this extension, with a specific value, is required for the add, update, get and delete commands.

proxyaddr <address>
proxy <address>

proxyaddr <address> and proxy <address> are synonyms that indicate the proxy address for the SA. A proxy address is used for an SA that is protecting an inner protocol header. The proxy address is the source address of the inner protocol's header. This extension is used by the add and update commands.

authkey <hexstring>

Specifies the authentication key for this SA. The key is expressed as a string of hexidecimal digits, with an optional / at the end, for example, 123/12. Bits are counted from the most-significant bits down. For example, to express three '1' bits, the proper syntax is the string "e/3". For multi-key algorithms, the string is the concatentation of the multiple keys. This extension is used by the add and update commands.

encrkey <hexstring>

Specifies the encryption key for this SA. The syntax of the key is the same as authkey. A concrete example of a multi-key encryption algorithm is 3des, which would express itself as a 192-bit key, which is three 64-bit parity-included DES keys. This extension is used by the add and update commands.

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.

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

An address prefix.

fqdn

A fully-qualified domain name.

domain

Domain name, synonym for fqdn.

user_fqdn

User identity of the form user@fqdn.

mailbox

Synonym for user_fqdn.

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

srcidtype <type, value>

Specifies a source certificate identity for this SA. This extension is used by the add and update commands.

dstidtype <type, value>

Specifies a destination certificate identity for this SA. This extension is ued by the add and update commands

SECURITY CONSIDERATIONS

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.

1. Is the TTY going over a network (interactive mode)?

   • If it is, then the security of the keying material is the security of the network path for this TTY's traffic. Using ipseckey over a clear-text telnet or rlogin session is risky.

   • Even local windows may be vulnerable to attacks where a concealed program that reads window events is present.

2. Is the file accessed over the network or readable to the world (-f option)?

   • A network-mounted file can be sniffed by an adversary as it is being read. A world-readable file with keying material in it is also risky.

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.

Security weaknesses often lie in misapplication of tools, not 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.

EXAMPLES

---

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

---

---

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 \ authalg md5 authkey 1234567890abcdef1234567890abcdef ipseckey> update ah spi 0x90125 dst you.domain.com hard_bytes \ 16000000 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 \ authalg md5 authkey bde359723576fdea08e56cbe876e24ad \ 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 CONSIDERATIONS section in this manual page for why this can be
### dangerous.

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

## End of file  -  This is a gratuitous comment

---

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcsu
Interface Stability	Evolving

SEE ALSO

ps(1),ipsecconf(1M),route(1M),attributes(5),ipsec(7P),ipsecah(7P),ipsecesp(7P),pf_key(7P)

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

DIAGNOSTICS

Parse error on line N.

If an interactive use of ipseckey would print usage information, this would print instead. Usually proceeded by another diagnostic.

Unexpected end of command line.

An additional argument was expected on the command line.

Unknown

A value for a specific extension was unknown.

Address type N not supported.

A name-to-address lookup returned an unsupported address family.

is not a bit specifier
bit length N is too big for
string is not a hex string

Keying material was not entered appropriately.

Can only specify single

A duplicate extension was entered.

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

An extension not used by a command was used.

NOTES

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.

If the -n flag is not used when saving SAs, the resulting name for an address may not directly map to the address of an SA. In the future ipseckey may be invoked under additional names as other security protocols become available to PF_KEY.

SunOS 5.8  Last Revised 11 Feb 1999

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | COMMANDS | SECURITY ASSOCIATION TYPES | EXTENSION VALUE TYPES | SECURITY CONSIDERATIONS | EXAMPLES | ATTRIBUTES | SEE ALSO | DIAGNOSTICS | NOTES