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.