rfc2628.txt

RFC 的详细文档！

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


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

   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 sign 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 - pointer to signature parameter (random number usually) if
      milen parameter in algorithm description is non-zero. In
      this case zero mi parameter indicates that the parameter
      should be chosen (generated) inside the algorithm. If
      milen parameter in algorithm description is set to zero
      then mi parameter is 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.




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


      CRYPTO_ERR_BAD_PARAMS - invalid parameters.

3.7.4. For CRYPTO_TYPE_VERIFY Algorithm Type:

   The function verifies input data signature. 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
         code error.

      inlen - input data size (in bytes). The zero parameter is allowed
         so that the function quits at once and returns CRYPTO_OK code.

      outbuff -pointer to the signature. If the parameter is set to NULL
         then the function returns CRYPTO_ERR_BAD_PARAMS error code. If
         the signature consists of several parts then they are combined
         to one array.

      outlen - specifies the signature length if the signature length is
         set to zero in algorithm description structure. If non-zero
         value is specified in algorithm description structure then the
         parameter is ignored. If the signature consists of several
         parts then the maximum part length multiplied by the number of
         parts is specified.

      mi - is not used.

   Returned values:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_INVALID_SIGNATURE - invalid signature.

      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.



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


3.7.5. For CRYPTO_TYPE_COMPRESS Algorithm Type:

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

      inbuff - pointer to the input data.

      inlen - input data size (in bytes). 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
         compress 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 - is not used.

   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.6. For CRYPTO_TYPE_UNCOMPRESS Algorithm Type:

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

      inbuff - pointer to the input data.




Smyslov                      Informational                     [Page 18]