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. INTRODUCTIONThis manual is a reference guide for users of RSAREF, RSALaboratories' portable, educational, reference implementation ofcryptography.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 operationsRSAREF is written entirely in C. Its application interface includesthe 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 structureR_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 keyAn Internet Privacy-Enhanced Mail [9-12] implementation can be builtdirectly on top of these routines, together with message parsing andformatting routines and certificate-management routines.Implementations of PKCS #7 and #10 [13,14] can be built in a similarmanner. Other secure applications can be built on top of theDiffie-Hellman routines.The following routines are supported for backward compatibility withRSAREF 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 certificateR_VerifyPEMSignature     verifies a digital signature on a messageR_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 messageThis manual is divided into eight sections and three appendices.This section introduces RSAREF. The next six sections explain RSAREFprocedures: random structures; cryptographic enhancements; printableASCII encoding and decoding; key-pair generation; Diffie-Hellman keyagreement; and version 1.0 routines. The last section documents theplatform-specific run-time library.Appendix A lists RSAREF error types. Appendix B lists RSAREF typesand constants. Appendix C lists platform-specific types andconstants.2. RANDOM STRUCTURESA random structure contains a seed from which a pseudorandom sequenceof bytes is derived. RSAREF generates keys and pads RSA encryptionblocks with bytes derived from a random structure.Random structures are used by both message-processing andkey-generation applications.RSAREF sets up a random structure with the procedure R_RandomInit. Atypical application calls R_RandomInit on entry.A new random structure is not ready for use until it is seeded bymixing in some random bytes. RSAREF seeds a random structure with theprocedure R_RandomUpdate and R_GetRandomBytesNeeded. A randomstructure is considered seeded when the number of bytes still neededreaches zero. More bytes can be mixed in after the random structureis seeded. A typical application calls R_GetRandomBytesNeeded andR_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_RandomInitint 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 compatibilityR_RandomUpdateint 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 compatibilityR_GetRandomBytesNeededint 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 stillneeded to seed randomStruct, storing the result in bytesNeeded.Return value:      0     success             nonzero     reserved for future compatibilityR_RandomFinalvoid R_RandomFinal (  R_RANDOM_STRUCT *randomStruct                 /* random structure */);R_RandomFinal zeroizes randomStruct.No return value.3. CRYPTOGRAPHIC ENHANCEMENTSRSAREF's cryptographic enhancements fall into five groups: signingdata; 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 alldata to be stored in memory at once.3.1 Signing dataRSAREF signs data with three procedures: R_SignInit, R_SignUpdate,and R_SignFinal. These procedures are typically called bymessage-processing applications, by key-generation applications whenconstructing a PEM or PKCS certification request, and bycertification applications when signing a certificate.An application first calls R_SignInit, giving an integer specifyingwhich message-digest algorithm to apply (see Appendix D). R_SignInitsets up a context for the signature operation, and returns thecontext.The application then calls R_SignUpdate any number of times, givingthe 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_SignFinalencrypts the message digest with the private key and returns theresult, which is the signature.An application may call R_SignUpdate again after R_SignFinal tosign other data, without setting up a new context.R_SignInitint 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, andmust be one of the values listed in Appendix D.Return value:      0     success RE_DIGEST_ALGORITHM     digestAlgorithm is invalidR_SignUpdateint 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, thenext data part, with the specified message-digest algorithm. It maybe called any number of times.Return value:      0     successR_SignFinalint 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 messagedigest with the signer's private key. It stores the resultingsignature 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 digest3.2 Verifying a signatureRSAREF verifies signatures with three procedures: R_VerifyInit,R_VerifyUpdate, and R_VerifyFinal. These procedures are typicallycalled by message-processing applications and by certificationapplications when processing a certification request.An application first calls R_VerifyInit, giving an integer specifyingwhich message-digest algorithm to apply (see Appendix D).R_VerifyInit sets up a context for the verification operation, andreturns the context.The application then calls R_VerifyUpdate any number of times, givingthe context and the next data part. R_VerifyUpdate digests the part.After all the parts are supplied, the application callsR_VerifyFinal, giving the context, the signer's RSA public key, andthe signature. R_SignFinal decrypts the signature with the public keyand compares the result to the message digest to see whether thesignature is valid.An application may call R_VerifyUpdate again after R_VerifyFinal toverify other signatures, without setting up a new context.R_VerifyInitint R_VerifyInit (  R_SIGNATURE_CTX *context,                          /* new context */  int digestAlgorithm                   /* message-digest algorithm */);R_VerifyInit begins a verification operation, setting up a newcontext.digestAlgorithm is the algorithm with which data are digested, andmust be one of the values listed in Appendix D.Return value:      0     success RE_DIGEST_ALGORITHM     digestAlgorithm is invalidR_VerifyUpdateint 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. Itmay be called any number of times.Return value:      0     successR_VerifyFinalint 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 thesignature with the signer's public key and comparing it to themessage 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 incorrect3.3 Sealing data in a digital envelopeRSAREF seals data in digital envelopes with three procedures:R_SealInit, R_SealUpdate, and R_SealFinal. There may be any number ofrecipients. These procedures are typically called bymessage-processing applications.An application first calls R_SealInit, giving an integer specifyingwhich data encryption algorithm to apply (see Appendix D), the publickey of each recipient, and a random structure. R_SealInit sets up acontext for the sealing operation, generates a data encryption keyand an initialization vector, and encrypts the data encryption keywith each recipient's public key.  It returns the context, theinitialization vector, and the encrypted data encryption keys.The application then calls R_SealUpdate any number of times, givingthe context and the next data part. R_SealUpdate encrypts the partand returns the next encrypted data part. (Depending on how data aresupplied, 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 toencrypt other data under the same data encryption key andinitialization vector. This is useful when message content is signedand encrypted, and the digital signature must also be encrypted.R_SealInitint 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 followingsteps:    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