X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=saml%2Fbinding%2FMessageDecoder.h;h=d93c7c90c234c3f47bbe3de4a1e917df7aa91a19;hb=f1208cd2f514700244816377443c4951dc22c848;hp=9f3905df64816105e84651034939d876452e5bdf;hpb=7748ee29f760b74bca03c744deacba466a333c43;p=shibboleth%2Fcpp-opensaml.git diff --git a/saml/binding/MessageDecoder.h b/saml/binding/MessageDecoder.h index 9f3905d..d93c7c9 100644 --- a/saml/binding/MessageDecoder.h +++ b/saml/binding/MessageDecoder.h @@ -1,35 +1,46 @@ -/* - * Copyright 2001-2007 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,45 +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 { - return true; - } + 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() {} + ArtifactResolver(); public: - virtual ~ArtifactResolver() {} + 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. - * + * 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( @@ -102,44 +118,50 @@ 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(const ArtifactResolver* artifactResolver) { - m_artifactResolver = artifactResolver; - } - + 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, @@ -148,14 +170,14 @@ namespace opensaml { ) const=0; protected: - MessageDecoder() : m_artifactResolver(NULL) {} + MessageDecoder(); /** 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