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/base.h>
  27
  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 shim for accessing HTTP request context.
  59          *
  60          * To supply information from the surrounding web server environment,
  61          * a shim must be supplied in the form of this interface to adapt the
  62          * library to different proprietary server APIs.
  63          */
  64         class SAML_API HTTPRequest {
  65             MAKE_NONCOPYABLE(HTTPRequest);
  66         protected:
  67             HTTPRequest() {}
  68         public:
  69             virtual ~HTTPRequest() {}
  70
  71             /**
  72              * Returns the HTTP method of the request (GET, POST, etc.)
  73              *
  74              * @return the HTTP method
  75              */
  76             virtual const char* getMethod() const=0;
  77
  78             /**
  79              * Returns the complete request URL, including scheme, host, port.
  80              *
  81              * @return the request URL
  82              */
  83             virtual const char* getRequestURL() const=0;
  84
  85             /**
  86              * Returns the HTTP query string appened to the request. The query
  87              * string is returned without any decoding applied, everything found
  88              * after the ? delimiter.
  89              *
  90              * @return the query string
  91              */
  92             virtual const char* getQueryString() const=0;
  93
  94             /**
  95              * Returns a decoded named parameter value from the query string or form body.
  96              * If a parameter has multiple values, only one will be returned.
  97              *
  98              * @param name  the name of the parameter to return
  99              * @return a single parameter value or NULL
 100              */
 101             virtual const char* getParameter(const char* name) const=0;
 102
 103             /**
 104              * Returns all of the decoded values of a named parameter from the query string
 105              * or form body. All values found will be returned.
 106              *
 107              * @param name      the name of the parameter to return
 108              * @param values    a vector in which to return pointers to the decoded values
 109              * @return  the number of values returned
 110              */
 111             virtual std::vector<const char*>::size_type getParameters(
 112                 const char* name, std::vector<const char*>& values
 113                 ) const=0;
 114         };
 115
 116         /**
 117          * Interface to caller-supplied artifact resolution mechanism.
 118          *
 119          * Resolving artifacts requires internally performing a SOAP-based
 120          * call to the artifact source, usually in a mutually authenticated fashion.
 121          * The potential options vary widely, so the work is encapsulated by this
 122          * interface, though of course other library facilities may be used.
 123          *
 124          * <p>A MessageDecoder implementation will invoke the supplied interface
 125          * when it requires an artifact be resolved.
 126          */
 127         class SAML_API ArtifactResolver {
 128             MAKE_NONCOPYABLE(ArtifactResolver);
 129         protected:
 130             ArtifactResolver() {}
 131
 132             /** Flag controlling schema validation. */
 133             bool m_validate;
 134
 135         public:
 136             virtual ~ArtifactResolver() {}
 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 resolver should use a validating XML parser
 144              */
 145             void setValidating(bool validate=true) {
 146                 m_validate = validate;
 147             }
 148
 149             /**
 150              * Resolves one or more SAML 1.x artifacts into a response containing a set of
 151              * resolved Assertions. The caller is responsible for the resulting Response.
 152              *
 153              * @param authenticated     output flag set to true iff the resolution channel was authenticated
 154              * @param artifacts         one or more SAML 1.x artifacts
 155              * @param idpDescriptor     reference to IdP role of artifact issuer
 156              * @param trustEngine       optional pointer to X509TrustEngine supplied to MessageDecoder
 157              * @return the corresponding SAML Assertions wrapped in a Response.
 158              */
 159             virtual saml1p::Response* resolve(
 160                 bool& authenticated,
 161                 const std::vector<SAMLArtifact*>& artifacts,
 162                 const saml2md::IDPSSODescriptor& idpDescriptor,
 163                 const X509TrustEngine* trustEngine=NULL
 164                 ) const=0;
 165
 166             /**
 167              * Resolves a SAML 2.0 artifact into the corresponding SAML protocol message.
 168              * The caller is responsible for the resulting ArtifactResponse message.
 169              *
 170              * @param authenticated     output flag set to true iff the resolution channel was authenticated
 171              * @param artifact          reference to a SAML 2.0 artifact
 172              * @param ssoDescriptor     reference to SSO role of artifact issuer (may be SP or IdP)
 173              * @param trustEngine       optional pointer to X509TrustEngine supplied to MessageDecoder
 174              * @return the corresponding SAML protocol message or NULL
 175              */
 176             virtual saml2p::ArtifactResponse* resolve(
 177                 bool& authenticated,
 178                 const saml2p::SAML2Artifact& artifact,
 179                 const saml2md::SSODescriptorType& ssoDescriptor,
 180                 const X509TrustEngine* trustEngine=NULL
 181                 ) const=0;
 182         };
 183
 184         /**
 185          * Provides an ArtifactResolver implementation for the MessageDecoder to use.
 186          * The implementation's lifetime must be longer than the lifetime of this object.
 187          * This method must be externally synchronized.
 188          *
 189          * @param artifactResolver   an ArtifactResolver implementation to use
 190          */
 191         void setArtifactResolver(ArtifactResolver* artifactResolver) {
 192             m_artifactResolver = artifactResolver;
 193             if (m_artifactResolver)
 194                 m_artifactResolver->setValidating(m_validate);
 195         }
 196
 197         /**
 198          * Controls schema validation of incoming XML messages.
 199          * This is separate from other forms of programmatic validation of objects,
 200          * but can detect a much wider range of syntax errors.
 201          *
 202          * @param validate  true iff the decoder should use a validating XML parser
 203          */
 204         void setValidating(bool validate=true) {
 205             m_validate = validate;
 206             if (m_artifactResolver)
 207                 m_artifactResolver->setValidating(m_validate);
 208         }
 209
 210         /**
 211          * Decodes an HTTP request into a SAML protocol message, and returns related
 212          * information about the issuer of the message and whether it can be trusted.
 213          * If the HTTP request does not contain the information necessary to decode
 214          * the request, a NULL will be returned. Errors during the decoding process
 215          * will be raised as exceptions.
 216          *
 217          * <p>Artifact-based bindings require an ArtifactResolver be set to
 218          * turn an artifact into the corresponding message.
 219          *
 220          * <p>In some cases, a message may be returned but not authenticated. The caller
 221          * should examine the issuerTrusted output value to establish this.
 222          *
 223          * @param relayState        RelayState/TARGET value accompanying message
 224          * @param issuer            role descriptor of issuing party
 225          * @param issuerTrusted     output flag set to true iff the message was authenticated
 226          *                          (signed or obtained via secure backchannel)
 227          * @param httpRequest       reference to interface for accessing HTTP message to decode
 228          * @param metadataProvider  optional MetadataProvider instance to authenticate the message
 229          * @param role              optional, identifies the role (generally IdP or SP) of the peer who issued the message
 230          * @param trustEngine       optional TrustEngine to authenticate the message
 231          * @return  the decoded message, or NULL if the decoder did not recognize the request content
 232          */
 233         virtual xmltooling::XMLObject* decode(
 234             std::string& relayState,
 235             const saml2md::RoleDescriptor*& issuer,
 236             bool& issuerTrusted,
 237             const HTTPRequest& httpRequest,
 238             const saml2md::MetadataProvider* metadataProvider=NULL,
 239             const xmltooling::QName* role=NULL,
 240             const TrustEngine* trustEngine=NULL
 241             ) const=0;
 242
 243     protected:
 244         MessageDecoder() : m_artifactResolver(NULL), m_validate(false) {}
 245
 246         /** Pointer to an ArtifactResolver implementation. */
 247         ArtifactResolver* m_artifactResolver;
 248
 249         /** Flag controlling schema validation. */
 250         bool m_validate;
 251     };
 252
 253     /**
 254      * Registers MessageDecoder plugins into the runtime.
 255      */
 256     void SAML_API registerMessageDecoders();
 257 };
 258
 259 #endif /* __saml_decoder_h__ */