/*

* Copyright (c) 2006-2006 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:       Class with methods used in encryption and decryption process.

*

*/

#ifndef C_ENCRYPT_H

#define C_ENCRYPT_H

#include <e32base.h>

#include <f32file.h>

#include <xmlengdocument.h>

class CXmlSecKeyManager;

/**

 *  Class used to encrypt/decrypt data.

 *

 *  How to use:

 *  

 *  Encryption:

 *  <pre>

 *  1. Create new object:

 *          CXmlSecEncrypt* enc = CXmlSecEncrypt::NewLC();      

 *  2. Set the key that should be used during encryption: 

 *          enc->SetKeyFromFileL(filename, keyname, CXmlSecEncrypt::E3DES);

 *  3. Set template for encryption: 

 *          enc->SetTemplateFromFileL(templatefile);

 *  4. Encrypt data from buffer:

 *          doc = enc->EncryptDataL(data);

 *     data will be added to template or encrypt xml node: 

 *	        enc->EncryptXmlNodeL(doc.DocumentElement()); 

 *     node will be replaced by template with encrypted data

 *  </pre>

 *  

 *  Decryption:

 *  <pre>

 *  1. Create new object:

 *          CXmlSecEncrypt* enc = CXmlSecEncrypt::NewLC();

 *  2. Set the key that should be used during decryption:  

 *          enc->SetKeyFromFileL(keyfile,keyname,CXmlSecEncrypt::EAES256);

 *  3. Decrypt xml node:

 *          enc->DecryptXmlNodeL(doc.DocumentElement()); 

 *   Function will replace encryption template with encrypted data. If result of encryption will

 *   not be a document then result will be returned as HBufC8*.

 *  </pre>

 *   

 *  @note Key should be set before encryption

 *

 *  @lib XmlSecWrapper.dll

 *  @since S60 v3.2

 */

class CXmlSecEncrypt : public CBase

    {

public:

    /**

     * Key types.

     * Currently symmetric key (AES (256 bit) or 3DES)

     */

    enum TXmlSecKeyType

        {

        EAES256 = 0,

        E3DES

        };

    /**

     * Encryption data types

     */

    enum TXmlSecDataType

        {

        ENode = 0,

        ENodeContent,

        EData

        };

public:

    /**

     * Creates new object.

     *

     * @since S60 v3.2

     * @return pointer to new object

     */

    IMPORT_C static CXmlSecEncrypt* NewL();

    /**

     * Creates new object and puts it on cleanup stack.

     *

     * @since S60 v3.2

     * @return pointer to new object

     */

    IMPORT_C static CXmlSecEncrypt* NewLC();

    /**

     * Destructor.

     *

     * @since S60 v3.2

     */

    virtual ~CXmlSecEncrypt();

    /**

     * Encrypts data from buffer.

     *

     * @since S60 v3.2

     * @param aData data that should be encrypted

     * @return xml document with encrypted data

     */

    IMPORT_C RXmlEngDocument EncryptDataL(const TDesC8& aData);

    /**

     * Encrypts xml document.

     *

     * @since S60 v3.2

     * @param aDocument xml document that should be encrypted.

     *

     * @note Encrypted content will replace aDocument content.

     *       aDocument contains the result.

     */

    IMPORT_C void EncryptXmlDocumentL(RXmlEngDocument& aDocument);

    /**

     * Encrypts xml node.

     *

     * @since S60 v3.2

     * @param aNode xml node that should be encrypted.

     *

     * @note Encrypted content will replace aNode.

     *       aNode contains the result.

     */

    IMPORT_C void EncryptXmlNodeL(TXmlEngElement aNode);

    /**

     * Encrypts xml node.

     *

     * @since S60 v3.2

     * @param aNode xml node that should be encrypted.

     * @param aTemplate DOM tree with template document

     * @param aKeyFile name of the file with key inside 

     * @param aKeyName name of the key. In case of AES and 3DES it can be null.

     * @param aKeyFormat key algorithm (i.e. AES)

     *

     * @note Encrypted content will replace aNode.

     *       aNode contains the result.

     */

    IMPORT_C void EncryptXmlNodeKeyFromFileL(TXmlEngElement aNode,

                                             RXmlEngDocument& aTemplate,

                                             const TDesC8& aKeyFile,

                                             const TDesC8& aKeyName,

                                             TXmlSecKeyType aKeyType);

    /**

     * Encrypts xml document.

     *

     * @since S60 v3.2

     * @param aDocument xml document that should be encrypted.

     * @param aTemplate DOM tree with template document

     * @param aKeyFile name of the file with key inside 

     * @param aKeyName name of the key. In case of AES and 3DES it can be null.

     * @param aKeyFormat key algorithm (i.e. AES)

     *

     * @note Encrypted content will replace aNode.

     *       aNode contains the result.

     */

    IMPORT_C void EncryptXmlDocumentKeyFromFileL(RXmlEngDocument& aDoc,

                                                 RXmlEngDocument& aTemplate,

                                                 const TDesC8& aKeyFile,

                                                 const TDesC8& aKeyName,

                                                 TXmlSecKeyType aKeyType);

    /**

     * Encrypts xml node.

     *

     * @since S60 v3.2

     * @param aNode xml node that should be encrypted.

     * @param aTemplate DOM tree with template document

     * @param aKey buffer with key inside 

     * @param aKeyName name of the key. In case of AES and 3DES it can be null.

     * @param aKeyFormat key algorithm (i.e. AES)

     *

     * @note Encrypted content will replace aNode.

     *       aNode contains the result.

     */

    IMPORT_C void EncryptXmlNodeKeyFromBufferL(TXmlEngElement aNode,

                                               RXmlEngDocument& aTemplate,

                                               const TDesC8& aKeyFile,

                                               const TDesC8& aKeyName,

                                               TXmlSecKeyType aKeyType);

    /**

     * Encrypts xml document.

     *

     * @since S60 v3.2

     * @param aDocument xml document that should be encrypted.

     * @param aTemplate DOM tree with template document

     * @param aKey buffer with key inside 

     * @param aKeyName name of the key. In case of AES and 3DES it can be null.

     * @param aKeyFormat key algorithm (i.e. AES)

     *

     * @note Encrypted content will replace aNode.

     *       aNode contains the result.

     */

    IMPORT_C void EncryptXmlDocumentKeyFromBufferL(RXmlEngDocument& aDoc,

                                                   RXmlEngDocument& aTemplate,

                                                   const TDesC8& aKey,

                                                   const TDesC8& aKeyName,

                                                   TXmlSecKeyType aKeyType);

    /**

     * Decrypts data contained in a node.

     *

     * @since S60 v3.2

     * @param aNode <EncryptedData> element (see XML Encryption recommendation)

     * @return Decryption result. If xml data will be a result then it will replace aNode content

     *         and null will be returned. If result type will be different then result will be returned

     *         in HBufC8 pointer.

     */

    IMPORT_C HBufC8* DecryptXmlNodeL(TXmlEngElement aNode);

    /**

     * Decrypts data contained in xml DOM tree.

     *

     * @since S60 v3.2

     * @param aDocument DOM tree with encrypted data

     * @return Decryption result. If xml data will be a result then it will replace aDocument content

     *         and null will be returned. If result type will be different then result will be returned

     *         in HBufC8 pointer.

     */

    IMPORT_C HBufC8* DecryptXmlDocumentL(RXmlEngDocument& aDocument);

    /**

     * Decrypts xml node.

     *

     * @since S60 v3.2

     * @param aNode xml node that should be decrypted.

     * @param aKeyFile name of the file with key inside 

     * @param aKeyName name of the key. In case of AES and 3DES it can be null.

     * @param aKeyFormat key algorithm (i.e. AES)

     * @return Decryption result. If xml data will be a result then it will replace aDocument content

     *         and null will be returned. If result type will be different then result will be returned

     *         in HBufC8 pointer.

     */

    IMPORT_C HBufC8* DecryptXmlNodeKeyFromFileL(TXmlEngElement aNode,

                                                const TDesC8& aKeyFile,

                                                const TDesC8& aKeyName,

                                                TXmlSecKeyType aKeyType);

    /**

     * Decrypts xml document.

     *

     * @since S60 v3.2

     * @param aDocument xml document that should be decrypted.

     * @param aKeyFile name of the file with key inside 

     * @param aKeyName name of the key. In case of AES and 3DES it can be null.

     * @param aKeyFormat key algorithm (i.e. AES)

     * @return Decryption result. If xml data will be a result then it will replace aDocument content

     *         and null will be returned. If result type will be different then result will be returned

     *         in HBufC8 pointer.

     */

    IMPORT_C HBufC8* DecryptXmlDocumentKeyFromFileL(RXmlEngDocument& aDocument,

                                                    const TDesC8& aKeyFile,

                                                    const TDesC8& aKeyName,

                                                    TXmlSecKeyType aKeyType);

    /**

     * Decrypts xml node.

     *

     * @since S60 v3.2

     * @param aNode xml node that should be decrypted.

     * @param aKey buffer with key inside 

     * @param aKeyName name of the key. In case of AES and 3DES it can be null.

     * @param aKeyFormat key algorithm (i.e. AES)

     * @return Decryption result. If xml data will be a result then it will replace aDocument content

     *         and null will be returned. If result type will be different then result will be returned

     *         in HBufC8 pointer.

     */

    IMPORT_C HBufC8* DecryptXmlNodeKeyFromBufferL(TXmlEngElement aNode,

                                                  const TDesC8& aKey,

                                                  const TDesC8& aKeyName,

                                                  TXmlSecKeyType aKeyType);

    /**

     * Decrypts xml document.

     *

     * @since S60 v3.2

     * @param aDocument xml document that should be decrypted.

     * @param aKey buffer with key inside 

     * @param aKeyName name of the key. In case of AES and 3DES it can be null.

     * @param aKeyFormat key algorithm (i.e. AES)

     * @return Decryption result. If xml data will be a result then it will repleace aDocument content

     *         and null will be returned. If result type will be different then result will be returned

     *         in HBufC8 pointer.

     */

    IMPORT_C HBufC8* DecryptXmlDocumentKeyFromBufferL(RXmlEngDocument& aDocument,

                                                      const TDesC8& aKey,

                                                      const TDesC8& aKeyName,

                                                      TXmlSecKeyType aKeyType);

    /**

     * Sets encryption template (parses template file).

     * This template will be used until new template will be set.

     *

     * @since S60 v3.2

     * @param aTemplate template file

     */

    IMPORT_C void SetTemplateFromFileL(const TDesC8& aTemplate);

    /**

     * Sets encryption template (parses template file).

     * This template will be used until new template will be set.

     *

     * @since S60 v3.2

     * @param aRFs handle to a file server session.

     * @param aTemplate template file

     */

    IMPORT_C void SetTemplateFromFileL(RFs& aRFs,

                                       const TDesC8& aTemplate);

    /**

     * Sets encryption template (parses buffer that contains template xml).

     * This template will be used until new template will be set.

     *

     * @since S60 v3.2

     * @param aTemplate template xml in buffer

     */

    IMPORT_C void SetTemplateFromBufferL(const TDesC8& aTemplate);

    /**

     * Set copy of the argument as a encryption template.

     * This template will be used until new template will be set.

     *

     * @since S60 v3.2

     * @param aTemplate DOM tree with template document

     */

    IMPORT_C void SetTemplateL(const RXmlEngDocument& aTemplate);

    /**

     * Adds <KeyName> element to <KeyInfo> node and sets the value of it.

     * The element will be added to current template.

     *

     * @since S60 v3.2

     * @param aKeyName Key name that should be set.

     */

    IMPORT_C void SetKeyInfoL(const TDesC8& aKeyName);

    /**

     * Adds element to <KeyInfo> node. This method allows to add specific data

     * to <KeyInfo> element.

     * The element will be added to current template.

     * 

     * @since S60 v3.2

     * @param aKeyProp Element that should be set.

     */

    IMPORT_C void SetKeyInfoL(TXmlEngElement aKeyProp);

    /**

     * Creates encryption template. Template will be created for specific key algorithm.

     * This template will be used until new template will be set.

     *

     * @since S60 v3.2

     * @param aKeyType Key algorithm

     * @param aDataType Type of encrypted data. It can be xml node or data.

     * @return template document

     */

    IMPORT_C const RXmlEngDocument& CreateTemplateL(TXmlSecKeyType aKeyType,

                                              TXmlSecDataType aDataType = CXmlSecEncrypt::ENode);

    /**

     * Return current encryption template.

     *

     * @since S60 v3.2

     * @return template document

     */

    IMPORT_C const RXmlEngDocument& CurrentTemplate() const;

    /**

     * Destroys current template.

     *

     * @since S60 v3.2

     */

    IMPORT_C void DestroyCurrentTemplate();

    /**

     * Reads key from file. Key will be used during encrypt/decrypt action until 

     * new key will be set.

     *

     * @since S60 v3.2

     * @param aKeyFile name of the file with key inside 

     * @param aKeyName name of the key. In case of AES and 3DES it can be null.

     * @param aKeyFormat key algorithm (i.e. AES)

     */

    IMPORT_C void SetKeyFromFileL(const TDesC8& aKeyFile,

                                  const TDesC8& aKeyName,

                                  TXmlSecKeyType aKeyType);

    /**

     * Reads key from buffer. Key will be used during encrypt/decrypt action until 

     * new key will be set.

     *

     * @since S60 v3.2

     * @param aKey buffer with key inside

     * @param aKeyName name of the key. In case of AES and 3DES it can be null.

     * @param aKeyType key algorithm (i.e. AES)

     */

    IMPORT_C void SetKeyFromBufferL(const TDesC8& aKey,

                                    const TDesC8& aKeyName,

                                    TXmlSecKeyType aKeyType);

private:

    /**

     * Default constructor.

     *

     * @since S60 v3.2

     */

    CXmlSecEncrypt();

    /**

     * Second phase constructor.

     *

     * @since S60 v3.2

     */

    void ConstructL();

private:   

    /**

     * DOM tree with template 

     */

    RXmlEngDocument iTemplate;

    /** 

     * Encryption context 

     */

    void* iEncCtx;

    /** 

     * Key manager 

     */

    CXmlSecKeyManager* iMngr;

    };

#endif // C_ENCRYPT_H