Adds, updates, dumps, or flushes security association database ( SAD) entries and security policy database ( SPD) entries on the board.
cgsetkey [option] -f filename
or
cgsetkey [option] command operation arguments
Where valid commands are:
Command |
Description |
|---|---|
-c |
Carries out a series of operations from standard input. For information about valid arguments to include within the file, refer to the options table. |
-D |
Displays all SAD entries. |
-F |
Flushes all SAD entries. |
- f filename |
Carries out a series of operations from a specified file (filename). For information about valid arguments to include within the file, refer to the options table. |
Valid options include:
Option |
Description |
|---|---|
-b boardnumb |
Indicates the OAM board number of the board to configure. |
-v |
Runs cgsetkey in verbose mode. The program dumps messages exchanged on PF_KEY socket. |
-P |
Displays all SPD and SAD entries when used with the -D command. Flushes all SPD and SAD entries when used with the -F command. |
-d |
Prints debugging messages for the command parser without communicating with the kernel. |
Operations specified through standard input or through a file must use the following syntax:
operation arguments;
Valid operations include:
Operation |
Description |
|---|---|
add arguments; |
Adds an SAD entry. The add operation takes the following form: add src dst protocol spi -t tag algorithm... ; For more information, refer to the arguments table. |
get arguments; |
Retrieves a particular SAD entry. The get operation takes the following form: get src dst protocol spi ; For more information, refer to the arguments table. |
delete arguments; |
Deletes an SAD entry. The delete operation takes the following form: delete src dst protocol spi ; For more information, refer to the arguments table. |
deleteall arguments; |
Deletes all SAD entries specified by arguments. The deleteall operation takes the following form: deleteall src dst protocol ; For more information, refer to the arguments table. |
flush; |
Removes all SAD entries specified by arguments. The flush operation takes the following form: flush; |
dump arguments; |
Displays all SAD entries specified by arguments. The dump operation takes the following form: dump protocol; For more information, refer to the arguments table. |
spdadd arguments; |
Adds an SPD entry. The spdadd operation takes the following form: spdadd src_range dst_range upperspec policy ; For more information, refer to the arguments table. |
spddelete arguments; |
Deletes an SPD entry. The spddelete operation takes the following form: spddelete src_range dst_range upperspec -P direction ; For more information, refer to the arguments table. |
spdflush; |
Clears all SPD entries, as well as all linked SA entries. |
spddump; |
Displays all SPD entries. |
In text files, lines beginning with a hash symbol (#) are regarded as comments. All lines containing an operation must end with a semi colon (;). Spaces within statements are ignored.
Valid arguments include:
Argument |
Description |
|||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
src |
Source of the secure communication specified in numeric form. DNS lookups are not performed. |
|||||||||||||||||||||
dst |
Destination of the secure communication specified in numeric form. DNS lookups are not performed. |
|||||||||||||||||||||
protocol |
Security protocol to implement. Valid protocols include: esp - encapsulating security payload header ah - authentication header When you specify ESP as the protocol, you can associate both an encryption and an authentication algorithm with the entry. |
|||||||||||||||||||||
spi |
Security parameter index ( SPI) for the SAD and the SPD. This value must be a decimal number or hexadecimal number. You cannot use SPI values in the range 0 through 255 (prefixed with 0x - hexadecimal numbers are permitted). |
|||||||||||||||||||||
tag |
Used in the following form: -t id where id specifies the identifier of the policy entry in the SPD. |
|||||||||||||||||||||
algorithm |
Specifies an encryption or authentication algorithm to use. Allowed values vary depending on the specified algorithm. Valid arguments include the following:
In either case, the key must be a double-quoted character string or series of hexadecimal digits (prefixed by 0x). The following encryption algorithm is supported when -E ealgo is specified as the algorithm argument:
The following authentication algorithms are supported when -A aalgo is specified as the algorithm argument:
When you specify ah as the protocol argument, you can use only -A (to specify an authentication algorithm). When you specify esp as the protocol argument, you can use both -E (to specify an encryption algorithm) and -A (to specify an authentication algorithm). |
|||||||||||||||||||||
src_range |
IPv6 source address or range of IPv6 source addresses to add or delete. (this argument can be accompanied by a TCP/UDP port specification). Addresses and address ranges take the following form:
prefixlen and UDPport must be specified as decimal numbers and the address and UDPport must be expressed in numeric form. |
|||||||||||||||||||||
dst_range |
IPv6 destination address or range of IPv6 destination addresses to add or delete. This argument can be accompanied by a TCP/UDP port specification. Addresses and address ranges can take the following form:
prefixlen and UDPport must be specified as decimal numbers and the address and UDPport must be expressed in numeric form. |
|||||||||||||||||||||
upperspec |
Upper-layer protocol to use. The following protocols are supported:
Where protocolnumb represents the protocol number in decimal notation. |
|||||||||||||||||||||
policy |
IPsec policy argument that takes one of the following forms:
where:
|
Use cgsetkey to add, change, or delete IPv6 security keys and policies. The IPSec authentication header and the encapsulating security payload are supported.
The security policy database (SPD) consists of a list of policies that describe a set of packets to match and an action to be taken for those packets. If the action is ipsec, then the policy must contain links to one or more security associations (SAs) that contain keying material for a simplex packet flow between two hosts. These links are made using the tag argument for the spdadd and add commands.
The spdadd command is used to add entries to the database of policies that is scanned when packets are transmitted and received. Policies are scanned in the order in which they are added to the database. Therefore, more general policies should follow more specific policies in the database. The first policy found matching a packet is be used for that packet.
The security association database (SAD) contains the set of all active security associations. Each SA must be linked explicitly to a policy in the SPD when it is created. When a policy is deleted, the SA is deleted as well.
The following examples show possible entries within cgsetkey configuration files for setting, retrieving, printing, or deleting IPSec keys or policies.
Example 1: Adding an entry to the SAD
The following operation adds an entry to the security association database:
add 3ffe:501:4819::1 3ffe:501:481d::1 esp 1234567
-E des-cbc "secret key" ;
where:
Source address is 3ffe:501:4819::1
Destination address is 3ffe:501:481d::1
esp protocol is selected for the entry
Security parameter index (SPI) for the entry is set to 1234567
des-cbc encryption algorithm is selected for the entry
Example 2: Adding an entry to the SAD
The following operation adds an entry to the security association database:
add 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456
-A hmac-sha1 "AH SA configuration!" ;
where:
Source address is 3ffe:501:4819::1
Destination address is 3ffe:501:481d::1
ah protocol is implemented for the entry
SAD and SPD security parameter index for the entry is set to 123456
hmac-sha1 authentication algorithm is enabled for the entry
Example 3: Adding an entry to the SAD
The following operation adds an entry to the security association database:
add 3ffe:501:4819::1 3ffe:501:481d::1 esp 0x10001
-E des-cbc "ESP with"
-A hmac-md5 "authentication!!" ;
where:
Source address is 3ffe:501:4819::1
Destination address is 3ffe:501:481d::1
esp protocol is specified
The security parameter index for the entry is 0x10001
des-cbc is the selected encryption algorithm
hmac-md5 is the selected authentication algorithm
Note: When using the esp protocol, you can specify both an encryption algorithm and authentication algorithm for the SAD entry.
Example 4: Retrieving an entry from the SAD
The following operation retrieves an entry from the security association database:
get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
where the SAD database entry is the same one added in Example 2.
Example 5: Flushing all SAD entries
The following operation removes all entries from the security association database:
flush ;
Example 6: Dumping all SAD entries
The following operation displays all entries that use the ESP protocol from the security association database:
dump esp ;
Example 7: Adding an entry to the SPD
The following operation adds an entry to the security policy database:
spdadd 3ffe:501:4819::1/32[21] 3ffe:501:481d::1/32[any] any
-P out ipsec esp/transport/654321;
where:
Source address is 3ffe:501:4819::1 on UDP port 21
Destination address is 3ffe:501:481d::1 on any UDP port
The entry can use any upper layer protocol
The following IPSec policy is established for the entry:
The policy is implemented on outbound packets.
The policy uses the esp protocol.
The policy associates the entry in the SPD with the string 654321, and creates an out-bound security association for the entry.
The following sample cgsetkey command file shows how to use cgsetkey commands in a text file to set up SAD and SPD entries for a particular board:
######################################################################
# This file assumes that one of the CG board's IPv6 interfaces has the
# link-local address FE80::220:22FF:FE31:4C46.
##############################################
# Clear out the SPD
spdflush;
# Clear out the SADB
flush;
#######################################################################
# Policy section
# Policies are added in the order they will be searched.
# If more than one policy matches a packet, the first match will be
# used.
# Add a policy requiring IPSEC for all outbound UDP packets
spdadd 0::0/0 0::0/0 udp -P out ipsec
ah/transport//tag:1;
# Add a policy requiring IPSEC for all inbound UDP packets.
spdadd 0::0/0 0::0/0 udp -P in ipsec
ah/transport//tag:2;
######################################################################
# Key section
# All SAs must contain a tag parameter which specifies the policy
# entry the SA will be linked to.
# If unspecified, the tag will default to zero.
# Add an SA. Since ...4C46 is a local address, this is an outbound SA.
# The destination is ...0C37 and the SPI is 1234. This SA will be
# linked to the outbound policy (tag 1).
# The key is specifyed as an ascii string of 160 bits.
add FE80::220:22FF:FE31:4C46 FE80:0000:0000:0000:206:4cff:Fe25:0C37 ah 1234 -t 1
-A hmac-sha1 "abcdefghijklmnopqrst";
# Add another SA. This is an inbound SA because the destination address is
# local. This one will be linked to the inbound policy (tag 2).
# The key is specified as a 160 bit hexadecimal number.
add FE80::206:4cff:Fe25:0c37 FE80:0000:0000:0000:0220:22FF:FE31:4C46 ah 4321 -t 2
-A hmac-sha1 0x1234567812345678123456781234567812345678;