rsaref.txt

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

         their lengths in encryptedKeyLens. (Note that each
         encryptedKeys member should be a pointer, initialized by
         the application.)
         
The encryptedKeyLens members will not be greater than
MAX_ENCRYPTED_KEY_LEN.

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

randomStruct must have been seeded.

Return value:      0     success
RE_ENCRYPTION_ALGORITHM  encryptionAlgorithm is invalid
       RE_PUBLIC_KEY     publicKey cannot encrypt data encryption
                           key
      RE_NEED_RANDOM     randomStruct is not seeded


R_SealUpdate

int R_SealUpdate (
  R_ENVELOPE_CTX *context,                               /* context */
  unsigned char *partOut,               /* next encrypted data part */
  unsigned int *partOutLen,   /* length of next encrypted data part */
  unsigned char *partIn,                          /* next data part */
  unsigned int partInLen                /* length of next data part */
);

R_SealUpdate continues a sealing operation, decrypting partIn, the
next data part, with the specified data encryption algorithm, and
returning partOut, the next encrypted data part. It may be called any
number of times.

partOutLen will always be a multiple of 8, and it will not be greater
than partInLen+7. If partInLen is a multiple of 8, then partOutLen
will be the same as partInLen.

(As a special case, if partInLen is a multiple of 24, then partOutLen
will be the same as partInLen; this is helpful when the output is to
be encoded in ASCII, since the length of each part input to
R_EncodePEMBlock should be a multiple of 3.)

Return value:      0     success


R_SealFinal

int R_SealFinal (
  R_ENVELOPE_CTX *context,                               /* context */
  unsigned char *partOut,               /* last encrypted data part */
  unsigned int *partOutLen    /* length of last encrypted data part */
);

R_SealFinal completes a sealing operation, returning partOut, the
last encrypted data part.

partOutLen will always be 8.

Return value:      0     success


3.4 Opening a digital envelope

RSAREF opens digital envelopes with three procedures: R_OpenInit,
R_OpenUpdate, and R_OpenFinal. These procedures are typically called
by message-processing applications.

An application first calls R_OpenInit, giving an integer specifying
which data encryption algorithm to apply (see Appendix D), an
initialization vector, the recipient's RSA private key, and an
encrypted data encryption key. R_OpenInit sets up a context for the
opening operation and decrypts the encrypted data encryption key with
the private key. It returns the context.

The application then calls R_OpenUpdate any number of times, giving
the context and the next encrypted data part. R_OpenUpdate decrypts
the encrypted part and returns the next recovered 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_OpenFinal,
giving the context. R_OpenFinal returns the last recovered data part.

As described for the sealing operations, an application may call
R_OpenUpdate again after R_OpenFinal to decrypt other data under the
same data encryption key and initialization vector.


R_OpenInit

int R_OpenInit (
  R_ENVELOPE_CTX *context,                                /* new context */
  int encryptionAlgorithm,                  /* data encryption algorithm */
  unsigned char *encryptedKey,          /* encrypted data encryption key */
  unsigned int encryptedKeyLen,               /* length of encrypted key */
  unsigned char iv[8],                          /* initialization vector */
  R_RSA_PRIVATE_KEY *privateKey           /* recipient's RSA private key */
);

R_OpenInit begins an "opening" operation, setting up a new context
and decrypting encryptedKey with privateKey.

iv is the initialization vector for the data encryption algorithm.
encryptionAlgorithm is the algorithm with which the data is
encrypted, and must be one of the values listed in Appendix D.

encryptedKeyLen must not be greater than MAX_ENCRYPTED_KEY_LEN.

Return value:      0     success
              RE_LEN     encryptedKeyLen out of range
RE_ENCRYPTION_ALGORITHM  encryptionAlgorithm is invalid
      RE_PRIVATE_KEY     privateKey cannot decrypt encrypted key


R_OpenUpdate

int R_OpenUpdate (
  R_ENVELOPE_CTX *context,                               /* context */
  unsigned char *partOut,               /* next recovered data part */
  unsigned int *partOutLen,   /* length of next recovered data part */
  unsigned char *partIn,                /* next encrypted data part */
  unsigned int partInLen      /* length of next encrypted data part */
);

R_OpenUpdate continues an opening operation, decrypting partIn, the
next encrypted data part, and returning partOut, the next recovered
data part. It may be called any number of times.

partOutLen will always be a multiple of 8, and it will not be greater
than partInLen+7.

Return value:      0     success


R_OpenFinal

int R_OpenFinal (
  R_ENVELOPE_CTX *context,                               /* context */
  unsigned char *partOut,               /* last recovered data part */
  unsigned int *partOutLen    /* length of last recovered data part */
);

R_SealFinal completes a sealing operation, returning partOut, the
last recovered data part.

partOutLen will not be greater than 7.

Return value:      0     success
              RE_KEY     recovered data encryption key cannot decrypt
                           encrypted data

3.5 Digesting a message

RSAREF digests messages with three procedures: R_DigestInit,
R_DigestUpdate, and R_DigestFinal. These procedures have no
particular PEM application, but may be useful in PKCS #7.

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

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

After all the parts are supplied, the application calls
R_DigestFinal, giving the context. R_DigestFinal returns the message
digest.

An application may call R_DigestUpdate again after R_DigestFinal to
digest other data, without setting up a new context.


R_DigestInit

int R_DigestInit (
  R_DIGEST_CTX *context,                             /* new context */
  int digestAlgorithm                   /* message-digest algorithm */
);

R_DigestInit begins a message-digest 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_DigestUpdate

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

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

Return value:      0     success


R_DigestFinal

int R_DigestFinal (
  R_DIGEST_CTX *context,                                 /* context */
  unsigned char *digest,                          /* message digest */
  unsigned int *digestLen               /* length of message digest */
);

R_DigestFinal completes a message-digest operation, storing the
message digest in digest and its length in bytes in digestLen.

digestLen will not be greater than MAX_DIGEST_LEN.

Return value:      0     success


4. ENCODING AND DECODING

RSAREF encodes and decodes blocks of data in printable ASCII
according to RFC 1421 with two procedures: R_EncodePEMBlock
and R_DecodePEMBlock. They are typically called by
message-processing applications to format and parse fields
of the encapsulated header of a privacy-enhanced message, as
well as the message content.

To encode a block in printable ASCII, an application calls
R_EncodePEMBlock, giving a pointer to the block and the block length.
R_EncodePEMBlock encodes the block in printable ASCII and returns the
encoded block.

To decode a block encoded in printable ASCII, an application calls
R_DecodePEMBlock, giving a pointer to the encoded block, and the
encoded block length. R_DecodePEMBlock decodes the encoded block and
returns the decoded block.

An application can process data in parts with these procedures,
provided that the length of each input part (except possibly the
last) is a multiple of the "quantum" size: three bytes for
encoding, four bytes for decoding.


R_EncodePEMBlock

int R_EncodePEMBlock (
  unsigned char *encodedBlock,                     /* encoded block */
  unsigned int *encodedBlockLen,         /* length of encoded block */
  unsigned char *block,                                    /* block */
  unsigned int blockLen                          /* length of block */
);

R_EncodePEMBlock encodes block in printable ASCII according to RFC
1421, storing the encoding in encodedBlock.

encodedBlock will be an ASCII string, encoded according to RFC 1421.
(It will not contain any line delimiters; the application must break
the string into lines.) encodedBlockLen will not be greater than
ENCODED_CONTENT_LEN(blockLen).

When processing data in parts, blockLen should be a multiple of 3,
except possibly for the last part.

Return value:      0     success
             nonzero     reserved for future compatibility


R_DecodePEMBlock

int R_DecodePEMBlock (block, blockLen, encodedBlock, encodedBlockLen)
  unsigned char *block,                                    /* block */
  unsigned int *blockLen,                        /* length of block */
  unsigned char *encodedBlock,                     /* encoded block */
  unsigned int encodedBlockLen           /* length of encoded block */
);

R_DecodePEMBlock decodes a block encoded according to RFC 1421. Its
operation is the reverse of R_EncodePEMBlock.

blockLen will not be greater than
DECODED_CONTENT_LEN(encodedBlockLen).

When processing data in parts, encodedBlockLen should be a multiple
of 4, except possibly for the last part.

Return value:      0     success
         RE_ENCODING     encodedBlock has RFC 1421 encoding error


5. KEY-PAIR GENERATION

RSAREF generates key pairs with the procedure R_GeneratePEMKeys.
R_GeneratePEMKeys is typically called by key generation applications.
To generate a new key pair, an application calls R_GeneratePEMKeys,
giving the length in bits of the modulus, the choice of public
exponent (3 or 65537), and a random structure. R_GeneratePEMKeys
generates an RSA key pair and returns the public and private keys.


R_GeneratePEMKeys

int R_GeneratePEMKeys (
  R_RSA_PUBLIC_KEY *publicKey,                /* new RSA public key */
  R_RSA_PRIVATE_KEY *privateKey,             /* new RSA private key */
  R_RSA_PROTO_KEY *protoKey,                   /* RSA prototype key */
  R_RANDOM_STRUCT *randomStruct                 /* random structure */
);

R_GeneratePEMKeys generates a random RSA key pair, storing the
resulting RSA public key in publicKey and the resulting RSA private
key in privateKey.

Other parameters are as follows:

            protoKey     The RSA prototype key specifying the length
                           in bits of the RSA modulus and the public
                           exponent. (See Appendix B.)

        randomStruct     Random structure from which the key pair is
                           derived. It must have been seeded.

Return value:      0     success
      RE_MODULUS_LEN     modulus length invalid
      RE_NEED_RANDOM     randomStruct is not seeded


6. DIFFIE-HELLMAN KEY AGREEMENT

To generate new Diffie-Hellman parameters, an application calls
R_GenerateDHParams, giving the length in bits of the Diffie-Hellman
prime and a random structure. R_GenerateDHParams generates the
parameters. Several users may share given Diffie-Hellman parameters,
or they may be unique to a given user.

To set up a key agreement, communicating applications call
R_SetupDHAgreement, giving these parameters:

  -  the Diffie-Hellman parameters
  -  a random structure

R_SetupDHAgreement generates a new "public value" and a new "private
value" for each party. The applications then exchange their public
values.

To compute the agreed-upon key, the applications call
R_ComputeDHAgreedKey, giving these parameters:

  -  the Diffie-Hellman parameters
  -  the other party's public value
  -  the private value

R_ComputeDHAgreedKey computes the agreed-upon key.

The applications may encrypt subsequent data with the agreed-upon
key. When the length of the Diffie-Hellman prime is large enough, it
is considered impractical for someone who sees the Diffie-Hellman
parameters and the exchanged public values to determine to
agreed-upon key, so the subsequent encryption is secure.


R_GenerateDHParams

int R_GenerateDHParams (
  R_DH_PARAMS *params,             /* new Diffie-Hellman parameters */
  unsigned int primeBits,               /* length in bits of prime  */
  unsigned int subPrimeBits,         /* length in bits of subprime  */
  R_RANDOM_STRUCT *randomStruct                 /* random structure */
);

R_GenerateDHParams generates random Diffie-Hellman parameters,
storing the result in params. primeBits specifies the length in bits
of the Diffie-Hellman prime p, and subPrimeBits specifies the length
in bits of the prime q that divides p-1. The resulting generator g
has order q.

The resulting params->primeLen and params->generatorLen will be at
most DH_PRIME_LEN (bits); params->prime and params->generator should
point to arrays at least that long.

randomStruct must have been seeded.

Return value:      0     success
      RE_MODULUS_LEN     prime length invalid
      RE_NEED_RANDOM     randomStruct is not seeded


R_SetupDHAgreement

int R_SetupDHAgreement (
  unsigned char *publicValue,                   /* new public value */
  unsigned char *privateValue,                 /* new private value */
  unsigned int privateValueLen,          /* length of private value */
  R_DH_PARAMS *params,                 /* Diffie-Hellman parameters */
  R_RANDOM_STRUCT *randomStruct                 /* random structure */
);

R_SetupDHAgreement sets up a Diffie-Hellman key agreement by