1.1 --- a/epoc32/include/mw/senwssecurityheader2.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/senwssecurityheader2.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,384 @@
1.4 -senwssecurityheader2.h
1.5 +/*
1.6 +* Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: CSenWsSecurityHeader represents security header functionality
1.19 +* according to oasis wss spesifications (2004/01)
1.20 +*
1.21 +*/
1.22 +
1.23 +
1.24 +
1.25 +
1.26 +
1.27 +
1.28 +
1.29 +
1.30 +
1.31 +#ifndef SEN_WS_SECURITY_HEADER2_H
1.32 +#define SEN_WS_SECURITY_HEADER2_H
1.33 +
1.34 +// INCLUDES
1.35 +#include <SenFragmentBase.h>
1.36 +#include <SenSoapConstants.h>
1.37 +
1.38 +// FORWARD DECLARATIONS
1.39 +class CSenIdentityProvider;
1.40 +
1.41 +// CLASS DECLARATION
1.42 +
1.43 +/**
1.44 +* CSenWsSecurityHeader represents security header functionality according to
1.45 +* oasis web services security (WSS) specifications (2004/01)
1.46 +* @lib SenUtils.lib
1.47 +* @since Series60 3.0
1.48 +*/
1.49 +class CSenWsSecurityHeader2 : public CSenFragmentBase
1.50 + {
1.51 + public: // Constructors and destructor
1.52 +
1.53 + /**
1.54 + * PasswordType Enumeration
1.55 + */
1.56 + enum TPasswordType
1.57 + {
1.58 + EText = 1, // default, wsse:PasswordText
1.59 + EDigest // wsse:Digest
1.60 + };
1.61 +
1.62 +
1.63 + /**
1.64 + * Basic constructor
1.65 + * @param aDocument The document which will be the owner of
1.66 + * the elements of this header
1.67 + * @param aElement An element which will be parent for this header.
1.68 + * @return a pointer to new CSenWsSecurityHeader class instance.
1.69 + */
1.70 + IMPORT_C static CSenWsSecurityHeader2* NewL(RSenDocument aDocument,
1.71 + TXmlEngElement aElement);
1.72 +
1.73 + /**
1.74 + * Basic constructor.
1.75 + * @param aDocument The document which will be the owner of
1.76 + * the elements of this header
1.77 + * @param aElement An element which will be parent for this header.
1.78 + * @return a new CSenWsSecurityHeader class instance, which pointer
1.79 + * is left on cleanup stack.
1.80 + */
1.81 + IMPORT_C static CSenWsSecurityHeader2* NewLC(RSenDocument aDocument,
1.82 + TXmlEngElement aElement);
1.83 +
1.84 + /**
1.85 + * Basic constructor.
1.86 + * @param aData Data to be set as header's content.
1.87 + * @param aDocument The document which will be the owner of
1.88 + * the elements of this header
1.89 + * @param aElement An element which will be parent for this header.
1.90 + * @return a pointer to new CSenWsSecurityHeader class instance.
1.91 + */
1.92 + IMPORT_C static CSenWsSecurityHeader2* NewL(const TDesC8& aData,
1.93 + RSenDocument aDocument,
1.94 + TXmlEngElement aElement);
1.95 +
1.96 + /**
1.97 + * Basic constructor.
1.98 + * @param aData Data to be set as header's content.
1.99 + * @param aDocument The document which will be the owner of
1.100 + * the elements of this header
1.101 + * @param aElement An element which will be parent for this header.
1.102 + * @return a new CSenWsSecurityHeader class instance, which pointer
1.103 + * is left on cleanup stack.
1.104 + */
1.105 + IMPORT_C static CSenWsSecurityHeader2* NewLC(const TDesC8& aData,
1.106 + RSenDocument aDocument,
1.107 + TXmlEngElement aElement);
1.108 +
1.109 + /**
1.110 + * Basic constructor.
1.111 + * @param aData Data to be set as header's content.
1.112 + * @param aSecurityNs A namespace to be set to the header.
1.113 + * @param aDocument The document which will be the owner of
1.114 + * the elements of this header
1.115 + * @param aElement An element which will be parent for this header.
1.116 + * @return a pointer to new CSenWsSecurityHeader class instance.
1.117 + */
1.118 + IMPORT_C static CSenWsSecurityHeader2* NewL(const TDesC8& aData,
1.119 + const TDesC8& aSecurityNs,
1.120 + RSenDocument aDocument,
1.121 + TXmlEngElement aElement);
1.122 +
1.123 + /**
1.124 + * Basic constructor.
1.125 + * @param aData Data to be set as header's content.
1.126 + * @param aSecurityNs A namespace to be set to the header.
1.127 + * @param aDocument The document which will be the owner of
1.128 + * the elements of this header
1.129 + * @param aElement An element which will be parent for this header.
1.130 + * @return a new CSenWsSecurityHeader class instance, which pointer
1.131 + * is left on cleanup stack.
1.132 + */
1.133 + IMPORT_C static CSenWsSecurityHeader2* NewLC(const TDesC8& aData,
1.134 + const TDesC8& aSecurityNs,
1.135 + RSenDocument aDocument,
1.136 + TXmlEngElement aElement);
1.137 +
1.138 + /**
1.139 + * Destructor.
1.140 + */
1.141 + IMPORT_C virtual ~CSenWsSecurityHeader2();
1.142 +
1.143 + // New functions
1.144 +
1.145 + /**
1.146 + * Constructs a username token.
1.147 + * @since Series60 3.0
1.148 + * @param aIdentityProvider Identity provider which is used to get
1.149 + * the authorization ID used in username token. Method takes the
1.150 + * AuthzID out from aIdentityProvider, and uses it as username for
1.151 + * this token.
1.152 + * Format of the token is as follows:
1.153 + *
1.154 + * <wsse:UsernameToken>
1.155 + * <wsse:Username>
1.156 + * username
1.157 + * </wsse:Username>
1.158 + * </wsse:UsernameToken>"
1.159 + *
1.160 + * The above token assumes, that wsse namespace is declared in
1.161 + * top level of the security header.
1.162 + * @return a pointer to buffer containing the username token. Does not
1.163 + * return NULL. Ownership is transferred to the caller. Method leaves
1.164 + * with value KErrNotSupported, if a password type is not supported.
1.165 + */
1.166 + IMPORT_C HBufC8* UsernameTokenL(CSenIdentityProvider &aIdentityProvider);
1.167 +
1.168 + /**
1.169 + * Constructs a username token.
1.170 + * @since Series60 3.0
1.171 + * @param aIdentityProvider Identity provider which is used to get
1.172 + * the authorization ID used in username token. Method takes the
1.173 + * AuthzID out from aIdentityProvider, and uses it as username for
1.174 + * this token. Password is also fetched from aIdentityProvider via
1.175 + * calling Password() getter, which must return a Base64 [XML-Schema]
1.176 + * encoded, SHA-1 hash value, of the UTF8 encoded password.
1.177 + * @param aType Specifies the type of the password, either
1.178 + * wsse:PasswordText or wsse:PasswordDigest
1.179 + *
1.180 + * Format of the token is as follows (if password type is wsse:PasswordText):
1.181 + *
1.182 + * <wsse:UsernameToken>
1.183 + * <wsse:Username>
1.184 + * username
1.185 + * </wsse:Username>
1.186 + * <wsse:Password>
1.187 + * password
1.188 + * </wsse:Password>
1.189 + * </wsse:UsernameToken>"
1.190 + *
1.191 + * If the password type is wsse:Password:Digest, then the password element
1.192 + * will be declared as follows:
1.193 + *
1.194 + * <wsse:Password Type="wsse:PasswordDigest">
1.195 + *
1.196 + * The above token assumes, that wsse namespace is declared in
1.197 + * top level of the security header.
1.198 + * @return a pointer to buffer containing the username token. Does not
1.199 + * return NULL. Ownership is transferred to the caller. Method leaves
1.200 + * with value KErrNotSupported, if a password type is not supported.
1.201 + */
1.202 + IMPORT_C HBufC8* UsernameTokenL(CSenIdentityProvider &aIdentityProvider,
1.203 + CSenWsSecurityHeader2::TPasswordType aType);
1.204 +
1.205 + // Static methods:
1.206 +
1.207 + /**
1.208 + * Constructs a username token. This method does not add the <Password>
1.209 + * element, since it is optional for basic username tokens.
1.210 + * @since Series60 3.0
1.211 + * @param aUsername User name which is used in the username
1.212 + * token.
1.213 + * @param aToken Ref-to-pointer where the token will be
1.214 + * allocated. Shouldn't contain any data when
1.215 + * called, or that data will be lost.
1.216 + * @return KErrNone or some system-wide Symbian error code.
1.217 + */
1.218 + IMPORT_C static TInt UsernameTokenL(const TDesC8& aUsername,
1.219 + HBufC8*& aToken);
1.220 +
1.221 + /**
1.222 + * Constructs a username token using a password, too.
1.223 + * @since Series60 5.0
1.224 + * @param aUsername User name which is to be used in new token.
1.225 + * @param aPassword Password which is to be use in new token.
1.226 + * The type will be set to default: wsse:PasswordDigest,
1.227 + * defined in KSecurityAttrTypeText. This is
1.228 + * a Base64 [XML-Schema] encoded, SHA-1 hash value,
1.229 + * of the UTF8 encoded password.
1.230 + * @param aToken Ref-to-pointer in which the token will be
1.231 + * allocated. Shouldn't contain any data when
1.232 + * called, or that data will be lost.
1.233 + * @return KErrNone or some system-wide Symbian error code.
1.234 + */
1.235 + IMPORT_C static TInt UsernameTokenL(const TDesC8& aUsername,
1.236 + const TDesC8& aPassword,
1.237 + HBufC8*& aToken);
1.238 +
1.239 + /**
1.240 + * Constructs a username token using a password, too.
1.241 + * @since Series60 5.0
1.242 + * @param aUsername User name which is to be used in new token.
1.243 + * @param aPassword Password which is to be use in new token
1.244 + * This is a Base64 [XML-Schema] encoded, SHA-1
1.245 + * hash value, of the UTF8 encoded password.
1.246 + * @param aType Specifies the type of the password:
1.247 + * - EText, being default refers to wsse:PasswordText,
1.248 + * but this method does not add this, since it can
1.249 + * be omitted.
1.250 + * - EDigest: will add wsse:PasswordDigest attribute
1.251 + * to the <Password> -element, as in here:
1.252 + *
1.253 + * <wsse:UsernameToken>
1.254 + * <wsse:Username>
1.255 + * username
1.256 + * </wsse:Username>
1.257 + * <wsse:Password Type="wsse:PasswordDigest">
1.258 + * password
1.259 + * </wsse:Password>
1.260 + * </wsse:UsernameToken>"
1.261 + *
1.262 + * @param aToken Ref-to-pointer where the token will be
1.263 + * allocated. Shouldn't contain any data when
1.264 + * called, or that data will be lost.
1.265 + * @return KErrNone or some system-wide Symbian error code.
1.266 + */
1.267 + IMPORT_C static TInt UsernameTokenL(const TDesC8& aUsername,
1.268 + const TDesC8& aPassword,
1.269 + CSenWsSecurityHeader2::TPasswordType aType,
1.270 + HBufC8*& aToken);
1.271 +
1.272 +
1.273 + /**
1.274 + * Constructs a timestamp.
1.275 + * @since Series60 5.0
1.276 + * Format of the timestamp is as follows:
1.277 + * <wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
1.278 + * <wsu:Created>2001-09-13T08:42:00Z</wsu:Created>
1.279 + * <wsu:Expires>2002-09-13T08:42:00Z</wsu:Expires>
1.280 + * </wsu:Timestamp>
1.281 + * The wsu namespace is declared inside this element.
1.282 + * Based on chapter 10 from WS-Security 2004
1.283 + * @param aCreated - creation time of token
1.284 + * @param aExpires - end of validation time for token
1.285 + * @param aTimestamp - a pointer to buffer containing the timestamp. Does not
1.286 + * return NULL. Ownership is transferred to the caller.
1.287 + * @return KErrNone or some system-wide Symbian error code.
1.288 + */
1.289 + IMPORT_C static TInt TimestampL(const TDesC8& aCreated, const TDesC8& aExpires, HBufC8*& aTimestamp);
1.290 +
1.291 + /**
1.292 + * Constructs a timestamp.
1.293 + * @since Series60 5.0
1.294 + * Format of the timestamp is as follows:
1.295 + * <wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
1.296 + * <wsu:Created>2001-09-13T08:42:00Z</wsu:Created>
1.297 + * </wsu:Timestamp>
1.298 + * The wsu namespace is declared inside this element.
1.299 + * Based on chapter 10 from WS-Security 2004
1.300 + * @param aCreated - creation time of token
1.301 + * @param aTimestamp - a pointer to buffer containing the timestamp. Does not
1.302 + * return NULL. Ownership is transferred to the caller.
1.303 + * @return KErrNone or some system-wide Symbian error code.
1.304 + */
1.305 + IMPORT_C static TInt TimestampL(const TDesC8& aCreated, HBufC8*& aTimestamp);
1.306 +
1.307 + /**
1.308 + * Constructs a security token reference.
1.309 + * @since Series60 5.0
1.310 + * Format of the token reference is as follows:
1.311 + * <wsse:SecurityTokenReference wsu:Id="...">
1.312 + * <wsse:Reference URI="..."/>
1.313 + * </wsse:SecurityTokenReference>
1.314 + *
1.315 + * The above token assumes, that wsse namespace is declared in
1.316 + * top level of the security header.
1.317 + * @param
1.318 + * @param aSTR - a pointer to buffer containing the token reference. Does not
1.319 + * return NULL. Ownership is transferred to the caller.
1.320 + * @return KErrNone or some system-wide Symbian error code.
1.321 + */
1.322 +// IMPORT_C static TInt SecurityTokenReferenceL(const TDesC8& aURI, HBufC8*& aSTR);
1.323 +
1.324 +
1.325 + // Virtual methods:
1.326 +
1.327 + /** Basic getter for XML namespace of the WS security header.
1.328 + * Subclasses should override this to use different namespace
1.329 + * @since Series60 3.0
1.330 + * @return the WS security header namespace as string
1.331 + */
1.332 + IMPORT_C virtual TPtrC8 XmlNs();
1.333 +
1.334 + /**
1.335 + * Basic getter for XML namespace prefix of the WS security header.
1.336 + * Subclasses should override this to use different namespace prefix
1.337 + * @since Series60 3.0
1.338 + * @return the WS security header namespace prefix as string
1.339 + */
1.340 + IMPORT_C virtual TPtrC8 XmlNsPrefix();
1.341 +
1.342 + protected:
1.343 +
1.344 + /**
1.345 + * C++ default constructor
1.346 + */
1.347 + IMPORT_C CSenWsSecurityHeader2();
1.348 +
1.349 + /**
1.350 + * Basic BaseConstructL function
1.351 + */
1.352 + IMPORT_C void BaseConstructL(RSenDocument aDocument,
1.353 + TXmlEngElement aElement);
1.354 +
1.355 + // Functions from base classes
1.356 +
1.357 + /**
1.358 + * From CSenBaseFragment Basic BaseConstructL function
1.359 + * @since Series60 3.0
1.360 + * @param aData Data which will be used as current token
1.361 + * (content) of this security header
1.362 + * @param aDocument The document which will be the owner of
1.363 + * the elements of this header
1.364 + * @param aElement An element which will be parent for this header.
1.365 + */
1.366 + IMPORT_C void BaseConstructL(const TDesC8& aData,
1.367 + RSenDocument aDocument,
1.368 + TXmlEngElement aElement);
1.369 +
1.370 + /**
1.371 + * From CSenBaseFragment Basic BaseConstructL function
1.372 + * @since Series60 3.0
1.373 + * @param aData Data which will be used as current token
1.374 + * (content) of this security header
1.375 + * @param aSecurityNs A namespace to be set to the header.
1.376 + * @param aDocument The document which will be the owner of
1.377 + * the elements of this header
1.378 + * @param aElement An element which will be parent for this header.
1.379 + */
1.380 + IMPORT_C void BaseConstructL(const TDesC8& aData,
1.381 + const TDesC8& aSecurityNs,
1.382 + RSenDocument aDocument,
1.383 + TXmlEngElement aElement);
1.384 + };
1.385 +
1.386 +#endif // SEN_WS_SECURITY_HEADER2_H
1.387 +
1.388 +// End of File