shibsp/handler/AbstractHandler.h

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