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