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

Reply via email to