Tribblix: manual page: ipsecalgs.8

IPSECALGS(8) Maintenance Commands and Procedures IPSECALGS(8)

NAME

ipsecalgs - configure the IPsec protocols and algorithms table

SYNOPSIS

ipsecalgs

ipsecalgs -l

ipsecalgs -s

ipsecalgs -a [-P protocol-number | -p protocol-name] -k keylen-list
[-i inc] [-K default-keylen] -b blocklen-list -n alg-names
-N alg-number -m mech-name [-f] [-s]

ipsecalgs -P protocol-number -p protocol-name
[-e exec-mode] [-f] [-s]

ipsecalgs -r -p protocol-name [] -n alg-name [-s]

ipsecalgs -r -p protocol-name [] -N alg-number [-s]

ipsecalgs -R -P protocol-number [-s]

ipsecalgs -R -p protocol-name [-s]

ipsecalgs -e exec-mode -P protocol-number [-s]

ipsecalgs -e exec-mode -p protocol-name [-s]

DESCRIPTION

Use the ipsecalgs command to query and modify the IPsec protocol and
algorithms stored in /etc/inet/ipsecalgs. You can use the ipsecalgs
command to do the following:

o list the currently defined IPsec protocols and algorithms

o modify IPsec protocols definitions

o modify IPsec algorithms definitions

Never edit the /etc/inet/ipsecalgs file manually. The valid IPsec
protocols and algorithms are described by the ISAKMP DOI. See RFC
2407. In the general sense, a Domain of Interpretation (DOI) defines
data formats, network traffic exchange types, and conventions for
naming security-relevant information such as security policies or
cryptographic algorithms and modes. For ipsecalgs, the DOI defines
naming and numbering conventions for algorithms and the protocols
they belong to. These numbers are defined by the Internet Assigned
Numbers Authority (IANA). Each algorithm belongs to a protocol.
Algorithm information includes supported key lengths, block or MAC
length, and the name of the cryptographic mechanism corresponding to
that algorithm. This information is used by the IPsec modules,
ipsecesp(4P) and ipsecah(4P), to determine the authentication and
encryption algorithms that can be applied to IPsec traffic.

The following protocols are predefined:

IPSEC_PROTO_ESP
Defines the encryption algorithms (transforms)
that can be used by IPsec to provide data
confidentiality.

IPSEC_PROTO_AH
Defines the authentication algorithms (transforms)
that can be used by IPsec to provide
authentication.

The mechanism name specified by an algorithm entry must correspond to
a valid Solaris Cryptographic Framework mechanism. You can obtain the
list of available mechanisms by using the cryptoadm(8) command.

Applications can retrieve the supported algorithms and their
associated protocols by using the functions getipsecalgbyname(3NSL),
getipsecalgbynum(3NSL), getipsecprotobyname(3NSL) and
getipsecprotobynum(3NSL).

Modifications to the protocols and algorithm by default update only
the contents of the /etc/inet/ipsecalgs configuration file. In order
for the new definitions to be used for IPsec processing, the changes
must be communicated to the kernel using the -s option. See NOTES for
a description of how the ipsecalgs configuration is synchronized with
the kernel at system restart.

When invoked without arguments, ipsecalgs displays the list of
mappings that are currently defined in /etc/inet/ipsecalgs. You can
obtain the corresponding kernel table of protocols and algorithms by
using the -l option.

OPTIONS

ipsecalgs supports the following options:

-a
Adds an algorithm of the protocol specified by the -P option.
The algorithm name(s) are specified with the -n option. The
supported key lengths and block sizes are specified with the
-k, -i, and -b options.

-b
Specifies the block or MAC lengths of an algorithm, in bytes.
Set more than one block length by separating the values with
commas.

-e
Designates the execution mode of cryptographic requests for the
specified protocol in the absence of cryptographic hardware
provider. See cryptoadm(8). exec-mode can be one of the
following values:

sync
Cryptographic requests are processed synchronously in
the absence of a cryptographic hardware provider. This
execution mode leads to better latency when no
cryptographic hardware providers are available

async
Cryptographic requests are always processed
asynchronously in the absence of cryptographic
hardware provider. This execution can improve the
resource utilization on a multi-CPU system, but can
lead to higher latency when no cryptographic hardware
providers are available.

This option can be specified when defining a new protocol or to
modify the execution mode of an existing protocol. By default,
the sync execution mode is used in the absence of a
cryptographic hardware provider.

-f
Used with the -a option to force the addition of an algorithm
or protocol if an entry with the same name or number already
exists.

-i
Specifies the valid key length increments in bits. This option
must be used when the valid key lengths for an algorithm are
specified by a range with the -k option.

-K
Specifies the default key lengths for an algorithm, in bits. If
the -K option is not specified, the minimum key length will be
determined as follows:

o If the supported key lengths are specified by range,
the default key length will be the minimum key
length.

o If the supported key lengths are specified by
enumeration, the default key length will be the
first listed key length.

-k
Specifies the supported key lengths for an algorithm, in bits.
You can designate the supported key lengths by enumeration or
by range.

Without the -i option, -k specifies the supported key lengths
by enumeration. In this case, keylen-list consists of a list of
one or more key lengths separated by commas, for example:

128,192,256

The listed key lengths need not be increasing, and the first
listed key length will be used as the default key length for
that algorithm unless the -K option is used.

With the -i option, -k specifies the range of supported key
lengths for the algorithm. The minimum and maximum key lengths
must be separated by a dash ('-') character, for example:

32-448

-l
Displays the kernel algorithm tables.

-m
Specifies the name of the cryptographic framework mechanism
name corresponding to the algorithm. Cryptographic framework
mechanisms are described in the cryptoadm(8) man page.

-N
Specifies an algorithm number. The algorithm number for a
protocol must be unique. IANA manages the algorithm numbers.
See RFC 2407.

-n
Specifies one or more names for an algorithm. When adding an
algorithm with the -a option, alg-names contains a string or a
comma-separated list of strings, for example:

des-cbs,des

When used with the -r option to remove an algorithm, alg-names
contains one of the valid algorithm names.

-P
Adds a protocol of the number specified by protocol-number with
the name specified by the -p option. This option is also used
to specify an IPsec protocol when used with the -a and the -R
options. Protocol numbers are managed by the IANA. See RFC
2407.

-p
Specifies the name of the IPsec protocol.

-R
Removes and IPsec protocol from the algorithm table. The
protocol can be specified by number by using the -P option or
by name by using the -p option. The algorithms associated with
the protocol are removed as well.

-r
Removes the mapping for an algorithm The algorithm can be
specified by algorithm number using the -N option or by
algorithm name using the -A option.

-s
Synchronizes the kernel with the contents of
/etc/inet/ipsecalgs. The contents of /etc/inet/ipsecalgs are
always updated, but new information is not passed on to the
kernel unless the -s is used. See NOTES for a description of
how the ipsecalgs configuration is synchronized with the kernel
at system restart.

EXAMPLES

Example 1: Adding a Protocol for IPsec Encryption

The following example shows how to add a protocol for IPsec
encryption:

example# ipsecalgs -P 3 -p "IPSEC_PROTO_ESP"

Example 2: Adding the Blowfish Algorithm

The following example shows how to add the Blowfish algorithm:

example# ipsecalgs -a -P 3 -k 32-488 -K 128 -i 8 -n "blowfish" \
-b 8 -N 7 -m CKM_BF_CBC

Example 3: Updating the Kernel Algorithm Table

The following example updates the kernel algorithm table with the
currently defined protocol and algorithm definitions:

example# svcadm refresh ipsecalgs

FILES

/etc/inet/ipsecalgs

File that contains the configured IPsec protocols and algorithm
definitions. Never edit this file manually.

ATTRIBUTES

NOTES

When protocols or algorithm definitions that are removed or altered,
services that rely upon these definitions can become unavailable. For
example, if the IPSEC_PROTO_ESP protocol is removed, then IPsec
cannot encrypt and decrypt packets.

Synchronization of the ipsecalgs configuration with the kernel at
system startup is provided by the following smf(7) service:

svc:/network/ipsec/ipsecalgs:default

The IPsec services are delivered as follows:

svc:/network/ipsec/policy:default (enabled)
svc:/network/ipsec/ipsecalgs:default (enabled)
svc:/network/ipsec/manual-key:default (disabled)
svc:/network/ipsec/ike:default (disabled)

Services that are delivered disabled are delivered that way because
the system administrator must create configuration files for those
services before enabling them. See ipseckey(8) and ike.config(5). The
default policy for the policy service is to allow all traffic to pass
without IPsec protection. See ipsecconf(8).

The correct administrative procedure is to create the configuration
file for each service, then enable each service using svcadm(8), as
shown in the following example:

example# svcadm enable ipsecalgs

The service's status can be queried using the svcs(1) command.

If the ipsecalgs configuration is modified, the new configuration
should be resynchronized as follows:

example# svcadm refresh ipsecalgs

Administrative actions on this service, such as enabling, disabling,
refreshing, and requesting restart can be performed using svcadm(8).
A user who has been assigned the authorization shown below can
perform these actions:

solaris.smf.manage.ipsec

See auths(1), user_attr(5), rbac(7).

The ipsecalgs smf(7) service does not have any user-configurable
properties.

The smf(7) framework records any errors in the service-specific log
file. Use any of the following commands to examine the logfile
property:

example# svcs -l ipsecalgs
example# svcprop ipsecalgs
example# svccfg -s ipsecalgs listprop

This command requires sys_ip_config privilege to operate and thus can
run in the global zone and in exclusive-IP zones. All shared-IP zones
share the same available set of algorithms; however, you can use
ipsecconf(8) to set up system policy that uses differing algorithms
for various shared-IP zones. All exclusive-IP zones have their own
set of algorithms.

July 5, 2007 IPSECALGS(8)