diff options
Diffstat (limited to 'ipsec-tools/src/setkey/setkey.8')
| -rw-r--r-- | ipsec-tools/src/setkey/setkey.8 | 837 |
1 files changed, 837 insertions, 0 deletions
diff --git a/ipsec-tools/src/setkey/setkey.8 b/ipsec-tools/src/setkey/setkey.8 new file mode 100644 index 00000000..76356790 --- /dev/null +++ b/ipsec-tools/src/setkey/setkey.8 @@ -0,0 +1,837 @@ +.\" $NetBSD: setkey.8,v 1.26 2010/12/03 14:32:52 tteras Exp $ +.\" +.\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd June 4, 2010 +.Dt SETKEY 8 +.Os +.\" +.Sh NAME +.Nm setkey +.Nd manually manipulate the IPsec SA/SP database +.\" +.Sh SYNOPSIS +.Nm setkey +.Op Fl knrv +.Ar file ... +.Nm setkey +.Op Fl knrv +.Fl c +.Nm setkey +.Op Fl krv +.Fl f Ar filename +.Nm setkey +.Op Fl aklPrv +.Fl D +.Nm setkey +.Op Fl Pvp +.Fl F +.Nm setkey +.Op Fl H +.Fl x +.Nm setkey +.Op Fl ?V +.\" +.Sh DESCRIPTION +.Nm +adds, updates, dumps, or flushes +Security Association Database (SAD) entries +as well as Security Policy Database (SPD) entries in the kernel. +.Pp +.Nm +takes a series of operations from standard input +.Po +if invoked with +.Fl c +.Pc +or the file named +.Ar filename +.Po +if invoked with +.Fl f Ar filename +.Pc . +.Bl -tag -width Ds +.It (no flag) +Dump the SAD entries or SPD entries contained in the specified +.Ar file . +.It Fl ? +Print short help. +.It Fl a +.Nm +usually does not display dead SAD entries with +.Fl D . +If +.Fl a +is also specified, the dead SAD entries will be displayed as well. +A dead SAD entry is one that has expired but remains in the +system because it is referenced by some SPD entries. +.It Fl D +Dump the SAD entries. +If +.Fl P +is also specified, the SPD entries are dumped. +If +.Fl p +is specified, the ports are displayed. +.It Fl F +Flush the SAD entries. +If +.Fl P +is also specified, the SPD entries are flushed. +.It Fl H +Add hexadecimal dump in +.Fl x +mode. +.It Fl h +On +.Nx , +synonym for +.Fl H . +On other systems, synonym for +.Fl ? . +.It Fl k +Use semantics used in kernel. +Available only in Linux. +See also +.Fl r . +.It Fl l +Loop forever with short output on +.Fl D . +.It Fl n +No action. +The program will check validity of the input, but no changes to +the SPD will be made. +.It Fl r +Use semantics described in IPsec RFCs. +This mode is default. +For details see section +.Sx RFC vs Linux kernel semantics . +Available only in Linux. +See also +.Fl k . +.It Fl x +Loop forever and dump all the messages transmitted to the +.Dv PF_KEY +socket. +.Fl xx +prints the unformatted timestamps. +.It Fl V +Print version string. +.It Fl v +Be verbose. +The program will dump messages exchanged on the +.Dv PF_KEY +socket, including messages sent from other processes to the kernel. +.El +.Ss Configuration syntax +With +.Fl c +or +.Fl f +on the command line, +.Nm +accepts the following configuration syntax. +Lines starting with hash signs +.Pq Sq # +are treated as comment lines. +.Bl -tag -width Ds +.It Li add Oo Fl 46n Oc Ar src Ar dst Ar protocol Ar spi \ +Oo Ar extensions Oc Ar algorithm ... Li ; +Add an SAD entry. +.Li add +can fail for multiple reasons, including when the key length does +not match the specified algorithm. +.\" +.It Li get Oo Fl 46n Oc Ar src Ar dst Ar protocol Ar spi Li ; +Show an SAD entry. +.\" +.It Li delete Oo Fl 46n Oc Ar src Ar dst Ar protocol Ar spi Li ; +Remove an SAD entry. +.\" +.It Li deleteall Oo Fl 46n Oc Ar src Ar dst Ar protocol Li ; +Remove all SAD entries that match the specification. +.\" +.It Li flush Oo Ar protocol Oc Li ; +Clear all SAD entries matched by the options. +.Fl F +on the command line achieves the same functionality. +.\" +.It Li dump Oo Ar protocol Oc Li ; +Dumps all SAD entries matched by the options. +.Fl D +on the command line achieves the same functionality. +.\" +.It Li spdadd Oo Fl 46n Oc Ar src_range Ar dst_range Ar upperspec \ +Ar label Ar policy Li ; +Add an SPD entry. +.\" +.It Li spdadd tagged Ar tag Ar policy Li ; +Add an SPD entry based on a PF tag. +.Ar tag +must be a string surrounded by double quotes. +.\" +.It Li spdupdate Oo Fl 46n Oc Ar src_range Ar dst_range Ar upperspec \ +Ar label Ar policy Li ; +Updates an SPD entry. +.\" +.It Li spdupdate tagged Ar tag Ar policy Li ; +Update an SPD entry based on a PF tag. +.Ar tag +must be a string surrounded by double quotes. +.\" +.It Li spddelete Oo Fl 46n Oc Ar src_range Ar dst_range Ar upperspec \ +Fl P Ar direction Li ; +Delete an SPD entry. +.\" +.It Li spdflush Li ; +Clear all SPD entries. +.Fl FP +on the command line achieves the same functionality. +.\" +.It Li spddump Li ; +Dumps all SPD entries. +.Fl DP +on the command line achieves the same functionality. +.El +.\" +.Pp +Meta-arguments are as follows: +.Pp +.Bl -tag -compact -width Ds +.It Ar src +.It Ar dst +Source/destination of the secure communication is specified as +an IPv4/v6 address, and an optional port number between square +brackets. +.Nm +can resolve a FQDN into numeric addresses. +If the FQDN resolves into multiple addresses, +.Nm +will install multiple SAD/SPD entries into the kernel +by trying all possible combinations. +.Fl 4 , +.Fl 6 , +and +.Fl n +restrict the address resolution of FQDN in certain ways. +.Fl 4 +and +.Fl 6 +restrict results into IPv4/v6 addresses only, respectively. +.Fl n +avoids FQDN resolution and requires addresses to be numeric addresses. +.\" +.Pp +.It Ar protocol +.Ar protocol +is one of following: +.Bl -tag -width Fl -compact +.It Li esp +ESP based on rfc2406 +.It Li esp-old +ESP based on rfc1827 +.It Li ah +AH based on rfc2402 +.It Li ah-old +AH based on rfc1826 +.It Li ipcomp +IPComp +.It Li tcp +TCP-MD5 based on rfc2385 +.El +.\" +.Pp +.It Ar spi +Security Parameter Index +.Pq SPI +for the SAD and the SPD. +.Ar spi +must be a decimal number, or a hexadecimal number with a +.Dq Li 0x +prefix. +SPI values between 0 and 255 are reserved for future use by IANA +and cannot be used. +TCP-MD5 associations must use 0x1000 and therefore only have per-host +granularity at this time. +.\" +.Pp +.It Ar extensions +take some of the following: +.Bl -tag -width Fl -compact +.\" +.It Fl m Ar mode +Specify a security protocol mode for use. +.Ar mode +is one of following: +.Li transport , tunnel , +or +.Li any . +The default value is +.Li any . +.\" +.It Fl r Ar size +Specify window size of bytes for replay prevention. +.Ar size +must be decimal number in 32-bit word. +If +.Ar size +is zero or not specified, replay checks don't take place. +.\" +.It Fl u Ar id +Specify the identifier of the policy entry in the SPD. +See +.Ar policy . +.\" +.It Fl f Ar pad_option +defines the content of the ESP padding. +.Ar pad_option +is one of following: +.Bl -tag -width random-pad -compact +.It Li zero-pad +All the paddings are zero. +.It Li random-pad +A series of randomized values are used. +.It Li seq-pad +A series of sequential increasing numbers started from 1 are used. +.El +.\" +.It Fl f Li nocyclic-seq +Don't allow cyclic sequence numbers. +.\" +.It Fl lh Ar time +.It Fl ls Ar time +Specify hard/soft life time duration of the SA measured in seconds. +.\" +.It Fl bh Ar bytes +.It Fl bs Ar bytes +Specify hard/soft life time duration of the SA measured in bytes transported. +.\" +.It Fl ctx Ar doi Ar algorithm Ar context-name +Specify an access control label. +The access control label is interpreted by the LSM (e.g., SELinux). +Ultimately, it enables MAC on network communications. +.Bl -tag -width Fl -compact +.It Ar doi +The domain of interpretation, which is used by the +IKE daemon to identify the domain in which negotiation takes place. +.It Ar algorithm +Indicates the LSM for which the label is generated (e.g., SELinux). +.It Ar context-name +The string representation of the label that is interpreted by the LSM. +.El +.El +.\" +.Pp +.It Ar algorithm +.Bl -tag -width Fl -compact +.It Fl E Ar ealgo Ar key +Specify an encryption algorithm +.Ar ealgo +for ESP. +.It Fl E Ar ealgo Ar key Fl A Ar aalgo Ar key +Specify an encryption algorithm +.Ar ealgo , +as well as a payload authentication algorithm +.Ar aalgo , +for ESP. +.It Fl A Ar aalgo Ar key +Specify an authentication algorithm for AH. +.It Fl C Ar calgo Op Fl R +Specify a compression algorithm for IPComp. +If +.Fl R +is specified, the +.Ar spi +field value will be used as the IPComp CPI +.Pq compression parameter index +on wire as-is. +If +.Fl R +is not specified, +the kernel will use well-known CPI on wire, and +.Ar spi +field will be used only as an index for kernel internal usage. +.El +.Pp +.Ar key +must be a double-quoted character string, or a series of hexadecimal +digits preceded by +.Dq Li 0x . +.Pp +Possible values for +.Ar ealgo , +.Ar aalgo , +and +.Ar calgo +are specified in the +.Sx Algorithms +sections. +.\" +.Pp +.It Ar src_range +.It Ar dst_range +These select the communications that should be secured by IPsec. +They can be an IPv4/v6 address or an IPv4/v6 address range, and +may be accompanied by a TCP/UDP port specification. +This takes the following form: +.Bd -literal -offset +.Ar address +.Ar address/prefixlen +.Ar address[port] +.Ar address/prefixlen[port] +.Ed +.Pp +.Ar prefixlen +and +.Ar port +must be decimal numbers. +The square brackets around +.Ar port +are really necessary, +they are not man page meta-characters. +For FQDN resolution, the rules applicable to +.Ar src +and +.Ar dst +apply here as well. +.\" +.Pp +.It Ar upperspec +Upper-layer protocol to be used. +You can use one of the words in +.Pa /etc/protocols +as +.Ar upperspec , +or +.Li icmp6 , +.Li ip4 , +.Li gre , +or +.Li any . +.Li any +stands for +.Dq any protocol . +You can also use the protocol number. +Additional specification can be placed after the protocol name for +some protocols. +You can specify a type and/or a code of ICMP or ICMPv6. +The type is separated from a code by single comma and the code must +always be specified. +GRE key can be specified in dotted-quad format or as plain number. +When a zero is specified, the kernel deals with it as a wildcard. +Note that the kernel can not distinguish a wildcard from an ICPMv6 +type of zero. +.Pp +For example, the following means that the policy doesn't require IPsec +for any inbound Neighbor Solicitation. +.Dl spdadd ::/0 ::/0 icmp6 135,0 -P in none ; +.Pp +A second example of requiring transport mode encryption of specific +GRE tunnel: +.Dl spdadd 0.0.0.0 0.0.0.0 gre 1234 ipsec esp/transport//require ; +.Pp +.Em Note : +.Ar upperspec +does not work against forwarding case at this moment, +as it requires extra reassembly at the forwarding node +.Pq not implemented at this moment . +There are many protocols in +.Pa /etc/protocols , +but all protocols except of TCP, UDP, GRE, and ICMP may not be suitable +to use with IPsec. +You have to consider carefully what to use. +.\" +.Pp +.It Ar label +.Ar label +is the access control label for the policy. +This label is interpreted by the LSM (e.g., SELinux). +Ultimately, it enables MAC on network communications. +When a policy contains an access control label, SAs +negotiated with this policy will contain the label. +Its format: +.Bl -tag -width Fl -compact +.\" +.It Fl ctx Ar doi Ar algorithm Ar context-name +.Bl -tag -width Fl -compact +.It Ar doi +The domain of interpretation, which is used by the +IKE daemon to identify the domain in which negotiation takes place. +.It Ar algorithm +Indicates the LSM for which the label is generated (e.g., SELinux). +.It Ar context-name +The string representation of the label that is interpreted by the LSM. +.El +.El +.\" +.Pp +.It Ar policy +.Ar policy +is in one of the following three formats: +.Bl -item -compact +.It +.Fl P Ar direction [priority specification] Li discard +.It +.Fl P Ar direction [priority specification] Li none +.It +.Fl P Ar direction [priority specification] Li ipsec +.Ar protocol/mode/src-dst/level Op ... +.El +.Pp +You must specify the direction of its policy as +.Ar direction . +Either +.Ar out , +.Ar in , +or +.Ar fwd +can be used. +.Pp +.Ar priority specification +is used to control the placement of the policy within the SPD. +Policy position is determined by +a signed integer where higher priorities indicate the policy is placed +closer to the beginning of the list and lower priorities indicate the +policy is placed closer to the end of the list. +Policies with equal priorities are added at the end of groups +of such policies. +.Pp +Priority can only +be specified when setkey has been compiled against kernel headers that +support policy priorities (Linux \*[Gt]= 2.6.6). +If the kernel does not support priorities, a warning message will +be printed the first time a priority specification is used. +Policy priority takes one of the following formats: +.Bl -tag -width "discard" +.It Ar {priority,prio} offset +.Ar offset +is an integer in the range from \-2147483647 to 214783648. +.It Ar {priority,prio} base {+,\-} offset +.Ar base +is either +.Li low (\-1073741824) , +.Li def (0) , +or +.Li high (1073741824) +.Pp +.Ar offset +is an unsigned integer. +It can be up to 1073741824 for +positive offsets, and up to 1073741823 for negative offsets. +.El +.Pp +.Li discard +means the packet matching indexes will be discarded. +.Li none +means that IPsec operation will not take place onto the packet. +.Li ipsec +means that IPsec operation will take place onto the packet. +.Pp +The +.Ar protocol/mode/src-dst/level +part specifies the rule how to process the packet. +Either +.Li ah , +.Li esp , +or +.Li ipcomp +must be used as +.Ar protocol . +.Ar mode +is either +.Li transport +or +.Li tunnel . +If +.Ar mode +is +.Li tunnel , +you must specify the end-point addresses of the SA as +.Ar src +and +.Ar dst +with +.Sq - +between these addresses, which is used to specify the SA to use. +If +.Ar mode +is +.Li transport , +both +.Ar src +and +.Ar dst +can be omitted. +.Ar level +is to be one of the following: +.Li default , use , require , +or +.Li unique . +If the SA is not available in every level, the kernel will +ask the key exchange daemon to establish a suitable SA. +.Li default +means the kernel consults the system wide default for the protocol +you specified, e.g. the +.Li esp_trans_deflev +sysctl variable, when the kernel processes the packet. +.Li use +means that the kernel uses an SA if it's available, +otherwise the kernel keeps normal operation. +.Li require +means SA is required whenever the kernel sends a packet matched +with the policy. +.Li unique +is the same as +.Li require ; +in addition, it allows the policy to match the unique out-bound SA. +You just specify the policy level +.Li unique , +.Xr racoon 8 +will configure the SA for the policy. +If you configure the SA by manual keying for that policy, +you can put a decimal number as the policy identifier after +.Li unique +separated by a colon +.Sq \&: +like: +.Li unique:number +in order to bind this policy to the SA. +.Li number +must be between 1 and 32767. +It corresponds to +.Ar extensions Fl u +of the manual SA configuration. +When you want to use SA bundle, you can define multiple rules. +For example, if an IP header was followed by an AH header followed +by an ESP header followed by an upper layer protocol header, the +rule would be: +.Dl esp/transport//require ah/transport//require ; +The rule order is very important. +.Pp +When NAT-T is enabled in the kernel, policy matching for ESP over +UDP packets may be done on endpoint addresses and port +(this depends on the system. +System that do not perform the port check cannot support +multiple endpoints behind the same NAT). +When using ESP over UDP, you can specify port numbers in the endpoint +addresses to get the correct matching. +Here is an example: +.Bd -literal -offset +spdadd 10.0.11.0/24[any] 10.0.11.33/32[any] any \-P out ipsec + esp/tunnel/192.168.0.1[4500]-192.168.1.2[30000]/require ; + +.Ed +These ports must be left unspecified (which defaults to 0) for +anything other than ESP over UDP. +They can be displayed in SPD dump using +.Nm +.Fl DPp . +.Pp +Note that +.Dq Li discard +and +.Dq Li none +are not in the syntax described in +.Xr ipsec_set_policy 3 . +There are a few differences in the syntax. +See +.Xr ipsec_set_policy 3 +for detail. +.El +.\" +.Ss Algorithms +The following list shows the supported algorithms. +.Sy protocol +and +.Sy algorithm +are almost orthogonal. +These authentication algorithms can be used as +.Ar aalgo +in +.Fl A Ar aalgo +of the +.Ar protocol +parameter: +.Pp +.Bd -literal -offset indent +algorithm keylen (bits) +hmac-md5 128 ah: rfc2403 + 128 ah-old: rfc2085 +hmac-sha1 160 ah: rfc2404 + 160 ah-old: 128bit ICV (no document) +keyed-md5 128 ah: 96bit ICV (no document) + 128 ah-old: rfc1828 +keyed-sha1 160 ah: 96bit ICV (no document) + 160 ah-old: 128bit ICV (no document) +null 0 to 2048 for debugging +hmac-sha256 256 ah: 96bit ICV + (draft-ietf-ipsec-ciph-sha-256-00) + 256 ah-old: 128bit ICV (no document) +hmac-sha384 384 ah: 96bit ICV (no document) + 384 ah-old: 128bit ICV (no document) +hmac-sha512 512 ah: 96bit ICV (no document) + 512 ah-old: 128bit ICV (no document) +hmac-ripemd160 160 ah: 96bit ICV (RFC2857) + ah-old: 128bit ICV (no document) +aes-xcbc-mac 128 ah: 96bit ICV (RFC3566) + 128 ah-old: 128bit ICV (no document) +tcp-md5 8 to 640 tcp: rfc2385 +.Ed +.Pp +These encryption algorithms can be used as +.Ar ealgo +in +.Fl E Ar ealgo +of the +.Ar protocol +parameter: +.Pp +.Bd -literal -offset indent +algorithm keylen (bits) +des-cbc 64 esp-old: rfc1829, esp: rfc2405 +3des-cbc 192 rfc2451 +null 0 to 2048 rfc2410 +blowfish-cbc 40 to 448 rfc2451 +cast128-cbc 40 to 128 rfc2451 +des-deriv 64 ipsec-ciph-des-derived-01 +3des-deriv 192 no document +rijndael-cbc 128/192/256 rfc3602 +twofish-cbc 0 to 256 draft-ietf-ipsec-ciph-aes-cbc-01 +aes-ctr 160/224/288 draft-ietf-ipsec-ciph-aes-ctr-03 +camellia-cbc 128/192/256 rfc4312 +.Ed +.Pp +Note that the first 128 bits of a key for +.Li aes-ctr +will be used as AES key, and the remaining 32 bits will be used as nonce. +.Pp +These compression algorithms can be used as +.Ar calgo +in +.Fl C Ar calgo +of the +.Ar protocol +parameter: +.Pp +.Bd -literal -offset indent +algorithm +deflate rfc2394 +.Ed +.\" +.Ss RFC vs Linux kernel semantics +The Linux kernel uses the +.Ar fwd +policy instead of the +.Ar in +policy for packets what are forwarded through that particular box. +.Pp +In +.Ar kernel +mode, +.Nm +manages and shows policies and SAs exactly as they are stored in the kernel. +.Pp +In +.Ar RFC +mode, +.Nm +.Bl -item +.It +creates +.Ar fwd +policies for every +.Ar in +policy inserted +.It +(not implemented yet) filters out all +.Ar fwd +policies +.El +.Sh RETURN VALUES +The command exits with 0 on success, and non-zero on errors. +.\" +.Sh EXAMPLES +.Bd -literal -offset +add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457 + \-E des-cbc 0x3ffe05014819ffff ; + +add \-6 myhost.example.com yourhost.example.com ah 123456 + \-A hmac-sha1 "AH SA configuration!" ; + +add 10.0.11.41 10.0.11.33 esp 0x10001 + \-E des-cbc 0x3ffe05014819ffff + \-A hmac-md5 "authentication!!" ; + +get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ; + +flush ; + +dump esp ; + +spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any + \-P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ; + +add 10.1.10.34 10.1.10.36 tcp 0x1000 \-A tcp-md5 "TCP-MD5 BGP secret" ; + +add 10.0.11.41 10.0.11.33 esp 0x10001 + \-ctx 1 1 "system_u:system_r:unconfined_t:SystemLow-SystemHigh" + \-E des-cbc 0x3ffe05014819ffff; + +spdadd 10.0.11.41 10.0.11.33 any + \-ctx 1 1 "system_u:system_r:unconfined_t:SystemLow-SystemHigh" + \-P out ipsec esp/transport//require ; +.Ed +.\" +.Sh SEE ALSO +.Xr ipsec_set_policy 3 , +.Xr racoon 8 , +.Xr sysctl 8 +.Rs +.%T "Changed manual key configuration for IPsec" +.%U "http://www.kame.net/newsletter/19991007/" +.%D "October 1999" +.Re +.\" +.Sh HISTORY +The +.Nm +command first appeared in the WIDE Hydrangea IPv6 protocol stack +kit. +The command was completely re-designed in June 1998. +.\" +.Sh BUGS +.Nm +should report and handle syntax errors better. +.Pp +For IPsec gateway configuration, +.Ar src_range +and +.Ar dst_range +with TCP/UDP port numbers does not work, as the gateway does not +reassemble packets +.Pq it cannot inspect upper-layer headers . |