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.









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


      group - algorithm implementation group (variants algorithm
         implementations with various parameters not covered by
         CryptoAlgInfo structure). Values in the range of 0..32767 are
         well-known numbers defined in Appendix A; vendors may
         arbitrarily use values in the range of 32768..65535.

      type - algorithm type (CRYPTO_TYPE_XXX). Unambiguously determines
         algorithm application.

      version - version of algorithm implementation (CRYPTO_VER
         (maj,min)).

      flags - flags that characterize the algorithm and its
         implementation. All bits, that are not defined in Appendix A,
         must be zeroed.

      maxcontexts - maximum cryptographic contexts number that are
         simultaneously supported by the algorithm implementation (0 if
         the number is unlimited or is limited only by environmental
         conditions like memory size).

      name - text algorithm name (ASCII characters use only; all unused
         bytes must be set to 0).

   The next information depends on algorithm type:

   For encryption algorithms (CRYPTO_TYPE_ENCRYPT and
   CRYPTO_TYPE_DECRYPT):

      blocklen - data block length in bytes (value 1 must be used for
         stream cipher algorithms).

      keylen - encrypting (or decrypting) key length in bytes.

      outlen - output data size for conversion of one input data block
         in bytes. Usually it is equal to blocklen. When prediction of
         this value is impossible zero value must be indicated.

      milen - size of initialization vector (for block algorithms) or
         message indicator (for stream algorithms) in bytes. For block
         algorithms zero value of the parameter means that the algorithm
         implements ECB encoding. Non-zero milen parameter means that
         the algorithm implements CBC encoding. For stream algorithms
         zero value of the parameter means that the message indicator is
         not required.






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


   For signature algorithms (CRYPTO_TYPE_SIGN):

      blocklen - block size in bytes. The length of input signature data
         will be padded up to this value. When there is no need in
         padding the value of 1 must be set.

      keylen - private key length in bytes.

      outlen - signature length in bytes. When prediction of this value
         is impossible 0 value must be indicated. If the signature
         consists of several values then the total length is indicated.

      milen - non-zero value specifies signature parameter length
         (random number), zero value indicates that the parameter is not
         required.

   For signature verification algorithms (CRYPTO_TYPE_VERIFY):

      blocklen - is not used.

      keylen - length of public key in bytes.

      outlen - signature length in bytes. When prediction of this value