shibsp/handler/AbstractHandler.h

   1 /*
   2  *  Copyright 2001-2009 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 #ifndef SHIBSP_LITE
  31 # include <saml/binding/MessageEncoder.h>
  32 # include <saml/saml2/core/Protocols.h>
  33 #endif
  34 #include <xmltooling/logging.h>
  35 #include <xmltooling/XMLObject.h>
  36 #include <xmltooling/io/HTTPRequest.h>
  37 #include <xmltooling/io/HTTPResponse.h>
  38
  39 namespace shibsp {
  40
  41     class SHIBSP_API Application;
  42     class SHIBSP_API SPRequest;
  43
  44 #if defined (_MSC_VER)
  45     #pragma warning( push )
  46     #pragma warning( disable : 4250 )
  47 #endif
  48
  49     /**
  50      * Base class for handlers based on a DOMPropertySet.
  51      */
  52     class SHIBSP_API AbstractHandler : public virtual Handler, public DOMPropertySet
  53     {
  54     protected:
  55         /**
  56          * Constructor
  57          *
  58          * @param e         DOM element to load as property set.
  59          * @param log       logging category to use
  60          * @param filter    optional filter controls what child elements to include as nested PropertySets
  61          * @param remapper  optional map of property rename rules for legacy property support
  62          */
  63         AbstractHandler(
  64             const xercesc::DOMElement* e,
  65             xmltooling::logging::Category& log,
  66             xercesc::DOMNodeFilter* filter=NULL,
  67             const std::map<std::string,std::string>* remapper=NULL
  68             );
  69
  70 #ifndef SHIBSP_LITE
  71         /**
  72          * Examines a protocol response message for errors and raises an annotated exception
  73          * if an error is found.
  74          *
  75          * <p>The base class version understands SAML 1.x and SAML 2.0 responses.
  76          *
  77          * @param response  a response message of some known protocol
  78          * @param role      issuer of message
  79          */
  80         virtual void checkError(
  81             const xmltooling::XMLObject* response,
  82             const opensaml::saml2md::RoleDescriptor* role=NULL
  83             ) const;
  84
  85         /**
  86          * Prepares Status information in a SAML 2.0 response.
  87          *
  88          * @param response  SAML 2.0 response message
  89          * @param code      SAML status code
  90          * @param subcode   optional SAML substatus code
  91          * @param msg       optional message to pass back
  92          */
  93         void fillStatus(
  94             opensaml::saml2p::StatusResponseType& response, const XMLCh* code, const XMLCh* subcode=NULL, const char* msg=NULL
  95             ) const;
  96
  97         /**
  98          * Encodes and sends SAML 2.0 message, optionally signing it in the process.
  99          * If the method returns, the message MUST NOT be freed by the caller.
 100          *
 101          * @param encoder           the MessageEncoder to use
 102          * @param msg               the message to send
 103          * @param relayState        any RelayState to include with the message
 104          * @param destination       location to send message, if not a backchannel response
 105          * @param role              recipient of message, if known
 106          * @param application       the Application sending the message
 107          * @param httpResponse      channel for sending message
 108          * @param signIfPossible    true iff signing should be attempted regardless of "signing" property
 109          * @return  the result of sending the message using the encoder
 110          */
 111         long sendMessage(
 112             const opensaml::MessageEncoder& encoder,
 113             xmltooling::XMLObject* msg,
 114             const char* relayState,
 115             const char* destination,
 116             const opensaml::saml2md::RoleDescriptor* role,
 117             const Application& application,
 118             xmltooling::HTTPResponse& httpResponse,
 119             bool signIfPossible=false
 120             ) const;
 121 #endif
 122
 123         /**
 124          * Implements various mechanisms to preserve RelayState,
 125          * such as cookies or StorageService-backed keys.
 126          *
 127          * <p>If a supported mechanism can be identified, the input parameter will be
 128          * replaced with a suitable state key.
 129          *
 130          * @param application   the associated Application
 131          * @param response      outgoing HTTP response
 132          * @param relayState    RelayState token to supply with message
 133          */
 134         virtual void preserveRelayState(
 135             const Application& application, xmltooling::HTTPResponse& response, std::string& relayState
 136             ) const;
 137
 138         /**
 139          * Implements various mechanisms to recover RelayState,
 140          * such as cookies or StorageService-backed keys.
 141          *
 142          * <p>If a supported mechanism can be identified, the input parameter will be
 143          * replaced with the recovered state information.
 144          *
 145          * @param application   the associated Application
 146          * @param request       incoming HTTP request
 147          * @param response      outgoing HTTP response
 148          * @param relayState    RelayState token supplied with message
 149          * @param clear         true iff the token state should be cleared
 150          */
 151         virtual void recoverRelayState(
 152             const Application& application,
 153             const xmltooling::HTTPRequest& request,
 154             xmltooling::HTTPResponse& response,
 155             std::string& relayState,
 156             bool clear=true
 157             ) const;
 158
 159         /**
 160          * Implements a mechanism to preserve form post data.
 161          *
 162          * @param application   the associated Application
 163          * @param request       incoming HTTP request
 164          * @param response      outgoing HTTP response
 165          * @param relayState    relay state information attached to current sequence, if any
 166          */
 167         virtual void preservePostData(
 168             const Application& application,
 169             const xmltooling::HTTPRequest& request,
 170             xmltooling::HTTPResponse& response,
 171             const char* relayState
 172             ) const;
 173
 174         /**
 175          * Implements storage service and cookie mechanism to recover PostData.
 176          *
 177          * <p>If a supported mechanism can be identified, the return value will be
 178          * the recovered state information.
 179          *
 180          * @param application   the associated Application
 181          * @param request       incoming HTTP request
 182          * @param response      outgoing HTTP response
 183          * @param relayState    relay state information attached to current sequence, if any
 184          * @return  recovered form post data associated with request as a DDF list of string members
 185          */
 186         virtual DDF recoverPostData(
 187             const Application& application,
 188             const xmltooling::HTTPRequest& request,
 189             xmltooling::HTTPResponse& response,
 190             const char* relayState
 191             ) const;
 192
 193         /**
 194          * Post a redirect response with post data.
 195          *
 196          * @param application   the associated Application
 197          * @param response      outgoing HTTP response
 198          * @param request       incoming HTTP request
 199          * @param url           action url for the form
 200          * @param postData      list of parameters to load into the form, as DDF string members
 201          */
 202         virtual long sendPostResponse(
 203             const Application& application,
 204             xmltooling::HTTPResponse& httpResponse,
 205             const char* url,
 206             DDF& postData
 207             ) const;
 208
 209         /** Logging object. */
 210         xmltooling::logging::Category& m_log;
 211
 212         /** Configuration namespace for custom properties. */
 213         xmltooling::auto_ptr_char m_configNS;
 214
 215     public:
 216         virtual ~AbstractHandler() {}
 217
 218     private:
 219         std::pair<std::string,const char*> getPostCookieNameProps(const Application& app, const char* relayState) const;
 220         DDF getPostData(const Application& application, const xmltooling::HTTPRequest& request) const;
 221     };
 222
 223 #if defined (_MSC_VER)
 224     #pragma warning( pop )
 225 #endif
 226
 227 };
 228
 229 #endif /* __shibsp_abshandler_h__ */