1. Introduction
   1.1 Project/Component Working Name:
       key generation and derivation for providers without keystore
   1.2 Name of Document Author/Supplier:
       Mark Powers, Anthony Scarpino
   1.3 Date of this Document:
       2/12/2007

4. Technical Description

   The Interface taxonomy is Consolidation Private.
   The Release taxonomy is Patch/Micro

   Diff-marked draft manpages, cspi design, and header files are included
   in the case directory.

4.0 Background

   The ncp provider, which is available on sun4v machines, is capable
   of significantly accelerating RSA and Diffie-Hellman (DH) key generation
   and derivation. However, it is not possible to take advantage of this
   because the existing Service Provider Interface (SPI) assumes providers
   capable of generating and deriving keys also have a keystore, and that
   keys are returned by reference rather than value. This proposal seeks
   to remove this limitation.

4.1 Proposal

       The case proposes the following:

       - modifications to the kcf kernel module to support new provider
         entry points for the generation and derivation of keys. The new
         entry points have two arguments per key instead of one. The extra
         argument is reserved for attributes that need to be copied back
         into a user's address space. Providers that register the new
         entry points should not register key ops (crypto_key_ops(9S))
         which are reserved for providers with keystores. Providers with
         these new entry points register SPI version 3.

       - modifications to pkcs11_kernel - a user library component - to use
         the new key generation and derivation entry points. The gist of
         this modification is to add additional PKCS#11 RSA and DH attributes
         to key templates so that generated and derived keys can be returned
         by value rather than by reference. Generated and derived keys will
         be stored as session objects by pkcs11_kernel.so.

       - modifications to metaslot and softtoken to move session keys
         from pkcs11_kernel to pkcs11_softtoken where they can be stored
         as token keys. Token keys are persistent objects whereas session
         keys are destroyed when sessions are closed.

       - modifications to the ncp driver to use version 3 of the SPI.
         The driver will be modified to support CKM_RSA_PKCS_KEY_PAIR_GEN,
         CKM_DH_PKCS_KEY_PAIR_GEN, and CKM_DH_PKCS_DERIVE.

       The new SPI entry points (see spi.h) are:
        int (*nostore_key_generate)(crypto_provider_handle_t,
            crypto_session_id_t, crypto_mechanism_t *,
            crypto_object_attribute_t *, uint_t, crypto_object_attribute_t *,
            uint_t, crypto_req_handle_t);

        int (*nostore_key_generate_pair)(crypto_provider_handle_t,
            crypto_session_id_t, crypto_mechanism_t *,
            crypto_object_attribute_t *, uint_t, crypto_object_attribute_t *,
            uint_t, crypto_object_attribute_t *, uint_t,
            crypto_object_attribute_t *, uint_t, crypto_req_handle_t);

        int (*nostore_key_derive)(crypto_provider_handle_t, crypto_session_id_t,
            crypto_mechanism_t *, crypto_key_t *, crypto_object_attribute_t *,
            uint_t, crypto_object_attribute_t *, uint_t, crypto_req_handle_t);

4.1.1 Compatibility

       The SPI interface was introduced by PSARC 2001/553. PSARC 2005/576
       changed the interface version from 1 to 2. The kernel kcf module will
       remain backwards compatible with version 1 and 2 providers.

4.2 Bug/RFE Number(s): 6339802, 6462782, 6462780

4.5 Exported Interfaces:

+--------------------------------+---------------------------+--------------+
|   Interface                    |  Classification           | Comments     |
+--------------------------------+---------------------------+--------------+
|   impl.h                       |  Consolidation            | include file |
|                                |  Private                  |              |
|                                |                           |              |
|   ioctl.h                      |  Project Private          | include file |
|                                |                           |              |
|   ops_impl.h                   |  Consolidation            | include file |
|                                |  Private                  |              |
|                                |                           |              |
|   spi.h                        |  Consolidation            | include file |
|                                |  Private                  |              |
|                                |                           |              |
|   ncp.h                        |  Consolidation            | include file |
|                                |  Private                  |              |
+--------------------------------+---------------------------+--------------+