xsec/enc/XSECCryptoProvider.hpp - santuario-cpp - Git at Google

 /**
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements. See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership. The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License. You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied. See the License for the
  * specific language governing permissions and limitations
  * under the License.
  */

 /*
  * XSEC
  *
  * XSECCryptoProvider := Base virtual class to define a crpyto module
  *
  * Author(s): Berin Lautenbach
  *
  * $Id$
  *
  */

 #ifndef XSECCRYPTOPROVIDER_INCLUDE
 #define XSECCRYPTOPROVIDER_INCLUDE

 #include <xsec/framework/XSECDefs.hpp>
 #include <xsec/enc/XSECCryptoHash.hpp>
 #include <xsec/enc/XSECCryptoKeyHMAC.hpp>
 #include <xsec/enc/XSECCryptoBase64.hpp>
 #include <xsec/enc/XSECCryptoX509.hpp>
 #include <xsec/enc/XSECCryptoKeyDSA.hpp>
 #include <xsec/enc/XSECCryptoKeyEC.hpp>
 #include <xsec/enc/XSECCryptoKeyRSA.hpp>
 #include <xsec/enc/XSECCryptoSymmetricKey.hpp>

 /**
  * @defgroup crypto Cryptographic Abstraction Layer
  * <p>The interface layer between the cryptographic modules and the XML
  * Security library.  It has been created to allow users to easily
  * integrate other cryptographic libraries into the XML-Security
  * library.</p>
  *
  * <p>The XML-Security-C library itself makes calls to this interface
  * layer to perform all cryptographic procedures.  In order to
  * instantiate the correct object (i.e. the object
  * that belongs to the correct crypto library), XSEC makes calls to
  * the virtual class XSECCryptoProvider, which returns pointers to
  * particular virtual class objects.</p>
  *
  * <p>The cryptographic interface has been kept as thin as possible.
  * The classes are not meant to provide a complete
  * wrapper for the cryptographic libraries involved.  The application
  * program is expected to deal directly with the chosen library.  This
  * ensures that the xml-security library can perform the functions it
  * needs to, but does not constrain the application in what it can do.</p>
  *
  * <p>Therefore, three type of methods are available on any cryptographic
  * class.</p>
  *
  * <ul>
  * <li><em>Required</em> methods are those absolutely necessary for
  * the library to operate.  For example, these include the methods
  * necessary for the library to decode a base64 encoded signature
  * and validate it against a defined key.</li>
  * <li><em>Optional</em> methods are used by the ancillary classes
  * in the library.  For example, the default KeyInfoResolver can
  * use an optional method to extract a public key from a certificate.
  * This is not strictly necessary, as the calling application could
  * provide a resolver that does this work directly rather than using
  * the XSECCryptoX509 class.</li>
  * <li><em>Library Specific</em> methods are those methods that are
  * unique to a particular library.  For example, the OpenSSLCryptoX509
  * class has a Library Specific constructor that takes an OpenSSL
  * X509 structure as its argument.</li>
  * </ul>
  *
  * <p>Unless marked otherwise, all methods defined in the XSECCrypto*
  * classes are <em>Required</em>.</p>
  *
  * <p>The particular instantiation of XSECCryptoProvider that is to
  * be used is set via the XSECPlatformUtils#Initialise() function
  * call.  If no provider is passed in, the Initialise function
  * generates an OpenSSLCryptoProvider class for use.  If OpenSSL
  * is not available under windows, the library will use the Windows
  * CAPI instead.</p>
  *
  * <p>The provider is kept in a global variable, and is used by
  * all signature objects created by a particular application.  At
  * this time there is no way to have different signature
  * objects use different CryptoProviders</p>
  *
  * @todo Add an ability to better handle "optional" functions.  The library
  * should make a call to the
  * provider to see whether an optional function (e.g. extract key from
  * X509) has been
  * provided.
  *
  *
  *\@{*/

 // Some constants

 /**
  *\brief Maximum length (in bytes) of any expected Digest results.
  *
  * This constant defines the maximum length (in bytes) of HASH returns.
  * We have defined it far and above the size we would normally expect.
  *
  * @todo This should really come from each of the providers and should
  * be implemented as a function call to *CryptoProvider
  */

 #define CRYPTO_MAX_HASH_SIZE		128

 /**
  *\brief OID For DSA
  */

 #define CRYPTO_OID_DSA				"1.2.840.10040.4.1"

 /**
  *\brief The base class that all *CryptoProviders need to implement.
  *
  * The instatiations of this class are used by the core library to
  * create cryptographic objects necessary for the library to do its work
  * without actually knowing any details at all about the provider library
  *
  * @note Subject to change
  * @see OpenSSLCryptoProvider
  */

 class DSIG_EXPORT XSECCryptoProvider {


 public :

 	/** @name Constructors and Destructors */
 	//@{

 	XSECCryptoProvider() {};
 	virtual ~XSECCryptoProvider() {};
 	//@}


 	/** @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 a Hash object that implements SHA1
 	 * @see XSECCryptoHash
 	 * @deprecated Use hashSHA instead
 	 */

 	virtual XSECCryptoHash			* hashSHA1() const = 0;

 	/**
 	 * \brief Return a SHA implementation.
 	 *
 	 * Call used by the library to obtain a SHA object from the
 	 * provider.  Size of hash determined by length argument (160 = SHA1)
 	 *
 	 * @returns A pointer to a Hash object that implements SHA1
 	 * @param length - length of hash.  E.g. 160 for SHA1 or 256 for SHA256
 	 * @see XSECCryptoHash
 	 */

 	virtual XSECCryptoHash			* hashSHA(int length = 160) const = 0;

 	/**
 	 * \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 XSECCryptoHash::setKey()
 	 *
 	 * @returns A pointer to a Hash object that implements HMAC-SHA1
 	 * @see XSECCryptoHash
 	 * @deprecated use hashHMACSHA instead
 	 */

 	virtual XSECCryptoHash			* hashHMACSHA1() const = 0;

 	/**
 	 * \brief Return a HMAC SHA(1-512) implementation.
 	 *
 	 * Call used by the library to obtain a HMAC SHA object from the
 	 * provider.  The caller will need to set the key in the hash
 	 * object with an XSECCryptoKeyHMAC using XSECCryptoHash::setKey()
 	 *
 	 * @returns A pointer to a Hash object that implements HMAC-SHA1
 	 * @param length Length of hash output (160 = SHA1, 256, 512 etc)
 	 * @see XSECCryptoHash
 	 */

 	virtual XSECCryptoHash			* hashHMACSHA(int length = 160) const = 0;

 	/**
 	 * \brief Return a MD5 implementation.
 	 *
 	 * Call used by the library to obtain a MD5 object from the
 	 * provider.
 	 *
 	 * @returns A pointer to a Hash object that implements MD5
 	 * @see XSECCryptoHash
 	 */

 	virtual XSECCryptoHash			* hashMD5() const = 0;

 	/**
 	 * \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 XSECCryptoHash
 	 */

 	virtual XSECCryptoHash			* hashHMACMD5() const = 0;

 	/**
 	 * \brief Return a HMAC key
 	 *
 	 * Sometimes the library needs to create an HMAC key (notably within
 	 * the XKMS utilities.
 	 *
 	 * This function allows the library to obtain a key that can then have
 	 * a value set within it.
 	 */

 	virtual XSECCryptoKeyHMAC		* keyHMAC() const = 0;

 	//@}

 	/** @name Encoding functions */
 	//@{

 	/**
 	 * \brief Return a Base64 encoder/decoder implementation.
 	 *
 	 * Call used by the library to obtain a Base64 encoder/decoder.
 	 *
 	 * @returns Pointer to the new Base64 encoder.
 	 * @see XSECCryptoBase64
 	 */

 	virtual XSECCryptoBase64		* base64() const = 0;

 	//@}

 	/** @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 XSECCryptoKeyDSA
 	 */

 	virtual XSECCryptoKeyDSA		* keyDSA() const = 0;

 	/**
 	 * \brief Return an RSA key implementation object.
 	 *
 	 * Call used by the library to obtain an RSA key object.
 	 *
 	 * @returns Pointer to the new RSA key
 	 * @see XSECCryptoKeyRSA
 	 */

 	virtual XSECCryptoKeyRSA		* keyRSA() const = 0;

 	/**
 	 * \brief Return an EC key implementation object.
 	 *
 	 * Call used by the library to obtain an EC key object.
 	 *
 	 * @returns Pointer to the new EC key
 	 * @see XSECCryptoKeyEC
 	 */

 	virtual XSECCryptoKeyEC         * keyEC() const;

 	/**
 	 * \brief Return a key implementation object based on DER-encoded input.
 	 *
 	 * Call used by the library to obtain a key object from a DER-encoded key.
 	 *
      * @param buf       DER-encoded data
      * @param buflen    length of data
      * @param base64    true iff data is base64-encoded
 	 * @returns Pointer to the new key
 	 * @see XSECCryptoKey
 	 */

 	virtual XSECCryptoKey         * keyDER(const char* buf, unsigned long buflen, bool base64) const;

     /**
 	 * \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 XSECCryptoX509
 	 */

 	virtual XSECCryptoX509			* X509() const = 0;

 	/**
 	 * \brief Determine whether a given algorithm is supported
 	 *
 	 * A call that can be used to determine whether a given
 	 * symmetric algorithm is supported
 	 */

 	virtual bool algorithmSupported(XSECCryptoSymmetricKey::SymmetricKeyType alg) const = 0;

 	/**
 	 * \brief Determine whether a given algorithm is supported
 	 *
 	 * A call that can be used to determine whether a given
 	 * digest algorithm is supported
 	 */

 	virtual bool algorithmSupported(XSECCryptoHash::HashType alg) const = 0;

 	/**
 	 * \brief Return a Symmetric Key implementation object.
 	 *
 	 * Call used by the library to obtain a bulk encryption
 	 * object.
 	 *
 	 * @returns Pointer to the new SymmetricKey object
 	 * @see XSECCryptoSymmetricKey
 	 */

 	virtual XSECCryptoSymmetricKey	* keySymmetric(XSECCryptoSymmetricKey::SymmetricKeyType alg) const = 0;

 	/**
 	 * \brief Obtain some random octets
 	 *
 	 * For generation of IVs and the like, the library needs to be able
 	 * to obtain "random" octets.  The library uses this call to the
 	 * crypto provider to obtain what it needs.
 	 *
 	 * @param buffer The buffer to place the random data in
 	 * @param numOctets Number of bytes required
 	 * @returns Number of bytes obtained.
 	 */

 	virtual unsigned int getRandom(unsigned char * buffer, unsigned int numOctets) const = 0;

 	//@}

 	/** @name Information Functions */
 	//@{

 	/**
 	 * \brief Returns a string that identifies the Crypto Provider
 	 */

 	virtual const XMLCh * getProviderName() const = 0;

 	//@}

 	/*\@}*/
 };


 #endif /* XSECCRYPTOPROVIDER_INCLUDE */
	/**
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the
	* "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing,
	* software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	* KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations
	* under the License.
	*/

	/*
	* XSEC
	*
	* XSECCryptoProvider := Base virtual class to define a crpyto module
	*
	* Author(s): Berin Lautenbach
	*
	* $Id$
	*
	*/

	#ifndef XSECCRYPTOPROVIDER_INCLUDE
	#define XSECCRYPTOPROVIDER_INCLUDE

	#include <xsec/framework/XSECDefs.hpp>
	#include <xsec/enc/XSECCryptoHash.hpp>
	#include <xsec/enc/XSECCryptoKeyHMAC.hpp>
	#include <xsec/enc/XSECCryptoBase64.hpp>
	#include <xsec/enc/XSECCryptoX509.hpp>
	#include <xsec/enc/XSECCryptoKeyDSA.hpp>
	#include <xsec/enc/XSECCryptoKeyEC.hpp>
	#include <xsec/enc/XSECCryptoKeyRSA.hpp>
	#include <xsec/enc/XSECCryptoSymmetricKey.hpp>

	/**
	* @defgroup crypto Cryptographic Abstraction Layer
	* <p>The interface layer between the cryptographic modules and the XML
	* Security library. It has been created to allow users to easily
	* integrate other cryptographic libraries into the XML-Security
	* library.</p>
	*
	* <p>The XML-Security-C library itself makes calls to this interface
	* layer to perform all cryptographic procedures. In order to
	* instantiate the correct object (i.e. the object
	* that belongs to the correct crypto library), XSEC makes calls to
	* the virtual class XSECCryptoProvider, which returns pointers to
	* particular virtual class objects.</p>
	*
	* <p>The cryptographic interface has been kept as thin as possible.
	* The classes are not meant to provide a complete
	* wrapper for the cryptographic libraries involved. The application
	* program is expected to deal directly with the chosen library. This
	* ensures that the xml-security library can perform the functions it
	* needs to, but does not constrain the application in what it can do.</p>
	*
	* <p>Therefore, three type of methods are available on any cryptographic
	* class.</p>
	*
	* <ul>
	* <li><em>Required</em> methods are those absolutely necessary for
	* the library to operate. For example, these include the methods
	* necessary for the library to decode a base64 encoded signature
	* and validate it against a defined key.</li>
	* <li><em>Optional</em> methods are used by the ancillary classes
	* in the library. For example, the default KeyInfoResolver can
	* use an optional method to extract a public key from a certificate.
	* This is not strictly necessary, as the calling application could
	* provide a resolver that does this work directly rather than using
	* the XSECCryptoX509 class.</li>
	* <li><em>Library Specific</em> methods are those methods that are
	* unique to a particular library. For example, the OpenSSLCryptoX509
	* class has a Library Specific constructor that takes an OpenSSL
	* X509 structure as its argument.</li>
	* </ul>
	*
	* <p>Unless marked otherwise, all methods defined in the XSECCrypto*
	* classes are <em>Required</em>.</p>
	*
	* <p>The particular instantiation of XSECCryptoProvider that is to
	* be used is set via the XSECPlatformUtils#Initialise() function
	* call. If no provider is passed in, the Initialise function
	* generates an OpenSSLCryptoProvider class for use. If OpenSSL
	* is not available under windows, the library will use the Windows
	* CAPI instead.</p>
	*
	* <p>The provider is kept in a global variable, and is used by
	* all signature objects created by a particular application. At
	* this time there is no way to have different signature
	* objects use different CryptoProviders</p>
	*
	* @todo Add an ability to better handle "optional" functions. The library
	* should make a call to the
	* provider to see whether an optional function (e.g. extract key from
	* X509) has been
	* provided.
	*
	*
	\@{/

	// Some constants

	/**
	*\brief Maximum length (in bytes) of any expected Digest results.
	*
	* This constant defines the maximum length (in bytes) of HASH returns.
	* We have defined it far and above the size we would normally expect.
	*
	* @todo This should really come from each of the providers and should
	* be implemented as a function call to *CryptoProvider
	*/

	#define CRYPTO_MAX_HASH_SIZE 128

	/**
	*\brief OID For DSA
	*/

	#define CRYPTO_OID_DSA "1.2.840.10040.4.1"

	/**
	\brief The base class that all CryptoProviders need to implement.
	*
	* The instatiations of this class are used by the core library to
	* create cryptographic objects necessary for the library to do its work
	* without actually knowing any details at all about the provider library
	*
	* @note Subject to change
	* @see OpenSSLCryptoProvider
	*/

	class DSIG_EXPORT XSECCryptoProvider {


	public :

	/** @name Constructors and Destructors */
	//@{

	XSECCryptoProvider() {};
	virtual ~XSECCryptoProvider() {};
	//@}


	/** @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 a Hash object that implements SHA1
	* @see XSECCryptoHash
	* @deprecated Use hashSHA instead
	*/

	virtual XSECCryptoHash * hashSHA1() const = 0;

	/**
	* \brief Return a SHA implementation.
	*
	* Call used by the library to obtain a SHA object from the
	* provider. Size of hash determined by length argument (160 = SHA1)
	*
	* @returns A pointer to a Hash object that implements SHA1
	* @param length - length of hash. E.g. 160 for SHA1 or 256 for SHA256
	* @see XSECCryptoHash
	*/

	virtual XSECCryptoHash * hashSHA(int length = 160) const = 0;

	/**
	* \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 XSECCryptoHash::setKey()
	*
	* @returns A pointer to a Hash object that implements HMAC-SHA1
	* @see XSECCryptoHash
	* @deprecated use hashHMACSHA instead
	*/

	virtual XSECCryptoHash * hashHMACSHA1() const = 0;

	/**
	* \brief Return a HMAC SHA(1-512) implementation.
	*
	* Call used by the library to obtain a HMAC SHA object from the
	* provider. The caller will need to set the key in the hash
	* object with an XSECCryptoKeyHMAC using XSECCryptoHash::setKey()
	*
	* @returns A pointer to a Hash object that implements HMAC-SHA1
	* @param length Length of hash output (160 = SHA1, 256, 512 etc)
	* @see XSECCryptoHash
	*/

	virtual XSECCryptoHash * hashHMACSHA(int length = 160) const = 0;

	/**
	* \brief Return a MD5 implementation.
	*
	* Call used by the library to obtain a MD5 object from the
	* provider.
	*
	* @returns A pointer to a Hash object that implements MD5
	* @see XSECCryptoHash
	*/

	virtual XSECCryptoHash * hashMD5() const = 0;

	/**
	* \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 XSECCryptoHash
	*/

	virtual XSECCryptoHash * hashHMACMD5() const = 0;

	/**
	* \brief Return a HMAC key
	*
	* Sometimes the library needs to create an HMAC key (notably within
	* the XKMS utilities.
	*
	* This function allows the library to obtain a key that can then have
	* a value set within it.
	*/

	virtual XSECCryptoKeyHMAC * keyHMAC() const = 0;

	//@}

	/** @name Encoding functions */
	//@{

	/**
	* \brief Return a Base64 encoder/decoder implementation.
	*
	* Call used by the library to obtain a Base64 encoder/decoder.
	*
	* @returns Pointer to the new Base64 encoder.
	* @see XSECCryptoBase64
	*/

	virtual XSECCryptoBase64 * base64() const = 0;

	//@}

	/** @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 XSECCryptoKeyDSA
	*/

	virtual XSECCryptoKeyDSA * keyDSA() const = 0;

	/**
	* \brief Return an RSA key implementation object.
	*
	* Call used by the library to obtain an RSA key object.
	*
	* @returns Pointer to the new RSA key
	* @see XSECCryptoKeyRSA
	*/

	virtual XSECCryptoKeyRSA * keyRSA() const = 0;

	/**
	* \brief Return an EC key implementation object.
	*
	* Call used by the library to obtain an EC key object.
	*
	* @returns Pointer to the new EC key
	* @see XSECCryptoKeyEC
	*/

	virtual XSECCryptoKeyEC * keyEC() const;

	/**
	* \brief Return a key implementation object based on DER-encoded input.
	*
	* Call used by the library to obtain a key object from a DER-encoded key.
	*
	* @param buf DER-encoded data
	* @param buflen length of data
	* @param base64 true iff data is base64-encoded
	* @returns Pointer to the new key
	* @see XSECCryptoKey
	*/

	virtual XSECCryptoKey * keyDER(const char* buf, unsigned long buflen, bool base64) const;

	/**
	* \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 XSECCryptoX509
	*/

	virtual XSECCryptoX509 * X509() const = 0;

	/**
	* \brief Determine whether a given algorithm is supported
	*
	* A call that can be used to determine whether a given
	* symmetric algorithm is supported
	*/

	virtual bool algorithmSupported(XSECCryptoSymmetricKey::SymmetricKeyType alg) const = 0;

	/**
	* \brief Determine whether a given algorithm is supported
	*
	* A call that can be used to determine whether a given
	* digest algorithm is supported
	*/

	virtual bool algorithmSupported(XSECCryptoHash::HashType alg) const = 0;

	/**
	* \brief Return a Symmetric Key implementation object.
	*
	* Call used by the library to obtain a bulk encryption
	* object.
	*
	* @returns Pointer to the new SymmetricKey object
	* @see XSECCryptoSymmetricKey
	*/

	virtual XSECCryptoSymmetricKey * keySymmetric(XSECCryptoSymmetricKey::SymmetricKeyType alg) const = 0;

	/**
	* \brief Obtain some random octets
	*
	* For generation of IVs and the like, the library needs to be able
	* to obtain "random" octets. The library uses this call to the
	* crypto provider to obtain what it needs.
	*
	* @param buffer The buffer to place the random data in
	* @param numOctets Number of bytes required
	* @returns Number of bytes obtained.
	*/

	virtual unsigned int getRandom(unsigned char * buffer, unsigned int numOctets) const = 0;

	//@}

	/** @name Information Functions */
	//@{

	/**
	* \brief Returns a string that identifies the Crypto Provider
	*/

	virtual const XMLCh * getProviderName() const = 0;

	//@}

	/\@}/
	};


	#endif /* XSECCRYPTOPROVIDER_INCLUDE */