Template Version: @(#)sac_nextcase %I% %G% SMI 1. Introduction 1.1. Project/Component Working Name: Crypto Context sharing between providers 1.2. Name of Document Author/Supplier: Author: Krishna Yenduri 1.3 Date of This Document: 13 February, 2007 4. Technical Description Title: Crypto Context sharing between providers 1. Overview This document describes changes to the Solaris Kernel Cryptographic SPI to support operation context sharing for improved performance. The Interface taxonomy is Consolidation Private. The Release taxonomy is Patch/Micro. Diff-marked draft manpages, and header files are included in the case directory. 2. Problem Many ciphers are faster to do in software for small data sizes. Doing them in hardware degrades performance instead of helping. Currently, the Solaris kernel crypto framework (kCF) checks that the input data size for a crypto operation is above a certain mechanism specific threshold before it will use a hardware provider. This check is possible only for atomic kernel API like crypto_encrypt() that do not keep any context across calls. But, there are many applications which do multi-part requests that require that context be kept across calls. Also, stream ciphers like RC4 are usable only with multi-part API in SSL. Currently, these applications that do multi-part API suffer from degraded performance for smaller data sizes as they will always use the hardware provider for each part of the multi-part API. So, there is a need to address this problem. 3. Solution The basic idea of the solution is to share the operation context between a hardware provider and a software provider and use the software provider for small data sizes and use the hardware provider otherwise. Note that a hardware provider may not be able share its operation context if the key object does not allow it. So, the solution is limited to cases where it is possible to do so. Initially, we considered using the existing PKCS #11 API C_GetOperationState/C_SetOperationState for this purpose. But, these API add overhead for each part of the multi-part API. Also, they are not intended to be usable across multiple providers. So, we extended the existing service provider interface (SPI) to enable the sharing of the operation context with little overhead. We discuss the details below. 3.3 SPI changes 3.3.1. cm_mech_flags field A provider that can support sharing of context needs to set CRYPTO_CAN_SHARE_OPSTATE bit flag in the cm_mech_flags field of crypto_mech_info_t structure. The existing field, cm_keysize_unit, in the crypto_mech_info_t structure is an uint32_t and it currently has only two bit flags defined. We rename this field to cm_mech_flags and maintain cm_keysize_unit as an alias for cm_mech_flags so that older providers continue to compile. The advantage with using an existing field rather than adding a new field is that we avoid having two versions of this structure that will add unnecessary complexity to kCF to maintain binary compatibility for older providers. 3.3.2. Format of the shared context The mechanism specific context that is shared between kCF and the provider is part of the SPI. Initially, we define the context for only the RC4 mechanism. typedef struct { uchar_t arr[256]; uchar_t i, j; uint64_t pad; /* For 64-bit alignment */ } arcfour_state_t; We will be adding definitions for other bulk ciphers as needed. 3.3.3. Changes to crypto_ctx_t structure Two new fields are added to crypto_ctx_t structure + uint32_t cc_flags; /* flags */ + void *cc_opstate; /* state */ } crypto_ctx_t; + /* Values for cc_flags field */ + #define CRYPTO_INIT_OPSTATE 0x00000001 /* allocate and init cc_opstate */ + #define CRYPTO_USE_OPSTATE 0x00000002 /* .. start using it as context */ + The new fields are added to the end of the crypto_ctx_t structure. So, a old provider continues to work. Note that a provider should never need to allocate this structure since it is allocated by kCF and is passed to the provider. 3.3.4. Provider responsibilities A provider that sets CRYPTO_CAN_SHARE_OPSTATE flag needs to check the cc_flags field of crypto_ctx_t argument a. if routine is init entry point (e.g. encrypt_init()) check for CRYPTO_INIT_OPSTATE flag. If flag is set and the configuration/key material permits sharing . allocate the mechanism specific context defined by kCF . Initialize the mechanism specific context . set CRYPTO_USE_OPSTATE flag in cc_flags field . set cc_opstate field to the context A provider can refuse sharing by NOT setting the CRYPTO_USE_OPSTATE flag. For example, a provider needs to do this if the key can not leave the hardware keystore. In this case, it should leave cc_opstate field alone. b. if routine is update entry point (e.g. encrypt_update()) check for CRYPTO_USE_OPSTATE flag. If flag is set, use/update mechanism specific context pointed to by cc_opstate c. A provider frees up cc_opstate at the same time it frees up cc_provider_private. So, a provider is in charge of both allocation and freeing cc_opstate. 3.3.5. Changes to existing providers KCF providers in ON consolidation are modified to use the updated interfaces. These include the software provider, arcfour, and the hardware provider, n2cp. 4. Bug/RFE Number(s): 6494834 5. Exported Interfaces: +--------------------------------+---------------------------+--------------+ | Interface | Classification | Comments | +--------------------------------+---------------------------+--------------+ | crypto_mech_info_t | Consolidation | structure | | | Private | | | | | | | crypto_ctx_t | | structure | | | | | | arcfour_state_t | | structure | | | | | | | | | | spi.h | | include files | | common.h | | | | | | | +--------------------------------+---------------------------+--------------+ 6. Resources and Schedule 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: ON 6.5. ARC review type: FastTrack