I'm sponsoring the following fasttrack for Mark Fenwick. Timer expires
09/29/2009. I am setting a shorter timer at the request of the
submitter. Please speak up if anyone needs more time.
Release binding is Patch/Micro. Commitment levels match
existing interfaces (Committed for CLI and PF_KEY, Project
Private for PF_POLICY).
Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
Changes to IPsec ESP to support Combined mode ciphers
1.2. Name of Document Author/Supplier:
Author: Mark Fenwick
1.3 Date of This Document:
24 September, 2009
4. Technical Description
Description:
------------
IPsec ESP provides network packet encryption and authentication using
encryption and authentication algorithms described by ipsecalgs(1m) and
configured using the ipsecconf(1m) tokens:
encr_algs
ancr_auth_algs
Each operation, that is encryption and authentication, is performed by a
separate
cryptographic mechanism in the encryption framework.
The introduction of AES combined mode ciphers into the encryption framework
began with AES CCM Mode (PSARC/2007/266), then AES GCM Mode. These combined mode
ciphers provide a mechanism to encrypt and authenticate in a single operation.
There are potential performance improvements when using combined mode ciphers.
There are currently two combined mode AES cipher modes supported by the
encryption framework:
AES CCM - (Counter with CBC-MAC)
AES GCM - (Galois/Counter Mode)
AES GCM Mode is a requirement for NSA Suite B Cryptography, a US government
standard for cryptographic algorithms. The support of AES GCM for IPsec ESP is
a significant step towards Suite B compliance and puts Solaris on par with
Linux and Microsoft Windows server 2008 R2 in this area.
Implementation guidelines are provided by the following RFCs:
4309 - Using Advanced Encryption Standard (AES) CCM Mode
with IPsec Encapsulating Security Payload (ESP)
4106 - The Use of Galois/Counter Mode (GCM)
in IPsec Encapsulating Security Payload (ESP)
Proposal:
---------
The encryption framework mechanisms that support AES CCM/GCM require
some additional parameters, which need to be provided by the key management
mechanism (in.iked(1m) or ipseckey(1m)). To allow these parameters to be
configured, the ipsecalgs(1m) command has been modified along with the
getipsecalgsbyname() function. The changes are described below in the manual
page diffs.
The new ipsecalgs(1m) algorithm descriptions can be used by ipsecconf(1m) as
part of the IPsec security policy.
A new argument to ipseckey(1m) allows a specified number of bits in the
keystring to be reserved, these are used for testing the algorithm, they would
not be used in practice.
The changes here are backwards compatible with existing IPsec algorithms and
configuration.
These changes are tracked by the following CRs:
6704686 IPsec/ESP needs to support Combined mode ciphers
6704682 IPsec/ESP should use AES-CCM
6884664 IPsec/ESP should support AES-GCM Mode
6843044 Need STC support for AES CCM/GCM Modes
Details:
--------
The following changes are proposed to pfkeyv2.h:
New PF_KEY Encryption algorithms:
#define SADB_EALG_AES_CCM_8 14
#define SADB_EALG_AES_CCM_12 15
#define SADB_EALG_AES_CCM_16 16
#define SADB_EALG_AES_GCM_8 18
#define SADB_EALG_AES_GCM_12 19
#define SADB_EALG_AES_GCM_16 20
The following changes to pfpolicy.h:
New flags:
#define ALG_FLAG_VALID 0x01
#define ALG_FLAG_COUNTERMODE 0x02
#define ALG_FLAG_COMBINED 0x04
#define ALG_FLAG_CCM 0x08
#define ALG_FLAG_GCM 0x10
New SPD attributes:
#define SPD_ATTR_ALG_NPARAMS 0x00000122
#define SPD_ATTR_ALG_PARAMS 0x00000123
#define SPD_ATTR_ALG_FLAGS 0x00000124
The following changes to netdb.h:
The a_mech_params and a_alg_flags elements have been added to
ipsecalgent_t:
typedef struct ipsecalgent {
char **a_names; /* algorithm names */
int a_proto_num; /* protocol number */
int a_alg_num; /* algorithm number */
char *a_mech_name; /* encryption framework mechanism name */
int *a_block_sizes; /* supported block sizes */
int *a_key_sizes; /* supported key sizes */
int a_key_increment; /* key size increment */
int *a_mech_params; /* mechanism specific parameters */
int a_alg_flags; /* algorithm flags */
} ipsecalgent_t;
Interfaces:
-----------
+-----------------------------------+--------------------+---------------------+
| Interface Name | Commitment | Comments |
+-----------------------------------+--------------------+---------------------+
| ipseckey(1m) commands: | Committed | documented in man |
| reserved_bits | | page. |
+-----------------------------------+--------------------+---------------------+
| ipsecalgs(1m) commands: | Committed | documented in man |
| -M flag | | page. |
| -I flag | | |
| -S flag | | |
+-----------------------------------+--------------------+---------------------+
| netdb.h | Committed | documented in man |
| *a_mech_params | | page. |
| a_alg_flags | | |
+-----------------------------------+--------------------+---------------------+
| pfkeyv2.h | Committed | The respective |
| SADB_EALG_AES_CCM_8 | | numbers were
assigned|
| SADB_EALG_AES_CCM_12 | | by IANA. |
| SADB_EALG_AES_CCM_16 | | |
| SADB_EALG_AES_GCM_8 | | |
| SADB_EALG_AES_GCM_12 | | |
| SADB_EALG_AES_GCM_16 | | |
+-----------------------------------+--------------------+---------------------+
| pfpolicy.h | Project Private | |
| ALG_FLAG_VALID | | |
| ALG_FLAG_COUNTERMODE | | |
| ALG_FLAG_COMBINED | | |
| ALG_FLAG_CCM | | |
| ALG_FLAG_GCM | | |
| SPD_ATTR_ALG_NPARAMS | | |
| SPD_ATTR_ALG_PARAMS | | |
| SPD_ATTR_ALG_FLAGS | | |
+-----------------------------------+--------------------+---------------------+
Man page changes:
-----------------
getipsecalgbyname(3NSL)
*** getipsecalgbyname.orig.text Mon Sep 21 16:34:28 2009
--- getipsecalgbyname.text Wed Sep 23 12:34:20 2009
***************
*** 102,111 ****
--- 102,113 ----
int a_alg_num; /* algorithm number */
char *a_mech_name; /* mechanism name */
int *a_block_sizes; /* supported block sizes */
int *a_key_sizes; /* supported key sizes */
int a_key_increment; /* key size increment */
+ int *a_mech_params; /* mechanism specific parameters */
+ int a_alg_flags; /* algorithm flags */
} ipsecalgent_t;
If a_key_increment is non-zero, a_key_sizes[0] contains the
***************
*** 150,162 ****
a_block_sizes is an array containing the supported block
lengths or MAC lengths, in bytes, supported by the algo-
rithm. The last valid value in the array is followed by an
element containing the value 0.
ERRORS
When the specified algorithm cannot be returned to the
! caller, getipsecalgbynam() and getipsecalgbynum() return a
value of NULL and set the integer pointed to by the errnop
parameter to one of the following values:
ENOMEM Not enough memory
--- 152,174 ----
a_block_sizes is an array containing the supported block
lengths or MAC lengths, in bytes, supported by the algo-
rithm. The last valid value in the array is followed by an
element containing the value 0.
+ a_mech_params is an array containing any additional
+ algorithm parameters needed by the cryptographic framework
+ mechanism. The order of the parameters and their use is not
+ specified. The last valid value in the array is followed by
+ an element containing the value 0.
+
+ a_alg_flags is a bit mask of flags, these are used internally
+ by the IPsec esp code and by the IPsec administrative utilities.
+ Their meaning is not described here.
+
ERRORS
When the specified algorithm cannot be returned to the
! caller, getipsecalgbyname() and getipsecalgbynum() return a
value of NULL and set the integer pointed to by the errnop
parameter to one of the following values:
ENOMEM Not enough memory
ipsecalgs(1m)
*** ipsecalgs.orig.text Mon Sep 21 15:25:40 2009
--- ipsecalgs.text Thu Sep 24 17:07:34 2009
***************
*** 314,324 ****
--- 314,353 ----
mation 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 sys-
tem restart.
+ The following options allow optional parameters to be configured.
+ These are currently only used for combined mode algorithms, that
+ is, algorithms that provide encryption and authentication in a
+ single operation.
+ -I The length of the Initialization Vector (IV) in bytes.
+ The default IV length is the same as the block length.
+
+ -M The length of the MAC or ICV in bytes for combined mode
+ algorithms.
+
+ -S The number of bytes of salt needed by the algorithm. The
+ salt needs to be provided by the key management mechanism.
+
+ -F Algorithm flags. These influence the way in which the kernel
+ handles esp authentication in the kernel. They are also used
+ by ipseckey(1m) and ipsecconf(1m). Flags can be specified as
+ a comma separated list of tokens, see the example below. The
+ following tokens are supported:
+
+ COUNTERMODE - The algorithm uses counter mode.
+ COMBINED - The algorithm provides encryption and authentication
+ in the same operation.
+ CCM - The cryptographic framework mechanism needs a
+ CK_AES_CCM_PARAMS structure.
+ GCM - The cryptographic framework mechanism needs a
+ CK_AES_GCM_PARAMS structure.
+
+ The algorithm flags can be displayed with the -l option.
+
EXAMPLES
Example 1 Adding a Protocol for IPsec Encryption
***************
*** 364,374 ****
--- 393,409 ----
example# svcadm refresh ipsecalgs
+ Example 4 Adding the AES Galois/Counter Mode (GCM) Algorithm
+ example# ipsecalgs -a -P3 -k 128-256 -K 128 -i 64 -N 20 -b 16 \
+ -n "aes-gcm16,aes-gcm" -m CKM_AES_GCM -M 16 -I 8 -S 4 \
+ -F GCM,COMBINED,COUNTER
+
+
FILES
/etc/inet/ipsecalgs
File that contains the configured IPsec protocols and
algorithm definitions. Never edit this file manually.
ipsecconf(1m)
*** ipsecconf.orig.text Mon Sep 21 16:58:37 2009
--- ipsecconf.text Thu Sep 24 11:08:21 2009
***************
*** 449,459 ****
hmac-sha1 | hmac-sha256 | hmac-sha384 |
hmac-sha512 |<number>
encr_alg ::= <encr_algname> ['(' <keylen> ')']
encr_algname ::= any | aes | aes-cbc | des | des-cbc | 3des |
! 3des-cbc | blowfish | blowfish-cbc | <number>
SunOS 5.11 Last change: 10 Jan 2008 7
--- 449,460 ----
hmac-sha1 | hmac-sha256 | hmac-sha384 |
hmac-sha512 |<number>
encr_alg ::= <encr_algname> ['(' <keylen> ')']
encr_algname ::= any | aes | aes-cbc | des | des-cbc | 3des |
! 3des-cbc | blowfish | blowfish-cbc | aes-ccm |
! aes-gcm | <number>
SunOS 5.11 Last change: 10 Jan 2008 7
***************
*** 1671,1680 ****
--- 1672,1704 ----
# Cover remote-site B traffic to my subnet.
{tunnel ip.tun1 negotiate tunnel raddr B-prefix/24 laddr
C-prefix/24} ipsec {encr_algs aes encr_auth_algs md5}
+ Example 18 Using Combined mode ciphers.
+
+ Combined mode ciphers provide data privacy and message
+ authentication in a single operation. They are treated as special
+ versions of encr_algs. They provide message authentication
+ without the need to specify encr_auth_algs. The two combined mode
+ ciphers supported are:
+
+ aes-ccm - AES CCM Mode(Counter with CBC-MAC)
+ aes-gcm - AES GCM Mode (Galois/Counter)
+
+ The parameters used are the same as any other encr_algs value.
+ In both examples, the number in the algorithm token indicates the
+ length of the Integrity Check Vector (ICV) - see ipsecalgs(1m).
+
+ # simple example using transport mode
+ {laddr 192.168.99.2 raddr 192.168.99.3} ipsec
+ {encr_algs aes-gcm sa shared}
+ # simple example using CCM mode and 128 bit keys
+ {laddr 192.168.99.100 raddr 192.168.99.200} ipsec
+ {encr_algs aes-ccm(128) sa shared}
+
+
FILES
/var/run/ipsecpolicy.conf
Cache of IPsec policies currently configured for the
system, maintained by ipsecconf command. Do not edit
ipseckey(1m)
*** ipseckey.orig.text Mon Sep 21 16:50:38 2009
--- ipseckey.text Mon Sep 21 16:58:04 2009
***************
*** 750,761 ****
--- 750,766 ----
multi-key encryption algorithm is 3des, which would
express itself as a 192-bit key, which is three 64-bit
parity-included DES keys. This extension is used by the
add and update commands.
+ reserved_bits <number>
+ The last <number> bits of the encrkey string are marked as
+ reserved in the PF_KEY message. This option is only for
+ testing certain encryption algorithms.
+
Certificate identities are very useful in the context of
automated key management, as they tie the SA to the public
key certificates used in most automated key management pro-
tocols. They are less useful for manually added SAs. Unlike
other extensions, srcidtype takes two values, a type, and an
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
on
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
