# cgsetkey - Configuring IPv6 security keys and policies

Adds, updates, dumps, or flushes security association database (SAD
) entries and security policy database (SPD
) entries on the board.

#### Usage

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.

#### Options

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;

#### Operations

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.

#### Arguments

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:
Argument | Description
-E ealgo key | Encryption algorithm.
-A aalgo key | Authentication algorithm. When -A is used in conjunction with the esp protocol, it is treated as the ESP payload authentication algorithm.
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:
Algorithm | Key length in bits | Description
des-cbc | 64 | ESP-old: RFC 1829, ESP: RFC 2405
The following authentication algorithms are supported when -A aalgo is specified as the algorithm argument:
Algorithm | Key length in bits | Description
hmac-md5 | 128 | AH: RFC 403
hmac-sha1 | 160 | AH: RFC 2404
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: address address/prefixlen address[UDPport] address/prefixlen[UDPport] 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: address address/prefixlen address[UDPport] address/prefixlen[UDPport] 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: udp icmp6 any protocolnumb Where protocolnumb represents the protocol number in decimal notation.
policy | IPsec policy argument that takes one of the following forms: -P direction discard -P direction bypass -P direction ipsec protocol/transport/tag:index where:
Valid options | Description
direction | Direction of the policy can be set to either out or in. discard Drop packets matching the specified policy. bypass No IP security is required for packets associated with the specified policy. ipsec IPsec is required for packets associated with the specified policy.
protocol | Protocol to use that can be set to either esp (encapsulating security payload) or ah (authentication header). transport Establishes that packets are transferred using transport mode.
tag:index | Number (index) between 1 and 32767 with which to bind the policy and create a unique identifier for the policy. This field associates manually configured SAs with policy entries. The decimal number (index) you enter as the policy identifier must be separated from the tag statement by a colon, as in the following example: tag:number

#### Details

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.

#### Command examples

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.

#### Example cgsetkey command file

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;