1.\" 2.\" The contents of this file are subject to the terms of the Common 3.\" Development and Distribution License (the "License"). You may not use 4.\" this file except in compliance with the License. 5.\" 6.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or 7.\" http://www.opensolaris.org/os/licensing. See the License for the 8.\" specific language governing permissions and limitations under the 9.\" License. 10.\" 11.\" When distributing Covered Code, include this CDDL HEADER in each file 12.\" and include the License file at usr/src/OPENSOLARIS.LICENSE. If 13.\" applicable, add the following below this CDDL HEADER, with the fields 14.\" enclosed by brackets "[]" replaced with your own identifying 15.\" information: Portions Copyright [yyyy] [name of copyright owner] 16.\" 17.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved 18.\" Copyright 2024 Oxide Computer Company 19.\" 20.Dd April 17, 2024 21.Dt TCPKEY 8 22.Os 23.Sh NAME 24.Nm tcpkey 25.Nd Manages the Security Association Database (SADB) for TCP 26.Sh SYNOPSIS 27.Nm 28.Op Fl nvp 29.Nm 30.Op Fl nvp 31.Fl f Ar filename 32.Nm 33.Fl c Ar filename 34.Nm 35.Op Fl nvp 36.Cm get 37.Brq Ar Extension value Ns No \&... 38.Nm 39.Op Fl nvp 40.Cm delete 41.Brq Ar Extension value Ns No \&... 42.Nm 43.Op Fl nvp 44.Cm flush 45.Nm 46.Op Fl nvp 47.Cm dump 48.Nm 49.Op Fl nvp 50.Cm save 51.Op Ar filename 52.Sh DESCRIPTION 53The 54.Nm 55command is used to manually manipulate the 56.Xr tcp 4P 57security association database. 58.Pp 59While the 60.Nm 61utility has only a limited number of general options, it supports a rich 62command language. 63The user may specify requests to be delivered by means of a programmatic 64interface specific for manual keying. 65See 66.Xr pf_key 4P . 67When 68.Nm 69is invoked with no arguments, it will enter an interactive mode which prints a 70prompt 71.Pq Dq tcpkey> 72to the standard output and accepts commands from the standard input until the 73end-of-file is reached. 74.Pp 75.Nm 76uses a 77.Dv PF_KEY 78socket and the message types 79.Dv SADB_ADD , 80.Dv SADB_DELETE , 81.Dv SADB_GET 82and 83.Dv SADB_FLUSH . 84Thus, you must have the 85.Dv PRIV_SYS_IP_CONFIG 86privilege to use this command. 87.Sh OPTIONS 88.Bl -tag -width Ds 89.It Fl c Op Ar filename 90Analogous to the 91.Fl f 92option 93.Pq see following , 94except that the input is not executed but only checked for syntactical 95correctness. 96Errors are reported to 97.Dv stderr . 98This option is provided to debug configurations without making changes. 99.It Fl f Op Ar filename 100Read commands from an input file, 101.Ar filename . 102The lines of the input file are identical to the command line language. 103The 104.Ic save 105command can generate files readable by the 106.Fl f 107argument. 108.It Fl n 109Prevent attempts to print host and network names symbolically when reporting 110actions. 111This is useful, for example, when all name servers are down or are otherwise 112unreachable. 113.It Fl p 114Paranoid. 115Do not print any keying material, even if saving. 116Instead of an actual hexadecimal digit, print an 117.Sq X 118when this flag is turned on. 119.It Fl v 120Verbose. 121Print the messages being sent into the 122.Dv PF_KEY 123socket, and print raw seconds values for lifetimes. 124.El 125.Sh COMMANDS 126.Bl -tag -width Ds 127.It Ic add 128Add an SA. 129Because it involves the transfer of keying material, it cannot be invoked from 130the shell, lest the keys be visible in 131.Xr ps 1 132output. 133It can be used either from the interactive tcpkey> prompt or in a command 134file specified by the 135.Fl f 136option. 137The 138.Ic add 139command accepts all extension-value pairs described below. 140.It Ic delete 141Delete a specific SA. 142This command requires the 143.Sy src 144extension, and the 145.Sy dest 146extension. 147If the SA is in use, it will be marked for deletion and no longer used for new 148connection setup. 149However, existing connections will continue to use it. 150.It Ic get 151Look up and display a security association. 152Like 153.Ic delete , 154this command only requires 155.Sy src 156and 157.Sy dest . 158.It Ic flush 159Remove all SAs. 160.It Ic dump 161Will display all SAs. 162Because of the large amount of data generated by this command, there is no 163guarantee that all SA information will be successfully delivered, or that this 164command will even complete. 165.It Ic save 166Is the command analog of the 167.Fl s 168option. 169.It Sy help 170Prints a brief summary of commands. 171.El 172.Sh EXTENSION VALUE TYPES 173Commands like 174.Ic add , 175.Ic delete , 176.Ic get , 177and 178.Ic update 179require that certain extensions and associated values be specified. 180The extensions will be listed here, followed by the commands that use them, and 181the commands that require them. 182.Pp 183.Bl -tag -width xxxxxxxxxxxxxxxxxxxx -compact 184.It Cm src Ar addr | name 185Source address of the SA. 186.It Cm src6 Ar IPv6addr 187.Pp 188.It Cm dst Ar addr | name 189Destination address of the SA. 190.It Cm dst6 Ar IPv6addr 191.Pp 192.It Cm sport Ar port 193Source port number. 194If unspecified, the SA will match any source port. 195.Pp 196.It Cm dport Ar port 197Destination port number. 198If unspecified, the SA will match any destination port. 199.Pp 200.It Cm authalg Ar algorithm 201Authentication algorithm. 202The only supported value is 203.Sq md5 . 204.It Cm authstring Ar string 205Authentication string. 206Only ASCII characters are supported and the authentication string must be no 207longer than 80 characters. 208.El 209.Sh FILES 210.Bl -tag -width Ds 211.It Pa /etc/inet/secret/tcpkeys 212Default configuration file used at boot time. 213.El 214.Sh EXAMPLES 215.Bl -tag -width 4 216.It Sy Example 1 No Empting Out All SAs 217.Bd -literal 218# tcpkey flush 219.Ed 220.It Sy Example 2 No Saving All SAs To Standard Output 221.Bd -literal 222# tcpkey save 223.Ed 224.It Sy Example 3 No Adding a pair of SAs 225.Pp 226Note that the second SA specifies 179 as the 227.Em source 228port so that it matches reply traffic. 229.Bd -literal 230# tcpkey 231tcpkey> add src 192.168.1.1 dst 192.168.1.2 dport 179 \e 232 authalg md5 authstring s3kr1t 233tcpkey> add src 192.168.1.2 dst 192.168.1.1 sport 179 \e 234 authalg md5 authstring s3kr1t 235tcpkey> exit 236.Ed 237.It Sy Example 4 No Displaying all SAs 238.Bd -literal 239# tcpkey dump 240Base message (version 2) type DUMP, SA type TCPSIG. 241Message length 112 bytes, seq=5, pid=649091. 242SRC: Source address (proto=6/tcp) 243SRC: AF_INET6: port 0, ::ffff:192.168.1.1/32 (host.example.com). 244DST: Destination address (proto=6/tcp) 245DST: AF_INET6: port 179, ::ffff:192.168.1.2/32 <unknown>. 246AST: Authentication string. 247AST: "s3kr1t" 248.Ed 249.El 250.Sh INTERFACE STABILITY 251The command line interface of 252.Nm 253is 254.Sy Uncommitted . 255The command line interface of 256.Nm 257is 258.Sy Not-An-Interface 259and may change at any time. 260.Sh SEE ALSO 261.Xr ps 1 , 262.Xr ipseckey 8 263