SunOS man pages : ipseckey (1)
Maintenance Commands 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 communicat-
ing 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_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]" 6 Read commands from an input file,
filename. The lines of the input file are
SunOS 5.8 Last change: 11 Feb 1999 1
Maintenance Commands ipseckey(1M)
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 hexade-
cimal 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 stan-
dard 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 com-
mands.
-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 manage-
ment), keying material and other extensions. Like
add, this command cannot be invoked from the com-
mand 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
SunOS 5.8 Last change: 11 Feb 1999 2
Maintenance Commands ipseckey(1M)
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 mes-
sages 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 sucess-
fully 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
SunOS 5.8 Last change: 11 Feb 1999 3
Maintenance Commands ipseckey(1M)
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 speci-
fied, 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 algo-
rithms 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 algo-
rithm 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.
SunOS 5.8 Last change: 11 Feb 1999 4
Maintenance Commands ipseckey(1M)
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 pro-
tected. 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.
SunOS 5.8 Last change: 11 Feb 1999 5
Maintenance Commands ipseckey(1M)
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 des-
tination 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 exam-
ple, 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 con-
crete 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
SunOS 5.8 Last change: 11 Feb 1999 6
Maintenance Commands ipseckey(1M)
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 ued by the add and
update commands
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.
SunOS 5.8 Last change: 11 Feb 1999 7
Maintenance Commands ipseckey(1M)
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
SunOS 5.8 Last change: 11 Feb 1999 8
Maintenance Commands ipseckey(1M)
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 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
SunOS 5.8 Last change: 11 Feb 1999 9
Maintenance Commands ipseckey(1M)
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." 6 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" 6
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.
SunOS 5.8 Last change: 11 Feb 1999 10
Maintenance Commands ipseckey(1M)
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 addi-
tional names as other security protocols become available to
PF_KEY.
SunOS 5.8 Last change: 11 Feb 1999 11
|
 |
|
|
