188 lines
6.8 KiB
C
188 lines
6.8 KiB
C
|
/* Copyright (c) 2005-2007 Apple Inc. All Rights Reserved. */
|
||
|
|
|
||
|
|
/*
|
||
|
|
* libgRSA.h - public API for RSA library based on libGiants
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef _LIBGRSA_LIBRSA_H_
|
||
|
|
#define _LIBGRSA_LIBRSA_H_
|
||
|
|
|
||
|
|
#include <libgRSA/rsaTypes.h>
|
||
|
|
#include <libgRSA/rsaGiantKey.h>
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/*
|
||
|
|
* This file declares the main public functions in the libgRSA library.
|
||
|
|
* Keys for all of these functions are expressed in "RSAGiantKey" format,
|
||
|
|
* defined in rsaGiantKey.h. This is the native key format for this
|
||
|
|
* library. RSAGiantKeys can be obtained in one of two ways:
|
||
|
|
*
|
||
|
|
* -- from DER-encoded, PKCS1-style key blobs, using the interface in
|
||
|
|
* libgRSA_DER.h.
|
||
|
|
* -- from raw byte strings representing individual key components, using
|
||
|
|
* the interface in rsaRawKey.h.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/*
|
||
|
|
* RSA_SIG_SHARE_GIANT, when true, is an optimization to reduce the stack
|
||
|
|
* requirements when performing an RSA_Sign operation. When true, caller
|
||
|
|
* allocates an RSASignBuffer union which contains both a sratch giant
|
||
|
|
* for use by lower level code and the buffer into which a signature
|
||
|
|
* will be written at the completion of RSA_Sign(). The input,
|
||
|
|
* dataToSign, can also be in this RSASignBuffer (i.e., dataToSign
|
||
|
|
* can equal RSASignBuffer.signature).
|
||
|
|
*/
|
||
|
|
#define RSA_SIG_SHARE_GIANT 0
|
||
|
|
#if RSA_SIG_SHARE_GIANT
|
||
|
|
|
||
|
|
typedef union {
|
||
|
|
lgiant g;
|
||
|
|
gi_uint8 signature[MAX_PRIME_SIZE_BYTES];
|
||
|
|
} RSASignBuffer;
|
||
|
|
|
||
|
|
#endif /* RSA_SIG_SHARE_GIANT */
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Given a private key and data to sign, generate a digital signature.
|
||
|
|
*
|
||
|
|
* If the padding argument is RP_PKCS1, PKCS1 padding will be performed
|
||
|
|
* prior to signing. If this argument is RP_None, the incoming data
|
||
|
|
* will be signed "as is". (OAEP padding is not supported for signing.)
|
||
|
|
* Note when PKCS1 padding is performed, the maximum length of data that
|
||
|
|
* can be signed is RSAKey.nLen-11 where RSAKey.nLen is the length of
|
||
|
|
* the modulus.
|
||
|
|
*
|
||
|
|
* NOTE: using RP_None will not work if the first byte of dataToSign
|
||
|
|
* is zero; there is no way to verify leading zeroes as they got chopped
|
||
|
|
* off during the calculation.
|
||
|
|
|
||
|
|
*
|
||
|
|
* If you want a proper PKCS1 style signature, with DER encoding of the
|
||
|
|
* incoming data - and the data is a SHA1 digest - use RSA_EncodeDigest
|
||
|
|
* to format the data in an encoded DigestInfo struct before calling
|
||
|
|
* this routine.
|
||
|
|
*
|
||
|
|
* If RSA_SIG_SHARE_GIANT is zero, caller allocates sig, the output buffer,
|
||
|
|
* into which the signature will be written. This must be at least as large
|
||
|
|
* as the key's modulus. On input, *sigLen is the size of the available buffer.
|
||
|
|
* On output it's the size of the signature actually written to sig.
|
||
|
|
*
|
||
|
|
* If RSA_SIG_SHARE_GIANT is nonzero, caller allocates the signBuffer of
|
||
|
|
* type RSASignBuffer; the signature will be written into
|
||
|
|
* signBuffer->signature and *sigLen will equal the size of the
|
||
|
|
* signature actually written to signBuffer->signature.
|
||
|
|
*
|
||
|
|
* When memory usage is a critical issue, note that the input buffer
|
||
|
|
* (dataToSign) can be the same as the output buffer (sig, or
|
||
|
|
* signBuffer->signature, depending on RSA_SIG_SHARE_GIANT).
|
||
|
|
*
|
||
|
|
* Returns an RSAStatus as described in libgRSA.h.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#if RSA_SIG_SHARE_GIANT
|
||
|
|
|
||
|
|
extern RSAStatus RSA_Sign(
|
||
|
|
RSAPrivGiantKey *privKey, /* private key */
|
||
|
|
RSAPadding padding, /* RP_None or RP_PKCS1 */
|
||
|
|
const gi_uint8 *dataToSign, /* signature over this data */
|
||
|
|
gi_uint16 dataToSignLen, /* length of dataToSign */
|
||
|
|
RSASignBuffer *signBuffer, /* signature RETURNED here */
|
||
|
|
gi_uint16 *sigLen); /* signature RETURNED here */
|
||
|
|
|
||
|
|
#else /* !RSA_SIG_SHARE_GIANT */
|
||
|
|
|
||
|
|
extern RSAStatus RSA_Sign(
|
||
|
|
RSAPrivGiantKey *privKey, /* private key */
|
||
|
|
RSAPadding padding, /* RP_None or RP_PKCS1 */
|
||
|
|
const gi_uint8 *dataToSign, /* signature over this data */
|
||
|
|
gi_uint16 dataToSignLen, /* length of dataToSign */
|
||
|
|
gi_uint8 *sig, /* signature, RETURNED */
|
||
|
|
gi_uint16 *sigLen); /* IN/OUT */
|
||
|
|
|
||
|
|
#endif /* RSA_SIG_SHARE_GIANT */
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Given a public key, data which has been signed, and a signature,
|
||
|
|
* verify the signature.
|
||
|
|
*
|
||
|
|
* If the padding argument is RP_PKCS1, PKCS1 padding will be performed
|
||
|
|
* prior to verification. If this argument is RP_None, the incoming data
|
||
|
|
* will be verified "as is". (OAEP padding is not supported for verifying.)
|
||
|
|
* Note when PKCS1 padding is performed, the maximum length of data that
|
||
|
|
* can be signed and verified is RSAKey.nLen-11 where RSAKey.nLen is the
|
||
|
|
* length of the modulus.
|
||
|
|
*
|
||
|
|
* If you are verifying a proper PKCS1 style signature, with DER encoding
|
||
|
|
* of the incoming data - and the data is a SHA1 digest - use
|
||
|
|
* DEREncodeSHA1DigestInfo to format the data in an encoded DigestInfo
|
||
|
|
* struct before calling this routine.
|
||
|
|
*
|
||
|
|
* Returns an RSAStatus as described above.
|
||
|
|
*/
|
||
|
|
extern RSAStatus RSA_SigVerify(
|
||
|
|
RSAPubGiantKey *pubKey, /* public key */
|
||
|
|
RSAPadding padding, /* RP_None or RP_PKCS1 */
|
||
|
|
const gi_uint8 *signedData, /* signature over this data */
|
||
|
|
gi_uint16 signedDataLen, /* length of dataToSign */
|
||
|
|
const gi_uint8 *sig, /* signature */
|
||
|
|
gi_uint16 sigLen); /* length of signature */
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Encrypt a block of plaintext with a public key.
|
||
|
|
* Resulting ciphertext is the same size as the key's modulus
|
||
|
|
* (RSAKey.nLen) and is allocated by the caller.
|
||
|
|
* The cipherTextLen argument, on input, specifies how much
|
||
|
|
* space is available for the ciphertext; on return, it
|
||
|
|
* is the actual number of ciphertext bytes written.
|
||
|
|
*
|
||
|
|
* When performing RP_PKCS1 or RP_OAEP padding, you must supply
|
||
|
|
* a callback to a pseudorandom number generator via the rngFcn
|
||
|
|
* argument.
|
||
|
|
*
|
||
|
|
* When memory usage is a critical issue, note that the input buffer
|
||
|
|
* (plainText) can be the same as the output buffer (cipherText).
|
||
|
|
*
|
||
|
|
* Returns an RSAStatus as described above.
|
||
|
|
*/
|
||
|
|
extern RSAStatus RSA_Encrypt(
|
||
|
|
RSAPubGiantKey *pubKey, /* public key */
|
||
|
|
RSAPadding padding, /* RP_None, RP_PKCS1, RP_OAEP */
|
||
|
|
RSARngCallback *rngCallback, /* required for RP_PKCS1, RP_OAEP */
|
||
|
|
const gi_uint8 *plainText,
|
||
|
|
gi_uint16 plainTextLen, /* length of plainText */
|
||
|
|
gi_uint8 *cipherText,
|
||
|
|
gi_uint16 *cipherTextLen); /* IN/OUT */
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Decrypt a block of ciphertext with a private key. The
|
||
|
|
* ciphertext must be equal in length to the size of the
|
||
|
|
* key's modulus. The plaintext buffer is allocated by
|
||
|
|
* the caller' en entry, *plainTextLen is the size of the
|
||
|
|
* available plaintext buffer; on return, it is the number
|
||
|
|
* of plaintext bytes actually written.
|
||
|
|
*
|
||
|
|
* When memory usage is a critical issue, note that the input buffer
|
||
|
|
* (cipherText) can be the same as the output buffer (plainText).
|
||
|
|
*
|
||
|
|
* Returns an RSAStatus as described above.
|
||
|
|
*/
|
||
|
|
extern RSAStatus RSA_Decrypt(
|
||
|
|
RSAPrivGiantKey *privKey, /* private key */
|
||
|
|
RSAPadding padding, /* RP_None, RP_PKCS1, RP_OAEP */
|
||
|
|
const gi_uint8 *cipherText,
|
||
|
|
gi_uint16 cipherTextLen, /* length of cipherText */
|
||
|
|
gi_uint8 *plainText,
|
||
|
|
gi_uint16 *plainTextLen); /* IN/OUT */
|
||
|
|
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#endif /* _LIBRSA_LIBRSA_H_ */
|
||
|
|
|