diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/senwssecurityheader2.h --- a/epoc32/include/mw/senwssecurityheader2.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/mw/senwssecurityheader2.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,384 @@ -senwssecurityheader2.h +/* +* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members +* which accompanies this distribution, and is available +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.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_HEADER2_H +#define SEN_WS_SECURITY_HEADER2_H + +// INCLUDES +#include +#include + +// FORWARD DECLARATIONS +class CSenIdentityProvider; + +// CLASS DECLARATION + +/** +* CSenWsSecurityHeader represents security header functionality according to +* oasis web services security (WSS) specifications (2004/01) +* @lib SenUtils.lib +* @since Series60 3.0 +*/ +class CSenWsSecurityHeader2 : public CSenFragmentBase + { + public: // Constructors and destructor + + /** + * PasswordType Enumeration + */ + enum TPasswordType + { + EText = 1, // default, wsse:PasswordText + EDigest // wsse:Digest + }; + + + /** + * Basic constructor + * @param aDocument The document which will be the owner of + * the elements of this header + * @param aElement An element which will be parent for this header. + * @return a pointer to new CSenWsSecurityHeader class instance. + */ + IMPORT_C static CSenWsSecurityHeader2* NewL(RSenDocument aDocument, + TXmlEngElement aElement); + + /** + * Basic constructor. + * @param aDocument The document which will be the owner of + * the elements of this header + * @param aElement An element which will be parent for this header. + * @return a new CSenWsSecurityHeader class instance, which pointer + * is left on cleanup stack. + */ + IMPORT_C static CSenWsSecurityHeader2* NewLC(RSenDocument aDocument, + TXmlEngElement aElement); + + /** + * Basic constructor. + * @param aData Data to be set as header's content. + * @param aDocument The document which will be the owner of + * the elements of this header + * @param aElement An element which will be parent for this header. + * @return a pointer to new CSenWsSecurityHeader class instance. + */ + IMPORT_C static CSenWsSecurityHeader2* NewL(const TDesC8& aData, + RSenDocument aDocument, + TXmlEngElement aElement); + + /** + * Basic constructor. + * @param aData Data to be set as header's content. + * @param aDocument The document which will be the owner of + * the elements of this header + * @param aElement An element which will be parent for this header. + * @return a new CSenWsSecurityHeader class instance, which pointer + * is left on cleanup stack. + */ + IMPORT_C static CSenWsSecurityHeader2* NewLC(const TDesC8& aData, + RSenDocument aDocument, + TXmlEngElement aElement); + + /** + * Basic constructor. + * @param aData Data to be set as header's content. + * @param aSecurityNs A namespace to be set to the header. + * @param aDocument The document which will be the owner of + * the elements of this header + * @param aElement An element which will be parent for this header. + * @return a pointer to new CSenWsSecurityHeader class instance. + */ + IMPORT_C static CSenWsSecurityHeader2* NewL(const TDesC8& aData, + const TDesC8& aSecurityNs, + RSenDocument aDocument, + TXmlEngElement aElement); + + /** + * Basic constructor. + * @param aData Data to be set as header's content. + * @param aSecurityNs A namespace to be set to the header. + * @param aDocument The document which will be the owner of + * the elements of this header + * @param aElement An element which will be parent for this header. + * @return a new CSenWsSecurityHeader class instance, which pointer + * is left on cleanup stack. + */ + IMPORT_C static CSenWsSecurityHeader2* NewLC(const TDesC8& aData, + const TDesC8& aSecurityNs, + RSenDocument aDocument, + TXmlEngElement aElement); + + /** + * Destructor. + */ + IMPORT_C virtual ~CSenWsSecurityHeader2(); + + // 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: + * + * + * + * username + * + * " + * + * 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): + * + * + * + * username + * + * + * password + * + * " + * + * If the password type is wsse:Password:Digest, then the password element + * will be declared as follows: + * + * + * + * 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, + CSenWsSecurityHeader2::TPasswordType aType); + + // Static methods: + + /** + * Constructs a username token. This method does not add the + * 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 -element, as in here: + * + * + * + * username + * + * + * password + * + * " + * + * @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, + CSenWsSecurityHeader2::TPasswordType aType, + HBufC8*& aToken); + + + /** + * Constructs a timestamp. + * @since Series60 5.0 + * Format of the timestamp is as follows: + * + * 2001-09-13T08:42:00Z + * 2002-09-13T08:42:00Z + * + * 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: + * + * 2001-09-13T08:42:00Z + * + * 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: + * + * + * + * + * 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 CSenWsSecurityHeader2(); + + /** + * Basic BaseConstructL function + */ + IMPORT_C void BaseConstructL(RSenDocument aDocument, + TXmlEngElement aElement); + + // Functions from base classes + + /** + * From CSenBaseFragment Basic BaseConstructL function + * @since Series60 3.0 + * @param aData Data which will be used as current token + * (content) of this security header + * @param aDocument The document which will be the owner of + * the elements of this header + * @param aElement An element which will be parent for this header. + */ + IMPORT_C void BaseConstructL(const TDesC8& aData, + RSenDocument aDocument, + TXmlEngElement aElement); + + /** + * From CSenBaseFragment Basic BaseConstructL function + * @since Series60 3.0 + * @param aData Data which will be used as current token + * (content) of this security header + * @param aSecurityNs A namespace to be set to the header. + * @param aDocument The document which will be the owner of + * the elements of this header + * @param aElement An element which will be parent for this header. + */ + IMPORT_C void BaseConstructL(const TDesC8& aData, + const TDesC8& aSecurityNs, + RSenDocument aDocument, + TXmlEngElement aElement); + }; + +#endif // SEN_WS_SECURITY_HEADER2_H + +// End of File