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=nullptr,
  77             const std::map<std::string,std::string>* remapper=nullptr
  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=nullptr
  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=nullptr, const char* msg=nullptr
 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 url           action url for the form
 175          * @param postData      list of parameters to load into the form, as DDF string members
 176          */
 177         virtual long sendPostResponse(
 178             const Application& application,
 179             xmltooling::HTTPResponse& response,
 180             const char* url,
 181             DDF& postData
 182             ) const;
 183
 184         /**
 185          * Bitmask of property sources to read from
 186          * (request query parameter, request mapper, fixed handler property).
 187          */
 188         enum PropertySourceTypes {
 189             HANDLER_PROPERTY_REQUEST = 1,
 190             HANDLER_PROPERTY_MAP = 2,
 191             HANDLER_PROPERTY_FIXED = 4,
 192             HANDLER_PROPERTY_ALL = 255
 193         };
 194
 195         using DOMPropertySet::getBool;
 196         using DOMPropertySet::getString;
 197         using DOMPropertySet::getUnsignedInt;
 198         using DOMPropertySet::getInt;
 199
 200         /**
 201          * Returns a boolean-valued property.
 202          *
 203          * @param name      property name
 204          * @param request   reference to incoming request
 205          * @param type      bitmask of property sources to use
 206          * @return a pair consisting of a nullptr indicator and the property value iff the indicator is true
 207          */
 208         std::pair<bool,bool> getBool(const char* name, const SPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const;
 209
 210         /**
 211          * Returns a string-valued property.
 212          *
 213          * @param name      property name
 214          * @param request   reference to incoming request
 215          * @param type      bitmask of property sources to use
 216          * @return a pair consisting of a nullptr indicator and the property value iff the indicator is true
 217          */
 218         std::pair<bool,const char*> getString(const char* name, const SPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const;
 219
 220         /**
 221          * Returns an unsigned integer-valued property.
 222          *
 223          * @param name      property name
 224          * @param request   reference to incoming request
 225          * @param type      bitmask of property sources to use
 226          * @return a pair consisting of a nullptr indicator and the property value iff the indicator is true
 227          */
 228         std::pair<bool,unsigned int> getUnsignedInt(const char* name, const SPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const;
 229
 230         /**
 231          * Returns an integer-valued property.
 232          *
 233          * @param name      property name
 234          * @param request   reference to incoming request
 235          * @param type      bitmask of property sources to use
 236          * @return a pair consisting of a nullptr indicator and the property value iff the indicator is true
 237          */
 238         std::pair<bool,int> getInt(const char* name, const SPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const;
 239
 240         /** Logging object. */
 241         xmltooling::logging::Category& m_log;
 242
 243         /** Configuration namespace for custom properties. */
 244         xmltooling::auto_ptr_char m_configNS;
 245
 246     public:
 247         virtual ~AbstractHandler();
 248
 249     private:
 250         std::pair<std::string,const char*> getPostCookieNameProps(const Application& app, const char* relayState) const;
 251         DDF getPostData(const Application& application, const xmltooling::HTTPRequest& request) const;
 252     };
 253
 254 #if defined (_MSC_VER)
 255     #pragma warning( pop )
 256 #endif
 257
 258 };
 259
 260 #endif /* __shibsp_abshandler_h__ */