path: root/usr/src/man/man1m/ipsecalgs.1m

'\" te
.\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH IPSECALGS 1M "Jul 5, 2007"
.SH NAME
ipsecalgs \- configure the IPsec protocols and algorithms table
.SH SYNOPSIS
.LP
.nf
\fBipsecalgs\fR
.fi

.LP
.nf
\fBipsecalgs\fR \fB-l\fR
.fi

.LP
.nf
\fBipsecalgs\fR \fB-s\fR
.fi

.LP
.nf
\fBipsecalgs\fR \fB-a\fR [\fB-P\fR \fIprotocol-number\fR | \fB-p\fR \fIprotocol-name\fR] \fB-k\fR \fIkeylen-list\fR
     [\fB-i\fR \fIinc\fR] [\fB-K\fR \fIdefault-keylen\fR] \fB-b\fR \fIblocklen-list\fR \fB-n\fR \fIalg-names\fR
     \fB-N\fR \fIalg-number\fR \fB-m\fR \fImech-name\fR [\fB-f\fR] [\fB-s\fR]
.fi

.LP
.nf
\fBipsecalgs\fR \fB-P\fR \fIprotocol-number\fR \fB-p\fR \fIprotocol-name\fR
     [\fB-e\fR \fIexec-mode\fR] [\fB-f\fR] [\fB-s\fR]
.fi

.LP
.nf
\fBipsecalgs\fR \fB-r\fR \fB-p\fR \fIprotocol-name\fR [] \fB-n\fR \fIalg-name\fR [\fB-s\fR]
.fi

.LP
.nf
\fBipsecalgs\fR \fB-r\fR \fB-p\fR \fIprotocol-name\fR [] \fB-N\fR \fIalg-number\fR [\fB-s\fR]
.fi

.LP
.nf
\fBipsecalgs\fR \fB-R\fR \fB-P\fR \fIprotocol-number\fR [\fB-s\fR]
.fi

.LP
.nf
\fBipsecalgs\fR \fB-R\fR \fB-p\fR \fIprotocol-name\fR [\fB-s\fR]
.fi

.LP
.nf
\fBipsecalgs\fR \fB-e\fR \fIexec-mode\fR \fB-P\fR \fIprotocol-number\fR [\fB-s\fR]
.fi

.LP
.nf
\fBipsecalgs\fR \fB-e\fR \fIexec-mode\fR \fB-p\fR \fIprotocol-name\fR [\fB-s\fR]
.fi

.SH DESCRIPTION
.sp
.LP
Use the \fBipsecalgs\fR command to query and modify the IPsec protocol and
algorithms stored in \fB/etc/inet/ipsecalgs\fR. You can use the \fBipsecalgs\fR
command to do the following:
.RS +4
.TP
.ie t \(bu
.el o
list the currently defined IPsec protocols and algorithms
.RE
.RS +4
.TP
.ie t \(bu
.el o
modify IPsec protocols definitions
.RE
.RS +4
.TP
.ie t \(bu
.el o
modify IPsec algorithms definitions
.RE
.sp
.LP
\fBNever\fR edit the \fB/etc/inet/ipsecalgs\fR file manually. The valid IPsec
protocols and algorithms are described by the ISAKMP DOI. See \fIRFC 2407\fR.
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 \fBipsecalgs\fR, 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, \fBipsecesp\fR(7P)
and \fBipsecah\fR(7P), to determine the authentication and encryption
algorithms that can be applied to IPsec traffic.
.sp
.LP
The following protocols are predefined:
.sp
.ne 2
.na
\fB\fBIPSEC_PROTO_ESP\fR\fR
.ad
.RS 19n
Defines the encryption algorithms (transforms) that can be used by IPsec to
provide data confidentiality.
.RE

.sp
.ne 2
.na
\fB\fBIPSEC_PROTO_AH\fR\fR
.ad
.RS 19n
Defines the authentication algorithms (transforms) that can be used by IPsec to
provide authentication.
.RE

.sp
.LP
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 \fBcryptoadm\fR(1M) command.
.sp
.LP
Applications can retrieve the supported algorithms and their associated
protocols by using the functions \fBgetipsecalgbyname\fR(3NSL),
\fBgetipsecalgbynum\fR(3NSL), \fBgetipsecprotobyname\fR(3NSL) and
\fBgetipsecprotobynum\fR(3NSL).
.sp
.LP
Modifications to the protocols and algorithm by default update only the
contents of the \fB/etc/inet/ipsecalgs\fR configuration file. In order for the
new definitions to be used for IPsec processing, the changes must be
communicated to the kernel using the \fB-s\fR option. See \fBNOTES\fR for a
description of how the \fBipsecalgs\fR configuration is synchronized with the
kernel at system restart.
.sp
.LP
When invoked without arguments, \fBipsecalgs\fR displays the list of mappings
that are currently defined in \fB/etc/inet/ipsecalgs\fR. You can obtain the
corresponding kernel table of protocols and algorithms by using the \fB-l\fR
option.
.SH OPTIONS
.sp
.LP
\fBipsecalgs\fR supports the following options:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 6n
Adds an algorithm of the protocol specified by the \fB-P\fR option. The
algorithm name(s) are specified with the \fB-n\fR option. The supported key
lengths and block sizes are specified with the \fB-k\fR, \fB-i\fR, and \fB-b\fR
options.
.RE

.sp
.ne 2
.na
\fB\fB-b\fR\fR
.ad
.RS 6n
Specifies the block or MAC lengths of an algorithm, in bytes. Set more than one
block length by separating the values with commas.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 6n
Designates the execution mode of cryptographic requests for the specified
protocol in the absence of cryptographic hardware provider. See
\fBcryptoadm\fR(1M). \fIexec-mode\fR can be one of the following values:
.sp
.ne 2
.na
\fB\fBsync\fR\fR
.ad
.RS 9n
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
.RE

.sp
.ne 2
.na
\fB\fBasync\fR\fR
.ad
.RS 9n
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.
.RE

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

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 6n
Used with the \fB-a\fR option to force the addition of an algorithm or protocol
if an entry with the same name or number already exists.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR\fR
.ad
.RS 6n
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
\fB-k\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-K\fR\fR
.ad
.RS 6n
Specifies the default key lengths for an algorithm, in bits. If the \fB-K\fR
option is not specified, the minimum key length will be determined as follows:
.RS +4
.TP
.ie t \(bu
.el o
If the supported key lengths are specified by range, the default key length
will be the minimum key length.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the supported key lengths are specified by enumeration, the default key
length will be the first listed key length.
.RE
.RE

.sp
.ne 2
.na
\fB\fB-k\fR\fR
.ad
.RS 6n
Specifies the supported key lengths for an algorithm, in bits. You can
designate the supported key lengths by enumeration or by range.
.sp
Without the \fB-i\fR option, \fB-k\fR specifies the supported key lengths by
enumeration. In this case, \fIkeylen-list\fR consists of a list of one or more
key lengths separated by commas, for example:
.sp
.in +2
.nf
128,192,256
.fi
.in -2
.sp

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 \fB-K\fR
option is used.
.sp
With the \fB-i\fR option, \fB-k\fR specifies the range of supported key lengths
for the algorithm. The minimum and maximum key lengths must be separated by a
dash ('\fB-\fR') character, for example:
.sp
.in +2
.nf
32-448
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 6n
Displays the kernel algorithm tables.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fR
.ad
.RS 6n
Specifies the name of the cryptographic framework mechanism name corresponding
to the algorithm. Cryptographic framework mechanisms are described in the
\fBcryptoadm\fR(1M) man page.
.RE

.sp
.ne 2
.na
\fB\fB-N\fR\fR
.ad
.RS 6n
Specifies an algorithm number. The algorithm number for a protocol must be
unique. IANA manages the algorithm numbers. See \fIRFC 2407\fR.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 6n
Specifies one or more names for an algorithm. When adding an algorithm with the
\fB-a\fR option, \fIalg-names\fR contains a string or a comma-separated list of
strings, for example:
.sp
.in +2
.nf
des-cbs,des
.fi
.in -2
.sp

When used with the \fB-r\fR option to remove an algorithm, \fIalg-names\fR
contains one of the valid algorithm names.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.RS 6n
Adds a protocol of the number specified by \fIprotocol-number\fR with the name
specified by the \fB-p\fR option. This option is also used to specify an IPsec
protocol when used with the \fB-a\fR and the \fB-R\fR options. Protocol numbers
are managed by the IANA. See \fIRFC 2407\fR.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 6n
Specifies the name of the IPsec protocol.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR\fR
.ad
.RS 6n
Removes and IPsec protocol from the algorithm table. The protocol can be
specified by number by using the \fB-P\fR option or by name by using the
\fB-p\fR option. The algorithms associated with the protocol are removed as
well.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.RS 6n
Removes the mapping for an algorithm The algorithm can be specified by
algorithm number using the \fB-N\fR option or by algorithm name using the
\fB-A\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 6n
Synchronizes the kernel with the contents of \fB/etc/inet/ipsecalgs\fR. The
contents of \fB/etc/inet/ipsecalgs\fR are always updated, but new information
is not passed on to the kernel unless the \fB-s\fR is used. See \fBNOTES\fR for
a description of how the \fBipsecalgs\fR configuration is synchronized with the
kernel at system restart.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRAdding a Protocol for IPsec Encryption
.sp
.LP
The following example shows how to add a protocol for IPsec encryption:

.sp
.in +2
.nf
example# \fBipsecalgs -P 3 -p "IPSEC_PROTO_ESP"\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRAdding the Blowfish Algorithm
.sp
.LP
The following example shows how to add the Blowfish algorithm:

.sp
.in +2
.nf
example# \fBipsecalgs -a -P 3 -k 32-488 -K 128 -i 8 -n "blowfish" \e
  -b 8 -N 7 -m CKM_BF_CBC\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRUpdating the Kernel Algorithm Table
.sp
.LP
The following example updates the kernel algorithm table with the currently
defined protocol and algorithm definitions:

.sp
.in +2
.nf
example# \fBsvcadm refresh ipsecalgs\fR
.fi
.in -2
.sp

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/inet/ipsecalgs\fR\fR
.ad
.sp .6
.RS 4n
File that contains the configured IPsec protocols and algorithm definitions.
Never edit this file manually.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
\fBcryptoadm\fR(1M), \fBipsecconf\fR(1M), \fBipseckey\fR(1M), \fBsvcadm\fR(1M),
\fBgetipsecalgbyname\fR(3NSL), \fBgetipsecprotobyname\fR(3NSL),
\fBike.config\fR(4), \fBattributes\fR(5), \fBsmf\fR(5), \fBipsecah\fR(7P),
\fBipsecesp\fR(7P)
.sp
.LP
Piper, Derrell, \fIRFC 2407, The Internet IP Security Domain of Interpretation
for ISAKMP\fR. Network Working Group. November 1998.
.SH NOTES
.sp
.LP
When protocols or algorithm definitions that are removed or altered, services
that rely upon these definitions can become unavailable. For example, if the
\fBIPSEC_PROTO_ESP\fR protocol is removed, then IPsec cannot encrypt and
decrypt packets.
.sp
.LP
Synchronization of the \fBipsecalgs\fR configuration with the kernel at system
startup is provided by the following \fBsmf\fR(5) service:
.sp
.in +2
.nf
svc:/network/ipsec/ipsecalgs:default
.fi
.in -2
.sp

.sp
.LP
The IPsec services are delivered as follows:
.sp
.in +2
.nf
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)
.fi
.in -2
.sp

.sp
.LP
Services that are delivered disabled are delivered that way because the system
administrator must create configuration files for those services before
enabling them. See \fBipseckey\fR(1M) and \fBike.config\fR(4). The default
policy for the \fBpolicy\fR service is to allow all traffic to pass without
IPsec protection. See \fBipsecconf\fR(1M).
.sp
.LP
The correct administrative procedure is to create the configuration file for
each service, then enable each service using \fBsvcadm\fR(1M), as shown in the
following example:
.sp
.in +2
.nf
example# \fBsvcadm enable ipsecalgs\fR
.fi
.in -2
.sp

.sp
.LP
The service's status can be queried using the \fBsvcs\fR(1) command.
.sp
.LP
If the \fBipsecalgs\fR configuration is modified, the new configuration should
be resynchronized as follows:
.sp
.in +2
.nf
example# \fBsvcadm refresh ipsecalgs\fR
.fi
.in -2
.sp

.sp
.LP
Administrative actions on this service, such as enabling, disabling,
refreshing, and requesting restart can be performed using \fBsvcadm\fR(1M). A
user who has been assigned the authorization shown below can perform these
actions:
.sp
.in +2
.nf
solaris.smf.manage.ipsec
.fi
.in -2
.sp

.sp
.LP
See \fBauths\fR(1), \fBuser_attr\fR(4), \fBrbac\fR(5).
.sp
.LP
The \fBipsecalgs\fR \fBsmf\fR(5) service does not have any user-configurable
properties.
.sp
.LP
The \fBsmf\fR(5) framework records any errors in the service-specific log file.
Use any of the following commands to examine the \fBlogfile\fR property:
.sp
.in +2
.nf
example# \fBsvcs -l ipsecalgs\fR
example# \fBsvcprop ipsecalgs\fR
example# \fBsvccfg -s ipsecalgs listprop\fR
.fi
.in -2
.sp

.sp
.LP
This command requires \fBsys_ip_config\fR 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 \fBipsecconf\fR(1M) to
set up system policy that uses differing algorithms for various shared-IP
zones. All exclusive-IP zones have their own set of algorithms.