rsaref.txt

私家珍藏的RSA Laborary有关加密的函数库

      RE_PRIVATE_KEY     privateKey cannot decrypt encrypted key
              RE_KEY     recovered DES key cannot decrypt encrypted
                           content or encrypted signature
 RE_DIGEST_ALGORITHM     digestAlgorithm is invalid
        RE_SIGNATURE     signature on content is incorrect


R_DigestBlock

int R_DigestBlock (
  unsigned char *digest,                          /* message digest */
  unsigned int *digestLen,              /* length of message digest */ 
  unsigned char *content,                                /* content */
  unsigned int contentLen,                     /* length of content */
  int digestAlgorithm                   /* message-digest algorithm */
);

R_DigestBlock computes the message digest of content, storing the
resulting message digest in digest and its length in bytes in
digestLen.

digestAlgorithm is the algorithm with which the content is digested,
and must be one of the values in Appendix D.

digestLen will not be greater than MAX_DIGEST_LEN.

Return value:       0    success
  RE_DIGEST_ALGORITHM    digestAlgorithm is invalid


8. RUN-TIME LIBRARY

RSAREF operates on memory blocks with three platform-specific library
procedures that are modeled after conventional C library functions:

             R_memcmp    compares two blocks of memory
             R_memcpy    copies a block of memory
             R_memset    sets a block of memory to a given value

These procedures can be found in the file 'r_stdlib.c'.


R_memcmp

int R_memcmp (
  POINTER firstBlock,                                /* first block */
  POINTER secondBlock,                              /* second block */
  unsigned int len                              /* length of blocks */
);

R_memcmp compares the first len bytes of firstBlock and secondBlock.
The value of len can be zero, in which case firstBlock and secondBlock
are undefined and R_memcmp returns 0. R_memcmp compares the blocks by
scanning the blocks from lowest address to highest until a difference
is found. The smaller-valued block is the one with the smaller-valued
byte at the point of difference. If no difference is found, the
blocks are equal.

Return value:     < 0    firstBlock is smaller
                  0      blocks are equal
                  > 0    firstBlock is larger


R_memcpy

void R_memcpy (
  POINTER output,                                   /* output block */
  POINTER input,                                     /* input block */
  unsigned int len                              /* length of blocks */
);

R_memcpy copies the first len bytes of input to output. The value of
len can be zero, in which output and input are undefined. The blocks
do not overlap.

No return value.


R_memset

void R_memset (
  POINTER output,                                   /* output block */
  int value,                                               /* value */
  unsigned int len                               /* length of block */
);

R_memset sets the first len bytes of output to value. The value of
len is zero, in which case output is undefined.

No return value.


APPENDIX A: RSAREF ERROR TYPES

This appendix lists RSAREF's error types.

             RE_DATA     other party's private value out of range

 RE_CONTENT_ENCODING     content, encrypted content, or encoded block
                           has RFC 1421 encoding error

 RE_DIGEST_ALGORITHM     message-digest algorithm is invalid

         RE_ENCODING     encoded block has RFC 1421 encoding error

RE_ENCRYPTION_ALGORITHM  encryption algorithm is invalid

              RE_KEY     recovered DES key cannot decrypt encrypted
                           content or encrypted signature

     RE_KEY_ENCODING     encrypted key has RFC 1421 encoding error

              RE_LEN     encrypted key length or signature length
                           out of range

      RE_MODULUS_LEN     modulus length out of range

      RE_NEED_RANDOM     random structure is not seeded

      RE_PRIVATE_KEY     private key cannot encrypt message digest,
                           or cannot decrypt encrypted key

       RE_PUBLIC_KEY     public key cannot encrypt data encryption
                           key, or cannot decrypt signature

        RE_SIGNATURE     signature on content or block is incorrect

RE_SIGNATURE_ENCODING    signature or encrypted signature has RFC 1421
                           encoding error


APPENDIX B: RSAREF TYPES

This appendix lists four RSAREF types: R_RSA_PUBLIC_KEY,
R_RSA_PRIVATE_KEY, R_RSA_PROTO_KEY, and R_DH_PARAMS.


R_RSA_PUBLIC_KEY

typedef struct {
  unsigned int bits;                   /* length in bits of modulus */
  unsigned char modulus[MAX_RSA_MODULUS_LEN];            /* modulus */
  unsigned char exponent[MAX_RSA_MODULUS_LEN];   /* public exponent */
} R_RSA_PUBLIC_KEY;

An R_RSA_PUBLIC_KEY value is a structure specifying an RSA public key.
There are three fields:

                bits     length in bits of the modulus (not less than
                           MIN_RSA_MODULUS_BITS and not greater than
                           MAX_RSA_MODULUS_BITS)

             modulus     modulus n, represented as a
                           MAX_RSA_MODULUS_LEN-byte number, most
                           significant byte first, as many leading zero
                           bytes as necessary

            exponent     public exponent e, represented like modulus


R_RSA_PRIVATE_KEY

typedef struct {
  unsigned int bits;                   /* length in bits of modulus */
  unsigned char modulus[MAX_RSA_MODULUS_LEN];            /* modulus */
  unsigned char publicExponent[MAX_RSA_MODULUS_LEN];
                                                 /* public exponent */
  unsigned char exponent[MAX_RSA_MODULUS_LEN];  /* private exponent */
  unsigned char prime[2][MAX_RSA_PRIME_LEN];       /* prime factors */
  unsigned char primeExponent[2][MAX_RSA_PRIME_LEN];
                                               /* exponents for CRT */
  unsigned char coefficient[MAX_RSA_PRIME_LEN];  /* CRT coefficient */
} R_RSA_PRIVATE_KEY;

An R_RSA_PRIVATE_KEY value is a structure specifying an RSA private
key. There are seven fields:

                bits     length in bits of the modulus (not less than
                           MIN_RSA_MODULUS_BITS and not greater than
                           MAX_RSA_MODULUS_BITS)

             modulus     modulus n, represented as a
                           MAX_RSA_MODULUS_LEN-byte number, most
                           significant byte first, as many leading zero
                           bytes as necessary

      publicExponent     public exponent e, represented like modulus

            exponent     private exponent d, represented like modulus

               prime     prime factors p and q of modulus, each
                           represented as MAX_RSA_PRIME_LEN-byte
                           numbers, most significant byte first, as
                           many leading zero bytes as necessary, where
                           p > q

      primeExponents     exponents (d mod p-1) and (d mod q-1) for
                           Chinese remainder theorem (CRT) operations,
                           each represented like prime factors

         coefficient     coefficient (q^{-1} mod p) for Chinese
                           remainder theorem operations, represented
                           like prime factors


R_RSA_PROTO_KEY

typedef struct {
  unsigned int bits;                   /* length in bits of modulus */
  int useFermat4;                /* public exponent (1 = F4, 0 = 3) */
} R_RSA_PROTO_KEY;

An R_RSA_PROTO_KEY value is a structure specifying the length in bits
of the RSA modulus and the public exponent for key-pair generation.
There are two fields:

                bits     length in bits of the modulus (not less than
                           MIN_RSA_MODULUS_BITS and not greater than
                           MAX_RSA_MODULUS_BITS)

          useFermat4     a flag specifying the public exponent. If
                           nonzero, it specifies F4 (65537); if 0, F0
                           (3)


R_DH_PARAMS

typedef struct {
  unsigned char *prime;                                    /* prime */
  unsigned int primeLen;                         /* length of prime */
  unsigned char *generator;                            /* generator */
  unsigned int generatorLen;                 /* length of generator */
} R_DH_PARAMS;

An R_DH_PARAMS value is a structure specifying Diffie-Hellman
parameters. There are four fields:

               prime     prime p, represented as a primeLen-byte
                           number, most significant byte first, as
                           many leading zero bytes as necessary

            primeLen     length in bytes of the prime

           generator     generator g, represented like prime

        generatorLen     length in bytes of the generator


APPENDIX C: PLATFORM-SPECIFIC TYPES AND CONSTANTS

This appendix lists three platform-specific types and one #define'd
constant.


TYPES

RSAREF requires three platform-specific types: POINTER, UINT2, and
UINT4. These are defined in the file 'global.h'.


POINTER

A POINTER value is a generic pointer to memory to which any other
pointer can be cast.

Example:

    typedef unsigned char *POINTER;


UINT2

A UINT2 value is a 16-bit unsigned integer.

Example:

    typedef unsigned short int UINT2;


UINT4

A UINT4 value is a 32-bit unsigned integer.

Example:

    typedef unsigned long int UINT4;


#DEFINE'D CONSTANTS

RSAREF requires one #define'd constant: PROTOTYPES. This is defined
in the 'makefile' on the C compiler command line.

PROTOTYPES indicates the form that C function declarations are to
take. If PROTOTYPES is nonzero, declarations take the form

    type function (type, ..., type);

Otherwise declarations take the form

    type function ();


APPENDIX D: ENCRYPTION ALGORITHMS AND IDENTIFIERS

This appendix lists message-digest and data encryption algorithms and
their identifiers.


D.1 Message-digest algorithms

RSAREF supports two message-digest algorithms, listed here with their
integer identifiers:

              DA_MD2     MD2 message-digest algorithm [3]

              DA_MD5     MD5 message-digest algorithm [4]


D.2 Data encryption algorithms

RSAREF supports four data encryption algorithms, listed here with
their integer identifiers:

          EA_DES_CBC     Data Encryption Standard [5] in cipher-block
                           chaining (CBC) mode [6]

         EA_DESX_CBC     RSA Data Security's DESX enhancement of DES,
                           in CBC mode (this algorithm exclusive-ors
                           with the previous ciphertext block,
                           exclusive-ors with a secret value, encrypts
                           with DES, then exclusive-ors with a second
                           secret value)

      EA_DES_EDE3_CBC    Three-key triple-DES in CBC mode (this
                           algorithm exclusive-ORs with the previous
                           ciphertext block, encrypts with one DES
                           key, decrypts with a second DES key, then
                           encrypts with a third DES key)

      EA_DES_EDE2_CBC    Two-key triple-DES in CBC mode (like three-
                           key, except that the first and third DES
                           keys are the same)

All four algorithms have a block size of eight bytes, and hence an
eight-byte initialization vector. All employ the padding rules
described in RFC 1423 [11].


REFERENCES

[1]  R.L. Rivest, A. Shamir, and L. Adleman. A method for obtaining
     digital signatures and public-key cryptosystems. Communications
     of the ACM, 21(2):120-126, February 1978.

[2]  RSA Laboratories. PKCS #1: RSA Encryption Standard. Version 1.5,
     November 1993. (PKCS documents are available via electronic mail
     to <[e-mail]>.)

[3]  B. Kaliski. RFC 1319: The MD2 Message-Digest Algorithm. April
     1992.

[4]  R. Rivest. RFC 1321: The MD5 Message-Digest Algorithm. April
     1992.

[5]  National Bureau of Standards. FIPS Publication 46-1: Data
     Encryption Standard. January 1988.

[6]  National Bureau of Standards. FIPS Publication 81: DES Modes of
     Operation. December 1980.

[7]  W. Diffie and M.E. Hellman. New directions in cryptography. IEEE
     Transactions on Information Theory, IT-22:644-654, 1976.

[8]  RSA Laboratories. PKCS #3: Diffie-Hellman Key-Agreement Standard.
     Version 1.4, November 1993.

[9]  J. Linn. RFC 1421: Privacy Enhancement for Internet Electronic
     Mail: Part I: Message Encryption and Authentication Procedures.
     February 1993.

[10] S. Kent. RFC 1422: Privacy Enhancement for Internet Electronic
     Mail: Part II: Certificate-Based Key Management. February 1993.

[11] D. Balenson. RFC 1423: Privacy Enhancement for Internet
     Electronic Mail: Part III: Algorithms, Modes, and Identifiers.
     February 1993.

[12] B. Kaliski. RFC 1424: Privacy Enhancement for Internet Electronic
     Mail: Part IV: Key Certification and Related Services. February
     1993.

[13] RSA Laboratories. PKCS #7: Cryptographic Message Syntax Standard.
     Version 1.5, November 1993.

[14] RSA Laboratories. PKCS #10: Certification Request Syntax
     Standard. Version 1.0, November 1993.