1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

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

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 

    22 

    23 

    24 #ifndef C_ENCRYPT_H

    25 #define C_ENCRYPT_H

    26 

    27 #include <e32base.h>

    28 #include <f32file.h>

    29 

    30 #include <xmlengdocument.h>

    31 

    32 class CXmlSecKeyManager;

    33 

    34 /**

    35  *  Class used to encrypt/decrypt data.

    36  *

    37  *  How to use:

    38  *  

    39  *  Encryption:

    40  *  <pre>

    41  *  1. Create new object:

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

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

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

    45  *  3. Set template for encryption: 

    46  *          enc->SetTemplateFromFileL(templatefile);

    47  *  4. Encrypt data from buffer:

    48  *          doc = enc->EncryptDataL(data);

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

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

    51  *     node will be replaced by template with encrypted data

    52  *  </pre>

    53  *  

    54  *  Decryption:

    55  *  <pre>

    56  *  1. Create new object:

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

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

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

    60  *  3. Decrypt xml node:

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

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

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

    64  *  </pre>

    65  *   

    66  *  @note Key should be set before encryption

    67  *

    68  *  @lib XmlSecWrapper.dll

    69  *  @since S60 v3.2

    70  */

    71 class CXmlSecEncrypt : public CBase

    72     {

    73 public:

    74     /**

    75      * Key types.

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

    77      */

    78     enum TXmlSecKeyType

    79         {

    80         EAES256 = 0,

    81         E3DES

    82         };

    83 

    84     /**

    85      * Encryption data types

    86      */

    87     enum TXmlSecDataType

    88         {

    89         ENode = 0,

    90         ENodeContent,

    91         EData

    92         };

    93 

    94 public:

    95     /**

    96      * Creates new object.

    97      *

    98      * @since S60 v3.2

    99      * @return pointer to new object

   100      */

   101     IMPORT_C static CXmlSecEncrypt* NewL();

   102     

   103     /**

   104      * Creates new object and puts it on cleanup stack.

   105      *

   106      * @since S60 v3.2

   107      * @return pointer to new object

   108      */

   109     IMPORT_C static CXmlSecEncrypt* NewLC();

   110     

   111     /**

   112      * Destructor.

   113      *

   114      * @since S60 v3.2

   115      */

   116     virtual ~CXmlSecEncrypt();

   117 

   118     /**

   119      * Encrypts data from buffer.

   120      *

   121      * @since S60 v3.2

   122      * @param aData data that should be encrypted

   123      * @return xml document with encrypted data

   124      */

   125     IMPORT_C RXmlEngDocument EncryptDataL(const TDesC8& aData);

   126     

   127     /**

   128      * Encrypts xml document.

   129      *

   130      * @since S60 v3.2

   131      * @param aDocument xml document that should be encrypted.

   132      *

   133      * @note Encrypted content will replace aDocument content.

   134      *       aDocument contains the result.

   135      */

   136     IMPORT_C void EncryptXmlDocumentL(RXmlEngDocument& aDocument);

   137                                       

   138     /**

   139      * Encrypts xml node.

   140      *

   141      * @since S60 v3.2

   142      * @param aNode xml node that should be encrypted.

   143      *

   144      * @note Encrypted content will replace aNode.

   145      *       aNode contains the result.

   146      */

   147     IMPORT_C void EncryptXmlNodeL(TXmlEngElement aNode);

   148                                   

   149     /**

   150      * Encrypts xml node.

   151      *

   152      * @since S60 v3.2

   153      * @param aNode xml node that should be encrypted.

   154      * @param aTemplate DOM tree with template document

   155      * @param aKeyFile name of the file with key inside 

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

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

   158      *

   159      * @note Encrypted content will replace aNode.

   160      *       aNode contains the result.

   161      */

   162     IMPORT_C void EncryptXmlNodeKeyFromFileL(TXmlEngElement aNode,

   163                                              RXmlEngDocument& aTemplate,

   164                                              const TDesC8& aKeyFile,

   165                                              const TDesC8& aKeyName,

   166                                              TXmlSecKeyType aKeyType);

   167     /**

   168      * Encrypts xml document.

   169      *

   170      * @since S60 v3.2

   171      * @param aDocument xml document that should be encrypted.

   172      * @param aTemplate DOM tree with template document

   173      * @param aKeyFile name of the file with key inside 

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

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

   176      *

   177      * @note Encrypted content will replace aNode.

   178      *       aNode contains the result.

   179      */

   180     IMPORT_C void EncryptXmlDocumentKeyFromFileL(RXmlEngDocument& aDoc,

   181                                                  RXmlEngDocument& aTemplate,

   182                                                  const TDesC8& aKeyFile,

   183                                                  const TDesC8& aKeyName,

   184                                                  TXmlSecKeyType aKeyType);

   185                                                  

   186     /**

   187      * Encrypts xml node.

   188      *

   189      * @since S60 v3.2

   190      * @param aNode xml node that should be encrypted.

   191      * @param aTemplate DOM tree with template document

   192      * @param aKey buffer with key inside 

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

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

   195      *

   196      * @note Encrypted content will replace aNode.

   197      *       aNode contains the result.

   198      */

   199     IMPORT_C void EncryptXmlNodeKeyFromBufferL(TXmlEngElement aNode,

   200                                                RXmlEngDocument& aTemplate,

   201                                                const TDesC8& aKeyFile,

   202                                                const TDesC8& aKeyName,

   203                                                TXmlSecKeyType aKeyType);

   204     /**

   205      * Encrypts xml document.

   206      *

   207      * @since S60 v3.2

   208      * @param aDocument xml document that should be encrypted.

   209      * @param aTemplate DOM tree with template document

   210      * @param aKey buffer with key inside 

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

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

   213      *

   214      * @note Encrypted content will replace aNode.

   215      *       aNode contains the result.

   216      */

   217     IMPORT_C void EncryptXmlDocumentKeyFromBufferL(RXmlEngDocument& aDoc,

   218                                                    RXmlEngDocument& aTemplate,

   219                                                    const TDesC8& aKey,

   220                                                    const TDesC8& aKeyName,

   221                                                    TXmlSecKeyType aKeyType);

   222 

   223     /**

   224      * Decrypts data contained in a node.

   225      *

   226      * @since S60 v3.2

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

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

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

   230      *         in HBufC8 pointer.

   231      */

   232     IMPORT_C HBufC8* DecryptXmlNodeL(TXmlEngElement aNode);

   233     

   234     /**

   235      * Decrypts data contained in xml DOM tree.

   236      *

   237      * @since S60 v3.2

   238      * @param aDocument DOM tree with encrypted data

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

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

   241      *         in HBufC8 pointer.

   242      */

   243     IMPORT_C HBufC8* DecryptXmlDocumentL(RXmlEngDocument& aDocument);

   244     

   245     /**

   246      * Decrypts xml node.

   247      *

   248      * @since S60 v3.2

   249      * @param aNode xml node that should be decrypted.

   250      * @param aKeyFile name of the file with key inside 

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

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

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

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

   255      *         in HBufC8 pointer.

   256      */

   257     IMPORT_C HBufC8* DecryptXmlNodeKeyFromFileL(TXmlEngElement aNode,

   258                                                 const TDesC8& aKeyFile,

   259                                                 const TDesC8& aKeyName,

   260                                                 TXmlSecKeyType aKeyType);

   261     /**

   262      * Decrypts xml document.

   263      *

   264      * @since S60 v3.2

   265      * @param aDocument xml document that should be decrypted.

   266      * @param aKeyFile name of the file with key inside 

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

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

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

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

   271      *         in HBufC8 pointer.

   272      */

   273     IMPORT_C HBufC8* DecryptXmlDocumentKeyFromFileL(RXmlEngDocument& aDocument,

   274                                                     const TDesC8& aKeyFile,

   275                                                     const TDesC8& aKeyName,

   276                                                     TXmlSecKeyType aKeyType);

   277                                          

   278     /**

   279      * Decrypts xml node.

   280      *

   281      * @since S60 v3.2

   282      * @param aNode xml node that should be decrypted.

   283      * @param aKey buffer with key inside 

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

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

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

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

   288      *         in HBufC8 pointer.

   289      */

   290     IMPORT_C HBufC8* DecryptXmlNodeKeyFromBufferL(TXmlEngElement aNode,

   291                                                   const TDesC8& aKey,

   292                                                   const TDesC8& aKeyName,

   293                                                   TXmlSecKeyType aKeyType);

   294     /**

   295      * Decrypts xml document.

   296      *

   297      * @since S60 v3.2

   298      * @param aDocument xml document that should be decrypted.

   299      * @param aKey buffer with key inside 

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

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

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

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

   304      *         in HBufC8 pointer.

   305      */

   306     IMPORT_C HBufC8* DecryptXmlDocumentKeyFromBufferL(RXmlEngDocument& aDocument,

   307                                                       const TDesC8& aKey,

   308                                                       const TDesC8& aKeyName,

   309                                                       TXmlSecKeyType aKeyType);

   310                              

   311     /**

   312      * Sets encryption template (parses template file).

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

   314      *

   315      * @since S60 v3.2

   316      * @param aTemplate template file

   317      */

   318     IMPORT_C void SetTemplateFromFileL(const TDesC8& aTemplate);

   319     

   320     /**

   321      * Sets encryption template (parses template file).

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

   323      *

   324      * @since S60 v3.2

   325      * @param aRFs handle to a file server session.

   326      * @param aTemplate template file

   327      */

   328     IMPORT_C void SetTemplateFromFileL(RFs& aRFs,

   329                                        const TDesC8& aTemplate);

   330     

   331     /**

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

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

   334      *

   335      * @since S60 v3.2

   336      * @param aTemplate template xml in buffer

   337      */

   338     IMPORT_C void SetTemplateFromBufferL(const TDesC8& aTemplate);

   339     

   340     /**

   341      * Set copy of the argument as a encryption template.

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

   343      *

   344      * @since S60 v3.2

   345      * @param aTemplate DOM tree with template document

   346      */

   347     IMPORT_C void SetTemplateL(const RXmlEngDocument& aTemplate);

   348     

   349     /**

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

   351      * The element will be added to current template.

   352      *

   353      * @since S60 v3.2

   354      * @param aKeyName Key name that should be set.

   355      */

   356     IMPORT_C void SetKeyInfoL(const TDesC8& aKeyName);

   357     

   358     /**

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

   360      * to <KeyInfo> element.

   361      * The element will be added to current template.

   362      * 

   363      * @since S60 v3.2

   364      * @param aKeyProp Element that should be set.

   365      */

   366     IMPORT_C void SetKeyInfoL(TXmlEngElement aKeyProp);

   367     

   368     /**

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

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

   371      *

   372      * @since S60 v3.2

   373      * @param aKeyType Key algorithm

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

   375      * @return template document

   376      */

   377     IMPORT_C const RXmlEngDocument& CreateTemplateL(TXmlSecKeyType aKeyType,

   378                                               TXmlSecDataType aDataType = CXmlSecEncrypt::ENode);

   379     

   380     /**

   381      * Return current encryption template.

   382      *

   383      * @since S60 v3.2

   384      * @return template document

   385      */

   386     IMPORT_C const RXmlEngDocument& CurrentTemplate() const;

   387     

   388     /**

   389      * Destroys current template.

   390      *

   391      * @since S60 v3.2

   392      */

   393     IMPORT_C void DestroyCurrentTemplate();

   394     

   395     /**

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

   397      * new key will be set.

   398      *

   399      * @since S60 v3.2

   400      * @param aKeyFile name of the file with key inside 

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

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

   403      */

   404     IMPORT_C void SetKeyFromFileL(const TDesC8& aKeyFile,

   405                                   const TDesC8& aKeyName,

   406                                   TXmlSecKeyType aKeyType);

   407     

   408     /**

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

   410      * new key will be set.

   411      *

   412      * @since S60 v3.2

   413      * @param aKey buffer with key inside

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

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

   416      */

   417     IMPORT_C void SetKeyFromBufferL(const TDesC8& aKey,

   418                                     const TDesC8& aKeyName,

   419                                     TXmlSecKeyType aKeyType);

   420     

   421 private:

   422     /**

   423      * Default constructor.

   424      *

   425      * @since S60 v3.2

   426      */

   427     CXmlSecEncrypt();

   428     

   429     /**

   430      * Second phase constructor.

   431      *

   432      * @since S60 v3.2

   433      */

   434     void ConstructL();

   435 

   436 private:   

   437     /**

   438      * DOM tree with template 

   439      */

   440     RXmlEngDocument iTemplate;

   441     

   442     /** 

   443      * Encryption context 

   444      */

   445     void* iEncCtx;

   446     

   447     /** 

   448      * Key manager 

   449      */

   450     CXmlSecKeyManager* iMngr;

   451     };

   452     

   453 #endif // C_ENCRYPT_H