shibsp/handler/AbstractHandler.h

   1 /*
   2  *  Copyright 2001-2010 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file shibsp/handler/AbstractHandler.h
  19  *
  20  * Base class for handlers based on a DOMPropertySet.
  21  */
  22
  23 #ifndef __shibsp_abshandler_h__
  24 #define __shibsp_abshandler_h__
  25
  26 #include <shibsp/handler/Handler.h>
  27 #include <shibsp/remoting/ddf.h>
  28 #include <shibsp/util/DOMPropertySet.h>
  29
  30 #include <map>
  31 #include <string>
  32 #include <xmltooling/logging.h>
  33
  34 #ifndef SHIBSP_LITE
  35 namespace opensaml {
  36     class SAML_API MessageEncoder;
  37     namespace saml2md {
  38         class SAML_API RoleDescriptor;
  39     };
  40     namespace saml2p {
  41         class SAML_API StatusResponseType;
  42     };
  43 };
  44 #endif
  45
  46 namespace xmltooling {
  47     class XMLTOOL_API XMLObject;
  48 };
  49
  50 namespace shibsp {
  51
  52     class SHIBSP_API Application;
  53
  54 #if defined (_MSC_VER)
  55     #pragma warning( push )
  56     #pragma warning( disable : 4250 )
  57 #endif
  58
  59     /**
  60      * Base class for handlers based on a DOMPropertySet.
  61      */
  62     class SHIBSP_API AbstractHandler : public virtual Handler, public DOMPropertySet
  63     {
  64     protected:
  65         /**
  66          * Constructor
  67          *
  68          * @param e         DOM element to load as property set.
  69          * @param log       logging category to use
  70          * @param filter    optional filter controls what child elements to include as nested PropertySets
  71          * @param remapper  optional map of property rename rules for legacy property support
  72          */
  73         AbstractHandler(
  74             const xercesc::DOMElement* e,
  75             xmltooling::logging::Category& log,
  76             xercesc::DOMNodeFilter* filter=NULL,
  77             const std::map<std::string,std::string>* remapper=NULL
  78             );
  79
  80         void log(SPRequest::SPLogLevel level, const std::string& msg) const;
  81
  82 #ifndef SHIBSP_LITE
  83         /**
  84          * Examines a protocol response message for errors and raises an annotated exception
  85          * if an error is found.
  86          *
  87          * <p>The base class version understands SAML 1.x and SAML 2.0 responses.
  88          *
  89          * @param response  a response message of some known protocol
  90          * @param role      issuer of message
  91          */
  92         virtual void checkError(
  93             const xmltooling::XMLObject* response,
  94             const opensaml::saml2md::RoleDescriptor* role=NULL
  95             ) const;
  96
  97         /**
  98          * Prepares Status information in a SAML 2.0 response.
  99          *
 100          * @param response  SAML 2.0 response message
 101          * @param code      SAML status code
 102          * @param subcode   optional SAML substatus code
 103          * @param msg       optional message to pass back
 104          */
 105         void fillStatus(
 106             opensaml::saml2p::StatusResponseType& response, const XMLCh* code, const XMLCh* subcode=NULL, const char* msg=NULL
 107             ) const;
 108
 109         /**
 110          * Encodes and sends SAML 2.0 message, optionally signing it in the process.
 111          * If the method returns, the message MUST NOT be freed by the caller.
 112          *
 113          * @param encoder           the MessageEncoder to use
 114          * @param msg               the message to send
 115          * @param relayState        any RelayState to include with the message
 116          * @param destination       location to send message, if not a backchannel response
 117          * @param role              recipient of message, if known
 118          * @param application       the Application sending the message
 119          * @param httpResponse      channel for sending message
 120          * @param signIfPossible    true iff signing should be attempted regardless of "signing" property
 121          * @return  the result of sending the message using the encoder
 122          */
 123         long sendMessage(
 124             const opensaml::MessageEncoder& encoder,
 125             xmltooling::XMLObject* msg,
 126             const char* relayState,
 127             const char* destination,
 128             const opensaml::saml2md::RoleDescriptor* role,
 129             const Application& application,
 130             xmltooling::HTTPResponse& httpResponse,
 131             bool signIfPossible=false
 132             ) const;
 133 #endif
 134
 135         /**
 136          * Implements a mechanism to preserve form post data.
 137          *
 138          * @param application   the associated Application
 139          * @param request       incoming HTTP request
 140          * @param response      outgoing HTTP response
 141          * @param relayState    relay state information attached to current sequence, if any
 142          */
 143         virtual void preservePostData(
 144             const Application& application,
 145             const xmltooling::HTTPRequest& request,
 146             xmltooling::HTTPResponse& response,
 147             const char* relayState
 148             ) const;
 149
 150         /**
 151          * Implements storage service and cookie mechanism to recover PostData.
 152          *
 153          * <p>If a supported mechanism can be identified, the return value will be
 154          * the recovered state information.
 155          *
 156          * @param application   the associated Application
 157          * @param request       incoming HTTP request
 158          * @param response      outgoing HTTP response
 159          * @param relayState    relay state information attached to current sequence, if any
 160          * @return  recovered form post data associated with request as a DDF list of string members
 161          */
 162         virtual DDF recoverPostData(
 163             const Application& application,
 164             const xmltooling::HTTPRequest& request,
 165             xmltooling::HTTPResponse& response,
 166             const char* relayState
 167             ) const;
 168
 169         /**
 170          * Post a redirect response with post data.
 171          *
 172          * @param application   the associated Application
 173          * @param response      outgoing HTTP response
 174          * @param request       incoming HTTP request
 175          * @param url           action url for the form
 176          * @param postData      list of parameters to load into the form, as DDF string members
 177          */
 178         virtual long sendPostResponse(
 179             const Application& application,
 180             xmltooling::HTTPResponse& httpResponse,
 181             const char* url,
 182             DDF& postData
 183             ) const;
 184
 185         /**
 186          * Bitmask of property sources to read from
 187          * (request query parameter, request mapper, fixed handler property).
 188          */
 189         enum PropertySourceTypes {
 190             HANDLER_PROPERTY_REQUEST = 1,
 191             HANDLER_PROPERTY_MAP = 2,
 192             HANDLER_PROPERTY_FIXED = 4,
 193             HANDLER_PROPERTY_ALL = 255
 194         };
 195
 196         using DOMPropertySet::getBool;
 197         using DOMPropertySet::getString;
 198         using DOMPropertySet::getUnsignedInt;
 199         using DOMPropertySet::getInt;
 200
 201         /**
 202          * Returns a boolean-valued property.
 203          *
 204          * @param name      property name
 205          * @param request   reference to incoming request
 206          * @param type      bitmask of property sources to use
 207          * @return a pair consisting of a NULL indicator and the property value iff the indicator is true
 208          */
 209         std::pair<bool,bool> getBool(const char* name, const SPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const;
 210
 211         /**
 212          * Returns a string-valued property.
 213          *
 214          * @param name      property name
 215          * @param request   reference to incoming request
 216          * @param type      bitmask of property sources to use
 217          * @return a pair consisting of a NULL indicator and the property value iff the indicator is true
 218          */
 219         std::pair<bool,const char*> getString(const char* name, const SPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const;
 220
 221         /**
 222          * Returns an unsigned integer-valued property.
 223          *
 224          * @param name      property name
 225          * @param request   reference to incoming request
 226          * @param type      bitmask of property sources to use
 227          * @return a pair consisting of a NULL indicator and the property value iff the indicator is true
 228          */
 229         std::pair<bool,unsigned int> getUnsignedInt(const char* name, const SPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const;
 230
 231         /**
 232          * Returns an integer-valued property.
 233          *
 234          * @param name      property name
 235          * @param request   reference to incoming request
 236          * @param type      bitmask of property sources to use
 237          * @return a pair consisting of a NULL indicator and the property value iff the indicator is true
 238          */
 239         std::pair<bool,int> getInt(const char* name, const SPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const;
 240
 241         /** Logging object. */
 242         xmltooling::logging::Category& m_log;
 243
 244         /** Configuration namespace for custom properties. */
 245         xmltooling::auto_ptr_char m_configNS;
 246
 247     public:
 248         virtual ~AbstractHandler();
 249
 250     private:
 251         std::pair<std::string,const char*> getPostCookieNameProps(const Application& app, const char* relayState) const;
 252         DDF getPostData(const Application& application, const xmltooling::HTTPRequest& request) const;
 253     };
 254
 255 #if defined (_MSC_VER)
 256     #pragma warning( pop )
 257 #endif
 258
 259 };
 260
 261 #endif /* __shibsp_abshandler_h__ */