rsaref.txt

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

generating a public value and a private value from the Diffie-Hellman
parameters. It stores the resulting public value in publicValue and
the resulting private value in private value.

The private value is a random number x whose length in bytes is
privateValueLen, and the public value is the number y such that

                            y = g^x mod p,

where p and g are the prime and generator in params. (Typically, one
selects privateValueLen according to the length in bits of the
"subprime" q.)

publicValue and privateValue will be represented most significant
byte first, with no leading zero bytes. publicValue will have the
same length as the prime.

randomStruct must have been seeded.

Return value:      0     success
      RE_NEED_RANDOM     randomStruct is not seeded


R_ComputeDHAgreedKey

int R_ComputeDHAgreedKey (
  unsigned char *agreedKey,                  /* new agreed-upon key */
  unsigned char *otherPublicValue,          /* other's public value */
  unsigned char *privateValue,                     /* private value */
  unsigned int privateValueLen,          /* length of private value */
  R_DH_PARAMS *params                  /* Diffie-Hellman parameters */
);

R_ComputeDHAgreedKey computes an agreed-upon key from the other
party's public value, a private value, and the Diffie-Hellman
parameters. It stores the resulting agreed key in agreedKey.

The agreed key is the number z such that

                            z = (y')^x mod p,

where y' is the other party's public value, x is the private value,
and p is the prime in params.

The other party's private value y' should be between 0 and p-1.

agreedKey will be represented most significant byte first, with no
leading zero bytes. agreedKey will have the same length as the prime.

Return value:      0     success
             RE_DATA     other party's private value out of range


7. VERSION 1.0 ROUTINES

The following procedures are retained for backward compatibility with
RSAREF 1.0: R_SignPEMBlock, R_SignBlock, R_VerifyPEMSignature,
R_VerifyBlockSignature, R_SealPEMBlock, R_OpenPEMBlock, and
R_DigestBlock.

The procedures are typically called by message-processing
applications. R_SignBlock is also typically called by key-generation
applications when constructing a PEM or PKCS certification request,
and by certification applications when signing a certificate.
R_DigestBlock has no particular PEM application, but may be useful in
PKCS #7.

To sign a message, an application calls R_SignPEMBlock, giving these
arguments:

  -  a pointer to the message content, and the message length
  -  an integer identifying which message-digest algorithm to apply
       (see Appendix D)
  -  a flag indicating whether to encode the message in printable
       ASCII according to RFC 1421
  -  the signer's RSA private key

R_SignPEMBlock signs the message with the signer's private key and
the specified message-digest algorithm, and optionally encodes the
message in printable ASCII. It returns the signature and possibly the
encoded message. The signature is encoded according to RFC 1421.

To sign a block of data such as a certificate where the signature is
not encoded in printable ASCII, an application calls R_SignBlock,
giving these arguments:

  -  a pointer to the block, and the block length
  -  an integer identifying which message-digest algorithm to apply
       (see Appendix D)
  -  the signer's RSA private key

R_SignBlock signs the message with the signer's private key and the
specified message-digest algorithm. It returns the signature.

To verify a signature on a message, an application calls
R_VerifyPEMSignature, giving these arguments:

  -  a pointer to the (possibly encoded) message, and the message
       length
  -  a pointer to the signature, and the signature length
  -  an integer identifying which message-digest algorithm was applied
       (see Appendix D)
  -  a flag indicating whether the message was encoded in printable
       ASCII
  -  the signer's RSA public key

R_VerifyPEMSignature decodes the message if it was encoded and
verifies the signature on the message with the signer's public key
and the specified message-digest algorithm. It returns the message
content if the message was encoded.

To verify a signature on a block of data such as a certificate where
the signature is not encoded in printable ASCII, an application calls
R_VerifyBlockSignature, giving these arguments:

  -  a pointer to the block, and the block length
  -  a pointer to the signature, and the signature length
  -  an integer identifying which message-digest algorithm was applied
       (see Appendix D)
  -  the signer's RSA public key

R_VerifyBlockSignature verifies the signature on the message with the
signer's public key and the specified message-digest algorithm.

To sign and encrypt a message, an application calls R_SealPEMBlock,
giving these arguments:

  -  a pointer to the message content, and the message length
  -  an integer identifying which message-digest algorithm to apply
       (see Appendix D)
  -  the signer's RSA private key
  -  the recipient's RSA public key
  -  a random structure

R_SealPEMBlock signs the message with the signer's private key and
the specified message-digest algorithm, encrypts the message and the
signature with a random DES key, and encrypts the DES key with the
recipient's public key. It returns the encrypted message, the
encrypted key, the encrypted signature, and the DES initialization
vector. The encrypted message, key, and signature are encoded
according to RFC 1421.

To open a message (decrypt it and verify its signature), an
application calls R_OpenPEMBlock, giving these arguments:

  -  a pointer to the encrypted message, and the encrypted message
       length
  -  a pointer to the encrypted key, and the encrypted key length
  -  a pointer to the encrypted signature, and the encrypted signature
       length
  -  a DES initialization vector
  -  an integer identifying which message-digest algorithm was applied
       (see Appendix D)
  -  the signer's RSA public key
  -  the recipient's RSA private key

R_OpenPEMBlock decrypts the encrypted DES key with the recipient's
private key, decrypts the encrypted message and the encrypted
signature with the DES key, and verifies the signature on the message
with the signer's public key and the specified message-digest
algorithm. It returns the message content.

To digest a block of data such as a prototype certificate, an
application calls R_DigestBlock, giving these arguments:

  -  a pointer to the block, and the block length
  -  an integer identifying which message-digest algorithm to apply
       (see Appendix D)

R_DigestBlock digests the block with the specified message-digest
algorithm. It returns the message digest.

ENCODED_CONTENT_LEN, DECODED_CONTENT_LEN, ENCRYPTED_CONTENT_LEN, and
DECRYPTED_CONTENT_LEN are macros that assist in determining the
maximum lengths of the results of cryptographic enhancements.


R_SignPEMBlock

int R_SignPEMBlock (
  unsigned char *encodedContent,                 /* encoded content */
  unsigned int *encodedContentLen,     /* length of encoded content */
  unsigned char *encodedSignature,             /* encoded signature */
  unsigned int *encodedSignatureLen, /* length of encoded signature */
  unsigned char *content,                                /* content */ 
  unsigned int contentLen,                     /* length of content */ 
  int recode,                                      /* recoding flag */
  int digestAlgorithm,                  /* message-digest algorithm */
  R_RSA_PRIVATE_KEY *privateKey         /* signer's RSA private key */
);

R_SignPEMBlock computes a digital signature on content. Specifically,
R_SignPEMBlock performs the following steps:

     1.   It digests content with digestAlgorithm, giving a message
          digest.

     2.   It encrypts the message digest with privateKey, giving a
          digital signature, and encodes the result in printable
          ASCII according to RFC 1421, storing the encoding in
          encodedSignature.

    3.    If recode is nonzero, it encodes content in printable ASCII,
          storing the encoding in encodedContent.

If recode is nonzero, encodedContent will be an ASCII string, encoded
according to RFC 1421. (It will not contain any line delimiters; the
application must break the string into 64-character lines.)
encodedContentLen will not be greater than
ENCODED_CONTENT_LEN(contentLen). If recode is zero, encodedContent is
ignored.

encodedSignature will be an ASCII string, encoded according to RFC
1421. encodedSignatureLen will not be greater than
MAX_PEM_SIGNATURE_LEN.

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

Return value:      0     success
 RE_DIGEST_ALGORITHM     digestAlgorithm is invalid
      RE_PRIVATE_KEY     privateKey cannot encrypt message digest


R_SignBlock

int R_SignBlock (
  unsigned char *signature,                    /* encoded signature */
  unsigned int *signatureLen,        /* length of encoded signature */
  unsigned char *block,                                    /* block */ 
  unsigned int blockLen,                         /* length of block */ 
  int digestAlgorithm,                  /* message-digest algorithm */
  R_RSA_PRIVATE_KEY *privateKey         /* signer's RSA private key */
);

R_SignBlock computes a digital signature on block of data such as a
certificate. Its operation is similar to R_SignPEMBlock, except that
the resulting signature is an arbitrary byte string, rather than an
RFC 1421-encoded string.

signatureLen will not be greater than MAX_SIGNATURE_LEN.

Return value:      0     success
 RE_DIGEST_ALGORITHM     digestAlgorithm is invalid
      RE_PRIVATE_KEY     privateKey cannot encrypt message digest


R_VerifyPEMSignature

int R_VerifyPEMSignature (
  unsigned char *content,                                /* content */ 
  unsigned int *contentLen,                    /* length of content */ 
  unsigned char *encodedContent,      /* (possibly) encoded content */
  unsigned int encodedContentLen,      /* length of encoded content */
  unsigned char *encodedSignature,             /* encoded signature */
  unsigned int encodedSignatureLen,  /* length of encoded signature */
  int recode,                                      /* recoding flag */
  int digestAlgorithm,                  /* message-digest algorithm */
  R_RSA_PUBLIC_KEY *publicKey            /* signer's RSA public key */
);

R_VerifyPEMSignature verifies a digital signature on a message. Its
operation is the inverse of R_SignPEMBlock. R_VerifyPEMSignature
operates on encodedSignature and encodedContent. If recode is
nonzero, it first decodes encodedContent according to RFC 1421, and
stores the result in content. If recode is zero, content is ignored.

If recode is nonzero, contentLen will not be greater than
DECODED_CONTENT_LEN(encodedContentLen).

Return value:      0     success
 RE_CONTENT_ENCODING     encodedContent has RFC 1421 encoding error
RE_SIGNATURE_ENCODING    encodedSignature has RFC 1421 encoding error
 RE_DIGEST_ALGORITHM     digestAlgorithm is invalid
       RE_PUBLIC_KEY     publicKey cannot decrypt signature
        RE_SIGNATURE     signature on content is incorrect


R_VerifyBlockSignature

int R_VerifyBlockSignature (
  unsigned char *block,                                    /* block */
  unsigned int blockLen,                         /* length of block */
  unsigned char *signature,                            /* signature */  
  unsigned int signatureLen,                 /* length of signature */
  int digestAlgorithm,                  /* message-digest algorithm */
  R_RSA_PUBLIC_KEY *publicKey            /* signer's RSA public key */
);

R_VerifyBlockSignature verifies a digital signature on a block of
data such as a certificate. Its operation is similar to
R_VerifyPEMSignature, except that the block and signature are
arbitrary byte strings, rather than RFC 1421-encoded strings.

Return value:      0     success
 RE_DIGEST_ALGORITHM     digestAlgorithm is invalid
       RE_PUBLIC_KEY     publicKey cannot decrypt signature
        RE_SIGNATURE     signature on block is incorrect


R_SealPEMBlock

int R_SealPEMBlock (
  unsigned char *encryptedContent,    /* encoded, encrypted content */
  unsigned int *encryptedContentLen,
                            /* length of encoded, encrypted content */
  unsigned char *encryptedKey,        /* encoded, encrypted DES key */  
  unsigned int *encryptedKeyLen,
                            /* length of encoded, encrypted DES key */  
  unsigned char *encryptedSignature,/* encoded, encrypted signature */
  unsigned int *encryptedSignatureLen,
                          /* length of encoded, encrypted signature */
  unsigned char iv[8],                 /* DES initialization vector */
  unsigned char *content,                                /* content */
  unsigned int contentLen,                     /* length of content */
  int digestAlgorithm,                  /* message-digest algorithm */
  R_RSA_PUBLIC_KEY *publicKey,        /* recipient's RSA public key */
  R_RSA_PRIVATE_KEY *privateKey,        /* signer's RSA private key */
  R_RANDOM_STRUCT *randomStruct                 /* random structure */
);

R_SealPEMBlock computes a digital signature on content then encrypts
the content and the signature. Specifically, R_SealPEMBlock performs
the following steps:

     1.   It digests content with digestAlgorithm, giving a message
          digest.

     2.   It encrypts the message digest with privateKey, giving a
          digital signature.

     3.   It generates a random DES key and initialization vector,
          storing the initialization vector in iv.

     4.   It encrypts content with the DES key and initialization vector
          in cipher-block chaining mode, and encodes the result in
          printable ASCII according to RFC 1421, storing the encoding
          in encryptedContent.

     5.   It encrypts the DES key with publicKey and encodes the
          result in printable ASCII, storing the encoding in
          encryptedKey.

     6.   It encrypts the digital signature with the DES key and
          initialization vector, and encodes the result in printable
          ASCII, storing the encoding in encryptedSignature.

encryptedContent will be an ASCII string, encoded according to RFC
1421. (It will not contain any line delimiters; the application must
break the string into 64-character lines.) encryptedContentLen will
not be greater than ENCRYPTED_CONTENT_LEN(contentLen).

encryptedKey and encryptedSignature will be ASCII strings, encoded
according to RFC 1421. encryptedKeyLen will not be greater than
MAX_PEM_ENCRYPTED_KEY_LEN. encryptedSignatureLen will not be greater
than MAX_PEM_ENCRYPTED_SIGNATURE_LEN.

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

randomStruct must have been seeded.

Return value:      0     success
 RE_DIGEST_ALGORITHM     digestAlgorithm is invalid
      RE_PRIVATE_KEY     privateKey cannot encrypt message digest
       RE_PUBLIC_KEY     publicKey cannot encrypt DES key
      RE_NEED_RANDOM     randomStruct is not seeded


R_OpenPEMBlock

int R_OpenPEMBlock (
  unsigned char *content,                                /* content */
  unsigned int *contentLen,                    /* length of content */
  unsigned char *encryptedContent,    /* encoded, encrypted content */
  unsigned int encryptedContentLen,
                            /* length of encoded, encrypted content */
  unsigned char *encryptedKey,        /* encoded, encrypted DES key */  
  unsigned int encryptedKeyLen,
                            /* length of encoded, encrypted DES key */  
  unsigned char *encryptedSignature,/* encoded, encrypted signature */
  unsigned int encryptedSignatureLen,
                          /* length of encoded, encrypted signature */
  unsigned char iv[8],                 /* DES initialization vector */
  int digestAlgorithm,                  /* message-digest algorithm */
  R_RSA_PRIVATE_KEY *privateKey,     /* recipient's RSA private key */
  R_RSA_PUBLIC_KEY *publicKey            /* signer's RSA public key */
);

R_OpenPEMBlock decrypts an encrypted message and verifies a digital
signature. Its operation is the inverse of R_SealPEMBlock.

contentLen will not be greater than
DECRYPTED_CONTENT_LEN(encryptedContentLen).

Return value:       0    success
 RE_CONTENT_ENCODING     encryptedContent has RFC 1421 encoding error
     RE_KEY_ENCODING     encryptedKey has RFC 1421 encoding error
RE_SIGNATURE_ENCODING    encryptedSignature has RFC 1421 encoding
                           error
       RE_PUBLIC_KEY     publicKey cannot decrypt signature