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.
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 * @file shibsp/handler/AbstractHandler.h
24 * Base class for handlers based on a DOMPropertySet.
27 #ifndef __shibsp_abshandler_h__
28 #define __shibsp_abshandler_h__
30 #include <shibsp/handler/Handler.h>
31 #include <shibsp/remoting/ddf.h>
32 #include <shibsp/util/DOMPropertySet.h>
36 #include <xmltooling/logging.h>
40 class SAML_API MessageEncoder;
42 class SAML_API RoleDescriptor;
45 class SAML_API StatusResponseType;
50 namespace xmltooling {
51 class XMLTOOL_API XMLObject;
56 class SHIBSP_API Application;
58 #if defined (_MSC_VER)
59 #pragma warning( push )
60 #pragma warning( disable : 4250 )
64 * Base class for handlers based on a DOMPropertySet.
66 class SHIBSP_API AbstractHandler : public virtual Handler, public DOMPropertySet
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
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
84 void log(SPRequest::SPLogLevel level, const std::string& msg) const;
88 * Examines a protocol response message for errors and raises an annotated exception
89 * if an error is found.
91 * <p>The base class version understands SAML 1.x and SAML 2.0 responses.
93 * @param response a response message of some known protocol
94 * @param role issuer of message
96 virtual void checkError(
97 const xmltooling::XMLObject* response,
98 const opensaml::saml2md::RoleDescriptor* role=nullptr
102 * Prepares Status information in a SAML 2.0 response.
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
110 opensaml::saml2p::StatusResponseType& response, const XMLCh* code, const XMLCh* subcode=nullptr, const char* msg=nullptr
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.
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
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
140 * Implements a mechanism to preserve form post data.
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
147 virtual void preservePostData(
148 const Application& application,
149 const xmltooling::HTTPRequest& request,
150 xmltooling::HTTPResponse& response,
151 const char* relayState
155 * Implements storage service and cookie mechanism to recover PostData.
157 * <p>If a supported mechanism can be identified, the return value will be
158 * the recovered state information.
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
166 virtual DDF recoverPostData(
167 const Application& application,
168 const xmltooling::HTTPRequest& request,
169 xmltooling::HTTPResponse& response,
170 const char* relayState
174 * Post a redirect response with post data.
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
181 virtual long sendPostResponse(
182 const Application& application,
183 xmltooling::HTTPResponse& response,
189 * Bitmask of property sources to read from
190 * (request query parameter, request mapper, fixed handler property).
192 enum PropertySourceTypes {
193 HANDLER_PROPERTY_REQUEST = 1,
194 HANDLER_PROPERTY_MAP = 2,
195 HANDLER_PROPERTY_FIXED = 4,
196 HANDLER_PROPERTY_ALL = 255
199 using DOMPropertySet::getBool;
200 using DOMPropertySet::getString;
201 using DOMPropertySet::getUnsignedInt;
202 using DOMPropertySet::getInt;
205 * Returns a boolean-valued property.
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
212 std::pair<bool,bool> getBool(const char* name, const SPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const;
215 * Returns a string-valued property.
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
222 std::pair<bool,const char*> getString(const char* name, const SPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const;
225 * Returns an unsigned integer-valued property.
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
232 std::pair<bool,unsigned int> getUnsignedInt(const char* name, const SPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const;
235 * Returns an integer-valued property.
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
242 std::pair<bool,int> getInt(const char* name, const SPRequest& request, unsigned int type=HANDLER_PROPERTY_ALL) const;
244 /** Logging object. */
245 xmltooling::logging::Category& m_log;
247 /** Configuration namespace for custom properties. */
248 xmltooling::auto_ptr_char m_configNS;
251 virtual ~AbstractHandler();
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;
258 #if defined (_MSC_VER)
259 #pragma warning( pop )
264 #endif /* __shibsp_abshandler_h__ */