rfc2628.txt

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

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


      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
         decompress 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.7. For CRYPTO_TYPE_HASH Algorithm Type:

   The function calculates the hash value of the input data. Its
   parameters are intended for:

      inbuff - pointer to the input data. If the parameter is of NULL
         value then the function calculates cumulative hash value for
         the data represented (taking into account all previous data
         represented). If total length of all the data represented by
         the moment is divisible by blocklen and outbuff is non-NULL
         then it is returned to outbuff.  Nothing is written in outbuff
         when the length is not divisible by blocklen. NULL inbuff
         indicates the last conversion when the input data is padded up



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


         to the blocklen size and the result is written to outbuff
         address. The padding procedure is defined for the algorithm.

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

      outbuff - output data buffer.

      outlen - Output buffer size is an input function parameter while
         the number of bytes written in the output buffer is the output
         parameter. If intermediate conversion value (inbuff is not
         NULL) and total length of data represented by the moment are
         not divisible by blocklen then outlen is set to zero and the
         hash value is not written in outbuff. 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.














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


3.7.8. For CRYPTO_TYPE_RANDOM Algorithm Type:

   The function generates a random number. Its parameters are intended
   for:

      inbuff - pointer to the input data used for generation (when one
         of the pseudorandom algorithms is implemented). NULL parameter
         indicates absence of the input data.

      inlen - input data size (in bytes).

      outbuff - output data

      outlen - Output buffer size is an input function parameter while
         the number of bytes written in the output buffer is the output
         parameter. If zero (i.e. arbitrary) generated number size is
         set in the algorithm description then the outlen value
         determines the number of random bytes required by the calling
         procedure.

      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.











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


3.8. Cryptographic Context Control Function

/* Algorithm control */
CRYPTO_STATUS   CryptoControl(
                CRYPTO_HANDLE   state,  /* Cipher state handle */
                long            cmd,    /* Control command */
                long            param,  /* Parameter id */
                char            val,    /* Parameter value */
                long            *len);  /* For CRYPTO_GET: on entry -
                                           val buffer length, on exit -
                                           number of bytes written to
                                           val; for CRYPTO_SET: length
                                           of value to set */

   The function provides cryptographic context internal parameters
   management. It may be used to check context parameters or to change
   the context state, for example it may return information about
   cryptoalgorithm (is given context uses hardware encryption
   facilities), or it may "scroll" stream algorithms context if
   necessary, etc.

   Description of parameters:

      state - cryptographic context handle.

      cmd - command (CRYPTO_GET or CRYPTO_SET).

   param - identifier of parameter. Values in the range of 0..32767
      are assigned well-known numbers for all algorithms.
      Values in the range of 32768..65535 mean various
      variables for various algorithms (may be arbitrarily used
      by cryptolibrary developer).

   val - pointer to the data buffer.

   len - data size (in bytes).

   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



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


         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.

4. Cryptoplugin Registration Procedure

   Cryptoplugin should be linked together with the cryptoplugin wrapper
   library delivered by the cryptoplugin's client developer according to
   the rules specified by the module-client developer for each platform.
   It should result in a driver (module) of appropriate operating system
   that implements the cryptolibrary functions. The driver should be one
   of the drivers loaded during operating system boot. The procedure of
   cryptoplugin driver installation should be defined, documented, and
   automated when necessary, by the cryptoplugin developer. At the
   beginning of operation the driver-client determines cryptoplugin
   driver availability and establishes interconnection with it. Both
   module-client configuration and current security policy determine
   data conversion algorithms to be chosen.

5. Security Considerations