-/*\r
- * Copyright 2001-2006 Internet2\r
- * \r
- * Licensed under the Apache License, Version 2.0 (the "License");\r
- * you may not use this file except in compliance with the License.\r
- * You may obtain a copy of the License at\r
- *\r
- * http://www.apache.org/licenses/LICENSE-2.0\r
- *\r
- * Unless required by applicable law or agreed to in writing, software\r
- * distributed under the License is distributed on an "AS IS" BASIS,\r
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
- * See the License for the specific language governing permissions and\r
- * limitations under the License.\r
- */\r
-\r
-/**\r
- * @file saml/binding/MessageDecoder.h\r
- * \r
- * Interface to SAML protocol binding message decoders. \r
- */\r
-\r
-#ifndef __saml_decoder_h__\r
-#define __saml_decoder_h__\r
-\r
-#include <saml/base.h>\r
-\r
-#include <xmltooling/XMLObject.h>\r
-\r
-namespace opensaml {\r
- \r
- class SAML_API SAMLArtifact;\r
- class SAML_API X509TrustEngine;\r
- namespace saml1p {\r
- class SAML_API Response;\r
- };\r
- namespace saml2p {\r
- class SAML_API SAML2Artifact;\r
- };\r
- namespace saml2md {\r
- class SAML_API MetadataProvider;\r
- class SAML_API IDPSSODescriptor;\r
- class SAML_API RoleDescriptor;\r
- class SAML_API SSODescriptorType;\r
- }\r
-\r
- /**\r
- * Interface to SAML protocol binding message decoders.\r
- */\r
- class SAML_API MessageDecoder\r
- {\r
- MAKE_NONCOPYABLE(MessageDecoder);\r
- public:\r
- virtual ~MessageDecoder() {}\r
-\r
- /**\r
- * Interface to caller-supplied shim for accessing HTTP request context.\r
- * \r
- * To supply information from the surrounding web server environment,\r
- * a shim must be supplied in the form of this interface to adapt the\r
- * library to different proprietary server APIs.\r
- */\r
- class SAML_API HTTPRequest {\r
- MAKE_NONCOPYABLE(HTTPRequest);\r
- protected:\r
- HTTPRequest() {}\r
- public:\r
- virtual ~HTTPRequest() {}\r
- \r
- /**\r
- * Returns the HTTP method of the request (GET, POST, etc.)\r
- * \r
- * @return the HTTP method\r
- */\r
- virtual const char* getMethod() const=0;\r
- \r
- /**\r
- * Returns the complete request URL, including scheme, host, port.\r
- * \r
- * @return the request URL\r
- */\r
- virtual const char* getRequestURL() const=0;\r
- \r
- /**\r
- * Returns the HTTP query string appened to the request. The query\r
- * string is returned without any decoding applied, everything found\r
- * after the ? delimiter. \r
- * \r
- * @return the query string\r
- */\r
- virtual const char* getQueryString() const=0;\r
- \r
- /**\r
- * Returns a decoded named parameter value from the query string or form body.\r
- * If a parameter has multiple values, only one will be returned.\r
- * \r
- * @param name the name of the parameter to return\r
- * @return a single parameter value or NULL\r
- */\r
- virtual const char* getParameter(const char* name) const=0;\r
-\r
- /**\r
- * Returns all of the decoded values of a named parameter from the query string\r
- * or form body. All values found will be returned.\r
- * \r
- * @param name the name of the parameter to return\r
- * @param values a vector in which to return pointers to the decoded values\r
- * @return the number of values returned\r
- */ \r
- virtual std::vector<const char*>::size_type getParameters(\r
- const char* name, std::vector<const char*>& values\r
- ) const=0;\r
- };\r
-\r
- /**\r
- * Interface to caller-supplied artifact resolution mechanism.\r
- * \r
- * Resolving artifacts requires internally performing a SOAP-based\r
- * call to the artifact source, usually in a mutually authenticated fashion.\r
- * The potential options vary widely, so the work is encapsulated by this\r
- * interface, though of course other library facilities may be used.\r
- * \r
- * <p>A MessageDecoder implementation will invoke the supplied interface\r
- * when it requires an artifact be resolved.\r
- */\r
- class SAML_API ArtifactResolver {\r
- MAKE_NONCOPYABLE(ArtifactResolver);\r
- protected:\r
- ArtifactResolver() {}\r
- public:\r
- virtual ~ArtifactResolver() {}\r
- \r
- /**\r
- * Resolves one or more SAML 1.x artifacts into a response containing a set of\r
- * resolved Assertions. The caller is responsible for the resulting Response. \r
- * \r
- * @param artifacts one or more SAML 1.x artifacts\r
- * @param idpDescriptor reference to IdP role of artifact issuer\r
- * @param trustEngine optional pointer to X509TrustEngine supplied to MessageDecoder\r
- * @return the corresponding SAML Assertions wrapped in a Response.\r
- */\r
- virtual saml1p::Response* resolve(\r
- const std::vector<const SAMLArtifact*>& artifacts,\r
- const saml2md::IDPSSODescriptor& idpDescriptor,\r
- const X509TrustEngine* trustEngine=NULL\r
- ) const=0;\r
-\r
- /**\r
- * Resolves a SAML 2.0 artifact into the corresponding SAML protocol message.\r
- * The caller is responsible for the resulting XMLObject.\r
- * \r
- * @param artifact reference to a SAML 2.0 artifact\r
- * @param ssoDescriptor reference to SSO role of artifact issuer (may be SP or IdP)\r
- * @param trustEngine optional pointer to X509TrustEngine supplied to MessageDecoder\r
- * @return the corresponding SAML protocol message or NULL\r
- */\r
- virtual xmltooling::XMLObject* resolve(\r
- const saml2p::SAML2Artifact& artifact,\r
- const saml2md::SSODescriptorType& ssoDescriptor,\r
- const X509TrustEngine* trustEngine=NULL\r
- ) const=0;\r
- };\r
-\r
- /**\r
- * Provides an ArtifactResolver implementation for the MessageDecoder to use.\r
- * The implementation's lifetime must be longer than the lifetime of this object. \r
- * This method must be externally synchronized. \r
- * \r
- * @param artifactResolver an ArtifactResolver implementation to use\r
- */\r
- void setArtifactResolver(ArtifactResolver* artifactResolver) {\r
- m_artifactResolver = artifactResolver;\r
- }\r
- \r
- /**\r
- * Controls schema validation of incoming XML messages.\r
- * This is separate from other forms of programmatic validation of objects,\r
- * but can detect a much wider range of syntax errors. \r
- * \r
- * @param validate true iff the decoder should use a validating XML parser\r
- */\r
- void setValidating(bool validate=true) {\r
- m_validate = validate;\r
- }\r
-\r
- /**\r
- * Decodes an HTTP request into a SAML protocol message, and returns related\r
- * information about the issuer of the message and whether it can be trusted.\r
- * If the HTTP request does not contain the information necessary to decode\r
- * the request, a NULL will be returned. Errors during the decoding process\r
- * will be raised as exceptions.\r
- * \r
- * <p>Artifact-based bindings require an ArtifactResolver be set to\r
- * turn an artifact into the corresponding message.\r
- * \r
- * <p>In some cases, a message may be returned but not authenticated. The caller\r
- * should examine the issuerTrusted output value to establish this. \r
- * \r
- * @param relayState RelayState/TARGET value accompanying message\r
- * @param issuer role descriptor of issuing party\r
- * @param issuerTrusted will be true iff the message was authenticated (signed or obtained via secure backchannel)\r
- * @param httpRequest reference to interface for accessing HTTP message to decode\r
- * @param metadataProvider optional MetadataProvider instance to authenticate the message\r
- * @param role optional, identifies the role (generally IdP or SP) of the peer who issued the message \r
- * @param trustEngine optional X509TrustEngine to authenticate the message\r
- * @return the decoded message, or NULL if the decoder did not recognize the request content\r
- */\r
- virtual xmltooling::XMLObject* decode(\r
- std::string& relayState,\r
- const saml2md::RoleDescriptor*& issuer,\r
- bool& issuerTrusted,\r
- const HTTPRequest& httpRequest,\r
- const saml2md::MetadataProvider* metadataProvider=NULL,\r
- const xmltooling::QName* role=NULL,\r
- const X509TrustEngine* trustEngine=NULL\r
- ) const=0;\r
-\r
- protected:\r
- MessageDecoder() : m_artifactResolver(NULL), m_validate(false) {}\r
-\r
- /** Pointer to an ArtifactResolver implementation. */\r
- const ArtifactResolver* m_artifactResolver;\r
- \r
- /** Flag controlling schema validation. */\r
- bool m_validate;\r
- };\r
-\r
- /**\r
- * Registers MessageDecoder plugins into the runtime.\r
- */\r
- void SAML_API registerMessageDecoders();\r
-\r
- /** MessageDecoder for SAML 1.x Browser/Artifact "binding" (really part of profile) */\r
- #define SAML1_ARTIFACT_DECODER "urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"\r
-\r
- /** MessageDecoder for SAML 1.x Browser/POST "binding" (really part of profile) */\r
- #define SAML1_POST_DECODER "urn:oasis:names:tc:SAML:1.0:profiles:browser-post"\r
- \r
- /** MessageDecoder for SAML 2.0 HTTP-Artifact binding */\r
- #define SAML2_ARTIFACT_DECODER "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"\r
-\r
- /** MessageDecoder for SAML 2.0 HTTP-POST binding */\r
- #define SAML2_POST_DECODER "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"\r
-\r
- /** MessageDecoder for SAML 2.0 HTTP-Redirect binding */\r
- #define SAML2_REDIRECT_DECODER "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"\r
-};\r
-\r
-#endif /* __saml_decoder_h__ */\r
+/*
+ * Copyright 2001-2009 Internet2
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file saml/binding/MessageDecoder.h
+ *
+ * Interface to SAML protocol binding message decoders.
+ */
+
+#ifndef __saml_decoder_h__
+#define __saml_decoder_h__
+
+#include <saml/binding/SecurityPolicy.h>
+#include <xmltooling/XMLObject.h>
+#include <xmltooling/io/GenericRequest.h>
+
+namespace opensaml {
+
+ class SAML_API SAMLArtifact;
+ namespace saml1p {
+ class SAML_API Response;
+ };
+ namespace saml2p {
+ class SAML_API SAML2Artifact;
+ class SAML_API ArtifactResponse;
+ };
+ namespace saml2md {
+ class SAML_API MetadataProvider;
+ class SAML_API IDPSSODescriptor;
+ class SAML_API RoleDescriptor;
+ class SAML_API SSODescriptorType;
+ };
+
+ /**
+ * Interface to SAML protocol binding message decoders.
+ */
+ class SAML_API MessageDecoder
+ {
+ MAKE_NONCOPYABLE(MessageDecoder);
+ public:
+ virtual ~MessageDecoder() {}
+
+ /**
+ * Indicates whether a web browser or similar user agent delivered the message.
+ *
+ * @return true iff the message was delivered by a user agent
+ */
+ virtual bool isUserAgentPresent() const {
+ return true;
+ }
+
+ /**
+ * Interface to caller-supplied artifact resolution mechanism.
+ *
+ * Resolving artifacts requires internally performing a SOAP-based
+ * call to the artifact source, usually in a mutually authenticated fashion.
+ * The potential options vary widely, so the work is encapsulated by this
+ * interface, though of course other library facilities may be used.
+ *
+ * <p>A MessageDecoder implementation will invoke the supplied interface
+ * when it requires an artifact be resolved.
+ */
+ class SAML_API ArtifactResolver {
+ MAKE_NONCOPYABLE(ArtifactResolver);
+ protected:
+ ArtifactResolver() {}
+
+ public:
+ virtual ~ArtifactResolver() {}
+
+ /**
+ * Resolves one or more SAML 1.x artifacts into a response containing a set of
+ * resolved Assertions. The caller is responsible for the resulting Response.
+ * The supplied SecurityPolicy is used to access caller-supplied infrastructure
+ * and to pass back the result of authenticating the resolution process.
+ *
+ * @param artifacts one or more SAML 1.x artifacts
+ * @param idpDescriptor reference to IdP role of artifact issuer
+ * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc.
+ * @return the corresponding SAML Assertions wrapped in a Response.
+ */
+ virtual saml1p::Response* resolve(
+ const std::vector<SAMLArtifact*>& artifacts,
+ const saml2md::IDPSSODescriptor& idpDescriptor,
+ SecurityPolicy& policy
+ ) const=0;
+
+ /**
+ * Resolves a SAML 2.0 artifact into the corresponding SAML protocol message.
+ * The caller is responsible for the resulting ArtifactResponse message.
+ * The supplied SecurityPolicy is used to access caller-supplied infrastructure
+ * and to pass back the result of authenticating the resolution process.
+ *
+ * @param artifact reference to a SAML 2.0 artifact
+ * @param ssoDescriptor reference to SSO role of artifact issuer (may be SP or IdP)
+ * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc.
+ * @return the corresponding SAML protocol message or NULL
+ */
+ virtual saml2p::ArtifactResponse* resolve(
+ const saml2p::SAML2Artifact& artifact,
+ const saml2md::SSODescriptorType& ssoDescriptor,
+ SecurityPolicy& policy
+ ) const=0;
+
+ /**
+ * Returns true iff the metadata provided includes a supported artifact resolution service.
+ *
+ * @param ssoDescriptor reference to SSO role of artifact issuer (may be SP or IdP)
+ * @return true iff the artifact issuer offers endpoints supported by this resolver
+ */
+ virtual bool isSupported(const saml2md::SSODescriptorType& ssoDescriptor) const;
+ };
+
+ /**
+ * Provides an ArtifactResolver implementation for the MessageDecoder to use.
+ * The implementation's lifetime must be longer than the lifetime of this object.
+ * This method must be externally synchronized.
+ *
+ * @param artifactResolver an ArtifactResolver implementation to use
+ */
+ void setArtifactResolver(const ArtifactResolver* artifactResolver) {
+ m_artifactResolver = artifactResolver;
+ }
+
+ /**
+ * Decodes a transport request into a SAML protocol message, and evaluates it
+ * against a supplied SecurityPolicy. If the transport request does not contain
+ * the information necessary to decode the request, NULL will be returned.
+ * Errors during the decoding process will be raised as exceptions.
+ *
+ * <p>Artifact-based bindings require an ArtifactResolver be set to
+ * turn an artifact into the corresponding message.
+ *
+ * @param relayState will be set to RelayState/TARGET value accompanying message
+ * @param genericRequest reference to interface for accessing transport request to decode
+ * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc.
+ * @return the decoded message, or NULL if the decoder did not recognize the request content
+ */
+ virtual xmltooling::XMLObject* decode(
+ std::string& relayState,
+ const xmltooling::GenericRequest& genericRequest,
+ SecurityPolicy& policy
+ ) const=0;
+
+ protected:
+ MessageDecoder() : m_artifactResolver(NULL) {}
+
+ /** Pointer to an ArtifactResolver implementation. */
+ const ArtifactResolver* m_artifactResolver;
+
+ /**
+ * Extracts policy-relevant message details.
+ *
+ * @param message the incoming message
+ * @param request the protocol request
+ * @param protocol the protocol family in use
+ * @param policy SecurityPolicy to provide various components and track message data
+ */
+ virtual void extractMessageDetails (
+ const xmltooling::XMLObject& message,
+ const xmltooling::GenericRequest& request,
+ const XMLCh* protocol,
+ SecurityPolicy& policy
+ ) const=0;
+ };
+
+ /**
+ * Registers MessageDecoder plugins into the runtime.
+ */
+ void SAML_API registerMessageDecoders();
+};
+
+#endif /* __saml_decoder_h__ */
projects / shibboleth / cpp-opensaml.git / blobdiff