LinuxReviws.org --get your your Linux knowledge
> Linux Reviews > Manual Pages (man) >

ipsec_spi

list IPSEC Security Associations


  1. ipsec_spi.5.man
  2. ipsec_spi.8.man


1. ipsec_spi.5.man

Manpage of IPSEC_SPI

IPSEC_SPI

Section: File Formats (5)
Updated: 26 Jun 2000
Index Return to Main Contents
 

NAME

ipsec_spi - list IPSEC Security Associations  

SYNOPSIS

ipsec spi

cat /proc/net/ipsec_spi

 

DESCRIPTION

/proc/net/ipsec_spi is a read-only file that lists the current IPSEC Security Associations. A Security Association (SA) is a transform through which packet contents are to be processed before being forwarded. A transform can be an IPv4-in-IPv4 or IPv6-in-IPv6 encapsulation, an IPSEC Authentication Header (authentication with no encryption), or an IPSEC Encapsulation Security Payload (encryption, possibly including authentication).

When a packet is passed from a higher networking layer through an IPSEC virtual interface, a search in the extended routing table (see ipsec_eroute(5)) yields a IP protocol number , a Security Parameters Index (SPI) and an effective destination address When an IPSEC packet arrives from the network, its ostensible destination, an SPI and an IP protocol specified by its outermost IPSEC header are used. The destination/SPI/protocol combination is used to select a relevant SA. (See ipsec_spigrp(5) for discussion of how multiple transforms are combined.)

An spi , proto, daddr and address_family arguments specify an SAID. Proto is an ASCII string, "ah", "esp", "comp" or "tun", specifying the IP protocol. Spi is a number, preceded by '.' indicating hexadecimal and IPv4 or by ':' indicating hexadecimal and IPv6, where each hexadecimal digit represents 4 bits, between 0x100 and 0xffffffff; values from 0x0 to 0xff are reserved. Daddr is a dotted-decimal IPv4 destination address or a coloned hex IPv6 destination address.

An SAID combines the three parameters above, such as: "tun.101@1.2.3.4" for IPv4 or "tun:101@3049:1::1" for IPv6

A table entry consists of:

+
SAID
+
<transform name (proto,encalg,authalg)>:
+
direction (dir=)
+
source address (src=)
+
source and destination addresses and masks for inner header policy check addresses (policy=), as dotted-quads or coloned hex, separated by '->', for IPv4-in-IPv4 or IPv6-in-IPv6 SAs only
+
initialisation vector length and value (iv_bits=, iv=) if non-zero
+
out-of-order window size, number of out-of-order errors, sequence number, recently received packet bitmask, maximum difference between sequence numbers (ooowin=, ooo_errs=, seq=, bit=, max_seq_diff=) if SA is AH or ESP and if individual items are non-zero
+
extra flags (flags=) if any are set
+
authenticator length in bits (alen=) if non-zero
+
authentication key length in bits (aklen=) if non-zero
+
authentication errors (auth_errs=) if non-zero
+
encryption key length in bits (eklen=) if non-zero
+
encryption size errors (encr_size_errs=) if non-zero
+
encryption padding error warnings (encr_pad_errs=) if non-zero
+
lifetimes legend, c=Current status, s=Soft limit when exceeded will initiate rekeying, h=Hard limit will cause termination of SA (life(c,s,h)=)
+
number of connections to which the SA is allocated (c), that will cause a rekey (s), that will cause an expiry (h) (alloc=), if any value is non-zero
+
number of bytes processesd by this SA (c), that will cause a rekey (s), that will cause an expiry (h) (bytes=), if any value is non-zero
+
time since the SA was added (c), until rekey (s), until expiry (h), in seconds (add=)
+
time since the SA was first used (c), until rekey (s), until expiry (h), in seconds (used=), if any value is non-zero
+
number of packets processesd by this SA (c), that will cause a rekey (s), that will cause an expiry (h) (packets=), if any value is non-zero
+
time since the last packet was processed, in seconds (idle=), if SA has been used
average compression ratio (ratio=)
 

EXAMPLES

tun.12a@192.168.43.1 IPIP: dir=out src=192.168.43.2
life(c,s,h)=bytes(14073,0,0)add(269,0,0)
use(149,0,0)packets(14,0,0)
idle=23

is an outbound IPv4-in-IPv4 (protocol 4) tunnel-mode SA set up between machines 192.168.43.2 and 192.168.43.1 with an SPI of 12a in hexadecimal that has passed about 14 kilobytes of traffic in 14 packets since it was created, 269 seconds ago, first used 149 seconds ago and has been idle for 23 seconds.

esp:9a35fc02@3049:1::1 ESP_3DES_HMAC_MD5:
dir=in src=9a35fc02@3049:1::2
ooowin=32 seq=7149 bit=0xffffffff
alen=128 aklen=128 eklen=192
life(c,s,h)=bytes(1222304,0,0)add(4593,0,0)
use(3858,0,0)packets(7149,0,0)
idle=23

is an inbound Encapsulating Security Payload (protocol 50) SA on machine 3049:1::1 with an SPI of 9a35fc02 that uses 3DES as the encryption cipher, HMAC MD5 as the authentication algorithm, an out-of-order window of 32 packets, a present sequence number of 7149, every one of the last 32 sequence numbers was received, the authenticator length and keys is 128 bits, the encryption key is 192 bits (actually 168 for 3DES since 1 of 8 bits is a parity bit), has passed 1.2 Mbytes of data in 7149 packets, was added 4593 seconds ago, first used 3858 seconds ago and has been idle for 23 seconds.

 

FILES

/proc/net/ipsec_spi, /usr/local/bin/ipsec  

SEE ALSO

ipsec(8), ipsec_manual(8), ipsec_tncfg(5), ipsec_eroute(5), ipsec_spigrp(5), ipsec_klipsdebug(5), ipsec_spi(8), ipsec_version(5), ipsec_pf_key(5)  

HISTORY

Written for the Linux FreeS/WAN project <http://www.freeswan.org/> by Richard Guy Briggs.  

BUGS

The add and use times are awkward, displayed in seconds since machine start. It would be better to display them in seconds before now for human readability.


 

Index

NAME
SYNOPSIS
DESCRIPTION
EXAMPLES
FILES
SEE ALSO
HISTORY
BUGS

This document was created by man2html using the manual pages.
Time: 17:31:18 GMT, October 23, 2013

2. ipsec_spi.8.man

Manpage of IPSEC_SPI

IPSEC_SPI

Section: Maintenance Commands (8)
Updated: 23 Oct 2001
Index Return to Main Contents
 

NAME

ipsec spi - manage IPSEC Security Associations  

SYNOPSIS


Note: In the following,
<SA> means: --af (inet | inet6) --edst daddr --spi spi --proto proto OR --said said,
<life> means: --life (soft | hard)-(allocations | bytes | addtime | usetime | packets)=value[,...]

ipsec spi

ipsec spi <SA> --src src --ah hmac-md5-96|hmac-sha1-96 [ --replay_window replayw ] [ <life> ] --authkey akey

ipsec spi <SA> --src src --esp 3des [ --replay_window replayw ] [ <life> ] --enckey ekey

ipsec spi <SA> --src src --esp 3des-md5-96|3des-sha1-96 [ --replay_window replayw ] [ <life> ] --enckey ekey --authkey akey

ipsec spi <SA> --src src --comp deflate

ipsec spi <SA> --ip4 --src encap-src --dst encap-dst

ipsec spi <SA> --ip6 --src encap-src --dst encap-dst

ipsec spi <SA> --del

ipsec spi --help

ipsec spi --version

ipsec spi --clear

 

DESCRIPTION

Spi creates and deletes IPSEC Security Associations. A Security Association (SA) is a transform through which packet contents are to be processed before being forwarded. A transform can be an IPv4-in-IPv4 or an IPv6-in-IPv6 encapsulation, an IPSEC Authentication Header (authentication with no encryption), or an IPSEC Encapsulation Security Payload (encryption, possibly including authentication).

When a packet is passed from a higher networking layer through an IPSEC virtual interface, a search in the extended routing table (see ipsec_eroute(8)) yields an effective destination address, a Security Parameters Index (SPI) and a IP protocol number. When an IPSEC packet arrives from the network, its ostensible destination, an SPI and an IP protocol specified by its outermost IPSEC header are used. The destination/SPI/protocol combination is used to select a relevant SA. (See ipsec_spigrp(8) for discussion of how multiple transforms are combined.)

The af, daddr, spi and proto arguments specify the SA to be created or deleted. af is the address family (inet for IPv4, inet6 for IPv6). Daddr is a destination address in dotted-decimal notation for IPv4 or in a coloned hex notation for IPv6. Spi is a number, preceded by '0x' for hexadecimal, between 0x100 and 0xffffffff; values from 0x0 to 0xff are reserved. Proto is an ASCII string, "ah", "esp", "comp" or "tun", specifying the IP protocol. The protocol must agree with the algorithm selected.

Alternatively, the said argument can also specify an SA to be created or deleted. Said combines the three parameters above, such as: "tun.101@1.2.3.4" or "tun:101@1:2::3:4", where the address family is specified by "." for IPv4 and ":" for IPv6. The address family indicators substitute the "0x" for hexadecimal.

The source address, src, must also be provided for the inbound policy check to function. The source address does not need to be included if inbound policy checking has been disabled.

Keys vectors must be entered as hexadecimal or base64 numbers. They should be cryptographically strong random numbers.

All hexadecimal numbers are entered as strings of hexadecimal digits (0-9 and a-f), without spaces, preceded by '0x', where each hexadecimal digit represents 4 bits. All base64 numbers are entered as strings of base64 digits
 (0-9, A-Z, a-z, '+' and '/'), without spaces, preceded by '0s', where each hexadecimal digit represents 6 bits and '=' is used for padding.

The deletion of an SA which has been grouped will result in the entire chain being deleted.

The form with no additional arguments lists the contents of /proc/net/ipsec_spi. The format of /proc/net/ipsec_spi is discussed in ipsec_spi(5).

The lifetime severity of soft sets a limit when the key management daemons are asked to rekey the SA. The lifetime severity of hard sets a limit when the SA must expire. The lifetime type allocations tells the system when to expire the SA because it is being shared by too many eroutes (not currently used). The lifetime type of bytes tells the system to expire the SA after a certain number of bytes have been processed with that SA. The lifetime type of addtime tells the system to expire the SA a certain number of seconds after the SA was installed. The lifetime type of usetime tells the system to expire the SA a certain number of seconds after that SA has processed its first packet. The lifetime type of packets tells the system to expire the SA after a certain number of packets have been processed with that SA.  

OPTIONS

--af
specifies the address family (inet for IPv4, inet6 for IPv6)
--edst
specifies the effective destination daddr of the Security Association
--spi
specifies the Security Parameters Index spi of the Security Association
--proto
specifies the IP protocol proto of the Security Association
--said
specifies the Security Association in monolithic format
--ah
add an SA for an IPSEC Authentication Header, specified by the following transform identifier (hmac-md5-96 or hmac-sha1-96) (RFC2402, obsoletes RFC1826)
hmac-md5-96
transform following the HMAC and MD5 standards, using a 128-bit key to produce a 96-bit authenticator (RFC2403)
hmac-sha1-96
transform following the HMAC and SHA1 standards, using a 160-bit key to produce a 96-bit authenticator (RFC2404)
--esp
add an SA for an IPSEC Encapsulation Security Payload, specified by the following transform identifier (3des, or 3des-md5-96) (RFC2406, obsoletes RFC1827)
3des
encryption transform following the Triple-DES standard in Cipher-Block-Chaining mode using a 64-bit iv (internally generated) and a 192-bit 3DES ekey (RFC2451)
3des-md5-96
encryption transform following the Triple-DES standard in Cipher-Block-Chaining mode with authentication provided by HMAC and MD5 (96-bit authenticator), using a 64-bit iv (internally generated), a 192-bit 3DES ekey and a 128-bit HMAC-MD5 akey (RFC2451, RFC2403)
3des-sha1-96
encryption transform following the Triple-DES standard in Cipher-Block-Chaining mode with authentication provided by HMAC and SHA1 (96-bit authenticator), using a 64-bit iv (internally generated), a 192-bit 3DES ekey and a 160-bit HMAC-SHA1 akey (RFC2451, RFC2404)
--replay_window replayw
sets the replay window size; valid values are decimal, 1 to 64
--life life_param[,life_param]
sets the lifetime expiry; the format of life_param consists of a comma-separated list of lifetime specifications without spaces; a lifetime specification is comprised of a severity of soft or hard followed by a '-', followed by a lifetime type of allocations, bytes, addtime, usetime or packets followed by an '=' and finally by a value
--comp
add an SA for IPSEC IP Compression, specified by the following transform identifier (deflate) (RFC2393)
deflate
compression transform following the patent-free Deflate compression algorithm (RFC2394)
--ip4
add an SA for an IPv4-in-IPv4 tunnel from encap-src to encap-dst
--ip6
add an SA for an IPv6-in-IPv6 tunnel from encap-src to encap-dst
--src
specify the source end of an IP-in-IP tunnel from encap-src to encap-dst and also specifies the source address of the Security Association to be used in inbound policy checking and must be the same address family as af and edst
--dst
specify the destination end of an IP-in-IP tunnel from encap-src to encap-dst
--del
delete the specified SA
--clear
clears the table of SAs
--help
display synopsis
--version
display version information
 

EXAMPLES

To keep line lengths down and reduce clutter, some of the long keys in these examples have been abbreviated by replacing part of their text with ``...''. Keys used when the programs are actually run must, of course, be the full length required for the particular algorithm.

ipsec spi --af inet --edst gw2 --spi 0x125 --proto esp \
--src gw1 \
--esp 3des-md5-96 \
   --enckey 0x6630...97ce \
--authkey 0x9941...71df

sets up an SA from gw1 to gw2 with an SPI of 0x125 and protocol ESP (50) using 3DES encryption with integral MD5-96 authentication transform, using an encryption key of 0x6630...97ce and an authentication key of 0x9941...71df (see note above about abbreviated keys).

ipsec spi --af inet6 --edst 3049:9::9000:3100 --spi 0x150 --proto ah \
--src 3049:9::9000:3101 \
--ah hmac-md5-96 \
   --authkey 0x1234...2eda \

sets up an SA from 3049:9::9000:3101 to 3049:9::9000:3100 with an SPI of 0x150 and protocol AH (50) using MD5-96 authentication transform, using an authentication key of 0x1234...2eda (see note above about abbreviated keys).

ipsec spi --said tun.987@192.168.100.100 --del

deletes an SA to 192.168.100.100 with an SPI of 0x987 and protocol IPv4-in-IPv4 (4).

ipsec spi --said tun:500@3049:9::1000:1 --del

deletes an SA to 3049:9::1000:1 with an SPI of 0x500 and protocol IPv6-in-IPv6 (4).

 

FILES

/proc/net/ipsec_spi, /usr/local/bin/ipsec  

SEE ALSO

ipsec(8), ipsec_manual(8), ipsec_tncfg(8), ipsec_eroute(8), ipsec_spigrp(8), ipsec_klipsdebug(8), ipsec_spi(5)  

HISTORY

Written for the Linux FreeS/WAN project <http://www.freeswan.org/> by Richard Guy Briggs.  

BUGS

The syntax is messy and the transform naming needs work.


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
FILES
SEE ALSO
HISTORY
BUGS

This document was created by man2html using the manual pages.
Time: 17:31:18 GMT, October 23, 2013

Meet new people