X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=saml%2Fbinding%2FMessageDecoder.h;h=d93c7c90c234c3f47bbe3de4a1e917df7aa91a19;hb=f1208cd2f514700244816377443c4951dc22c848;hp=80254ba837c7af4370d92bcd610c4a3829861e45;hpb=a30857e2c0f4bcd1817aa2939ffdc0856e93a533;p=shibboleth%2Fcpp-opensaml.git diff --git a/saml/binding/MessageDecoder.h b/saml/binding/MessageDecoder.h index 80254ba..d93c7c9 100644 --- a/saml/binding/MessageDecoder.h +++ b/saml/binding/MessageDecoder.h @@ -1,35 +1,46 @@ -/* - * Copyright 2001-2006 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 +/** + * Licensed to the University Corporation for Advanced Internet + * Development, Inc. (UCAID) under one or more contributor license + * agreements. See the NOTICE file distributed with this work for + * additional information regarding copyright ownership. + * + * UCAID licenses this file to you 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 + * 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. + * 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. + * + * Interface to SAML protocol binding message decoders. */ #ifndef __saml_decoder_h__ #define __saml_decoder_h__ -#include -#include -#include +#include + +#include +#include + +namespace xmltooling { + class XMLTOOL_API GenericRequest; + class XMLTOOL_API XMLObject; +}; namespace opensaml { - + class SAML_API SAMLArtifact; + class SAML_API SecurityPolicy; namespace saml1p { class SAML_API Response; }; @@ -51,50 +62,50 @@ namespace opensaml { { MAKE_NONCOPYABLE(MessageDecoder); public: - virtual ~MessageDecoder() {} + virtual ~MessageDecoder(); + + /** + * Returns identifier for the protocol family associated with the decoder. + * + * @return a protocol family identifier, or nullptr + */ + virtual const XMLCh* getProtocolFamily() const; + + /** + * 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; /** * 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. - * + * *

A MessageDecoder implementation will invoke the supplied interface * when it requires an artifact be resolved. */ class SAML_API ArtifactResolver { MAKE_NONCOPYABLE(ArtifactResolver); protected: - ArtifactResolver() {} - - /** Flag controlling schema validation. */ - bool m_validate; + ArtifactResolver(); public: - virtual ~ArtifactResolver() {} + virtual ~ArtifactResolver(); /** - * Controls schema validation of incoming XML messages. - * This is separate from other forms of programmatic validation of objects, - * but can detect a much wider range of syntax errors. - * - * @param validate true iff the resolver should use a validating XML parser - */ - void setValidating(bool validate=true) { - m_validate = validate; - } - - /** * 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. - * + * 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. + * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc. * @return the corresponding SAML Assertions wrapped in a Response. */ virtual saml1p::Response* resolve( @@ -107,74 +118,77 @@ namespace opensaml { * 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. - * + * 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 + * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc. + * @return the corresponding SAML protocol message or nullptr */ 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. - * + * 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(ArtifactResolver* artifactResolver) { - m_artifactResolver = artifactResolver; - if (m_artifactResolver) - m_artifactResolver->setValidating(m_validate); - } - - /** - * Controls schema validation of incoming XML messages. - * This is separate from other forms of programmatic validation of objects, - * but can detect a much wider range of syntax errors. - * - * @param validate true iff the decoder should use a validating XML parser - */ - void setValidating(bool validate=true) { - m_validate = validate; - if (m_artifactResolver) - m_artifactResolver->setValidating(m_validate); - } + void setArtifactResolver(const 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. + * the information necessary to decode the request, nullptr will be returned. * Errors during the decoding process will be raised as exceptions. - * + * *

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 + * @param policy reference to policy containing rules, MetadataProvider, TrustEngine, etc. + * @return the decoded message, or nullptr if the decoder did not recognize the request content */ virtual xmltooling::XMLObject* decode( std::string& relayState, - const GenericRequest& genericRequest, + const xmltooling::GenericRequest& genericRequest, SecurityPolicy& policy ) const=0; protected: - MessageDecoder() : m_artifactResolver(NULL), m_validate(false) {} + MessageDecoder(); /** Pointer to an ArtifactResolver implementation. */ - ArtifactResolver* m_artifactResolver; - - /** Flag controlling schema validation. */ - bool m_validate; + 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; }; /**