saml/binding/MessageDecoder.h

   1 /*
   2  *  Copyright 2001-2006 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file saml/binding/MessageDecoder.h
  19  *
  20  * Interface to SAML protocol binding message decoders.
  21  */
  22
  23 #ifndef __saml_decoder_h__
  24 #define __saml_decoder_h__
  25
  26 #include <saml/binding/GenericRequest.h>
  27 #include <saml/binding/SecurityPolicy.h>
  28 #include <xmltooling/XMLObject.h>
  29
  30 namespace opensaml {
  31
  32     class SAML_API SAMLArtifact;
  33     class SAML_API X509TrustEngine;
  34     namespace saml1p {
  35         class SAML_API Response;
  36     };
  37     namespace saml2p {
  38         class SAML_API SAML2Artifact;
  39         class SAML_API ArtifactResponse;
  40     };
  41     namespace saml2md {
  42         class SAML_API MetadataProvider;
  43         class SAML_API IDPSSODescriptor;
  44         class SAML_API RoleDescriptor;
  45         class SAML_API SSODescriptorType;
  46     };
  47
  48     /**
  49      * Interface to SAML protocol binding message decoders.
  50      */
  51     class SAML_API MessageDecoder
  52     {
  53         MAKE_NONCOPYABLE(MessageDecoder);
  54     public:
  55         virtual ~MessageDecoder() {}
  56
  57         /**
  58          * Interface to caller-supplied artifact resolution mechanism.
  59          *
  60          * Resolving artifacts requires internally performing a SOAP-based
  61          * call to the artifact source, usually in a mutually authenticated fashion.
  62          * The potential options vary widely, so the work is encapsulated by this
  63          * interface, though of course other library facilities may be used.
  64          *
  65          * <p>A MessageDecoder implementation will invoke the supplied interface
  66          * when it requires an artifact be resolved.
  67          */
  68         class SAML_API ArtifactResolver {
  69             MAKE_NONCOPYABLE(ArtifactResolver);
  70         protected:
  71             ArtifactResolver() {}
  72
  73             /** Flag controlling schema validation. */
  74             bool m_validate;
  75
  76         public:
  77             virtual ~ArtifactResolver() {}
  78
  79             /**
  80              * Controls schema validation of incoming XML messages.
  81              * This is separate from other forms of programmatic validation of objects,
  82              * but can detect a much wider range of syntax errors.
  83              *
  84              * @param validate  true iff the resolver should use a validating XML parser
  85              */
  86             void setValidating(bool validate=true) {
  87                 m_validate = validate;
  88             }
  89
  90             /**
  91              * Resolves one or more SAML 1.x artifacts into a response containing a set of
  92              * resolved Assertions. The caller is responsible for the resulting Response.
  93              * The supplied SecurityPolicy is used to access caller-supplied infrastructure
  94              * and to pass back the result of authenticating the resolution process.
  95              *
  96              * @param artifacts         one or more SAML 1.x artifacts
  97              * @param idpDescriptor     reference to IdP role of artifact issuer
  98              * @param policy            reference to policy containing rules, MetadataProvider, TrustEngine, etc.
  99              * @return the corresponding SAML Assertions wrapped in a Response.
 100              */
 101             virtual saml1p::Response* resolve(
 102                 const std::vector<SAMLArtifact*>& artifacts,
 103                 const saml2md::IDPSSODescriptor& idpDescriptor,
 104                 SecurityPolicy& policy
 105                 ) const=0;
 106
 107             /**
 108              * Resolves a SAML 2.0 artifact into the corresponding SAML protocol message.
 109              * The caller is responsible for the resulting ArtifactResponse message.
 110              * The supplied SecurityPolicy is used to access caller-supplied infrastructure
 111              * and to pass back the result of authenticating the resolution process.
 112              *
 113              * @param artifact          reference to a SAML 2.0 artifact
 114              * @param ssoDescriptor     reference to SSO role of artifact issuer (may be SP or IdP)
 115              * @param policy            reference to policy containing rules, MetadataProvider, TrustEngine, etc.
 116              * @return the corresponding SAML protocol message or NULL
 117              */
 118             virtual saml2p::ArtifactResponse* resolve(
 119                 const saml2p::SAML2Artifact& artifact,
 120                 const saml2md::SSODescriptorType& ssoDescriptor,
 121                 SecurityPolicy& policy
 122                 ) const=0;
 123         };
 124
 125         /**
 126          * Provides an ArtifactResolver implementation for the MessageDecoder to use.
 127          * The implementation's lifetime must be longer than the lifetime of this object.
 128          * This method must be externally synchronized.
 129          *
 130          * @param artifactResolver   an ArtifactResolver implementation to use
 131          */
 132         void setArtifactResolver(ArtifactResolver* artifactResolver) {
 133             m_artifactResolver = artifactResolver;
 134             if (m_artifactResolver)
 135                 m_artifactResolver->setValidating(m_validate);
 136         }
 137
 138         /**
 139          * Controls schema validation of incoming XML messages.
 140          * This is separate from other forms of programmatic validation of objects,
 141          * but can detect a much wider range of syntax errors.
 142          *
 143          * @param validate  true iff the decoder should use a validating XML parser
 144          */
 145         void setValidating(bool validate=true) {
 146             m_validate = validate;
 147             if (m_artifactResolver)
 148                 m_artifactResolver->setValidating(m_validate);
 149         }
 150
 151         /**
 152          * Decodes a transport request into a SAML protocol message, and evaluates it
 153          * against a supplied SecurityPolicy. If the transport request does not contain
 154          * the information necessary to decode the request, NULL will be returned.
 155          * Errors during the decoding process will be raised as exceptions.
 156          *
 157          * <p>Artifact-based bindings require an ArtifactResolver be set to
 158          * turn an artifact into the corresponding message.
 159          *
 160          * @param relayState        will be set to RelayState/TARGET value accompanying message
 161          * @param genericRequest    reference to interface for accessing transport request to decode
 162          * @param policy            reference to policy containing rules, MetadataProvider, TrustEngine, etc.
 163          * @return  the decoded message, or NULL if the decoder did not recognize the request content
 164          */
 165         virtual xmltooling::XMLObject* decode(
 166             std::string& relayState,
 167             const GenericRequest& genericRequest,
 168             SecurityPolicy& policy
 169             ) const=0;
 170
 171     protected:
 172         MessageDecoder() : m_artifactResolver(NULL), m_validate(false) {}
 173
 174         /** Pointer to an ArtifactResolver implementation. */
 175         ArtifactResolver* m_artifactResolver;
 176
 177         /** Flag controlling schema validation. */
 178         bool m_validate;
 179     };
 180
 181     /**
 182      * Registers MessageDecoder plugins into the runtime.
 183      */
 184     void SAML_API registerMessageDecoders();
 185 };
 186
 187 #endif /* __saml_decoder_h__ */