rfc2628.txt

著名的RFC文档,其中有一些文档是已经翻译成中文的的.

         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]

RFC 2628                       Crypto API                      June 1999


3.7. Data Transformation Function

/* Perform CryptoTransform (depends on cipher state type) */
CRYPTO_STATUS   CryptoTransform(
                CRYPTO_HANDLE   state,  /* Cipher state */
                const char      *inbuff,/* input data */
                long            inlen,  /* input data length */
                char            *outbuff,/* output buffer */
                long            *outlen,/* On entry - output buffer
                                          length, on exit -  number of
                                          bytes written to outbuff */
                char            *mi);   /* Message indicator  */

   This is a cryptographic data transformation function. Function call
   results and function parameters are dependent on algorithm type. For
   algorithm types CRYTO_TYPE_ENCRYPT, CRYPTO_TYPE_DECRYPT,
   CRYPTO_TYPE_SIGN and CRYPTO_TYPE_VERIFY (items 3.7.1 - 3.7.4)
   function call results are history independent.

   Note. Stream encryption algorithms may seem an "exception". However
   the same cryptoalgorithm handle must hide its history dependence. For
   algorithm types CRYPTO_TYPE_COMPRESS, CRYPTO_TYPE_UNCOMPRESS and
   CRYPTO_TYPE_HASH (items 3.7.5 - 3.7.7) function calls are history
   dependent. For the CRYPTO_TYPE_RANDOM algorithm function call may be
   for different implementations either dependent or independent on the
   history.

3.7.1. For CRYPTO_TYPE_ENCRYPT Algorithm Type:

      The function encrypts input data. Its parameters are intended for:

      inbuff - pointer to the input data. If this parameter is equal to
         NULL then the function should return the
         CRYPTO_ERR_BAD_PARAMS error code.

      inlen - input data size (in bytes). If the size indicated in
         algorithm description is divisible by blocklen then
         padding is not carried out. Otherwise the algorithm
         either caries out padding according to the algorithm
         standard or returns appropriate error code
         (CRYPTO_ERR_BAD_PARAMS). The zero parameter is allowed so
         that the function quits at once and returns CRYPTO_OK
         code.

      outbuff - output data buffer. NULL parameter value results in the
         outlen parameter setting to output buffer size required
         to encrypt the input buffer represented. In this case the
         CRYPTO_ERR_SMALL_BUFFER error should not be returned.



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


      outlen - Output buffer size is an input function parameter while
         the number of bytes written in the output buffer is the
         output parameter. Both the NULL parameter value and the
         zero value addressed result in CRYPTO_ERR_BAD_PARAMS code
         returned by the function.

      mi - message indicator. Its content depends on whether the
         block or stream algorithm is applied. In the block
         algorithm case it is set to the last block encrypted.
         When the first block is encrypted mi parameter specifies
         initial initialization vector. In the stream algorithm
         case it is set to the offset of the first byte encrypted
         in the stream. If the algorithm uses the message
         indicator and the mi parameter value is set to NULL then
         function should return CRYPTO_ERR_BAD_PARAMS. If the
         algorithm (ECB Mode encrypting as an example) does not
         apply the message indicator then NULL value of mi is
         acceptable while non-NULL value should be ignored.

   Returned values:

      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 can release system memory (if it is in
         position to) and try to call the function once again.

      CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters.

3.7.2. For CRYPTO_TYPE_DECRYPT Algorithm Type:

   The function decrypts the input data. Its parameters are intended for:

      inbuff - pointer to the input data. If the parameter is equal to
         NULL then the function should return the
         CRYPTO_ERR_BAD_PARAMS error code.

      inlen - input data size (in bytes). When the parameter is set to
         zero the function quits at once and CRYPTO_OK code is returned.



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


      outbuff - output data buffer. NULL parameter value results in the
         outlen parameter setting to output buffer size required
         to decrypt the input buffer represented. In this case the
         CRYPTO_ERR_SMALL_BUFFER error should not be returned.

      outlen - Output buffer size is an input function parameter while
         the number of bytes written in the output buffer is the
         output parameter. Both the NULL parameter value and the
         zero value addressed result in CRYPTO_ERR_BAD_PARAMS code
         returned by the function.

      mi - message indicator. The content depends on whether the
         block or stream algorithm is applied. In the block
         algorithm case it is set to the last block encrypted.
         When the first block is decrypted mi specifies initial
         initialization vector. In the stream algorithm case it is
         set to the offset of the first byte decrypted in the
         stream. If the algorithm uses the message indicator and
         the mi parameter is set to NULL then function should
         return CRYPTO_ERR_BAD_PARAMS. If the algorithm (ECB Mode
         as an example) does not apply the message indicator then
         NULL value of mi is acceptable while non-NULL value
         should be ignored.

   Returned values:

      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 can release system memory (if it is in
         position to) and try to call the function once again.

      CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters.

3.7.3. For CRYPTO_TYPE_SIGN Type Algorithm:

   The function signs the input data. Its parameters are intended for:





Smyslov                      Informational                     [Page 15]