.\"
.\" The contents of this file are subject to the terms of the Common
.\" Development and Distribution License (the "License").  You may not use
.\" this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or
.\" http://www.opensolaris.org/os/licensing.  See the License for the
.\" specific language governing permissions and limitations under the
.\" License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each file
.\" and include the License file at usr/src/OPENSOLARIS.LICENSE.  If
.\" applicable, add the following below this CDDL HEADER, with the fields
.\" enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 2024 Oxide Computer Company
.\"
.Dd August 14, 2024
.Dt TCPKEY 8
.Os
.Sh NAME
.Nm tcpkey
.Nd Manages the Security Association Database (SADB) for TCP
.Sh SYNOPSIS
.Nm
.Op Fl nvp
.Nm
.Op Fl nvp
.Fl f Ar filename
.Nm
.Fl c Ar filename
.Nm
.Op Fl nvp
.Cm get
.Brq Ar Extension value Ns No \&...
.Nm
.Op Fl nvp
.Cm delete
.Brq Ar Extension value Ns No \&...
.Nm
.Op Fl nvp
.Cm flush
.Nm
.Op Fl nvp
.Cm dump
.Nm
.Op Fl nvp
.Cm save
.Op Ar filename
.Sh DESCRIPTION
The
.Nm
command is used to manually manipulate the
.Xr tcp 4P
security association
.Pq SA
database.
.Pp
TCP SAs are in one of three states:
.Bl -tag -width indent
.It Sy mature
A newly added SA starts in the mature state and will remain there unless it
is configured with any limits on its lifetime.
.It Sy dying
A mature SA which exceeds a soft lifetime limit will transition into the
.Sy dying
state.
This state is informational only; the SA can continue to be used.
A
.Sy dying
SA can be moved back to the
.Sy mature
state by updating its lifetime limits via the
.Ic update
command, so that they are no longer exceeded.
A
.Sy dying
SA will transition to
.Sy dead
and be removed when it is either deleted via a
.Ic delete
or
.Ic flush
command, or subsequently exceeds a hard lifetime limit.
.It Sy dead
An SA which exceeds a hard lifetime limit will transition into the
.Sy 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.
.El
.Pp
While the
.Nm
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
.Xr pf_key 4P .
When
.Nm
is invoked with no arguments, it will enter an interactive mode which prints a
prompt
.Pq Dq tcpkey>
to the standard output and accepts commands from the standard input until the
end-of-file is reached.
.Pp
.Nm
uses a
.Xr pf_key 4P
socket and the message types
.Dv SADB_ADD ,
.Dv SADB_UPDATE ,
.Dv SADB_DELETE ,
.Dv SADB_GET
and
.Dv SADB_FLUSH .
Thus, you must have the
.Dv PRIV_SYS_IP_CONFIG
privilege to use this command.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl c Op Ar filename
Analogous to the
.Fl f
option
.Pq see following ,
except that the input is not executed but only checked for syntactical
correctness.
Errors are reported to
.Dv stderr .
This option is provided to debug configurations without making changes.
.It Fl f Op Ar filename
Read commands from an input file,
.Ar filename .
The lines of the input file are identical to the command line language.
The
.Ic save
command can generate files readable by the
.Fl f
argument.
.It Fl 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.
.It Fl p
Paranoid.
Do not print any keying material, even if saving.
Instead of an actual hexadecimal digit, print an
.Sq X
when this flag is turned on.
.It Fl v
Verbose.
Print the messages being sent into the
.Xr pf_key 4P
socket, and print raw seconds values for lifetimes.
.El
.Sh COMMANDS
.Bl -tag -width Ds
.It Ic add
Add an SA.
Because it involves the transfer of keying material, this command and its
parameters cannot be passed in as arguments to
.Nm ,
lest the keys be visible in
.Xr ps 1
output.
It can be used either from the interactive
.Sq tcpkey>
prompt or in a command file specified by the
.Fl f
option.
The
.Ic add
command accepts all extension-value pairs described below.
.It Ic update
Update SA lifetime extensions.
Like
.Ic add
this command can only be used either from the interactive
.Sq tcpkey>
prompt or in a command file specified by the
.Fl f
option.
The
.Ic 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.
.It Ic delete
Delete a specific SA.
This command requires the
.Sy src
extension, and the
.Sy 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.
.It Ic get
Look up and display a security association.
Like
.Ic delete ,
this command only requires
.Sy src
and
.Sy dest .
.It Ic flush
Remove all SAs.
.It Ic 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.
.It Ic save
Is the command analog of the
.Fl s
option.
.It Sy help
Prints a brief summary of commands.
.El
.Sh EXTENSION VALUE TYPES
Commands like
.Ic add ,
.Ic delete ,
.Ic get ,
and
.Ic 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.
.Pp
.Bl -tag -width xxxxxxxxxxxxxxxxxxxx -compact
.It Cm src Ar addr | name
Source address of the SA.
.It Cm src6 Ar IPv6addr
.Pp
.It Cm dst Ar addr | name
Destination address of the SA.
.It Cm dst6 Ar IPv6addr
.Pp
.It Cm sport Ar port
Source port number.
If unspecified, the SA will match any source port.
.Pp
.It Cm dport Ar port
Destination port number.
If unspecified, the SA will match any destination port.
.Pp
.It Cm authalg Ar algorithm
Authentication algorithm.
The only supported value is
.Sq md5 .
.It Cm authstring Ar string
Authentication string.
Only ASCII characters are supported and the authentication string must be no
longer than 80 characters.
.El
.Pp
The next four extensions are lifetime extensions.
There are two varieties,
.Dq hard
and
.Dq 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
.Dv SADB_EXPIRE
message will be queued by the system and transmitted upstream on the
.Xr pf_key 4P
socket the next time a downstream command is received.
The
.Xr ipseckey 8
.Ic monitor
command to key allows you to view
.Dv SADB_EXPIRE
messages.
.Pp
.Bl -tag -width xxxxxxxxxxxxxxxxxxxx -compact
.It Cm soft_addtime
.It Cm 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
.Ic add
and
.Ic update
commands.
.It Cm soft_usetime
.It Cm 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
.Ic add
and
.Ic update
commands.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa /etc/inet/secret/tcpkeys
Default configuration file used at boot time.
.El
.Sh EXAMPLES
.Bl -tag -width 4
.It Sy Example 1 No Empting Out All SAs
.Bd -literal
# tcpkey flush
.Ed
.It Sy Example 2 No Saving All SAs To Standard Output
.Bd -literal
# tcpkey save
.Ed
.It Sy Example 3 No Adding a pair of SAs
.Pp
Note that the second SA specifies 179 as the
.Em source
port so that it matches reply traffic.
.Bd -literal
# tcpkey
tcpkey> add src 192.168.1.1 dst 192.168.1.2 dport 179 \e
    authalg md5 authstring s3kr1t
tcpkey> add src 192.168.1.2 dst 192.168.1.1 sport 179 \e
    authalg md5 authstring s3kr1t
tcpkey> exit
.Ed
.It Sy Example 4 No Displaying all SAs
.Bd -literal
# 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"
.Ed
.El
.Sh INTERFACE STABILITY
The command line interface of
.Nm
is
.Sy Uncommitted .
The command line interface of
.Nm
is
.Sy Not-An-Interface
and may change at any time.
.Sh SEE ALSO
.Xr ps 1 ,
.Xr pf_key 4P ,
.Xr ipseckey 8