blautenb 2003/06/15 02:34:28
Modified: c/src/enc XSECCryptoHash.hpp XSECCryptoProvider.hpp
c/src/enc/OpenSSL OpenSSLCryptoBase64.hpp
OpenSSLCryptoHash.hpp OpenSSLCryptoHashHMAC.hpp
OpenSSLCryptoKeyDSA.hpp OpenSSLCryptoKeyHMAC.hpp
OpenSSLCryptoKeyRSA.hpp OpenSSLCryptoProvider.hpp
OpenSSLCryptoX509.hpp
c/src/enc/WinCAPI WinCAPICryptoHash.hpp
WinCAPICryptoHashHMAC.hpp WinCAPICryptoKeyDSA.hpp
WinCAPICryptoKeyHMAC.hpp WinCAPICryptoKeyRSA.hpp
WinCAPICryptoProvider.hpp WinCAPICryptoX509.hpp
c/src/enc/XSCrypt XSCryptCryptoBase64.hpp
Log:
Updated encryption interface docs
Revision Changes Path
1.7 +1 -3 xml-security/c/src/enc/XSECCryptoHash.hpp
Index: XSECCryptoHash.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/XSECCryptoHash.hpp,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- XSECCryptoHash.hpp 7 Apr 2003 12:27:13 -0000 1.6
+++ XSECCryptoHash.hpp 15 Jun 2003 09:34:27 -0000 1.7
@@ -64,9 +64,7 @@
*
* Author(s): Berin Lautenbach
*
- * $ID$
- *
- * $LOG$
+ * $Id$
*
*/
1.8 +2 -4 xml-security/c/src/enc/XSECCryptoProvider.hpp
Index: XSECCryptoProvider.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/XSECCryptoProvider.hpp,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- XSECCryptoProvider.hpp 7 Jun 2003 10:33:28 -0000 1.7
+++ XSECCryptoProvider.hpp 15 Jun 2003 09:34:27 -0000 1.8
@@ -64,9 +64,7 @@
*
* Author(s): Berin Lautenbach
*
- * $ID$
- *
- * $LOG$
+ * $Id$
*
*/
@@ -317,7 +315,6 @@
virtual XSECCryptoKeyRSA * keyRSA() = 0;
-
/**
* \brief Return an X509 implementation object.
*
@@ -327,6 +324,7 @@
* @returns Pointer to the new X509 object
* @see XSECCryptoX509
*/
+
virtual XSECCryptoX509 * X509() = 0;
//@}
1.3 +129 -12 xml-security/c/src/enc/OpenSSL/OpenSSLCryptoBase64.hpp
Index: OpenSSLCryptoBase64.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/OpenSSL/OpenSSLCryptoBase64.hpp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- OpenSSLCryptoBase64.hpp 9 Feb 2003 11:13:49 -0000 1.2
+++ OpenSSLCryptoBase64.hpp 15 Jun 2003 09:34:27 -0000 1.3
@@ -64,9 +64,7 @@
*
* Author(s): Berin Lautenbach
*
- * $ID$
- *
- * $LOG$
+ * $Id$
*
*/
@@ -80,37 +78,154 @@
#include <openssl/evp.h>
+/**
+ * @ingroup opensslcrypto
+ */
+ /[EMAIL PROTECTED]/
+
+/**
+ * \brief Base64 encode/decode handler interface class.
+ *
+ * The XSEC library will use implementations of this interface
+ * for translating bytes to/from base64 encoding.
+ *
+ * Uses the EVP decode/encode routines in OpenSSL to perform the
+ * work.
+ *
+ *
+ *
+ * @note Requires implementation of OpenSSL > 0.9.6e as there was a bug
+ * in the Base64 decoding routines in this version and prior.
+ *
+ */
+
+
class DSIG_EXPORT OpenSSLCryptoBase64 : public XSECCryptoBase64 {
public :
- // Constructors/Destructors
OpenSSLCryptoBase64() {};
virtual ~OpenSSLCryptoBase64() {};
- // Decoding Activities
- virtual void decodeInit(void);
// Setup
+ /** @name Decoding Functions */
+ //@{
+
+ /**
+ * \brief Initialise the base64 object.
+ *
+ * Initialises the OpenSSL decode context and gets ready for data
+ * to be decoded.
+ *
+ */
+
+ virtual void decodeInit(void);
+
+ /**
+ * \brief Decode some passed in data.
+ *
+ * Pass the encoded data through the OpenSSL base64 decode function
+ * and place the data in the outData buffer.
+ *
+ * @note The OpenSSL library is very unkind if the output buffer is
+ * not large enough. It is the responsibility of the caller to ensure
+ * the buffer will take the data.
+ *
+ * @param inData Pointer to the buffer holding encoded data.
+ * @param inLength Length of the encoded data in the buffer
+ * @param outData Buffer to place decoded data into
+ * @param outLength Maximum amount of data that can be placed in
+ * the buffer.
+ * @returns The number of bytes placed in the outData buffer.
+ */
+
virtual unsigned int decode(unsigned char * inData,
unsigned int
inLength,
unsigned char *
outData,
- unsigned int
outLength); // decode
+ unsigned int
outLength);
+
+
+ /**
+ * \brief Finish off a decode.
+ *
+ * Clean out any extra data in the OpenSSL decode context
+ * variable into the outData buffer.
+ *
+ * @param outData Buffer to place any remaining decoded data
+ * @param outLength Max amount of data to be placed in the buffer.
+ * @returns Amount of data placed in the outData buffer
+ */
+
virtual unsigned int decodeFinish(unsigned char * outData,
- unsigned
int outLength);// Finish
+ unsigned
int outLength);
+
+ //@}
+
+ /** @name Encoding Functions */
+ //@{
+
+ /**
+ * \brief Initialise the base64 object for encoding
+ *
+ * Get the context variable ready for a base64 decode
+ *
+ */
+
+ virtual void encodeInit(void);
+
+ /**
+ * \brief Encode some passed in data.
+ *
+ * Pass the data through the OpenSSL Base64 encoder and place
+ * the output in the outData buffer. Will keep any "overhang"
+ * data in the context buffer ready for the next pass of input
+ * data.
+ *
+ * @param inData Pointer to the buffer holding data to be encoded.
+ * @param inLength Length of the data in the buffer
+ * @param outData Buffer to place encoded data into
+ * @param outLength Maximum amount of data that can be placed in
+ * the buffer.
+ * @returns The number of bytes placed in the outData buffer.
+ */
- // Encoding activities
- virtual void encodeInit(void);
// Setup
virtual unsigned int encode(unsigned char * inData,
unsigned int
inLength,
unsigned char *
outData,
- unsigned int
outLength); // decode
+ unsigned int
outLength);
+
+ /**
+ * \brief Finish off an encode.
+ *
+ * Take any data left in the context variable, and create the
+ * tail of the base64 encoding.
+ *
+ * @param outData Buffer to place any remaining encoded data
+ * @param outLength Max amount of data to be placed in the buffer.
+ * @returns Amount of data placed in the outData buffer
+ */
+
virtual unsigned int encodeFinish(unsigned char * outData,
unsigned
int outLength); // Finish
- // Utility functions
+
+ //@}
+
+ /** @name Library Specific Functions */
+ //@{
+
+ /**
+ * \brief Translate a base64 encoded BN to a bignum
+ *
+ * Take a ds:CryptoBinary number and translate to an OpenSSL
+ * representation of a "big number" BIGNUM.
+ *
+ */
+
static BIGNUM * b642BN(char * b64in, unsigned int len);
+ //@}
private :
@@ -118,5 +233,7 @@
EVP_ENCODE_CTX m_dctx; // Decode context
};
+
+/[EMAIL PROTECTED]/
#endif /* OPENSSLCRYPTOBASE64_INCLUDE */
1.3 +84 -11 xml-security/c/src/enc/OpenSSL/OpenSSLCryptoHash.hpp
Index: OpenSSLCryptoHash.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/OpenSSL/OpenSSLCryptoHash.hpp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- OpenSSLCryptoHash.hpp 9 Feb 2003 11:13:49 -0000 1.2
+++ OpenSSLCryptoHash.hpp 15 Jun 2003 09:34:27 -0000 1.3
@@ -64,9 +64,7 @@
*
* Author(s): Berin Lautenbach
*
- * $ID$
- *
- * $LOG$
+ * $Id$
*
*/
@@ -80,28 +78,103 @@
#include <openssl/evp.h>
-class DSIG_EXPORT OpenSSLCryptoHash : public XSECCryptoHash {
+/**
+ * @ingroup opensslcrypto
+ * @{
+ */
+/**
+ * \brief Interface definition for Hash functions.
+ *
+ * Uses the OpenSSL EVP_digest functions to implement the various
+ * hash functions required by the OpenSSL library.
+ *
+ */
+
+class DSIG_EXPORT OpenSSLCryptoHash : public XSECCryptoHash {
public :
- // Constructors/Destructors
-
+ /** @name Constructors and Destructors */
+ //@{
+
OpenSSLCryptoHash(XSECCryptoHash::HashType alg);
virtual ~OpenSSLCryptoHash();
+
+ //@}
+
+ /** @name HMAC Functions */
+ //@{
+
+ /**
+ *\brief
+ *
+ * Does nothing. If the required function is an HMAC function,
+ * then OpenSSLCryptoHashHMAC should be used.
+ *
+ * @param key The key the HMAC function should use.
+ */
- // Key activities
virtual void setKey(XSECCryptoKey * key) {}
- // Hashing Activities
- virtual void reset(void);
// Reset the hash
+ //@}
+
+ /** @name Digest/Hash functions */
+ //@{
+
+ /**
+ * \brief Rest the hash function
+ *
+ * Re-initialises the digest structure.
+ */
+
+ virtual void reset(void);
+
+ /**
+ * \brief Hash some data.
+ *
+ * Take length bytes of data from the data buffer and update the hash
+ * that already exists. This function may (and normally will) be called
+ * many times for large blocks of data.
+ *
+ * @param data The buffer containing the data to be hashed.
+ * @param length The number of bytes to be read from data
+ */
+
virtual void hash(unsigned char * data,
- unsigned int length);
// Hash some data
+ unsigned int length);
+ /**
+ * \brief Finish up a Digest operation and read the result.
+ *
+ * This call tells the CryptoHash object that the input is complete and
+ * to finalise the Digest. The output of the digest is read into the
+ * hash buffer (at most maxLength bytes)
+ *
+ * @param hash The buffer the hash should be read into.
+ * @param maxLength The maximum number of bytes to be read into hash
+ * @returns The number of bytes copied into the hash buffer
+ */
+
virtual unsigned int finish(unsigned char * hash,
unsigned int
maxLength);// Finish and get hash
- // Get information
+ //@}
+
+ /** @name Information functions */
+ //@{
+
+ /**
+ *\brief
+ *
+ * Determine the hash type of this object
+ *
+ * @returns The hash type
+ */
+
virtual HashType getHashType(void);
+
+ //@}
+
private:
1.4 +105 -9 xml-security/c/src/enc/OpenSSL/OpenSSLCryptoHashHMAC.hpp
Index: OpenSSLCryptoHashHMAC.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/OpenSSL/OpenSSLCryptoHashHMAC.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- OpenSSLCryptoHashHMAC.hpp 7 Apr 2003 12:27:13 -0000 1.3
+++ OpenSSLCryptoHashHMAC.hpp 15 Jun 2003 09:34:27 -0000 1.4
@@ -80,29 +80,125 @@
#include <openssl/evp.h>
#include <openssl/hmac.h>
-class DSIG_EXPORT OpenSSLCryptoHashHMAC : public XSECCryptoHash {
+/**
+ * @ingroup opensslcrypto
+ * @{
+ */
+
+/**
+ * \brief Implementation of HMAC Hash functions in OpenSSL
+ *
+ * Uses the OpenSSL EVP_digest functions to implement the various
+ * HMAC hash functions required by the library.
+ *
+ */
+class DSIG_EXPORT OpenSSLCryptoHashHMAC : public XSECCryptoHash {
public :
- // Constructors/Destructors
-
+ /** @name Constructors and Destructors */
+ //@{
+
+ /**
+ * \brief Constructor
+ *
+ * Create the object, with the indicated algorithm
+ * (Currently supports MD5 and SHA1)
+ *
+ * @param alg Digest algorithm to use
+ */
+
OpenSSLCryptoHashHMAC(XSECCryptoHash::HashType alg);
+
+ /**
+ * \brief Destructor
+ *
+ * Destroy the object. Will ensure any key material is also destroyed
+ */
+
virtual ~OpenSSLCryptoHashHMAC();
- // Key activities
+ //@}
+
+ /** @name HMAC Functions */
+ //@{
+
+ /**
+ *\brief Set the HMAC key
+ *
+ * Sets the key - which needs to have a base class of
+ * OpenSSLCryptoKeyHMAC.
+ *
+ * @param key The key the HMAC function should use.
+ */
+
virtual void setKey(XSECCryptoKey * key);
+
+ /**
+ * \brief Return the string identifier for the OpenSSL interface
+ */
+
virtual const XMLCh * getProviderName() {return
DSIGConstants::s_unicodeStrPROVOpenSSL;}
- // Hashing Activities
- virtual void reset(void);
// Reset the hash
+ //@}
+
+ /** @name Hash Functions */
+ //{@
+
+ /**
+ * \brief Reset the hash function
+ *
+ * Re-initialises the digest structure.
+ */
+
+ virtual void reset(void);
+
+ /**
+ * \brief Hash some data.
+ *
+ * Take length bytes of data from the data buffer and update the hash
+ * that already exists. This function may (and normally will) be called
+ * many times for large blocks of data.
+ *
+ * @param data The buffer containing the data to be hashed.
+ * @param length The number of bytes to be read from data
+ */
+
virtual void hash(unsigned char * data,
- unsigned int length);
// Hash some data
+ unsigned int length);
+ /**
+ * \brief Finish up a Digest operation and read the result.
+ *
+ * This call tells the CryptoHash object that the input is complete and
+ * to finalise the Digest. The output of the digest is read into the
+ * hash buffer (at most maxLength bytes). This is effectively the
+ * signature for the data that has been run through the HMAC function.
+ *
+ * @param hash The buffer the hash should be read into.
+ * @param maxLength The maximum number of bytes to be read into hash
+ * @returns The number of bytes copied into the hash buffer
+ */
+
virtual unsigned int finish(unsigned char * hash,
unsigned int
maxLength);// Finish and get hash
- // Get information
+ //@}
+
+ /** @name Information functions */
+ //@{
+
+ /**
+ *\brief
+ *
+ * Determine the hash type of this object
+ *
+ * @returns The hash type
+ */
+
virtual HashType getHashType(void);
+
+ //@}
private:
1.4 +143 -15 xml-security/c/src/enc/OpenSSL/OpenSSLCryptoKeyDSA.hpp
Index: OpenSSLCryptoKeyDSA.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/OpenSSL/OpenSSLCryptoKeyDSA.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- OpenSSLCryptoKeyDSA.hpp 7 Apr 2003 12:27:13 -0000 1.3
+++ OpenSSLCryptoKeyDSA.hpp 15 Jun 2003 09:34:27 -0000 1.4
@@ -75,46 +75,174 @@
#include <openssl/evp.h>
+/**
+ * \ingroup opensslcrypto
+ * @{
+ */
+
+/**
+ * \brief OpenSSL implementation class for DSA keys.
+ *
+ * The library uses classes derived from this to process DSA keys.
+ */
+
+
class DSIG_EXPORT OpenSSLCryptoKeyDSA : public XSECCryptoKeyDSA {
public :
- // Constructors/Destructors
+ /** @name Constructors and Destructors */
+ //@{
OpenSSLCryptoKeyDSA();
+
+ /**
+ * \brief Destructor
+ *
+ * Will call the OpenSSL function to destroy the DSA key - which will
+ * also overwrite any Private keys
+ */
+
virtual ~OpenSSLCryptoKeyDSA();
- // Generic key functions
+ //@}
+
+ /** @name Required Key Interface methods */
+ //@{
+
+ /**
+ * \brief Return the type of this key.
+ *
+ * Allows the caller (and library) to determine whether this is a
+ * public key, private key or a key pair
+ */
virtual XSECCryptoKey::KeyType getKeyType();
+
+ /**
+ *\brief Return the OpenSSL string identifier
+ */
+
virtual const XMLCh * getProviderName() {return
DSIGConstants::s_unicodeStrPROVOpenSSL;}
+ /**
+ * \brief Replicate key
+ */
+
virtual XSECCryptoKey * clone();
- // DSA Specific Functions
+ //@}
- virtual void loadPBase64BigNums(const char * b64, unsigned int len);
- virtual void loadQBase64BigNums(const char * b64, unsigned int len);
- virtual void loadGBase64BigNums(const char * b64, unsigned int len);
- virtual void loadYBase64BigNums(const char * b64, unsigned int len);
- virtual void loadJBase64BigNums(const char * b64, unsigned int len);
+ /** @name Required DSA methods */
+ //@{
- // Signatures
- virtual bool verifyBase64Signature(unsigned char * hashBuf,
- unsigned int hashLen,
- char * base64Signature,
- unsigned int sigLen);
+ /**
+ * \brief Create a signature
+ *
+ * Sign the buffer using the internal private key. Will throw a
DSAError
+ * if the key is not set, or is not a private key.
+ *
+ * @param hashBuf Buffer containing the pre-calculated (binary) digest
+ * @param hashLen Number of bytes of hash in the hashBuf
+ * @param base64SignatureBuf Buffer to place the base64 encoded result
+ * in.
+ * @param base64SignatureBufLen Implementations need to ensure they do
+ * not write more bytes than this into the buffer
+ */
virtual unsigned int signBase64Signature(unsigned char * hashBuf,
unsigned int hashLen,
char * base64SignatureBuf,
unsigned int base64SignatureBufLen);
+ /**
+ * \brief Verify a signature
+ *
+ * The library will call this function to validate a signature
+ *
+ * @param hashBuf Buffer containing the pre-calculated (binary) digest
+ * @param hashLen Length of the data in the digest buffer
+ * @param base64Signature Buffer containing the Base64 encoded signature
+ * @param sigLen Length of the data in the signature buffer
+ * @returns true if the signature was valid, false otherwise
+ */
+
+
+ virtual bool verifyBase64Signature(unsigned char * hashBuf,
+ unsigned int hashLen,
+ char * base64Signature,
+ unsigned int sigLen);
+
+ //@}
+
+ /** @name Optional Interface methods
+ *
+ * Have been fully implemented in the OpenSSL interface to allow interop
+ * testing to occur.
+ *
+ */
+ //@{
+
+ /**
+ * \brief Load P
+ *
+ * @param b64 Base64 encoded parameter - read from XML document
+ * @param len Length of the encoded string
+ */
+ virtual void loadPBase64BigNums(const char * b64, unsigned int len);
- // "Hidden" OpenSSL functions
+ /**
+ * \brief Load Q
+ *
+ * @param b64 Base64 encoded parameter - read from XML document
+ * @param len Length of the encoded string
+ */
+
+ virtual void loadQBase64BigNums(const char * b64, unsigned int len);
+
+ /**
+ * \brief Load G
+ *
+ * @param b64 Base64 encoded parameter - read from XML document
+ * @param len Length of the encoded string
+ */
+
+ virtual void loadGBase64BigNums(const char * b64, unsigned int len);
+
+ /**
+ * \brief Load Y
+ *
+ * @param b64 Base64 encoded parameter - read from XML document
+ * @param len Length of the encoded string
+ */
+
+ virtual void loadYBase64BigNums(const char * b64, unsigned int len);
+
+ /**
+ * \brief Load J
+ *
+ * @param b64 Base64 encoded parameter - read from XML document
+ * @param len Length of the encoded string
+ */
+
+ virtual void loadJBase64BigNums(const char * b64, unsigned int len);
+
+ //@}
+
+ /** @name OpenSSL Specific functions */
+ //@{
+
+ /**
+ * \brief Library specific constructor
+ *
+ * Used to create a new key around an OpenSSL EVP_PKEY object
+ * holding a DSA key
+ */
OpenSSLCryptoKeyDSA(EVP_PKEY *k);
+
+ //@}
private:
1.4 +74 -6 xml-security/c/src/enc/OpenSSL/OpenSSLCryptoKeyHMAC.hpp
Index: OpenSSLCryptoKeyHMAC.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/OpenSSL/OpenSSLCryptoKeyHMAC.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- OpenSSLCryptoKeyHMAC.hpp 7 Apr 2003 12:27:13 -0000 1.3
+++ OpenSSLCryptoKeyHMAC.hpp 15 Jun 2003 09:34:27 -0000 1.4
@@ -73,25 +73,93 @@
#include <xsec/enc/XSECCryptoKeyHMAC.hpp>
+/**
+ * \ingroup opensslcrypto
+ * @{
+ */
+
+/**
+ * \brief OpenSSL implementation for HMAC keys.
+ *
+ * Used to provide HMAC keys to OpenSSLCryptoHashHMAC
+ */
+
class DSIG_EXPORT OpenSSLCryptoKeyHMAC : public XSECCryptoKeyHMAC {
public :
- // Constructors/Destructors
-
+ /** @name Constructors and Destructors */
+ //@{
+
OpenSSLCryptoKeyHMAC();
virtual ~OpenSSLCryptoKeyHMAC() {};
- virtual XSECCryptoKey * clone();
- // Generic key functions
+ //@}
+
+ /** @name Key Interface methods */
+ //@{
+
+ /**
+ * \brief Return the type of this key.
+ *
+ * For DSA keys, this allows people to determine whether this is a
+ * public key, private key or a key pair
+ */
virtual XSECCryptoKey::KeyType getKeyType() {return KEY_HMAC;}
+
+ /**
+ * \brief Replicate key
+ */
+
+ virtual XSECCryptoKey * clone();
+
+ /**
+ * \brief Return the OpenSSL string identifier
+ */
+
virtual const XMLCh * getProviderName() {return
DSIGConstants::s_unicodeStrPROVOpenSSL;}
+
+ //@}
- // HMAC Key functions
+ /** @name Optional Interface methods
+ *
+ * These functions do not necessarily have to be implmented. They
+ * are used by XSECKeyInfoResolverDefault to try to create a key from
+ * KeyInfo elements without knowing anything else.
+ *
+ * If an interface class does not implement these functions, a simple
+ * stub that does nothing should be used.
+ */
+ //@{
+
+ /**
+ * \brief Set the key
+ *
+ * Set the key from the buffer
+ *
+ * @param inBuf Buffer containing the key
+ * @param inLength Number of bytes of key in the buffer
+ *
+ * @note isSensitive() should have been called on the inbound buffer
+ * to ensure the contents is overwritten when the safeBuffer is deleted
+ */
virtual void setKey(unsigned char * inBuf, unsigned int inLength);
+
+ /**
+ * \brief Get the key value
+ *
+ * Copy the key into the safeBuffer and return the number of bytes
+ * copied.
+ *
+ * @param outBuf Buffer to copy key into
+ * @returns number of bytes copied in
+ */
+
virtual unsigned int getKey(safeBuffer &outBuf);
+
+ //@}
private:
1.4 +112 -9 xml-security/c/src/enc/OpenSSL/OpenSSLCryptoKeyRSA.hpp
Index: OpenSSLCryptoKeyRSA.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/OpenSSL/OpenSSLCryptoKeyRSA.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- OpenSSLCryptoKeyRSA.hpp 7 Apr 2003 12:27:13 -0000 1.3
+++ OpenSSLCryptoKeyRSA.hpp 15 Jun 2003 09:34:27 -0000 1.4
@@ -75,41 +75,144 @@
#include <openssl/evp.h>
+/**
+ * \ingroup opensslcrypto
+ * @{
+ */
+
+/**
+ * \brief Implementation of the interface class for RSA keys.
+ *
+ * The library uses classes derived from this to process RSA keys.
+ */
+
class DSIG_EXPORT OpenSSLCryptoKeyRSA : public XSECCryptoKeyRSA {
public :
- // Constructors/Destructors
+ /** @name Constructors and Destructors */
+ //@{
OpenSSLCryptoKeyRSA();
virtual ~OpenSSLCryptoKeyRSA();
- // Generic key functions
+ //@}
+
+ /** @name Key Interface methods */
+ //@{
+
+ /**
+ * \brief Return the type of this key.
+ *
+ * For RSA keys, this allows people to determine whether this is a
+ * public key, private key or a key pair
+ */
virtual XSECCryptoKey::KeyType getKeyType();
+
+ /**
+ * \brief Return the OpenSSL identifier string
+ */
+
virtual const XMLCh * getProviderName() {return
DSIGConstants::s_unicodeStrPROVOpenSSL;}
- virtual XSECCryptoKey * clone();
- // RSA Specific Functions
+ /**
+ * \brief Replicate key
+ */
- virtual void loadPublicModulusBase64BigNums(const char * b64, unsigned
int len);
- virtual void loadPublicExponentBase64BigNums(const char * b64, unsigned
int len);
+ virtual XSECCryptoKey * clone();
- // Signature functions
+ //@}
+
+ /** @name Mandatory RSA interface methods
+ *
+ * These classes are required by the library.
+ */
+ //@{
+
+ /**
+ * \brief Verify a SHA1 PKCS1 encoded signature
+ *
+ * The library will call this function to validate an RSA signature
+ * The standard by default uses SHA1 in a PKCS1 encoding.
+ *
+ * @param hashBuf Buffer containing the pre-calculated (binary) digest
+ * @param hashLen Length of the data in the digest buffer
+ * @param base64Signature Buffer containing the Base64 encoded signature
+ * @param sigLen Length of the data in the signature buffer
+ * @returns true if the signature was valid, false otherwise
+ */
virtual bool verifySHA1PKCS1Base64Signature(const unsigned char *
hashBuf,
unsigned int
hashLen,
const char *
base64Signature,
unsigned int
sigLen);
+ /**
+ * \brief Create a signature
+ *
+ * The library will call this function to create a signature from
+ * a pre-calculated digest. The output signature will
+ * be Base64 encoded such that it can be placed directly into the
+ * XML document
+ *
+ * @param hashBuf Buffer containing the pre-calculated (binary) digest
+ * @param hashLen Number of bytes of hash in the hashBuf
+ * @param base64SignatureBuf Buffer to place the base64 encoded result
+ * in.
+ * @param base64SignatureBufLen Implementations need to ensure they do
+ * not write more bytes than this into the buffer
+ */
+
virtual unsigned int signSHA1PKCS1Base64Signature(unsigned char *
hashBuf,
unsigned int hashLen,
char * base64SignatureBuf,
unsigned int base64SignatureBufLen);
- // "Hidden" OpenSSL functions
+ //@}
+
+ /** @name Optional Interface methods
+ *
+ * Have been implemented to allow interoperability testing
+ */
+
+ //@{
+
+ /**
+ * \brief Load the modulus
+ *
+ * Load the modulus from a Base64 encoded string
+ *
+ * param b64 A buffer containing the encoded string
+ * param len The length of the data in the buffer
+ */
+
+ virtual void loadPublicModulusBase64BigNums(const char * b64, unsigned
int len);
+
+ /**
+ * \brief Load the exponent
+ *
+ * Load the exponent from a Base64 encoded string
+ *
+ * param b64 A buffer containing the encoded string
+ * param len The length of the data in the buffer
+ */
+
+ virtual void loadPublicExponentBase64BigNums(const char * b64, unsigned
int len);
+
+ //@}
+
+ /** @name OpenSSL specific methods */
+ //@{
+
+ /**
+ * \brief Constructor to create the object around an existing OpenSSL
RSA
+ * key
+ */
OpenSSLCryptoKeyRSA(EVP_PKEY *k);
+
+ //@}
private:
1.4 +117 -9 xml-security/c/src/enc/OpenSSL/OpenSSLCryptoProvider.hpp
Index: OpenSSLCryptoProvider.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/OpenSSL/OpenSSLCryptoProvider.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- OpenSSLCryptoProvider.hpp 30 Mar 2003 06:57:12 -0000 1.3
+++ OpenSSLCryptoProvider.hpp 15 Jun 2003 09:34:27 -0000 1.4
@@ -64,9 +64,7 @@
*
* Author(s): Berin Lautenbach
*
- * $ID$
- *
- * $LOG$
+ * $Id$
*
*/
@@ -79,7 +77,14 @@
/**
* @defgroup opensslcrypto OpenSSL Interface
* @ingroup crypto
- * The OpenSSL code provides an implementation....
+ * The OpenSSL/OpenSSL* classes provide an implementation of the
+ * XSECCrypto interface layer for OpenSSL. The layer is very thin -
+ * it only provides the functionality necessary to provide cryptographic
+ * services to the library.
+ *
+ * Calling applications need to do the work to initialise OpenSSL, load
+ * keys from disk etc.
+ *
*/
/[EMAIL PROTECTED]/
@@ -88,26 +93,129 @@
public :
- // Constructors/Destructors
+ /** @name Constructors and Destructors */
+ //@{
OpenSSLCryptoProvider();
virtual ~OpenSSLCryptoProvider();
- // Hashing classes
+ //@}
+
+ /** @name Hashing (Digest) Functions */
+ //@{
+
+ /**
+ * \brief Return a SHA1 implementation.
+ *
+ * Call used by the library to obtain a SHA1 object from the
+ * provider.
+ *
+ * @returns A pointer to an OpenSSL Hash object that implements SHA1
+ * @see XSECCryptoHash
+ */
+
virtual XSECCryptoHash * hashSHA1();
+
+ /**
+ * \brief Return a HMAC SHA1 implementation.
+ *
+ * Call used by the library to obtain a HMAC SHA1 object from the
+ * provider. The caller will need to set the key in the hash
+ * object with an XSECCryptoKeyHMAC using OpenSSLCryptoHash::setKey()
+ *
+ * @returns A pointer to a Hash object that implements HMAC-SHA1
+ * @see OpenSSLCryptoHash
+ */
+
virtual XSECCryptoHash * hashHMACSHA1();
+
+ /**
+ * \brief Return a MD5 implementation.
+ *
+ * Call used by the library to obtain a MD5 object from the
+ * OpenSSL provider.
+ *
+ * @returns A pointer to a Hash object that implements MD5
+ * @see OpenSSLCryptoHash
+ */
+
virtual XSECCryptoHash * hashMD5();
+
+ /**
+ * \brief Return a HMAC MD5 implementation.
+ *
+ * Call used by the library to obtain a HMAC MD5 object from the
+ * provider. The caller will need to set the key in the hash
+ * object with an XSECCryptoKeyHMAC using XSECCryptoHash::setKey()
+ *
+ * @note The use of MD5 is explicitly marked as <b>not recommended</b>
+ * in the XML Digital Signature standard due to recent advances in
+ * cryptography indicating there <em>may</em> be weaknesses in the
+ * algorithm.
+ *
+ * @returns A pointer to a Hash object that implements HMAC-MD5
+ * @see OpenSSLCryptoHash
+ */
+
virtual XSECCryptoHash * hashHMACMD5();
- // Encode/Decode
+ //@}
+
+ /** @name Encoding functions */
+ //@{
+
+ /**
+ * \brief Return a Base64 encoder/decoder implementation.
+ *
+ * Call used by the library to obtain an OpenSSL Base64
+ * encoder/decoder.
+ *
+ * @returns Pointer to the new Base64 encoder.
+ * @see OpenSSLCryptoBase64
+ */
+
virtual XSECCryptoBase64 * base64();
- // Keys
+ //@}
+
+ /** @name Keys and Certificates */
+ //@{
+
+ /**
+ * \brief Return a DSA key implementation object.
+ *
+ * Call used by the library to obtain a DSA key object.
+ *
+ * @returns Pointer to the new DSA key
+ * @see OpenSSLCryptoKeyDSA
+ */
+
virtual XSECCryptoKeyDSA * keyDSA();
+
+ /**
+ * \brief Return an RSA key implementation object.
+ *
+ * Call used by the library to obtain an OpenSSL RSA key object.
+ *
+ * @returns Pointer to the new RSA key
+ * @see OpenSSLCryptoKeyRSA
+ */
+
virtual XSECCryptoKeyRSA * keyRSA();
- // X509
+ /**
+ * \brief Return an X509 implementation object.
+ *
+ * Call used by the library to obtain an object that can work
+ * with X509 certificates.
+ *
+ * @returns Pointer to the new X509 object
+ * @see OpenSSLCryptoX509
+ */
+
virtual XSECCryptoX509 * X509();
+
+ //@}
/[EMAIL PROTECTED]/
1.3 +67 -5 xml-security/c/src/enc/OpenSSL/OpenSSLCryptoX509.hpp
Index: OpenSSLCryptoX509.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/OpenSSL/OpenSSLCryptoX509.hpp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- OpenSSLCryptoX509.hpp 9 Feb 2003 11:13:50 -0000 1.2
+++ OpenSSLCryptoX509.hpp 15 Jun 2003 09:34:27 -0000 1.3
@@ -79,27 +79,89 @@
#include <openssl/x509.h>
#include <openssl/bio.h>
+/**
+ * \brief Implementation class for interface for X509 certificates.
+ * @ingroup opensslcrypto
+ *
+ * The library uses classes derived from this to process X509 Certificates.
+ *
+ */
+
class DSIG_EXPORT OpenSSLCryptoX509 : public XSECCryptoX509 {
public :
+ /** @name Constructors and Destructors */
+ //@{
+
OpenSSLCryptoX509();
virtual ~OpenSSLCryptoX509();
- // load functions
+ //@}
- virtual void loadX509Base64Bin(const char * buf, unsigned int len);
- // Info functions
+ //@}
+ /** @name Key Interface methods */
+ //@{
+
+ /**
+ * \brief Return the type of the key stored in the certificate.
+ *
+ * Will extract the key from the certificate to return the appropriate
+ * type
+ *
+ */
virtual XSECCryptoKey::KeyType getPublicKeyType();
- // Get functions
+ /**
+ * \brief Get a copy of the public key.
+ *
+ * Extracts the public key from the certificate and returns the
appropriate
+ * OpenSSLCryrptoKey (DSA or RSA) object
+ *
+ */
+
virtual XSECCryptoKey * clonePublicKey();
+
+ //@}
+
+ /** @name Load and Get the certificate */
+ //@{
+
+ /**
+ * \brief Load a certificate into the object.
+ *
+ * Take a base64 DER encoded certificate and load.
+ *
+ * @param buf A buffer containing the Base64 encoded certificate
+ * @param len The number of bytes of data in the certificate.
+ */
+
+ virtual void loadX509Base64Bin(const char * buf, unsigned int len);
+
+ /**
+ * \brief Get a Base64 DER encoded copy of the certificate
+ *
+ * @returns A safeBuffer containing the DER encoded certificate
+ */
+
virtual safeBuffer &getDEREncodingSB(void) {return m_DERX509;}
- // OpenSSL specific functions
+ //@}
+
+ /** @name OpenSSL Library Specific functions */
+ //@{
+
+ /**
+ * \brief OpenSSL specific constructor
+ *
+ * Construct the object around an existing X509 certificate
+ */
+
OpenSSLCryptoX509(X509 * x);
+
+ //@}
private:
1.2 +82 -7 xml-security/c/src/enc/WinCAPI/WinCAPICryptoHash.hpp
Index: WinCAPICryptoHash.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/WinCAPI/WinCAPICryptoHash.hpp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- WinCAPICryptoHash.hpp 7 Apr 2003 12:13:35 -0000 1.1
+++ WinCAPICryptoHash.hpp 15 Jun 2003 09:34:27 -0000 1.2
@@ -84,28 +84,103 @@
class WinCAPICryptoProvider;
+/**
+ * @ingroup wincapicrypto
+ * @{
+ */
+
+/**
+ * \brief Windows Crypto API Implementation of Hash functions.
+ *
+ * Uses the Windows Crypt functions to perform digest functions.
+ *
+ */
+
class DSIG_EXPORT WinCAPICryptoHash : public XSECCryptoHash {
public :
- // Constructors/Destructors
+ /** @name Constructors/Destructors */
+ //@{
WinCAPICryptoHash(WinCAPICryptoProvider * owner,
XSECCryptoHash::HashType alg);
virtual ~WinCAPICryptoHash();
- // Key activities
+ //@}
+
+ /** @name HMAC Functions */
+ //@{
+
+ /**
+ *\brief
+ *
+ * Does nothing. If the required function is an HMAC function,
+ * then WinCAPICryptoHashHMAC should be used.
+ *
+ * @param key The key the HMAC function should use.
+ */
+
virtual void setKey(XSECCryptoKey * key) {}
- // Hashing Activities
- virtual void reset(void);
// Reset the hash
+ //@}
+
+ /** @name Digest/Hash functions */
+ //@{
+
+ /**
+ * \brief Rest the hash function
+ *
+ * Re-initialises the digest structure.
+ */
+
+ virtual void reset(void);
+
+ /**
+ * \brief Hash some data.
+ *
+ * Take length bytes of data from the data buffer and update the hash
+ * that already exists. This function may (and normally will) be called
+ * many times for large blocks of data.
+ *
+ * @param data The buffer containing the data to be hashed.
+ * @param length The number of bytes to be read from data
+ */
+
virtual void hash(unsigned char * data,
- unsigned int length);
// Hash some data
+ unsigned int length);
+
+ /**
+ * \brief Finish up a Digest operation and read the result.
+ *
+ * This call tells the CryptoHash object that the input is complete and
+ * to finalise the Digest. The output of the digest is read into the
+ * hash buffer (at most maxLength bytes)
+ *
+ * @param hash The buffer the hash should be read into.
+ * @param maxLength The maximum number of bytes to be read into hash
+ * @returns The number of bytes copied into the hash buffer
+ */
+
virtual unsigned int finish(unsigned char * hash,
unsigned int
maxLength);// Finish and get hash
- // Get information
+ //@}
+
+ /** @name Information functions */
+ //@{
+
+ /**
+ *\brief
+ *
+ * Determine the hash type of this object
+ *
+ * @returns The hash type
+ */
+
virtual HashType getHashType(void);
+
+ //@}
private:
1.2 +105 -8 xml-security/c/src/enc/WinCAPI/WinCAPICryptoHashHMAC.hpp
Index: WinCAPICryptoHashHMAC.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/WinCAPI/WinCAPICryptoHashHMAC.hpp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- WinCAPICryptoHashHMAC.hpp 7 Apr 2003 12:13:35 -0000 1.1
+++ WinCAPICryptoHashHMAC.hpp 15 Jun 2003 09:34:27 -0000 1.2
@@ -82,28 +82,125 @@
class WinCAPICryptoProvider;
+/**
+ * @ingroup wincapilcrypto
+ * @{
+ */
+
+/**
+ * \brief Implementation of HMAC Hash functions in the Windows providers
+ *
+ * Uses the Windows Crypt* API functions to implement an HMAC.
+ *
+ * Unfortunately the Windows Crypto API does not allow callers to enter an
+ * HMAC key directly. It relies on a seed being entered into a digest
+ * function that is then used to derive a key that can be used in an
+ * HMAC function.
+ *
+ * Two types of key can therefore be used - a direct Windows key, or
+ * a "standard" string as the HMAC key. In the latter case, the HMAC
+ * function is implemented internally around a standard Windows
+ * hash function. In the former case, the Windows HMAC functions are
+ * used. (The latter case is mainly for interoperability testing, where
+ * the key is provided and needs to be entered "as is".
+ *
+ */
+
class DSIG_EXPORT WinCAPICryptoHashHMAC : public XSECCryptoHash {
public :
- // Constructors/Destructors
+ /** @name Constructors and Destructors */
+ //@{
+
+ /**
+ * \brief Constructor
+ *
+ * Create the object, with the indicated algorithm
+ * (Currently supports MD5 and SHA1)
+ *
+ * @param alg Digest algorithm to use
+ */
WinCAPICryptoHashHMAC(WinCAPICryptoProvider * owner,
XSECCryptoHash::HashType alg);
virtual ~WinCAPICryptoHashHMAC();
- // Key activities
+ //@}
+
+ /** @name HMAC Functions */
+ //@{
+
+ /**
+ *\brief Set the HMAC key
+ *
+ * Sets the key - which needs to have a base class of
+ * WinCAPICryptoKeyHMAC.
+ *
+ * @param key The key the HMAC function should use.
+ */
+
virtual void setKey(XSECCryptoKey * key);
- // Hashing Activities
- virtual void reset(void);
// Reset the hash
+ //@}
+
+ /** @name Hash functions */
+ //@{
+
+ /**
+ * \brief Reset the hash function
+ *
+ * Re-initialises the digest structure.
+ */
+
+ virtual void reset(void);
+
+ /**
+ * \brief Hash some data.
+ *
+ * Take length bytes of data from the data buffer and update the hash
+ * that already exists. This function may (and normally will) be called
+ * many times for large blocks of data.
+ *
+ * @param data The buffer containing the data to be hashed.
+ * @param length The number of bytes to be read from data
+ */
+
virtual void hash(unsigned char * data,
- unsigned int length);
// Hash some data
+ unsigned int length);
+
+ /**
+ * \brief Finish up a Digest operation and read the result.
+ *
+ * This call tells the CryptoHash object that the input is complete and
+ * to finalise the Digest. The output of the digest is read into the
+ * hash buffer (at most maxLength bytes). This is effectively the
+ * signature for the data that has been run through the HMAC function.
+ *
+ * @param hash The buffer the hash should be read into.
+ * @param maxLength The maximum number of bytes to be read into hash
+ * @returns The number of bytes copied into the hash buffer
+ */
+
virtual unsigned int finish(unsigned char * hash,
- unsigned int
maxLength);// Finish and get hash
+ unsigned int
maxLength);
+
+ //@}
+
+ /** @name Information functions */
+ //@{
+
+ /**
+ *\brief
+ *
+ * Determine the hash type of this object
+ *
+ * @returns The hash type
+ */
- // Get information
virtual HashType getHashType(void);
+
+ //@}
private:
1.2 +164 -16 xml-security/c/src/enc/WinCAPI/WinCAPICryptoKeyDSA.hpp
Index: WinCAPICryptoKeyDSA.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/WinCAPI/WinCAPICryptoKeyDSA.hpp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- WinCAPICryptoKeyDSA.hpp 7 Apr 2003 12:13:35 -0000 1.1
+++ WinCAPICryptoKeyDSA.hpp 15 Jun 2003 09:34:27 -0000 1.2
@@ -81,17 +81,30 @@
class WinCAPICryptoProvider;
+/**
+ * \ingroup wincapicrypto
+ * @{
+ */
+
+/**
+ * \brief WinCAPI implementation class for DSA keys.
+ *
+ * The library uses classes derived from this to process DSA keys.
+ */
+
+
class DSIG_EXPORT WinCAPICryptoKeyDSA : public XSECCryptoKeyDSA {
public :
- // Constructors/Destructors
+ /** @name Constructors and Destructors */
+ //@{
WinCAPICryptoKeyDSA(WinCAPICryptoProvider * owner);
virtual ~WinCAPICryptoKeyDSA();
/**
- * \brief Dedicated WinCAPI constructor
+ * \brief WinCAPI Specific constructor
*
* Create a DSA key for use in XSEC from an existing HCRYPTKEY
*
@@ -105,39 +118,174 @@
WinCAPICryptoKeyDSA(WinCAPICryptoProvider * owner, HCRYPTKEY k, bool
havePrivate = false);
- // Generic key functions
+ //@}
+
+ /** @name Required Key Interface methods */
+ //@{
+
+ /**
+ * \brief Return the type of this key.
+ *
+ * Allows the caller (and library) to determine whether this is a
+ * public key, private key or a key pair
+ */
virtual XSECCryptoKey::KeyType getKeyType();
+
+ /**
+ *\brief Return the OpenSSL string identifier
+ */
+
virtual const XMLCh * getProviderName() {return
DSIGConstants::s_unicodeStrPROVWinCAPI;}
+
+ /**
+ * \brief Replicate key
+ */
+
virtual XSECCryptoKey * clone();
- // DSA Specific Functions
+ //@}
+
+ /** @name Required DSA methods */
+ //@{
+
+ /**
+ * \brief Create a signature
+ *
+ * Sign the buffer using the internal private key. Will throw a
DSAError
+ * if the key is not set, or is not a private key.
+ *
+ * @param hashBuf Buffer containing the pre-calculated (binary) digest
+ * @param hashLen Number of bytes of hash in the hashBuf
+ * @param base64SignatureBuf Buffer to place the base64 encoded result
+ * in.
+ * @param base64SignatureBufLen Implementations need to ensure they do
+ * not write more bytes than this into the buffer
+ */
+
+ virtual unsigned int signBase64Signature(unsigned char * hashBuf,
+ unsigned int hashLen,
+ char * base64SignatureBuf,
+ unsigned int
base64SignatureBufLen);
+
+ /**
+ * \brief Verify a signature
+ *
+ * The library will call this function to validate a signature
+ *
+ * @param hashBuf Buffer containing the pre-calculated (binary) digest
+ * @param hashLen Length of the data in the digest buffer
+ * @param base64Signature Buffer containing the Base64 encoded signature
+ * @param sigLen Length of the data in the signature buffer
+ * @returns true if the signature was valid, false otherwise
+ */
+
+ virtual bool verifyBase64Signature(unsigned char * hashBuf,
+ unsigned int hashLen,
+ char * base64Signature,
+ unsigned int sigLen);
+
+ //@}
+
+ /** @name Optional Interface methods
+ *
+ * Have been fully implemented in the OpenSSL interface to allow interop
+ * testing to occur.
+ *
+ */
+ //@{
+
+ /**
+ * \brief Load P
+ *
+ * @param b64 Base64 encoded parameter - read from XML document
+ * @param len Length of the encoded string
+ */
virtual void loadPBase64BigNums(const char * b64, unsigned int len);
+
+ /**
+ * \brief Load Q
+ *
+ * @param b64 Base64 encoded parameter - read from XML document
+ * @param len Length of the encoded string
+ */
+
virtual void loadQBase64BigNums(const char * b64, unsigned int len);
+
+ /**
+ * \brief Load G
+ *
+ * @param b64 Base64 encoded parameter - read from XML document
+ * @param len Length of the encoded string
+ */
+
virtual void loadGBase64BigNums(const char * b64, unsigned int len);
+
+ /**
+ * \brief Load Y
+ *
+ * @param b64 Base64 encoded parameter - read from XML document
+ * @param len Length of the encoded string
+ */
+
virtual void loadYBase64BigNums(const char * b64, unsigned int len);
+
+ /**
+ * \brief Load J
+ *
+ * @param b64 Base64 encoded parameter - read from XML document
+ * @param len Length of the encoded string
+ */
+
virtual void loadJBase64BigNums(const char * b64, unsigned int len);
- // Signatures
- virtual bool verifyBase64Signature(unsigned char * hashBuf,
- unsigned int hashLen,
- char * base64Signature,
- unsigned int sigLen);
+ //@}
- virtual unsigned int signBase64Signature(unsigned char * hashBuf,
- unsigned int hashLen,
- char * base64SignatureBuf,
- unsigned int base64SignatureBufLen);
+ /** @name WinCAPI Specific functions */
+ //@{
- // Some useful functions for extracting parameters from a Windows key
+ /**
+ * \brief Retrieve P
+ *
+ * @param b64 Buffer to place ds:CryptoBinary encoded P parameter in
+ * @len Max amount of data to be placed in buffer
+ * @returns The number of bytes placed in the buffer
+ */
unsigned int getPBase64BigNums(char * b64, unsigned int len);
+
+ /**
+ * \brief Retrieve Q
+ *
+ * @param b64 Buffer to place ds:CryptoBinary encoded Q parameter in
+ * @len Max amount of data to be placed in buffer
+ * @returns The number of bytes placed in the buffer
+ */
+
unsigned int getQBase64BigNums(char * b64, unsigned int len);
+
+ /**
+ * \brief Retrieve G
+ *
+ * @param b64 Buffer to place ds:CryptoBinary encoded G parameter in
+ * @len Max amount of data to be placed in buffer
+ * @returns The number of bytes placed in the buffer
+ */
+
unsigned int getGBase64BigNums(char * b64, unsigned int len);
- unsigned int getYBase64BigNums(char * b64, unsigned int len);
+ /**
+ * \brief Retrieve Y
+ *
+ * @param b64 Buffer to place ds:CryptoBinary encoded Y parameter in
+ * @len Max amount of data to be placed in buffer
+ * @returns The number of bytes placed in the buffer
+ */
+
+ unsigned int getYBase64BigNums(char * b64, unsigned int len);
+ //@}
private:
1.2 +99 -6 xml-security/c/src/enc/WinCAPI/WinCAPICryptoKeyHMAC.hpp
Index: WinCAPICryptoKeyHMAC.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/WinCAPI/WinCAPICryptoKeyHMAC.hpp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- WinCAPICryptoKeyHMAC.hpp 7 Apr 2003 12:13:35 -0000 1.1
+++ WinCAPICryptoKeyHMAC.hpp 15 Jun 2003 09:34:27 -0000 1.2
@@ -79,29 +79,122 @@
#include <wincrypt.h>
+/**
+ * \ingroup wincapicrypto
+ * @{
+ */
+
+/**
+ * \brief Windows Crypto API implementation for HMAC keys.
+ *
+ * Used to provide HMAC keys to WinCAPI CryptoHashHMAC
+ *
+ * Provides two types of key.
+ *
+ * A <b>Windows Key</b> (via setWinKey) is a direct key that can be used
+ * by the Windows HMAC implementation.
+ *
+ * A <b>byte</b> key (via setKey) is a string of bytes that will be used
+ * as a key. This requires an internal implementation of an HMAC using the
+ * Windows Digest functions, as the Windows API does not allow direct
+ * loading of these keys.
+ */
+
class DSIG_EXPORT WinCAPICryptoKeyHMAC : public XSECCryptoKeyHMAC {
public :
- // Constructors/Destructors
+ /** @name Constructors and Destructors */
+ //@{
WinCAPICryptoKeyHMAC();
virtual ~WinCAPICryptoKeyHMAC() {};
- virtual XSECCryptoKey * clone();
- // Generic key functions
+ //@}
+
+ /** @name Key Interface methods */
+ //@{
+
+ /**
+ * \brief Return the type of this key.
+ *
+ * For DSA keys, this allows people to determine whether this is a
+ * public key, private key or a key pair
+ */
virtual XSECCryptoKey::KeyType getKeyType() {return KEY_HMAC;}
+
+ /**
+ * \brief Replicate key
+ */
+
+ virtual XSECCryptoKey * clone();
+
+ /**
+ * \brief Return the WinCAPI string identifier
+ */
+
virtual const XMLCh * getProviderName() {return
DSIGConstants::s_unicodeStrPROVWinCAPI;}
- // HMAC Key functions
+ //@}
+
+ /** @name Optional Interface methods */
+ //@{
+
+ /**
+ * \brief Set the key
+ *
+ * Set the key from the buffer
+ *
+ * @param inBuf Buffer containing the direct bitwise representation of
the key
+ * @param inLength Number of bytes of key in the buffer
+ *
+ * @note isSensitive() should have been called on the inbound buffer
+ * to ensure the contents is overwritten when the safeBuffer is deleted
+ */
virtual void setKey(unsigned char * inBuf, unsigned int inLength);
+
+ /**
+ * \brief Get the key value
+ *
+ * Copy the key into the safeBuffer and return the number of bytes
+ * copied.
+ *
+ * @param outBuf Buffer to copy key into
+ * @returns number of bytes copied in
+ */
+
virtual unsigned int getKey(safeBuffer &outBuf);
- // Windows specific Key Functions
+ //@}
+
+ /** @name Windows specific keys */
+ //@{
+
+ /**
+ * \brief Set a Windows key
+ *
+ * Set a Windows Crypto key that has been either derived via the
+ * various Crypt functions or has been loaded from an encrypted BLOB
+ *
+ * @param k Windows CAPI key to load
+ */
+
void setWinKey(HCRYPTKEY k);
+
+ /**
+ * \brief Get a windows key
+ *
+ * Used by WinCAPICryptoHashHMAC to retrieve the key in order to
+ * load it into the HMAC function.
+ *
+ * @returns The key to use or 0 if this object does not hold one
+ */
+
HCRYPTKEY getWinKey(void);
+
+ //@}
private:
1.2 +136 -13 xml-security/c/src/enc/WinCAPI/WinCAPICryptoKeyRSA.hpp
Index: WinCAPICryptoKeyRSA.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/WinCAPI/WinCAPICryptoKeyRSA.hpp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- WinCAPICryptoKeyRSA.hpp 11 Apr 2003 12:24:06 -0000 1.1
+++ WinCAPICryptoKeyRSA.hpp 15 Jun 2003 09:34:27 -0000 1.2
@@ -81,12 +81,24 @@
class WinCAPICryptoProvider;
+/**
+ * \ingroup wincapicrypto
+ * @{
+ */
+
+/**
+ * \brief WinCAPI implementation of the interface class for RSA keys.
+ *
+ * The library uses classes derived from this to process RSA keys.
+ */
+
class DSIG_EXPORT WinCAPICryptoKeyRSA : public XSECCryptoKeyRSA {
public :
- // Constructors/Destructors
-
+ /** @name Constructors and Destructors */
+ //@{
+
WinCAPICryptoKeyRSA(WinCAPICryptoProvider * owner);
/**
@@ -106,37 +118,148 @@
virtual ~WinCAPICryptoKeyRSA();
- // Generic key functions
+ //@}
+
+ /** @name Key Interface methods */
+ //@{
+
+ /**
+ * \brief Return the type of this key.
+ *
+ * For RSA keys, this allows people to determine whether this is a
+ * public key, private key or a key pair
+ */
virtual XSECCryptoKey::KeyType getKeyType();
+
+ /**
+ * \brief Return the WinCAPI identifier string
+ */
+
virtual const XMLCh * getProviderName() {return
DSIGConstants::s_unicodeStrPROVWinCAPI;}
+
+ /**
+ * \brief Replicate key
+ */
+
virtual XSECCryptoKey * clone();
- // RSA Specific Functions
+ //@}
- virtual void loadPublicModulusBase64BigNums(const char * b64, unsigned
int len);
- virtual void loadPublicExponentBase64BigNums(const char * b64, unsigned
int len);
+ /** @name Mandatory RSA interface methods
+ *
+ * These classes are required by the library.
+ */
+ //@{
- // Signature functions
+ /**
+ * \brief Verify a SHA1 PKCS1 encoded signature
+ *
+ * The library will call this function to validate an RSA signature
+ * The standard by default uses SHA1 in a PKCS1 encoding.
+ *
+ * @param hashBuf Buffer containing the pre-calculated (binary) digest
+ * @param hashLen Length of the data in the digest buffer
+ * @param base64Signature Buffer containing the Base64 encoded signature
+ * @param sigLen Length of the data in the signature buffer
+ * @returns true if the signature was valid, false otherwise
+ */
virtual bool verifySHA1PKCS1Base64Signature(const unsigned char *
hashBuf,
unsigned int
hashLen,
const char *
base64Signature,
unsigned int
sigLen);
+ /**
+ * \brief Create a signature
+ *
+ * The library will call this function to create a signature from
+ * a pre-calculated digest. The output signature will
+ * be Base64 encoded such that it can be placed directly into the
+ * XML document
+ *
+ * @param hashBuf Buffer containing the pre-calculated (binary) digest
+ * @param hashLen Number of bytes of hash in the hashBuf
+ * @param base64SignatureBuf Buffer to place the base64 encoded result
+ * in.
+ * @param base64SignatureBufLen Implementations need to ensure they do
+ * not write more bytes than this into the buffer
+ */
+
virtual unsigned int signSHA1PKCS1Base64Signature(unsigned char *
hashBuf,
- unsigned int hashLen,
- char * base64SignatureBuf,
- unsigned int base64SignatureBufLen);
+ unsigned int
hashLen,
+ char *
base64SignatureBuf,
+ unsigned int
base64SignatureBufLen);
+
+ //@}
+
+ /** @name Optional Interface methods
+ *
+ * Have been implemented to allow interoperability testing
+ */
- // "Extra" WinCAPI functions
+ //@{
+
+ /**
+ * \brief Load the modulus
+ *
+ * Load the modulus from a Base64 encoded string
+ *
+ * param b64 A buffer containing the encoded string
+ * param len The length of the data in the buffer
+ */
+
+ virtual void loadPublicModulusBase64BigNums(const char * b64, unsigned
int len);
+
+ /**
+ * \brief Load the exponent
+ *
+ * Load the exponent from a Base64 encoded string
+ *
+ * param b64 A buffer containing the encoded string
+ * param len The length of the data in the buffer
+ */
+
+ virtual void loadPublicExponentBase64BigNums(const char * b64, unsigned
int len);
+
+ //@}
+
+ /** @name WinCAPI Specific Functions */
+ //@{
+
+ /**
+ * \brief Constructor that loads the Windows CAPI key directly
+ *
+ * @param k The key to load
+ */
WinCAPICryptoKeyRSA(HCRYPTKEY k);
- // Some useful functions for extracting parameters from a Windows key
+ /**
+ * \brief Retrieve the exponent
+ *
+ * Retrieves the exponent in ds:CryptoBinary encoded format
+ *
+ * @param b64 Buffer to place encoded exponent into
+ * @param len Maximum number of bytes to place in buffer
+ * @returns The number of bytes placed in the buffer
+ */
unsigned int getExponentBase64BigNums(char * b64, unsigned int len);
+
+ /**
+ * \brief Retrieve the modulus
+ *
+ * Retrieves the modulus in ds:CryptoBinary encoded format
+ *
+ * @param b64 Buffer to place the encoded modulus into
+ * @param len Maximum number of bytes to place in buffer
+ * @returns The number of bytes placed in the buffer
+ */
+
unsigned int getModulusBase64BigNums(char * b64, unsigned int len);
+
+ //@}
private:
1.3 +150 -15 xml-security/c/src/enc/WinCAPI/WinCAPICryptoProvider.hpp
Index: WinCAPICryptoProvider.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/WinCAPI/WinCAPICryptoProvider.hpp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- WinCAPICryptoProvider.hpp 11 Apr 2003 12:24:41 -0000 1.2
+++ WinCAPICryptoProvider.hpp 15 Jun 2003 09:34:27 -0000 1.3
@@ -83,12 +83,28 @@
#define WINCAPI_DSSSEEDLEN 0x18
#define WINCAPI_RSAPUBKEYLEN 0x0C
-
/**
* @defgroup wincapicrypto Windows Crypto API Interface
* @ingroup crypto
* The WinCAPI crypto provides an experimental inerface to
- * the Windows Cryptographic API
+ * the Windows Cryptographic API.
+ *
+ * All initialisation of the Windows providers needs to be done
+ * by the calling application. The interface will call the provided
+ * DSS (PROV_DSS) provider and RSA (PROV_RSA_FULL) provider to perform
+ * cryptographic functions.
+ *
+ * The tools use the default providers, but the calling application
+ * can use any providers that implement PROV_DSS and PROV_FULL_RSA.
+ *
+ * Note that, unlike the OpenSSL classes, the various implementation
+ * classes all require their owner provider class to be passed into
+ * the constructor. This allows them to access the RSA and DSS CAPI
+ * providers being used for the implementation.
+ *
+ * @todo Need to allow the various classes to over-ride the PROV
+ * objects to allow specific private key instances rather than one
+ * instance across the library instance.
*/
/[EMAIL PROTECTED]/
@@ -97,8 +113,8 @@
public :
- // Constructors/Destructors
-
+ /** @name Constructors and Destructors */
+ //@{
/**
* \brief Create a Windows CAPI interface layer
*
@@ -124,32 +140,149 @@
virtual ~WinCAPICryptoProvider();
- // Hashing classes
+ //@}
+
+ /** @name Hashing (Digest) Functions */
+ //@{
+
+ /**
+ * \brief Return a SHA1 implementation.
+ *
+ * Call used by the library to obtain a SHA1 object from the
+ * provider.
+ *
+ * @returns A pointer to an OpenSSL Hash object that implements SHA1
+ * @see WinCAPICryptoHash
+ */
+
virtual XSECCryptoHash * hashSHA1();
+
+ /**
+ * \brief Return a HMAC SHA1 implementation.
+ *
+ * Call used by the library to obtain a HMAC SHA1 object from the
+ * provider. The caller will need to set the key in the hash
+ * object with an XSECCryptoKeyHMAC using WinCAPICryptoHash::setKey()
+ *
+ * @returns A pointer to a Hash object that implements HMAC-SHA1
+ * @see WinCAPICryptoHash
+ */
+
virtual XSECCryptoHash * hashHMACSHA1();
+
+ /**
+ * \brief Return a MD5 implementation.
+ *
+ * Call used by the library to obtain a MD5 object from the
+ * OpenSSL provider.
+ *
+ * @returns A pointer to a Hash object that implements MD5
+ * @see WinCAPICryptoHash
+ */
+
virtual XSECCryptoHash * hashMD5();
+
+ /**
+ * \brief Return a HMAC MD5 implementation.
+ *
+ * Call used by the library to obtain a HMAC MD5 object from the
+ * provider. The caller will need to set the key in the hash
+ * object with an XSECCryptoKeyHMAC using XSECCryptoHash::setKey()
+ *
+ * @note The use of MD5 is explicitly marked as <b>not recommended</b>
+ * in the XML Digital Signature standard due to recent advances in
+ * cryptography indicating there <em>may</em> be weaknesses in the
+ * algorithm.
+ *
+ * @returns A pointer to a Hash object that implements HMAC-MD5
+ * @see WinCAPICryptoHash
+ */
+
virtual XSECCryptoHash * hashHMACMD5();
- // Encode/Decode
+ //@}
+
+ /** @name Encoding functions */
+ //@{
+
+ /**
+ * \brief Return a Base64 encoder/decoder implementation.
+ *
+ * Call used by the library to obtain a Base64
+ * encoder/decoder.
+ *
+ * @note Windows providers do not implement Base64, so the internal
+ * implementation (XSCrypt) is used instead.
+ *
+ *
+ * @returns Pointer to the new Base64 encoder.
+ * @see XSCryptCryptoBase64
+ */
+
virtual XSECCryptoBase64 * base64();
- // Keys
+ //@}
+
+ /** @name Keys and Certificates */
+ //@{
+
+ /**
+ * \brief Return a DSA key implementation object.
+ *
+ * Call used by the library to obtain a DSA key object.
+ *
+ * @returns Pointer to the new DSA key
+ * @see WinCAPICryptoKeyDSA
+ */
+
virtual XSECCryptoKeyDSA * keyDSA();
+
+ /**
+ * \brief Return an RSA key implementation object.
+ *
+ * Call used by the library to obtain an OpenSSL RSA key object.
+ *
+ * @returns Pointer to the new RSA key
+ * @see WinCAPICryptoKeyRSA
+ */
+
virtual XSECCryptoKeyRSA * keyRSA();
- // X509
+ /**
+ * \brief Return an X509 implementation object.
+ *
+ * Call used by the library to obtain an object that can work
+ * with X509 certificates.
+ *
+ * @returns Pointer to the new X509 object
+ * @see WinCAPICryptoX509
+ */
+
virtual XSECCryptoX509 * X509();
+ //@}
+
+ /** @name Windows CAPI Specific methods */
+ //@{
+
+ /**
+ * \brief Returns the Crypto Provider being used for DSS
+ */
- // WinCAPI Unique
HCRYPTPROV getProviderDSS(void) {return m_provDSS;}
+
+ /**
+ * \brief Returns the Provider being used for RSA functions
+ */
+
HCRYPTPROV getProviderRSA(void) {return m_provRSA;}
/**
* \brief Translate B64 I2OS integer to a WinCAPI int.
*
- * Decodes a Base64 integer and reverses the order to allow loading into
- * a Windows CAPI function. (CAPI uses Little Endian storage of
integers).
+ * Decodes a Base64 (ds:CryptoBinary) integer and reverses the order to
+ * allow loading into a Windows CAPI function. (CAPI uses Little
Endian
+ * storage of integers).
*
* @param b64 Base 64 string
* @param b64Len Length of base64 string
@@ -170,9 +303,7 @@
static unsigned char * WinBN2b64(BYTE * n, DWORD nLen, unsigned int
&retLen);
- /[EMAIL PROTECTED]/
-
-
+ //@}
private:
@@ -181,4 +312,8 @@
};
+/[EMAIL PROTECTED]/
+
+
#endif /* WINCAPICRYPTOPROVIDER_INCLUDE */
+
1.2 +56 -5 xml-security/c/src/enc/WinCAPI/WinCAPICryptoX509.hpp
Index: WinCAPICryptoX509.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/WinCAPI/WinCAPICryptoX509.hpp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- WinCAPICryptoX509.hpp 7 Apr 2003 12:13:35 -0000 1.1
+++ WinCAPICryptoX509.hpp 15 Jun 2003 09:34:27 -0000 1.2
@@ -79,25 +79,76 @@
class WinCAPICryptoProvider;
+/**
+ * \brief WinCAPI implementation class for interface for X509 certificates.
+ * @ingroup wincapicrypto
+ *
+ * The library uses classes derived from this to process X509 Certificates.
+ *
+ */
+
class DSIG_EXPORT WinCAPICryptoX509 : public XSECCryptoX509 {
public :
+ /** @name Constructors and Destructors */
+ //@{
+
WinCAPICryptoX509(WinCAPICryptoProvider * owner);
virtual ~WinCAPICryptoX509();
- // load functions
+ //@}
- virtual void loadX509Base64Bin(const char * buf, unsigned int len);
- // Info functions
+ //@}
+ /** @name Key Interface methods */
+ //@{
+
+ /**
+ * \brief Return the type of the key stored in the certificate.
+ *
+ * Will extract the key from the certificate to return the appropriate
+ * type
+ *
+ */
virtual XSECCryptoKey::KeyType getPublicKeyType();
- // Get functions
+ /**
+ * \brief Get a copy of the public key.
+ *
+ * Extracts the public key from the certificate and returns the
appropriate
+ * OpenSSLCryrptoKey (DSA or RSA) object
+ *
+ */
+
virtual XSECCryptoKey * clonePublicKey();
+
+ //@}
+
+ /** @name Load and Get the certificate */
+ //@{
+
+ /**
+ * \brief Load a certificate into the object.
+ *
+ * Take a base64 DER encoded certificate and load.
+ *
+ * @param buf A buffer containing the Base64 encoded certificate
+ * @param len The number of bytes of data in the certificate.
+ */
+
+ virtual void loadX509Base64Bin(const char * buf, unsigned int len);
+
+ /**
+ * \brief Get a Base64 DER encoded copy of the certificate
+ *
+ * @returns A safeBuffer containing the DER encoded certificate
+ */
+
virtual safeBuffer &getDEREncodingSB(void) {return m_DERX509;}
+ //@}
private:
1.2 +93 -8 xml-security/c/src/enc/XSCrypt/XSCryptCryptoBase64.hpp
Index: XSCryptCryptoBase64.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/enc/XSCrypt/XSCryptCryptoBase64.hpp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- XSCryptCryptoBase64.hpp 7 Apr 2003 12:11:54 -0000 1.1
+++ XSCryptCryptoBase64.hpp 15 Jun 2003 09:34:28 -0000 1.2
@@ -75,6 +75,17 @@
#include <xsec/enc/XSECCryptoBase64.hpp>
#include <xsec/utils/XSECSafeBuffer.hpp>
+ /**
+ * @defgroup xscryptcrypto Internal Crypto API Interface
+ * @ingroup crypto
+ * The XSCrypt Interface provides cryptographic functions that are missing
+ * from other libraries.
+ *
+ * Currently this only provides Base64 functionality which is not
+ * available in the Windows Crypto API.
+ *
+ */
+
class DSIG_EXPORT XSCryptCryptoBase64 : public XSECCryptoBase64 {
@@ -85,23 +96,97 @@
XSCryptCryptoBase64() : m_state(B64_UNINITIALISED) {};
virtual ~XSCryptCryptoBase64() {};
- // Decoding Activities
+ /** @name Decoding Functions */
+ //@{
+
+ /**
+ * \brief Initialise the base64 object.
+ *
+ * Initialises the OpenSSL decode context and gets ready for data
+ * to be decoded.
+ *
+ */
+
virtual void decodeInit(void);
// Setup
+
+ /**
+ * \brief Decode some passed in data.
+ *
+ * Decode the passed in data and place the data in the outData buffer
+ *
+ * @param inData Pointer to the buffer holding encoded data.
+ * @param inLength Length of the encoded data in the buffer
+ * @param outData Buffer to place decoded data into
+ * @param outLength Maximum amount of data that can be placed in
+ * the buffer.
+ * @returns The number of bytes placed in the outData buffer.
+ */
+
virtual unsigned int decode(unsigned char * inData,
unsigned int
inLength,
unsigned char *
outData,
- unsigned int
outLength); // decode
+ unsigned int
outLength);
+
+ /**
+ * \brief Finish off a decode.
+ *
+ * Clean out any extra data from previous decode operations and place
+ * into the outData buffer.
+ *
+ * @param outData Buffer to place any remaining decoded data
+ * @param outLength Max amount of data to be placed in the buffer.
+ * @returns Amount of data placed in the outData buffer
+ */
+
virtual unsigned int decodeFinish(unsigned char * outData,
- unsigned
int outLength);// Finish
+ unsigned
int outLength);
+
+ //@}
+
+ /** @name Encoding Functions */
+ //@{
+
+ /**
+ * \brief Initialise the base64 object for encoding
+ *
+ * Get the context variable ready for a base64 decode
+ *
+ */
+
+ virtual void encodeInit(void);
+
+ /**
+ * \brief Encode some passed in data.
+ *
+ * @param inData Pointer to the buffer holding data to be encoded.
+ * @param inLength Length of the data in the buffer
+ * @param outData Buffer to place encoded data into
+ * @param outLength Maximum amount of data that can be placed in
+ * the buffer.
+ * @returns The number of bytes placed in the outData buffer.
+ */
- // Encoding activities
- virtual void encodeInit(void);
// Setup
virtual unsigned int encode(unsigned char * inData,
unsigned int
inLength,
unsigned char *
outData,
- unsigned int
outLength); // decode
+ unsigned int
outLength);
+
+ /**
+ * \brief Finish off an encode.
+ *
+ * Take any data from previous encode operations and create the
+ * tail of the base64 encoding.
+ *
+ * @param outData Buffer to place any remaining encoded data
+ * @param outLength Max amount of data to be placed in the buffer.
+ * @returns Amount of data placed in the outData buffer
+ */
+
+
virtual unsigned int encodeFinish(unsigned char * outData,
- unsigned
int outLength); // Finish
+ unsigned
int outLength);
+
+ //@}
private :
