ipseckey(1M)
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 ser-
vices, 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 gen-
eral options, it supports a rich command language. The user
may specify requests to be delivered by means of a program-
matic 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 out-
put 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 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 func-
tionality. The -s option or the save command can gen-
erate files readable by the -f argument.
-n Prevent attempts to print host and network names sym-
bolically when reporting actions. This is useful, for
example, when all name servers are down or are other-
wise 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, but with some names not used.
This occurs because a single name may often indicate
multiple addresses.
-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 shell, lest
the keys be visible in ps(1) output. It can be used
either from the interactive ipseckey> prompt or in a
command file specified by the -f command. The add com-
mand accepts all extension-value pairs described
below.
update
Update SA lifetime, and in the cases of larval SAs
(leftover from aborted automated key management), key-
ing material and other extensions. Like add, this com-
mand cannot be invoked from the shell because keying
material would be seen by the ps(1) command. It can be
used either from the interactive ipseckey> prompt or
in a command file specified by the -f 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 com-
mand requires the spi extension, and the dest exten-
sion for IPsec SAs. Other extension-value pairs are
superfluous for a delete message.
get Lookup and display a security association from a
specific 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 successfully 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 cer-
tain 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. Require-
ments are currently documented based upon the IPsec defini-
tions 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>
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 com-
mand.
encr_alg <string>|<number>
encralg <string>|<number>
Specifies the encryption algorithm for an SA, either
by numeric value, or by strings indicating an algo-
rithm name. Current encryption algorithms include DES
("des"), Triple-DES ("3des"), Blowfish ("blowfish"),
and AES ("aes"). 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 pro-
tect. If this extension is not present, 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 this extension is not present,
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 this extension is not
present, 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.
saddr <address|name>
srcaddr <address|name>
saddr6 <IPv6 address>
srcaddr6 <IPv6 address>
src <address|name>
src6 <IPv6 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. To not specify the source
address is valid for IPsec SAs. Future SA types may
alter this assumption. This extension is used by the
add, update, get and delete commands.
daddr <address|name>
dstaddr <address|name>
daddr6 <IPv6 address|name>
dstaddr6 <IPv6 address|name>
dst <addr|name>
dst6 <IPv6 address|name>
dstaddr <addr> and dst <addr> are synonyms that indi-
cate the destination address of the SA. If unspeci-
fied, 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.
If a name is given, ipseckey will attempt to invoke
the command on multiple SAs with all of the destina-
tion addresses that the name can identify. This is
similar to how ipsecconf handles addresses.
If dst6 or dstaddr6 is specified, only the IPv6
addresses identified by a name are used.
proxyaddr <address|name>
proxy <address|name>
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 hexadecimal 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 concatenation 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 pro-
tocols. 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 used by the add and update com-
mands
SECURITY CONSIDERATIONS
The ipseckey command allows a privileged user to enter cryp-
tographic 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)?
o 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.
o 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)?
o A network-mounted file can be sniffed by an adver-
sary 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: Proto-
cols, 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 des-
tination 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 communi-
cate 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
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
authalg md5 authkey bde359723576fdea08e56cbe876e24ad
encralg des encrkey be02938e7def2839 hard_usetime 28800
ipseckey>exit
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| 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)
Schneier, 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 pro-
ceeded 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.
One of the entered values is incorrect: Diagnostic code NN:<msg>
This is a general invalid parameter error. The diag-
nostic code and message provides more detail about
what precise value was incorrect and why.
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.
In the future ipseckey may be invoked under additional names
as other security protocols become available to PF_KEY.
Man(1) output converted with
man2html