rfc2628.txt

RFC 的详细文档！

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

   Security issues are addressed throughout this memo.

6. References

   [Schneier] Bruce Schneier, Applied Cryptography - Protocols,
              Algorithms, and Source Code in C (Second Edition), John
              Wiley & Sons, Inc., 1996.

   [IPsec]    Kent, S. and R. Atkinson, "Security Architecture for the
              Internet Protocol", RFC 2401, November 1998.

   [ISAKMP]   Maughhan, D., Schertler, M. Schneider, M. and J. Turner,
              "Internet Security Association and Key Management Protocol
              (ISAKMP)", RFC 2408, November 1998.

   [IKE]      Harkins, D. and D. Carrel, "The Internet Key Exchange
              (IKE)", RFC 2409, November 1998.

   [TLS]      Dierks, T. and C. Allen, "The TLS protocol Version 1.0",
              RFC 2246, January 1999.






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


7. Author's Address

   Valery Smyslov
   TWS
   Centralny prospekt, 11,
   Moscow, Russia

   Phone: [phone]
   Fax:   [phone]
   EMail: [e-mail]









































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