xref: /illumos-gate/usr/src/man/man8/tcpkey.8 (revision 1edba515a3484e0f74b638b203d462b3112ac84d)

.\"
.\" 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 April 17, 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 database.
.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
.Dv PF_KEY
socket and the message types
.Dv SADB_ADD ,
.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
.Dv PF_KEY
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, it cannot be invoked from
the shell, lest the keys be visible in
.Xr ps 1
output.
It can be used either from the interactive 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 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.
However, existing connections will continue to use it.
.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
.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 ipseckey 8