rfc2628.txt

RFC 的详细文档！

Network Working Group                                         V. Smyslov
Request for Comments: 2628                                           TWS
Category: Informational                                        June 1999


          Simple Cryptographic Program Interface (Crypto API)

Status of this Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1999).  All Rights Reserved.

Abstract

   This document describes a simple Application Program Interface to
   cryptographic functions. The main purpose of such an interface is to
   separate cryptographic libraries from internet applications, thus
   allowing an independent development of both. It can be used in
   various internet applications such as [IPsec], [ISAKMP], [IKE],
   [TLS].

Table of Contents

   1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . .  2
   1.1. Summary . . . . . . . . . . . . . . . . . . . . . . . . . . .  2
   1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . .  2
   1.3. Objectives of Development . . . . . . . . . . . . . . . . . .  3
   2. Cryptoplugin Structure. . . . . . . . . . . . . . . . . . . . .  3
   3. Program Interface . . . . . . . . . . . . . . . . . . . . . . .  4
   3.1. Cryptoplugin Initialization Function. . . . . . . . . . . . .  4
   3.1.1. Description of CryptoPluginInfo structure . . . . . . . . .  6
   3.1.2. Description of CryptoAlgInfo structure. . . . . . . . . . .  6
   3.2. Cryptoplugin Deinitialization Function. . . . . . . . . . . .  9
   3.3. Cryptographic Context Opening Function. . . . . . . . . . . . 10
   3.4. Cryptographic Context Reopening Function. . . . . . . . . . . 11
   3.5. Cryptographic Context Closing Function. . . . . . . . . . . . 12
   3.6. Key Verification Function . . . . . . . . . . . . . . . . . . 12
   3.7. Data Transformation Function. . . . . . . . . . . . . . . . . 13
   3.7.1. For CRYPTO_TYPE_ENCRYPT Algorithm Type. . . . . . . . . . . 13
   3.7.2. For CRYPTO_TYPE_DECRYPT Algorithm Type. . . . . . . . . . . 14
   3.7.3. For CRYPTO_TYPE_SIGN Algorithm Type . . . . . . . . . . . . 15
   3.7.4. For CRYPTO_TYPE_VERIFY Algorithm Type . . . . . . . . . . . 17
   3.7.5. For CRYPTO_TYPE_COMPRESS Algorithm Type . . . . . . . . . . 18



Smyslov                      Informational                      [Page 1]

RFC 2628                       Crypto API                      June 1999


   3.7.6. For CRYPTO_TYPE_UNCOMPRESS Algorithm Type . . . . . . . . . 18
   3.7.7. For CRYPTO_TYPE_HASH Algorithm Type . . . . . . . . . . . . 19
   3.7.8. For CRYPTO_TYPE_RANDOM Algorithm Type.  . . . . . . . . . . 21
   3.8. Cryptographic Context Control Function. . . . . . . . . . . . 22
   4. Cryptoplugin Registration Procedure . . . . . . . . . . . . . . 23
   5. Security Considerations . . . . . . . . . . . . . . . . . . . . 23
   6. References. . . . . . . . . . . . . . . . . . . . . . . . . . . 23
   7. Author's Address  . . . . . . . . . . . . . . . . . . . . . . . 24
   Appendix A. The interface specification as a C header file . . . . 25
   Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 30

1. Introduction

1.1. Summary

   Nowadays internet applications that require cryptographic functions
   at the level of operating system kernel, use the method that assumes
   the libraries must be compiled/linked together with the module
   (driver) which provides product functionality. For the sake of
   possibility of independent development of the cryptographic modules
   and in order to provide a simple, effective and universal (suitable
   for application and as well kernel level of operating system)
   solution this specification offers the method to extract encrypting
   algorithms to the separate cryptographic modules.

   This document describes simple open interface (Crypto API) to
   external cryptographic libraries optimized both for the application
   and kernel level of the operating system.

1.2. Terminology

   Cryptoplugin

      Operation system unit (driver, shared library, module) that
      provides cryptographic functions via well-defined (but OS-
      specific) interface.

   Cryptolibrary

      Part of cryptoplugin that provides its cryptographic functionality
      via Crypto API.

   Wrapper

      Part of cryptoplugin that provides interfaces translation between
      Crypto API and OS-specific interface.





Smyslov                      Informational                      [Page 2]

RFC 2628                       Crypto API                      June 1999


   Definition of all cryptography related terms can be found in
   [Schneier].

1.3. Objectives of Development

   The objectives of Simple CryptoAPI development are as follows:

      1) To extract program implementations of encryption, one-way hash
         function, digital signature and random numbers generation
         algorithms to separate, independently developed modules.

      2) To provide version independence between using encryption
         modules and external cryptoplugin.

      3) To ensure platform independent developments of encrypting
         algorithm modules with portable source code.

      4) To enable independent development of modules and compatibility
         of modules developed independently.

2. Cryptoplugin Structure

   In order to provide fast exchange between the cryptoplugin and its
   client the cryptoplugin is implemented as a separate driver (or
   module) of the particular operating system (Fig.1). Cryptoplugin
   consists of two parts (Fig.2):

      1) cryptolibrary itself (1)

      2) system-dependent module (wrapper) for interaction between
         cryptolibrary and its client (2)

                                       Cryptoplugin initialization
                                     / by the operating system
                                     |
                                     |
     +------------------+          +-|-+-------------+
     |                  |          |   |             |
     |  Cryptoplugin's  | -------> |                 |
     |                  |          |  Cryptoplugin   |
     |     client       | <------- |                 |
     |                  |          |   |             |
     +------------------+     |    +---+-------------+
                              |
                              \
                               \ System-dependent CPI

    Fig. 1  Interaction between cryptoplugin and its client



Smyslov                      Informational                      [Page 3]

RFC 2628                       Crypto API                      June 1999


     +---------------+-------------------------------+
     |               |                               |
     |              -->       Submodule of           |
     |  Submodule -  |                               |
     |               |   encrypting algorithms (1)   |
     |  wrapper (2)  |                               |
     |              <--       (cryptolibrary)        |
     |               |                               |
     +---------------+-------------------------------+
                     |
                     \
                      \ Cryptographic Program Interface

                Fig. 2  Cryptoplugin structure

   The system-dependent module (wrapper) is delivered by the driver-
   client developer in the form of source code or in the form of
   libraries (for example, in the form of object files) for particular
   operating system.  The wrapper is intended for translation of
   system-independent application interface to the particular system-
   dependent interface with the cryptoplugin's client. The wrapper
   context does not include components specific to cryptoplugin's client
   functionality or to some cryptographic algorithm. The interface
   described in section 3 is the standard for interaction between the
   submodules (1) and (2).

   A cryptoplugin can contain a number of different algorithms.
   Moreover, it can contain some different implementations of one
   particular algorithm.

3. Program Interface

   The CPI (Cryptographic Program Interface) consists of a set of
   functions exported by encrypting algorithm submodule (cryptolibrary).
   The interface functions are described below (see also Appendix A).

3.1. Cryptoplugin Initialization Function

   The function is intended for cryptoplugin initialization and
   obtaining information about algorithms contained in cryptoplugin. The
   function is called once before the beginning of cryptoplugin
   operation.

   /* CryptoPlugin initialization. Returns pointer to CryptoPluginInfo
   structure on success or NULL on fatal error. */
   CryptoPluginInfo *CryptoPluginInit(
                   void            *param);/* Ptr to OS parameters
                                              (platform-specific) */



Smyslov                      Informational                      [Page 4]

RFC 2628                       Crypto API                      June 1999


   Description of parameters:

      param - pointer to system-dependent parameters transmitted to
         cryptoplugin by the operating system. Intention and format of
         parameters are specific to each operating system and should be
         described in documentation on the cryptoplugin wrapper.

   The function is called at the moment of cryptoplugin initialization.
   If succeeded it returns the pointer to CryptoPluginInfo structure
   that describes the module and algorithms implemented in the
   cryptolibrary.  If function call did not succeed, function will
   return NULL or appropriate error code in CryptoPluginInfo structure
   status field. If the initialization is partially succeeded then the
   cryptoplugin either returns CryptoPluginInfo structure transformed so
   that it contains only successfully initialized algorithms or returns
   appropriate error code in status field of CryptoAlgInfo structures
   that describes the reason for the failure.

   Error codes for the function:

      NULL - fatal unsuccessful cryptoplugin initialization. The module
         is unable even to indicate the reason of failure.

   The pointer to cryptoplugin description structure in the case of full
   or partial success. The status fields in CryptoPluginInfo structure
   and in comprised CryptoAlgInfo structures can be set to the following
   values:

      CRYPTO_OK - cryptoplugin (algorithm) is initialized successfully.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_NOT_SUPPORTED - (only for algorithm) - the algorithm
         is not supported by the module at the moment.

      CRYPTO_ERR_HARDWARE - error of hardware initialization.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general
         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in position
         to) and try to call the function once again.








Smyslov                      Informational                      [Page 5]

RFC 2628                       Crypto API                      June 1999


3.1.1. Description of CryptoPluginInfo structure

   The CryptoPluginInfo structure consists of header of fixed size that
   generally describes cryptoplugin and array of CryptoAlgInfo
   structures following the header. Each structure describes particular
   algorithm implemented in the cryptolibrary (see Appendix A)

   Structure fields description:

      cpi_version -  CPI version (should be CRYPTO_VER (1,0)). CPI
         version determines both functions set and fields layout in
         CryptoPluginInfo/CryptoAlgInfo structures.

      status - returns the error code if cryptoplugin initialization
         failed (otherwise should be CRYPTO_OK)

      name - text cryptoplugin description (ASCII-7 characters only; all
         unused bytes must be set to 0).

      version - cryptoplugin version (CRYPTO_VER(maj,min)).

      flags - various flags that characterize the cryptoplugin.

      number_of_algs - number of algorithms the cryptolibrary comprises
         of (i.e. the number of consequent CryptoAlgInfo structures).

3.1.2. Description of CryptoAlgInfo structure

   Structure fields description

      status - returns the error code if particular algorithm
         initialization failed (otherwise should be CRYPTO_OK).

      id - algorithm identifier (CRYPTO_A_XXX). Values in the range of
         0..249 are reserved; Values in the range of 250..32767 indicate
         algorithms not enrolled in standard list. It should be
         emphasized that algorithm IDs are independent for each
         algorithm type. But it is considered that pairs of types
         CRYPTO_TYPE_ENCRYPT and CRYPTO_TYPE_DECRYPT, CRYPTO_TYPE_SIGN
         and CRYPTO_TYPE_VERIFY, CRYPTO_TYPE_COMPRESS and
         CRYPTO_TYPE_UNCOMPRESS are equivalent because they define
         reverse actions of the same nature.