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 during signing and verification process.

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 

    22 

    23 

    24 #ifndef C_SIGN_H

    25 #define C_SIGN_H

    26 

    27 #include <e32base.h>

    28 #include <f32file.h>

    29 

    30 #include <xmlengdocument.h>

    31     

    32 class CXmlSecKeyManager;

    33 class TXmlEngElement;

    34 

    35 /**

    36  *  Class used to sign data.

    37  *

    38  *  How to use:

    39  *  

    40  *  Signing with key from file:

    41  *  <pre>

    42  *  1. Create new object:

    43  *          CXmlSecSign* sign = CXmlSecSign::NewLC();

    44  *  2. Set template for signing: 

    45  *          sign->SetTemplateFromFileL(doc);

    46  *  3. Set the key that should be used during signing: 

    47  *          sign->SetKeyFromFileL(keyfilename,keyname,CXmlSecSign::ERSA_PRIVATE); 

    48  *  4. Sign xml node:

    49  *          element = sign->SignXmlDocumentL(doc); 

    50  *  </pre>

    51  *

    52  *  Signing with key from SymbianKeyStore:

    53  *  <pre>

    54  *  1. Create new object:

    55  *          CXmlSecSign* sign = CXmlSecSign::NewLC();

    56  *  2. Set template for signing: 

    57  *          sign->SetTemplateFromFileL(doc);

    58  *  3. Set the name of the key that should be used during signing: 

    59  *          sign->SetKeyInfoL(keyname);

    60  *  4. Sign xml node:

    61  *          element = sign->SignXmlDocumentL(doc,FALSE);

    62  *	   second parameter sets to FALSE determine using keys from SymbianKeyStore.

    63  *  </pre>

    64  *  

    65  *  Verification with key:

    66  *  <pre>

    67  *  1. Create new object:

    68  *          CXmlSecSign* sign = CXmlSecSign::NewLC();

    69  *  3. Set the key that should be used during verification (it should be set before verification): 

    70  *          sign->SetKeyFromFileL(keyfilename, keyname, CXmlSecSign::ERSA_PUBLIC); 

    71  *  3. Verify the signature 

    72  *          ver=sign->VerifyXmlNodeL(element);

    73  *     function will return true if sign is correct

    74  *  </pre>

    75  *  

    76  *  Verification with certificate from root's cert chain:

    77  *  <pre>

    78  *  1. Create new object:

    79  *          CXmlSecSign* sign = CXmlSecSign::NewLC();

    80  *  2. Add trusted root certificate from file:

    81  *          sign->AddTrustedCertFromFileL(trustedCert);

    82  *  3. Verify the signature:

    83  *          ver=sign->VerifyXmlNodeL(element, CXmlSecSign::ERootCertChain);

    84  *     Function will return true if sign is correct.

    85  *  </pre>

    86  *  

    87  *  Verification with certificate from SymbianCertStore:

    88  *  <pre>

    89  *  1. Create new object:

    90  *          CXmlSecSign* sign = CXmlSecSign::NewLC();

    91  *  2. Verify the signature:

    92  *          ver=sign->VerifyXmlNodeL(element, CXmlSecSign::ECertStore);

    93  *     Function will return true if sign is correct

    94  *  </pre>

    95  *

    96  *  @lib XmlSecWrapper.dll

    97  *  @since S60 v3.2

    98  */

    99 class CXmlSecSign : public CBase

   100     {

   101 public:

   102     /** 

   103      * Key types. 

   104      * Currently simmetric key (used by HMAC algorithm) and

   105      * asimmetric key (used by RSA algorithm) is supported.

   106      * RSAPrivate is for private key (PKCS#8 syntax, DER encoding)

   107      * RSAPrivate is for public key (DER encoding)

   108      */ 

   109      enum TXmlSecKeyType 

   110          { 

   111          ERSAPrivate = 0,

   112          ERSAPublic, 

   113          EHMAC 

   114          };

   115 

   116     /** 

   117      * Verification key repository.

   118      * A place where is key to use in verification.

   119      *      EThisObject      -   Key can set by SetKey method

   120      *      ECertStore       -   Symbian certificate store (@see CUnifiedCertStore)

   121      *      ERootCertChain   -   Trusted root cert set can be add by AddTrustedCertFrom(File/Buffer)L method

   122      */ 

   123      enum TXmlSecVerificationKeyRepository 

   124          { 

   125          EThisObject = 0,

   126          ECertStore, 

   127          ERootCertChain

   128          };

   129 

   130     /** Use Enveloped Signature Transform */

   131     static const TUint KEnvelopedSignature   = 0x01;

   132     /** Use c14n Transform */

   133 	static const TUint KC14N                 = 0x02;

   134 	/** Use Exclusive c14n Transform */

   135 	static const TUint KExclusiveC14N        = 0x04;

   136 

   137 public:

   138     /**

   139      * Creates new object.

   140      *

   141      * @since S60 v3.2

   142      * @return pointer to new object

   143      */

   144     IMPORT_C static CXmlSecSign* NewL();

   145 

   146     /**

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

   148      *

   149      * @since S60 v3.2

   150      * @return pointer to new object

   151      */

   152     IMPORT_C static CXmlSecSign* NewLC();

   153     

   154     /**

   155      * Destructor

   156      */

   157     virtual ~CXmlSecSign();

   158 

   159     /**

   160      * Signs xml document.

   161      *

   162      * @since S60 v3.2

   163      * @param aDocument DOM tree that should be signed.

   164      * @param aUseCurrentKey Current key (sets by SetKey function) will be used.

   165      *            If sets to FALSE then key manager will be used.

   166      * @return TElement with signature node (It is part of the document).

   167      *

   168      * @note If signature template was used, result should be added by user to 

   169      *       correct node in the document. If signature context was in

   170      *       document previously, no action is needed (signature is in place

   171      *       where it was before signing)

   172      */

   173     IMPORT_C TXmlEngElement SignXmlDocumentL(RXmlEngDocument& aDocument,

   174                                              TBool aUseCurrentKey = ETrue);

   175     

   176     /**

   177      * Signs xml document.

   178      *

   179      * @since S60 v3.2

   180      * @param aDocument DOM tree that should be signed.

   181      * @param aTemplate Template document

   182      * @param aKeyFile File with key (only binary format. 

   183      *                 In case of RSA key type - PKCS#8 syntax, DER encoding)

   184      * @param aKeyName name of the key

   185      * @param aKeyType key type (i.e. HMAC)

   186      * @return TElement with signature node (It is part of the document).

   187      *

   188      * @note If signature template was used, result should be added by user to 

   189      *       correct node in the document. If signature context was in

   190      *       document previously, no action is needed (signature is in place

   191      *       where it was before signing)

   192      */

   193     IMPORT_C TXmlEngElement SignXmlDocumentKeyFromFileL(RXmlEngDocument& aDocument,

   194                                                         RXmlEngDocument& aTemplate,

   195                                                         const TDesC8& aKeyFile,

   196                                                         const TDesC8& aKeyName,

   197                                                         TXmlSecKeyType aKeyType);

   198                                    

   199     /**

   200      * Signs xml document.

   201      *

   202      * @since S60 v3.2

   203      * @param aDocument DOM tree that should be signed.

   204      * @param aKeyFile File with key (only binary format. 

   205      *                 In case of RSA key type - PKCS#8 syntax, DER encoding)

   206      * @param aKeyName name of the key

   207      * @param aKeyType key type (i.e. HMAC)

   208      * @return TElement with signature node (It is part of the document).

   209      *

   210      * @note Signature context should be in the document that should be sign

   211      * @note If signature template was used, result should be added by user to 

   212      *       correct node in the document. If signature context was in

   213      *       document previously, no action is needed (signature is in place

   214      *       where it was before signing)

   215      */

   216     IMPORT_C TXmlEngElement SignXmlDocumentKeyFromFileL(RXmlEngDocument& aDocument,

   217                                                   const TDesC8& aKeyFile,

   218                                                   const TDesC8& aKeyName,

   219                                                   TXmlSecKeyType aKeyType);

   220     

   221     /**

   222      * Signs xml document.

   223      *

   224      * @since S60 v3.2

   225      * @param aDocument DOM tree that should be signed.

   226      * @param aTemplate Template document

   227      * @param aKey Buffer with key (only binary format. 

   228      *             In case of RSA key type - PKCS#8 syntax, DER encoding)

   229      * @param aKeyName name of the key

   230      * @param aKeyType key type (i.e. HMAC)

   231      * @return TElement with signature node (It is part of the document).

   232      *

   233      * @note If signature template was used, result should be added by user to 

   234      *       correct node in the document. If signature context was in

   235      *       document previously, no action is needed (signature is in place

   236      *       where it was before signing)

   237      */

   238     IMPORT_C TXmlEngElement SignXmlDocumentKeyFromBufferL(RXmlEngDocument& aDocument,

   239                                                     RXmlEngDocument& aTemplate,

   240                                                     const TDesC8& aKey,

   241                                                     const TDesC8& aKeyName,

   242                                                     TXmlSecKeyType aKeyType);

   243                                    

   244     /**

   245      * Signs xml document.

   246      *

   247      * @since S60 v3.2

   248      * @param aDocument DOM tree that should be signed.

   249      * @param aKey Buffer with key (only binary format. 

   250      *             In case of RSA key type - PKCS#8 syntax, DER encoding)

   251      * @param aKeyName name of the key

   252      * @param aKeyType key type (i.e. HMAC)

   253      * @return TElement with signature node (It is part of the document).

   254      *

   255      * @note Signature context should be in the document that should be sign

   256      * @note If signature template was used, result should be added by user to 

   257      *       correct node in the document. If signature context was in

   258      *       document previously, no action is needed (signature is in place

   259      *       where it was before signing)

   260      */

   261     IMPORT_C TXmlEngElement SignXmlDocumentKeyFromBufferL(RXmlEngDocument& aDocument,

   262                                                     const TDesC8& aKey,

   263                                                     const TDesC8& aKeyName,

   264                                                     TXmlSecKeyType aKeyType);

   265                                    

   266     /**

   267      * Signs xml nodes.

   268      *

   269      * @since S60 v3.2

   270      * @param aNodes Nodes that should be signed.

   271      * @param aUseCurrentKey Current key (sets by SetKey method) will be used.

   272      *            If sets to FALSE then key manager will be used.

   273      * @return TElement with signature node (It is part of the document).

   274      *

   275      * @note If signature template was used, result should be added by user to 

   276      *       correct node in the document. If signature context was in

   277      *       document previously, no action is needed (signature is in place

   278      *       where it was before signing)

   279      */

   280     IMPORT_C TXmlEngElement SignXmlNodesL(RArray<TXmlEngElement>& aNodes,

   281                                     TBool aUseCurrentKey = ETrue);

   282     

   283     /**

   284      * Verifies xml node.

   285      *

   286      * @since S60 v3.2

   287      * @param aNode Node that should be verified (<Signature> element).

   288      * @param aKeySource place from key to verification will be taken. @see TXmlSecVerificationKeyRepository

   289      * @return ETrue if correctly verificated.

   290      */

   291     IMPORT_C TBool VerifyXmlNodeL(TXmlEngElement aNode,

   292                                   TXmlSecVerificationKeyRepository aKeyRepository = EThisObject);

   293     

   294     /**

   295      * Verifies xml node.

   296      *

   297      * @since S60 v3.2

   298      * @param aNode Node that should be verified (<Signature> element).

   299      * @param aKeyFile File with key (only binary format. 

   300      *                 In case of RSA key type - PKCS#8 syntax, DER encoding)

   301      * @param aKeyName name of the key

   302      * @param aKeyType key type (i.e. HMAC)

   303      * @return TRUE if node was correctly verificated.

   304      */

   305     IMPORT_C TBool VerifyXmlNodeKeyFromFileL(TXmlEngElement aNode,

   306                                              const TDesC8& aKeyFile,

   307                                              const TDesC8& aKeyName,

   308                                              TXmlSecKeyType aKeyType);

   309                                       

   310     /**

   311      * Verifies xml node.

   312      *

   313      * @since S60 v3.2

   314      * @param aNode Node that should be verified (<Signature> element).

   315      * @param aKey Buffer with key (only binary format. 

   316      *             In case of RSA key type - PKCS#8 syntax, DER encoding)

   317      * @param aKeyName name of the key

   318      * @param aKeyType key type (i.e. HMAC)

   319      * @return TRUE if node was correctly verificated.

   320      */

   321     IMPORT_C TBool VerifyXmlNodeKeyFromBufferL(TXmlEngElement aNode,

   322                                                const TDesC8& aKey,

   323                                                const TDesC8& aKeyName,

   324                                                TXmlSecKeyType aKeyType);

   325     

   326     /**

   327      * Verifies xml document.

   328      *

   329      * @since S60 v3.2

   330      * @param aDocument Document that should be verified.

   331      * @param aKeySource place from key to verification will be taken. @see TXmlSecVerificationKeyRepository

   332      * @return TRUE if node was correctly verificated.

   333      */

   334     IMPORT_C TBool VerifyXmlDocumentL(const RXmlEngDocument& aDocument, 

   335                                 TXmlSecVerificationKeyRepository aKeyRepository = EThisObject);

   336     

   337     /**

   338      * Verifies xml document.

   339      *

   340      * @since S60 v3.2

   341      * @param aDocument DOM tree that should be verified.

   342      * @param aKeyFile File with key (only binary format. 

   343      *                 In case of RSA key type - PKCS#8 syntax, DER encoding)

   344      * @param aKeyName name of the key

   345      * @param aKeyType key type (i.e. HMAC)

   346      * @return TRUE if document was correctly verificated.

   347      */

   348     IMPORT_C TBool VerifyXmlDocumentKeyFromFileL(const RXmlEngDocument& aDocument,

   349                                                  const TDesC8& aKeyFile,

   350                                                  const TDesC8& aKeyName,

   351                                                  TXmlSecKeyType aKeyType);

   352                                       

   353     /**

   354      * Verifies xml document.

   355      *

   356      * @since S60 v3.2

   357      * @param aDocument DOM tree that should be verified.

   358      * @param aKey Buffer with key (only binary format. 

   359      *             In case of RSA key type - PKCS#8 syntax, DER encoding)

   360      * @param aKeyName name of the key

   361      * @param aKeyType key type (i.e. HMAC)

   362      * @return TRUE if document was correctly verificated.

   363      */

   364     IMPORT_C TBool VerifyXmlDocumentKeyFromBufferL(const RXmlEngDocument& aDocument,

   365                                                    const TDesC8& aKey,

   366                                                    const TDesC8& aKeyName,

   367                                                    TXmlSecKeyType aKeyType);

   368                              

   369     /**

   370      * Sets signing template (parses template file).

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

   372      *

   373      * @since S60 v3.2

   374      * @param aTemplate template file

   375      */

   376     IMPORT_C void SetTemplateFromFileL(const TDesC8& aTemplate);

   377     

   378     /**

   379      * Sets signing template (parses template file).

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

   381      *

   382      * @since S60 v3.2

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

   384      * @param aTemplate template file

   385      */

   386     IMPORT_C void SetTemplateFromFileL(RFs& aRFs, const TDesC8& aTemplate);

   387     

   388     /**

   389      * Sets signing template (parses buffer that contains template xml).

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

   391      *

   392      * @since S60 v3.2

   393      * @param aTemplate template xml in buffer

   394      */

   395     IMPORT_C void SetTemplateFromBufferL(const TDesC8& aTemplate);

   396     

   397     /**

   398      * Set copy of the argument as a sign template.

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

   400      *

   401      * @since S60 v3.2

   402      * @param aTemplate DOM tree with template document

   403      */

   404     IMPORT_C void SetTemplateL(const RXmlEngDocument& aTemplate);

   405     

   406     /**

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

   408      * The element will be added to current template.

   409      *

   410      * @since S60 v3.2

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

   412      */

   413     IMPORT_C void SetKeyInfoL(const TDesC8& aKeyName);

   414     

   415     /**

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

   417      * to <KeyInfo> element.

   418      * The element will be added to current template.

   419      * 

   420      * @since S60 v3.2

   421      * @param aKeyProp Element that should be set.

   422      */

   423     IMPORT_C void SetKeyInfoL(TXmlEngElement aKeyProp);

   424             

   425     /**

   426      * Creates template for singning. Template is created for specific key algorithm.

   427      * This templete will sign whole xml document.

   428      *

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

   430      * Only SHA1 digest method is supported.

   431      *

   432      * @since S60 v3.2

   433      * @param aKeyType Key type determine signatureMethod.

   434      * @param aCert If sets to TRUE then element <X509Certificate> will be added to template.

   435      * @param aTransform Decide what transform should be used in reference elements

   436      *          Use one or more const (e.g. KEnvelopeSignature | KExclusiveC14N)

   437      * @param aPref prefix that will be used for signature namespace

   438      * @param aNewLine should new line be used in template

   439      * @return template document

   440      */

   441     IMPORT_C const RXmlEngDocument& CreateTemplateL(TXmlSecKeyType aKeyType,                                        

   442                                         TBool aCert = EFalse,

   443                                         TUint aTransforms = KEnvelopedSignature,

   444                                         const TDesC8& aPref = KNullDesC8(),

   445                                         TBool aNewLine = TRUE);

   446     

   447     /**

   448      * Creates template for signing. Template is created for specific key algorithm.

   449      * Templete allows to sign element(s) identified by id.

   450      *

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

   452      * Only SHA1 digest method is supported.

   453      *

   454      * @since S60 v3.2

   455      * @param aKeyType Key type determine signatureMethod.

   456      * @param aNodes Array with nodes that should be signed

   457      * @param aId Id name that should be used in Reference (i.e."ns:Id")

   458      * @param aCert If sets to TRUE then element <X509Certificate> will be added to template.

   459      * @param aTransform Decide what transform should be used in reference elements

   460      *          Use one or more const (e.g. KEnvelopeSignature | KExclusiveC14N)

   461      * @param aPref prefix that will be used for signature namespace

   462      * @param aNewLine should new line be used in template

   463      * @return template document

   464      */

   465     IMPORT_C const RXmlEngDocument& CreateTemplateL(TXmlSecKeyType aKeyType,

   466                                         RArray<TXmlEngElement>& aNodes,

   467                                         const TDesC8& aId,

   468                                         TBool aCert = EFalse,

   469                                         TUint aTransforms = KEnvelopedSignature,

   470                                         const TDesC8& aPref = KNullDesC8(),

   471                                         TBool aNewLine = TRUE);

   472         

   473     /**

   474      * Gets current template.

   475      *

   476      * @since S60 v3.2

   477      * @return template document

   478      */

   479     IMPORT_C const RXmlEngDocument& CurrentTemplate() const;

   480     

   481     /**

   482      * Destroys current template.

   483      *

   484      * @since S60 v3.2

   485      */

   486     IMPORT_C void DestroyCurrentTemplate();

   487     

   488     /**

   489      * Reads key from file and puts it to the SymbianKeyStore. 

   490      * Key will be used during signing/verification action until new key will be set.

   491      *

   492      * @since S60 v3.2

   493      * @param aKeyFile File with key (only binary format. 

   494      *                 In case of RSA private key type - PKCS#8 syntax, DER encoding)

   495      * @param aKeyName name of the key (it can be null descriptor when HMAC key is used)

   496      * @param aKeyFormat key type (i.e. HMAC)

   497      */

   498     IMPORT_C void SetKeyFromFileL(const TDesC8& aKeyFile,

   499                                   const TDesC8& aKeyName,

   500                                   TXmlSecKeyType aKeyType);

   501     

   502     /**

   503      * Reads key from buffer and puts it to the SymbianKeyStore. 

   504      * Key will be used during signing/verification action until new key will be set.

   505      *

   506      * @since S60 v3.2

   507      * @param aKey Buffer with key (only binary format. 

   508      *             In case of RSA private key type - PKCS#8 syntax, DER encoding)

   509      * @param aKeyName name of the key (it can be null descriptor when HMAC key is used)

   510      * @param aKeyFormat key type (i.e. HMAC). 

   511      */

   512     IMPORT_C void SetKeyFromBufferL(const TDesC8& aKey,

   513                                     const TDesC8& aKeyName,

   514                                     TXmlSecKeyType aKeyType);

   515     /**

   516      * Reads certificate from file. 

   517      * This certificate will be added to current key.

   518      *

   519      * @since S60 v3.2

   520      * @param aCertFile Name of the file with certificate inside 

   521      */

   522     IMPORT_C void SetCertFromFileL(const TDesC8& aCertFile);

   523     

   524     /**

   525      * Reads certificate from buffer. 

   526      * This certificate will be added to current key.

   527      *

   528      * @since S60 v3.2

   529      * @param aCert Buffer with certificate inside 

   530      */

   531     IMPORT_C void SetCertFromBufferL(const TDesC8& aCert);

   532 

   533     /**

   534      * Reads X509 certificate from file and adds it to root's cert chain handled in memory (destroyed after session). 

   535      * This certificate IS NOT added to SymbianCertStore. 

   536      *

   537      * @since S60 v3.2

   538      * @param aCertFile Name of the file with certificate.

   539      */

   540     IMPORT_C void AddTrustedCertFromFileL(const TDesC8& aCertFile);

   541 

   542     /**

   543      * Reads X509 certificate from buffer and adds it to root's cert chain handled in memory (destroyed after session). 

   544      * This certificate IS NOT added to SymbianCertStore. 

   545      *

   546      * @since S60 v3.2

   547      * @param aCert Buffer with certificate.

   548      */

   549     IMPORT_C void AddTrustedCertFromBufferL(const TDesC8& aCert);

   550 

   551 private:

   552     /**

   553      * Default constructor.

   554      *

   555      * @since S60 v3.2

   556      */

   557     CXmlSecSign();

   558     

   559     /**

   560      * Second phase constructor.

   561      *

   562      * @since S60 v3.2

   563      */

   564     void ConstructL();

   565     

   566     /**

   567      * Signs the xml node.

   568      *

   569      * @since S60 v3.2

   570      * @param aNode TElement Node that should be sign.

   571      * @param aUseCurrentKey Current key (set by SetKey method) will be used.

   572      *            If sets to FALSE then key manager will be used.

   573      * @return TElement with signed node.

   574      */

   575     TXmlEngElement CXmlSecSign::SignXmlNodeL(TXmlEngElement aNode, TBool aUseCurrentKey);

   576 

   577 private:   

   578     /** 

   579      * DOM tree with template 

   580      */

   581     RXmlEngDocument iTemplate;

   582     

   583     /** 

   584      * Signing context 

   585      */

   586     void* iSigCtx;

   587     

   588     /**

   589      * Key manager 

   590      */

   591     CXmlSecKeyManager* iMngr;

   592 

   593     /**

   594      * Flag to skip searching for Template in document 

   595      */

   596     TBool iSkipTmplLookUp;

   597 

   598     };

   599     

   600 #endif // C_SIGN_H