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 property rename mapper for legacy property support 76 */ 77 AbstractHandler( 78 const xercesc::DOMElement* e, 79 xmltooling::logging::Category& log, 80 xercesc::DOMNodeFilter* filter=nullptr, 81 const Remapper* 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 defaultSigningProperty the effective value of the "signing" property if unset 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 const char* defaultSigningProperty 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 xmltooling::HTTPRequest& 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 xmltooling::HTTPRequest& 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 xmltooling::HTTPRequest& 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 xmltooling::HTTPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const; 243 244 /** Logging object. */ 245 xmltooling::logging::Category& m_log; 246 247 public: 248 virtual ~AbstractHandler(); 249 250 private: 251 std::string getPostCookieName(const Application& app, const char* relayState) const; 252 DDF getPostData(const Application& application, const xmltooling::HTTPRequest& request) const; 253 }; 254 255 #if defined (_MSC_VER) 256 #pragma warning( pop ) 257 #endif 258 259 }; 260 261 #endif /* __shibsp_abshandler_h__ */ 262