rsaref.txt

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

                 RSAREF(TM): A Cryptographic Toolkit
                       Library Reference Manual

                           RSA Laboratories
                            March 21, 1994

                             Version 2.0

    Copyright (C) 1991-4 RSA Laboratories, a division of RSA Data
                 Security, Inc. All rights reserved.


1. INTRODUCTION

This manual is a reference guide for users of RSAREF, RSA
Laboratories' portable, educational, reference implementation of
cryptography.

RSAREF supports the following algorithms:

     o    RSA encryption and key generation [1], as defined by RSA
          Laboratories' Public-Key Cryptography Standards (PKCS) [2]

     o    MD2 and MD5 message digests [3,4]

     o    DES (Data Encryption Standard) in cipher-block chaining mode
          [5,6]

     o    Diffie-Hellman key agreement [7], as defined by PKCS #3 [8]

     o    DESX, RSA Data Security's efficient, secure DES enhancement

     o    Triple-DES, for added security with three DES operations

RSAREF is written entirely in C. Its application interface includes
the following routines:

         R_SignInit,     computes a digital signature on data of
       R_SignUpdate,       arbitrary length, processing in parts
     and R_SignFinal

       R_VerifyInit,     verifies a digital signature, processing in
     R_VerifyUpdate,       parts
   and R_VerifyFinal

         R_SealInit,     creates a digital envelope on data of
       R_SealUpdate,       arbitrary length, processing in parts
     and R_SealFinal

         R_OpenInit,     opens a digital envelope, processing in
       R_OpenUpdate,       parts
     and R_OpenFinal

       R_DigestInit,     digests data of arbitrary length, processing
     R_DigestUpdate,       in parts
   and R_DigestFinal

    R_EncodePEMBlock     encodes a message in printable ASCII
                           according to RFC 1421 [9]
    R_DecodePEMBlock     decodes a message encoded according to RFC
                           1421

   R_GeneratePEMKeys     generates an RSA public/private key pair

        R_RandomInit     initializes a random structure
      R_RandomUpdate     mixes bytes into a random structure
R_GetRandomBytesNeeded   computes the number of mix-in bytes still
                           needed to seed a random structure
       R_RandomFinal     zeroizes a random structure

  R_GenerateDHParams     generates Diffie-Hellman parameters
  R_SetupDHAgreement     sets up a key agreement
 R_ComputeDHAgreedKey    computes the agreed-upon key

An Internet Privacy-Enhanced Mail [9-12] implementation can be built
directly on top of these routines, together with message parsing and
formatting routines and certificate-management routines.
Implementations of PKCS #7 and #10 [13,14] can be built in a similar
manner. Other secure applications can be built on top of the
Diffie-Hellman routines.

The following routines are supported for backward compatibility with
RSAREF 1.0:

      R_SignPEMBlock     computes a digital signature on a message
         R_SignBlock     computes a digital signature on a block of
                           data such as a certificate
R_VerifyPEMSignature     verifies a digital signature on a message
R_VerifyBlockSignature   verifies a digital signature on a block of
                           data such as a certificate

      R_SealPEMBlock     computes a digital signature and encrypts a
                           message
      R_OpenPEMBlock     decrypts an encrypted message and verifies a
                           digital signature

       R_DigestBlock     computes the message digest of a message

This manual is divided into eight sections and three appendices.

This section introduces RSAREF. The next six sections explain RSAREF
procedures: random structures; cryptographic enhancements; printable
ASCII encoding and decoding; key-pair generation; Diffie-Hellman key
agreement; and version 1.0 routines. The last section documents the
platform-specific run-time library.

Appendix A lists RSAREF error types. Appendix B lists RSAREF types
and constants. Appendix C lists platform-specific types and
constants.


2. RANDOM STRUCTURES

A random structure contains a seed from which a pseudorandom sequence
of bytes is derived. RSAREF generates keys and pads RSA encryption
blocks with bytes derived from a random structure.

Random structures are used by both message-processing and
key-generation applications.

RSAREF sets up a random structure with the procedure R_RandomInit. A
typical application calls R_RandomInit on entry.

A new random structure is not ready for use until it is seeded by
mixing in some random bytes. RSAREF seeds a random structure with the
procedure R_RandomUpdate and R_GetRandomBytesNeeded. A random
structure is considered seeded when the number of bytes still needed
reaches zero. More bytes can be mixed in after the random structure
is seeded. A typical application calls R_GetRandomBytesNeeded and
R_RandomUpdate immediately after calling R_RandomInit.

RSAREF zeroizes a random structure with the procedure R_RandomFinal.
A typical application calls R_RandomFinal on exit.


R_RandomInit

int R_RandomInit (
  R_RANDOM_STRUCT *randomStruct             /* new random structure */
);

R_RandomInit sets up a new random structure.

Return value:      0     success
             nonzero     reserved for future compatibility


R_RandomUpdate

int R_RandomUpdate (
  R_RANDOM_STRUCT *randomStruct,                /* random structure */
  unsigned char *block,                /* block of values to mix in */
  unsigned int blockLen                          /* length of block */
);

R_RandomUpdate mixes blockLen bytes from block into randomStruct.

Return value:      0     success
             nonzero     reserved for future compatibility


R_GetRandomBytesNeeded

int R_GetRandomBytesNeeded (
  unsigned int *bytesNeeded,       /* number of mix-in bytes needed */
  R_RANDOM_STRUCT *randomStruct                 /* random structure */
);

R_GetRandomBytesNeeded computes the number of mix-in bytes still
needed to seed randomStruct, storing the result in bytesNeeded.

Return value:      0     success
             nonzero     reserved for future compatibility


R_RandomFinal

void R_RandomFinal (
  R_RANDOM_STRUCT *randomStruct                 /* random structure */
);

R_RandomFinal zeroizes randomStruct.

No return value.


3. CRYPTOGRAPHIC ENHANCEMENTS

RSAREF's cryptographic enhancements fall into five groups: signing
data; verifying signatures; sealing data in digital envelopes;
opening digital envelopes; and digesting data.

All the procedures process data in parts; it is not necessary for all
data to be stored in memory at once.


3.1 Signing data

RSAREF signs data with three procedures: R_SignInit, R_SignUpdate,
and R_SignFinal. These procedures are typically called by
message-processing applications, by key-generation applications when
constructing a PEM or PKCS certification request, and by
certification applications when signing a certificate.

An application first calls R_SignInit, giving an integer specifying
which message-digest algorithm to apply (see Appendix D). R_SignInit
sets up a context for the signature operation, and returns the
context.

The application then calls R_SignUpdate any number of times, giving
the context and the next data part. R_SignUpdate digests the part.

After all the parts are supplied, the application calls R_SignFinal,
giving the context and the signer's RSA private key. R_SignFinal
encrypts the message digest with the private key and returns the
result, which is the signature.

An application may call R_SignUpdate again after R_SignFinal to
sign other data, without setting up a new context.


R_SignInit

int R_SignInit (
  R_SIGNATURE_CTX *context,                          /* new context */
  int digestAlgorithm                   /* message-digest algorithm */
);

R_SignInit begins a signature operation, setting up a new context.

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

Return value:      0     success
 RE_DIGEST_ALGORITHM     digestAlgorithm is invalid


R_SignUpdate

int R_SignUpdate (
  R_SIGNATURE_CTX *context,                              /* context */
  unsigned char *partIn,                          /* next data part */
  unsigned char partInLen               /* length of next data part */
);

R_SignUpdate continues a signature operation, digesting partIn, the
next data part, with the specified message-digest algorithm. It may
be called any number of times.

Return value:      0     success


R_SignFinal

int R_SignFinal (
  R_SIGNATURE_CTX *context,                              /* context */
  unsigned char *signature,                            /* signature */
  unsigned int *signatureLen,                /* length of signature */
  R_RSA_PRIVATE_KEY *privateKey         /* signer's RSA private key */
);

R_SignFinal completes a signature operation, encrypting the message
digest with the signer's private key. It stores the resulting
signature in signature and its length in signatureLen.

signatureLen will not be greater than MAX_SIGNATURE_LEN.

Return value:      0     success
      RE_PRIVATE_KEY     privateKey cannot encrypt message digest


3.2 Verifying a signature

RSAREF verifies signatures with three procedures: R_VerifyInit,
R_VerifyUpdate, and R_VerifyFinal. These procedures are typically
called by message-processing applications and by certification
applications when processing a certification request.

An application first calls R_VerifyInit, giving an integer specifying
which message-digest algorithm to apply (see Appendix D).
R_VerifyInit sets up a context for the verification operation, and
returns the context.

The application then calls R_VerifyUpdate any number of times, giving
the context and the next data part. R_VerifyUpdate digests the part.

After all the parts are supplied, the application calls
R_VerifyFinal, giving the context, the signer's RSA public key, and
the signature. R_SignFinal decrypts the signature with the public key
and compares the result to the message digest to see whether the
signature is valid.

An application may call R_VerifyUpdate again after R_VerifyFinal to
verify other signatures, without setting up a new context.


R_VerifyInit

int R_VerifyInit (
  R_SIGNATURE_CTX *context,                          /* new context */
  int digestAlgorithm                   /* message-digest algorithm */
);

R_VerifyInit begins a verification operation, setting up a new
context.

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

Return value:      0     success
 RE_DIGEST_ALGORITHM     digestAlgorithm is invalid


R_VerifyUpdate

int R_VerifyUpdate (
  R_SIGNATURE_CTX *context,                              /* context */
  unsigned char *partIn,                          /* next data part */
  unsigned int partInLen                /* length of next data part */
);

R_VerifyUpdate continues a verification operation, digesting partIn,
the next data part, with the specified message-digest algorithm. It
may be called any number of times.

Return value:      0     success


R_VerifyFinal

int R_VerifyFinal (
  R_SIGNATURE_CTX *context,                              /* context */
  unsigned char *signature,                            /* signature */
  unsigned int signatureLen,                 /* length of signature */
  R_RSA_PUBLIC_KEY *publicKey            /* signer's RSA public key */
);

R_VerifyFinal completes a verification operation, decrypting the
signature with the signer's public key and comparing it to the
message digest.

signatureLen must not be greater than MAX_SIGNATURE_LEN.

Return value:      0     success
              RE_LEN     signatureLen out of range
       RE_PUBLIC_KEY     publicKey cannot decrypt signature
        RE_SIGNATURE     signature is incorrect


3.3 Sealing data in a digital envelope

RSAREF seals data in digital envelopes with three procedures:
R_SealInit, R_SealUpdate, and R_SealFinal. There may be any number of
recipients. These procedures are typically called by
message-processing applications.

An application first calls R_SealInit, giving an integer specifying
which data encryption algorithm to apply (see Appendix D), the public
key of each recipient, and a random structure. R_SealInit sets up a
context for the sealing operation, generates a data encryption key
and an initialization vector, and encrypts the data encryption key
with each recipient's public key.  It returns the context, the
initialization vector, and the encrypted data encryption keys.

The application then calls R_SealUpdate any number of times, giving
the context and the next data part. R_SealUpdate encrypts the part
and returns the next encrypted data part. (Depending on how data are
supplied, it may return more or less data than are supplied.)

After all the parts are supplied, the application calls R_SealFinal,
giving the context. R_SealFinal returns the last encrypted data part.

An application may call R_SealUpdate again after R_SealFinal to
encrypt other data under the same data encryption key and
initialization vector. This is useful when message content is signed
and encrypted, and the digital signature must also be encrypted.


R_SealInit

int R_SealInit (
  R_ENVELOPE_CTX *context,                                /* new context */
  unsigned char **encryptedKeys,                       /* encrypted keys */
  unsigned int *encryptedKeyLens,           /* lengths of encrypted keys */
  unsigned char iv[8],                          /* initialization vector */
  unsigned int publicKeyCount,                  /* number of public keys */
  R_RSA_PUBLIC_KEY **publicKeys,                          /* public keys */
  int encryptionAlgorithm,                  /* data encryption algorithm */
  R_RANDOM_STRUCT *randomStruct                      /* random structure */
);

R_SealInit begins a "sealing" operation. It performs the following
steps:

    1.   It sets up a new context.

    2.   It generates a random data encryption key and initialization
         vector, storing the initialization vector in iv.

    3.   It encrypts the data encryption key with each recipient's
         public key, storing the encrypted keys in encryptedKeys and