/**
 * 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 OID For DSA
 */

#define CRYPTO_OID_DSA "1.2.840.10040.4.1"

/**
 *\brief The base class that all *CryptoProviders need to implement.
 *
 * The instantiations 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
 */

class XSEC_EXPORT XSECCryptoProvider {


public :

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

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


    /** @name Hashing (Digest) Functions */
    //@{

    /**
     * \brief Get the provider's maximum digest length.
     *
     * Call used by the library to max out the buffer sizes it uses.
     *
     * @returns maximum size to allow for
     */
    virtual unsigned int getMaxHashSize() const = 0;

    /**
     * \brief Return a hashing implementation.
     *
     * Call used by the library to obtain a hashing implementation from the
     * provider.
     *
     * @param uri hashing algorithm identifier
     * @returns a pointer to a hashing object
     */
    virtual XSECCryptoHash* hash(const XMLCh* uri) const;

    /**
     * \brief Return a hashing implementation.
     *
     * Call used by the library to obtain a hashing implementation from the
     * provider.
     *
     * @param type enumerated hashing algorithm
     * @returns a pointer to a hashing object
     */
    virtual XSECCryptoHash* hash(XSECCryptoHash::HashType type) const = 0;

    /**
     * \brief Return an HMAC implementation.
     *
     * Call used by the library to obtain an HMAC implementation from the
     * provider.  The caller will need to set the key in the hash
     * object with an XSECCryptoKeyHMAC using XSECCryptoHash::setKey().
     *
     * @param uri hashing algorithm identifier
     * @returns a pointer to the hashing object
     */
    virtual XSECCryptoHash* HMAC(const XMLCh* uri) const;

    /**
     * \brief Return an HMAC implementation.
     *
     * Call used by the library to obtain an HMAC implementation from the
     * provider.  The caller will need to set the key in the hash
     * object with an XSECCryptoKeyHMAC using XSECCryptoHash::setKey().
     *
     * @param type enumerated hashing algorithm
     * @returns a pointer to the hashing object
     */
    virtual XSECCryptoHash* HMAC(XSECCryptoHash::HashType type) 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 = 0;

    /**
     * \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 = 0;

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