rfc2628.txt

RFC 的详细文档！

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
         is impossible 0 value must be indicated. If the signature
         consists of several values then the total length is indicated.

      milen - is not used.

   For data compression algorithms (CRYPTO_TYPE_COMPRESS):

      blocklen - see outlen.

      keylen - is not used.

      outlen - if the algorithm provides the fixed compression with
         known value then it is indicated as blocklen/outlen ratio. The
         values can be arbitrary. If the compression value is not known
         then outlen is set to 0 and blocklen is not used.

      milen - is not used.

   For data uncompressing algorithms (CRYPTO_TYPE_UNCOMPRESS):

      blocklen - see outlen.

      keylen - is not used.





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


      outlen - if the algorithm provides the fixed compression with
         known value then it is indicated as blocklen/outlen ratio. The
         values can be arbitrary. It is natural that the ratio will be
         reverse to the similar value for the same algorithm but of
         CRYPTO_TYPE_COMPRESS type. If the compression value is not
         known then outlen is set to 0 and blocklen is not used.

      milen - is not used.

   For one-way hash function algorithms (CRYPTO_TYPE_HASH):

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

      keylen - is not used.

      outlen - resulting hash value length in bytes.

      milen - is not used.

   For random number generation algorithms (CRYPTO_TYPE_RANDOM):

      blocklen - is not used.

      keylen - initial seed length (0 - if not required, for example in
         a physical effects based generators).

      outlen - resulting random number length in bytes (0 - arbitrary)

      milen - is not used.

3.2. Cryptoplugin Deinitialization Function

   /* Plugin deinitialization */
   CRYPTO_STATUS   CryptoPluginFini(void);

   The function is called before the cryptoplugin operation is to be
   terminated. Function execution causes closing of all open
   cryptographic contexts, system resources deallocation and hardware
   deinitialization.  The value returned is informational only.

   Return codes for the function:

      CRYPTO_OK - cryptoplugin is deinitialized successfully.

      CRYPTO_ERR_GENERAL - internal error.




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


      CRYPTO_ERR_UNCLOSED_HANDLES - warning that there were open
         cryptographic contexts during cryptoplugin deinitialization.
         The warning is informational only. The open contexts are
         destroyed anyway.

3.3. Cryptographic Context Opening Function

   New algorithm instance (cipher state) */
   CRYPTO_STATUS   CryptoOpen(

         CRYPTO_HANDLE   *state, /* Pointer to cipher state
                                    handle (filled on exit) */
         long            algnum, /* Algorithm number in
                                    CryptoPluginInfo structure */
         const char      *key);  /* key (in plain) */

   The function creates cryptographic context copy inside cryptoplugin
   and initializes it with the provided key. Later the handle of the
   context is used in calls of other algorithm functions.

   Description of parameters:

      state - pointer to the variable that will be set to the handle of
         the context created if succeeded. NULL parameter value should
         result in the CRYPTO_ERR_BAD_PARAMS code returned by the
         function.

      algnum - algorithm number in the cryptoplugin. It is equal to the
         number of CryptoAlgInfo structure (that describes the
         algorithm) in CryptoPluginInfo structure. The number begins
         with zero value. It should be taken into account that it is not
         an algorithm identifier but its number in the cryptoplugin.

      key - pointer to the key (if it is required) or to the seed (for
         random number generation algorithm).

Notes.

   1. Generated cryptographic context is stored inside the cryptoplugin
      until it will be destroyed by the CryptoAlgClose function call.
      The maximum number of cryptographic contexts supported by
      cryptoplugin can be indicated in algorithm parameters description.
      If maximum number of cryptographic contexts equals to zero then
      the cryptographic contexts number is either unlimited (for
      example, for stateless algorithms like random number generators
      and one-way hash functions) or it is limited by external factors
      only (like memory size).




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


      Return codes for the function:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      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.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters (invalid algorithm
         number, zero pointer to the handle or to key (seed) if it is
      required.

3.4. Cryptographic Context Reopening Function

/* Reinitialize algorithm instance */
CRYPTO_STATUS   CryptoReOpen(
                CRYPTO_HANDLE   state, /* current cipher state handle */
                const char      *key);  /* key (in plain) */

   The function reinitializes an existing context. This function is used
   for key change without new system resources allocation. The function
   parameters are handle of opened earlier context and pointer to a new
   key.

   Return codes for the function:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

      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 may release system memory and try function
         call once more.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters (invalid algorithm
         number, zero pointer to the handle or to key (seed) if it is
         required.



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


3.5. Cryptographic Context Closing Function

/* Destroy algorithm instance */
CRYPTO_STATUS   CryptoClose(
                CRYPTO_HANDLE   state); /* Handle of cipher state */

   The function provides cryptographic context destruction. The
   cryptographic context handle is its parameter. The value returned is
   informational only.

   Return codes for the function:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

3.6. Key Verification Function

      /* Check key for possible weakness */
      CRYPTO_STATUS   CryptoCheckForWeakKey(
                    long            algnum, /* Algorithm number in
                                    CryptoPluginInfo structure */
                    const char      *key);  /* Proposed key */

   The function verifies key material whether it is weak (from the
   algorithm's point of view). The function is actual for
   encryption/decryption or signing/verification algorithms only.
   Algorithm number (similar to CryptoAlgOpen) and pointer to the key to
   be verified are the parameters.

   Return codes for the function:

      CRYPTO_O - the key has passed the test.

      CRYPTO_ERR_WEAK_KEY - the key has not passed the test (being weak
         or possibly weak).

      CRYPTO_ERR_NOT_SUPPORTED - is not supported.

      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 12]