Tribblix: manual page: tcpkey.8

TCPKEY(8) Maintenance Commands and Procedures TCPKEY(8)

NAME

tcpkey - Manages the Security Association Database (SADB) for TCP

SYNOPSIS

tcpkey [-nvp]
tcpkey [-nvp] -f filename
tcpkey -c filename
tcpkey [-nvp] get {Extension value...}
tcpkey [-nvp] delete {Extension value...}
tcpkey [-nvp] flush
tcpkey [-nvp] dump
tcpkey [-nvp] save [filename]

DESCRIPTION

The tcpkey command is used to manually manipulate the tcp(4P) security
association (SA) database.

TCP SAs are in one of three states:

mature A newly added SA starts in the mature state and will remain
there unless it is configured with any limits on its lifetime.

dying A mature SA which exceeds a soft lifetime limit will transition
into the dying state. This state is informational only; the SA
can continue to be used. A dying SA can be moved back to the
mature state by updating its lifetime limits via the update
command, so that they are no longer exceeded. A dying SA will
transition to dead and be removed when it is either deleted via
a delete or flush command, or subsequently exceeds a hard
lifetime limit.

dead An SA which exceeds a hard lifetime limit will transition into
the dead state, be unavailable for use on any new connections,
and be removed from the system as soon as it is no longer used
by any established TCP session.

While the tcpkey 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(4P). When tcpkey is invoked with no arguments, it
will enter an interactive mode which prints a prompt ("tcpkey>") to the
standard output and accepts commands from the standard input until the
end-of-file is reached.

tcpkey uses a pf_key(4P) socket and the message types SADB_ADD,
SADB_UPDATE, SADB_DELETE, SADB_GET and SADB_FLUSH. Thus, you must have
the PRIV_SYS_IP_CONFIG privilege to use this command.

OPTIONS

-c [filename]
Analogous to the -f option (see following), except that the
input is not executed but only checked for syntactical
correctness. Errors are reported to stderr. This option is
provided to debug configurations without making changes.

-f [filename]
Read commands from an input file, filename. The lines of the
input file are identical to the command line language. 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.
Instead of an actual hexadecimal digit, print an `X' when this
flag is turned on.

-v Verbose. Print the messages being sent into the pf_key(4P)
socket, and print raw seconds values for lifetimes.

COMMANDS

add Add an SA. Because it involves the transfer of keying
material, this command and its parameters cannot be passed in
as arguments to tcpkey, lest the keys be visible in ps(1)
output. It can be used either from the interactive `tcpkey>'
prompt or in a command file specified by the -f option. The
add command accepts all extension-value pairs described below.

update Update SA lifetime extensions. Like add this command can only
be used either from the interactive `tcpkey>' prompt or in a
command file specified by the -f option. The update command
accepts all extension-value pairs described below with the
exception of those used to configure algorithm or keying
material, which cannot be changed once an SA is established.

delete Delete a specific SA. This command requires the src extension,
and the dest extension. If the SA is in use, it will be marked
for deletion and no longer used for new connection setup.
Existing connections will however continue to use it until they
are closed.

get Look up and display a security association. Like delete, this
command only requires src and dest.

flush Remove all SAs.

dump 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.

help Prints a brief summary of commands.

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.

src addr | name Source address of the SA.
src6 IPv6addr

dst addr | name Destination address of the SA.
dst6 IPv6addr

sport port Source port number. If unspecified, the SA will
match any source port.

dport port Destination port number. If unspecified, the SA
will match any destination port.

authalg algorithm Authentication algorithm. The only supported
value is `md5'.
authstring string Authentication string. Only ASCII characters are
supported and the authentication string must be
no longer than 80 characters.

The next four 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, or marked for deletion and no
longer used for new connection setup if it is in use. Existing
connections will continue to use the SA until they are closed. If a
soft lifetime expires, its state is downgraded to dying from mature.
In either case, an SADB_EXPIRE message will be queued by the system and
transmitted upstream on the pf_key(4P) socket the next time a
downstream command is received. The ipseckey(8) monitor command to key
allows you to view SADB_EXPIRE messages.

soft_addtime
hard_addtime Specifies the number of seconds that this SA can
exist after being added. Updating an SA does not
reset the initial time that it was added. If the
system clock has been altered since the SA was
established, you may need to adjust the specified
duration to achieve the desired outcome. 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
hard_usetime Specifies the number of seconds this SA can exist
after first being used. If the system clock has
been altered since the SA was first used, you may
need to adjust the specified duration to achieve
the desired outcome. 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 first used. This extension is
used by the add and update commands.

FILES

/etc/inet/secret/tcpkeys
Default configuration file used at boot time.

EXAMPLES

Example 1 Empting Out All SAs

# tcpkey flush

Example 2 Saving All SAs To Standard Output

# tcpkey save

Example 3 Adding a pair of SAs

Note that the second SA specifies 179 as the source port so that it
matches reply traffic.

# tcpkey
tcpkey> add src 192.168.1.1 dst 192.168.1.2 dport 179 \
authalg md5 authstring s3kr1t
tcpkey> add src 192.168.1.2 dst 192.168.1.1 sport 179 \
authalg md5 authstring s3kr1t
tcpkey> exit

Example 4 Displaying all SAs

# tcpkey dump
Base message (version 2) type DUMP, SA type TCPSIG.
Message length 112 bytes, seq=5, pid=649091.
SRC: Source address (proto=6/tcp)
SRC: AF_INET6: port 0, ::ffff:192.168.1.1/32 (host.example.com).
DST: Destination address (proto=6/tcp)
DST: AF_INET6: port 179, ::ffff:192.168.1.2/32 <unknown>.
AST: Authentication string.
AST: "s3kr1t"

INTERFACE STABILITY

The command line interface of tcpkey is Uncommitted. The command line
interface of tcpkey is Not-An-Interface and may change at any time.