shibsp/handler/AbstractHandler.h

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