/*

* Copyright (c) 2004 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:        CSenWsSecurityHeader represents security header functionality

*                according to oasis wss spesifications (2004/01)

*

*/

#ifndef SEN_WS_SECURITY_HEADER_H

#define SEN_WS_SECURITY_HEADER_H

//  INCLUDES

#include <SenBaseFragment.h>

#include <SenSoapConstants.h>

// FORWARD DECLARATIONS

class CSenIdentityProvider;

// CLASS DECLARATION

/**

* CSenWsSecurityHeader represents security header functionality according to 

* oasis web services security (WSS) specifications (2004/01) or older (2003/06)

* @lib SenUtils.lib

* @since Series60 3.0

*/

class CSenWsSecurityHeader : public CSenBaseFragment

    {

    public:  // Constructors and destructor

		/**

		* PasswordType Enumeration

		*/

        enum TPasswordType

            {

            EText = 1,        // default, wsse:PasswordText

            EDigest           // wsse:Digest

            };

        /**

        * Basic constructor.

        * @return a pointer to new CSenWsSecurityHeader class instance.

        */

        IMPORT_C static CSenWsSecurityHeader* NewL();

        /**

        * Basic constructor.

        * @return a new CSenWsSecurityHeader class instance, which pointer

        * is left on cleanup stack.

        */

        IMPORT_C static CSenWsSecurityHeader* NewLC();

        /**

        * Basic constructor.

        * @param    aData   Data to be set as header's content.

        * @return a pointer to new CSenWsSecurityHeader class instance.

        */

        IMPORT_C static CSenWsSecurityHeader* NewL(const TDesC8& aData);

        /**

        * Basic constructor.

        * @param    aData   Data to be set as header's content.

        * @return a new CSenWsSecurityHeader class instance, which pointer

        * is left on cleanup stack.

        */

        IMPORT_C static CSenWsSecurityHeader* NewLC(const TDesC8& aData);

        /**

        * Basic constructor.

        * @param    aData           Data to be set as header's content.

        * @param    aSecurityNs     A namespace to be set to the header.

        * @return a pointer to new CSenWsSecurityHeader class instance.

        */

        IMPORT_C static CSenWsSecurityHeader* NewL(const TDesC8& aData, const TDesC8& aSecurityNs);

        /**

        * Basic constructor.

        * @param    aData           Data to be set as header's content.

        * @param    aSecurityNs     A namespace to be set to the header.

        * @return a new CSenWsSecurityHeader class instance, which pointer

        * is left on cleanup stack.

        */

        IMPORT_C static CSenWsSecurityHeader* NewLC(const TDesC8& aData, const TDesC8& aSecurityNs);

        /**

        * Destructor.

        */

        IMPORT_C virtual ~CSenWsSecurityHeader();

        // New functions

        /**

        * Constructs a username token.

        * @since Series60 3.0

        * @param  aIdentityProvider  Identity provider which is used to get

        * the authorization ID used in username token. Method takes the

        * AuthzID out from aIdentityProvider, and uses it as username for

        * this token.

        * Format of the token is as follows:

        *

        * <wsse:UsernameToken>

        *   <wsse:Username>

        *       username

        *   </wsse:Username>

        * </wsse:UsernameToken>"

        *

        * The above token assumes, that wsse namespace is declared in 

        * top level of the security header.

        * @return a pointer to buffer containing the username token. Does not

        * return NULL. Ownership is transferred to the caller. Method leaves

        * with value KErrNotSupported, if a password type is not supported.

        */

        IMPORT_C HBufC8* UsernameTokenL(CSenIdentityProvider &aIdentityProvider);

        /**

        * Constructs a username token.

        * @since Series60 3.0

        * @param  aIdentityProvider  Identity provider which is used to get

        * the authorization ID used in username token. Method takes the

        * AuthzID out from aIdentityProvider, and uses it as username for

        * this token. Password is also fetched from aIdentityProvider via

        * calling Password() getter, which must return a Base64 [XML-Schema]

        * encoded, SHA-1 hash value, of the UTF8 encoded password.

        * @param  aType Specifies the type of the password, either

        * wsse:PasswordText or wsse:PasswordDigest

        *

        * Format of the token is as follows (if password type is wsse:PasswordText):

        *

        * <wsse:UsernameToken>

        *   <wsse:Username>

        *       username

        *   </wsse:Username>

        *   <wsse:Password>

        *       password

        *   </wsse:Password>

        * </wsse:UsernameToken>"

        *

        * If the password type is wsse:Password:Digest, then the password element

        * will be declared as follows:

        *

        *   <wsse:Password Type="wsse:PasswordDigest">

        *

        * The above token assumes, that wsse namespace is declared in 

        * top level of the security header.

        * @return a pointer to buffer containing the username token. Does not

        * return NULL. Ownership is transferred to the caller. Method leaves

        * with value KErrNotSupported, if a password type is not supported.

        */

        IMPORT_C HBufC8* UsernameTokenL(CSenIdentityProvider &aIdentityProvider,

                                        CSenWsSecurityHeader::TPasswordType aType);

        // Static methods:

        /**

        * Constructs a username token. This method does not add the <Password>

        * element, since it is optional for basic username tokens.

        * @since Series60 3.0

        * @param  aUsername     User name which is used in the username 

        *                       token.

        * @param  aToken        Ref-to-pointer where the token will be

        *                       allocated. Shouldn't contain any data when

        *                       called, or that data will be lost.

        * @return KErrNone or some system-wide Symbian error code.

        */

        IMPORT_C static TInt UsernameTokenL(const TDesC8& aUsername,

                                            HBufC8*& aToken);

        /**

        * Constructs a username token using a password, too.

        * @since Series60 5.0

        * @param  aUsername     User name which is to be used in new token.

        * @param  aPassword     Password which is to be use in new token.

        *                       The type will be set to default: wsse:PasswordDigest,

        *                       defined in KSecurityAttrTypeText. This is

        *                       a Base64 [XML-Schema] encoded, SHA-1 hash value, 

        *                       of the UTF8 encoded password.

        * @param  aToken        Ref-to-pointer in which the token will be

        *                       allocated. Shouldn't contain any data when

        *                       called, or that data will be lost.

        * @return KErrNone or some system-wide Symbian error code.

        */

        IMPORT_C static TInt UsernameTokenL(const TDesC8& aUsername,

                                            const TDesC8& aPassword,

                                            HBufC8*& aToken);

       /**

        * Constructs a username token using a password, too.

        * @since Series60 5.0

        * @param  aUsername     User name which is to be used in new token.

        * @param  aPassword     Password which is to be use in new token

        *                       This is a Base64 [XML-Schema] encoded, SHA-1 

        *                       hash value, of the UTF8 encoded password.

        * @param  aType         Specifies the type of the password:

        *                       - EText, being default refers to wsse:PasswordText,

        *                       but this method does not add this, since it can

        *                       be omitted.

        *                       - EDigest: will add wsse:PasswordDigest attribute

        *                       to the <Password> -element, as in here:

        *

        *                        <wsse:UsernameToken>

        *                           <wsse:Username>

        *                               username

        *                           </wsse:Username>

        *                           <wsse:Password Type="wsse:PasswordDigest">

        *                               password

        *                           </wsse:Password>

        *                         </wsse:UsernameToken>"

        *                        

        * @param  aToken        Ref-to-pointer where the token will be

        *                       allocated. Shouldn't contain any data when

        *                       called, or that data will be lost.

        * @return KErrNone or some system-wide Symbian error code.

        */

        IMPORT_C static TInt UsernameTokenL(const TDesC8& aUsername,

                                            const TDesC8& aPassword,

                                            CSenWsSecurityHeader::TPasswordType aType,

                                            HBufC8*& aToken);

       /**

        * Constructs a BinarySecurityToken.

        * @since Series60 5.0

        *                        

        * @param  aContent      Encoded EncryptedData which is to be used in token.

        * @param  aToken        Ref-to-pointer where the token will be

        *                       allocated. Shouldn't contain any data when

        *                       called, or that data will be lost.

        * @return KErrNone or some system-wide Symbian error code.

        */

        IMPORT_C static TInt BinarySecurityTokenL(const TDesC8& aContent,

                                                  HBufC8*& aToken);

        /**

        * Constructs a BinarySecurityToken.

        * @since Series60 5.0

        *                        

        * @param  aContent      Encoded EncryptedData which is to be used in token.

        * @param  aValueType  Indicates what the security token is

        * @param  aToken        Ref-to-pointer where the token will be

        *                       allocated. Shouldn't contain any data when

        *                       called, or that data will be lost.

        * @return KErrNone or some system-wide Symbian error code.

        */

        IMPORT_C static TInt BinarySecurityTokenL(const TDesC8& aContent,

                                                  const TDesC8& aValueType,

                                                  HBufC8*& aToken);

        /**

        * Constructs a timestamp.

        * @since Series60 5.0

        * Format of the timestamp is as follows:

        *   <wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

        *       <wsu:Created>2001-09-13T08:42:00Z</wsu:Created>

        *       <wsu:Expires>2002-09-13T08:42:00Z</wsu:Expires>

        *   </wsu:Timestamp>

        * The wsu namespace is declared inside this element.

        *   Based on chapter 10 from WS-Security 2004

        * @param aCreated - creation time of token

        * @param aExpires - end of validation time for token

        * @param aTimestamp - a pointer to buffer containing the timestamp. Does not

        *         return NULL. Ownership is transferred to the caller.

        * @return KErrNone or some system-wide Symbian error code.

        */

        IMPORT_C static TInt TimestampL(const TDesC8& aCreated, const TDesC8& aExpires, HBufC8*& aTimestamp);

        /**

        * Constructs a timestamp.

        * @since Series60 5.0

        * Format of the timestamp is as follows:

        *   <wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

        *       <wsu:Created>2001-09-13T08:42:00Z</wsu:Created>

        *   </wsu:Timestamp>

        * The wsu namespace is declared inside this element.

        *   Based on chapter 10 from WS-Security 2004

        * @param aCreated - creation time of token

        * @param aTimestamp - a pointer to buffer containing the timestamp. Does not

        *         return NULL. Ownership is transferred to the caller.

        * @return KErrNone or some system-wide Symbian error code.

        */

        IMPORT_C static TInt TimestampL(const TDesC8& aCreated, HBufC8*& aTimestamp);

        /**

        * Constructs a security token reference.

        * @since Series60 5.0

        * Format of the token reference is as follows:

        *   <wsse:SecurityTokenReference wsu:Id="...">

        *       <wsse:Reference URI="..."/>

        *   </wsse:SecurityTokenReference>

        *

        * The above token assumes, that wsse namespace is declared in 

        * top level of the security header.

        * @param  

        * @param aSTR - a pointer to buffer containing the token reference. Does not

        *         return NULL. Ownership is transferred to the caller.

        * @return KErrNone or some system-wide Symbian error code.

        */

//        IMPORT_C static TInt SecurityTokenReferenceL(const TDesC8& aURI, HBufC8*& aSTR); 

        // Virtual methods: 

        /** Basic getter for XML namespace of the WS security header.

        * Subclasses should override this to use different namespace 

        * @since Series60 3.0

        * @return the WS security header namespace as string

        */

        IMPORT_C virtual TPtrC8 XmlNs();

        /**

        * Basic getter for XML namespace prefix of the WS security header.

        * Subclasses should override this to use different namespace prefix

        * @since Series60 3.0

        * @return the WS security header namespace prefix as string

        */

        IMPORT_C virtual TPtrC8 XmlNsPrefix();    

    protected:  

        /**

        * C++ default constructor

        */

        IMPORT_C CSenWsSecurityHeader();

        /**

        * Basic BaseConstructL function 

        */

        IMPORT_C void BaseConstructL();

        // Functions from base classes

        /**

        * From CSenBaseFragment Basic BaseConstructL function 

        * @since Series60 3.0

        * @param aData will be used as current token (content) of this security 

        *        header

        */

        IMPORT_C void BaseConstructL(const TDesC8& aData);

        IMPORT_C void BaseConstructL(const TDesC8& aData, const TDesC8& aSecurityNs);

    };

#endif // SEN_WS_SECURITY_HEADER_H

// End of File