saml/binding/MessageEncoder.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/MessageEncoder.h
  19  *
  20  * Interface to SAML protocol binding message encoders.
  21  */
  22
  23 #ifndef __saml_encoder_h__
  24 #define __saml_encoder_h__
  25
  26 #include <saml/base.h>
  27
  28 #include <map>
  29 #include <string>
  30 #include <istream>
  31 #include <xmltooling/XMLObject.h>
  32 #include <xmltooling/signature/CredentialResolver.h>
  33
  34 namespace opensaml {
  35
  36     class SAML_API SAMLArtifact;
  37     namespace saml2p {
  38         class SAML_API SAML2Artifact;
  39     };
  40
  41     /**
  42      * Interface to SAML protocol binding message encoders.
  43      */
  44     class SAML_API MessageEncoder
  45     {
  46         MAKE_NONCOPYABLE(MessageEncoder);
  47     public:
  48         virtual ~MessageEncoder() {}
  49
  50         /**
  51          * Interface to caller-supplied shim for issuing an HTTP response.
  52          *
  53          * <p>To supply information to the surrounding web server environment,
  54          * a shim must be supplied in the form of this interface to adapt the
  55          * library to different proprietary server APIs.
  56          *
  57          * <p>This interface need not be threadsafe.
  58          */
  59         class SAML_API HTTPResponse {
  60             MAKE_NONCOPYABLE(HTTPResponse);
  61         protected:
  62             HTTPResponse() {}
  63         public:
  64             virtual ~HTTPResponse() {}
  65
  66             /**
  67              * Sets or clears a response header.
  68              *
  69              * @param name  header name
  70              * @param value value to set, or NULL to clear
  71              */
  72             virtual void setHeader(const char* name, const char* value)=0;
  73
  74             /**
  75              * Sets a client cookie.
  76              *
  77              * @param name  cookie name
  78              * @param value value to set, or NULL to clear
  79              */
  80             virtual void setCookie(const char* name, const char* value)=0;
  81
  82             /**
  83              * Redirect the client to the specified URL and complete the response.
  84              * Any headers previously set will be sent ahead of the redirect.
  85              *
  86              * @param url   location to redirect client
  87              * @return a result code to return from the calling MessageEncoder
  88              */
  89             virtual long sendRedirect(const char* url)=0;
  90
  91             /**
  92              * Sends a completed response to the client. Any headers previously set
  93              * will be sent ahead of the data.
  94              *
  95              * @param inputStream   reference to source of response data
  96              * @param status        HTTP status code to return
  97              * @param contentType   Content-Type header to return
  98              * @return a result code to return from the calling MessageEncoder
  99              */
 100             virtual long sendResponse(std::istream& inputStream, int status = 200, const char* contentType = "text/html")=0;
 101         };
 102
 103         /**
 104          * Interface to caller-supplied artifact generation mechanism.
 105          *
 106          * Generating an artifact for storage and retrieval requires knowledge of
 107          * the sender's SourceID (or sometimes SourceLocation), and the relying party's
 108          * preferred artifact type. This information can be supplied using whatever
 109          * configuration or defaults are appropriate for the SAML application.
 110          * A MessageEncoder implementation will invoke the supplied generator interface
 111          * when it requires an artifact be created.
 112          */
 113         class SAML_API ArtifactGenerator {
 114             MAKE_NONCOPYABLE(ArtifactGenerator);
 115         protected:
 116             ArtifactGenerator() {}
 117         public:
 118             virtual ~ArtifactGenerator() {}
 119
 120             /**
 121              * Generate a SAML 1.x artifact suitable for consumption by the relying party.
 122              *
 123              * @param relyingParty  the party that will recieve the artifact
 124              * @return a SAML 1.x artifact with a random assertion handle
 125              */
 126             virtual SAMLArtifact* generateSAML1Artifact(const char* relyingParty) const=0;
 127
 128             /**
 129              * Generate a SAML 2.0 artifact suitable for consumption by the relying party.
 130              *
 131              * @param relyingParty  the party that will recieve the artifact
 132              * @return a SAML 2.0 artifact with a random message handle
 133              */
 134             virtual saml2p::SAML2Artifact* generateSAML2Artifact(const char* relyingParty) const=0;
 135         };
 136
 137         /**
 138          * Provides an ArtifactGenerator implementation for the MessageEncoder to use.
 139          * The implementation's lifetime must be longer than the lifetime of this object.
 140          * This method must be externally synchronized.
 141          *
 142          * @param artifactGenerator   an ArtifactGenerator implementation to use
 143          */
 144         void setArtifactGenerator(ArtifactGenerator* artifactGenerator) {
 145             m_artifactGenerator = artifactGenerator;
 146         }
 147
 148         /**
 149          * Encodes an XML object/message into a binding-specific HTTP response.
 150          * The XML content cannot have a parent object, and any existing references to
 151          * the content will be invalidated if the encode method returns successfully.
 152          *
 153          * If a CredentialResolver is supplied, the message is also signed in a
 154          * binding-specific manner. The CredentialResolver <strong>MUST</strong>
 155          * be locked by the caller.
 156          *
 157          * <p>Artifact-based bindings require an ArtifactGenerator be set to
 158          * produce an artifact suitable for the intended recipient.
 159          *
 160          * @param httpResponse      reference to interface for sending encoded response to client
 161          * @param xmlObject         XML message to encode
 162          * @param destination       destination URL for message
 163          * @param recipientID       optional entityID of message recipient
 164          * @param relayState        optional RelayState value to accompany message
 165          * @param credResolver      optional CredentialResolver instance to supply signing material
 166          * @param sigAlgorithm      optional signature algorithm identifier
 167          */
 168         virtual long encode(
 169             HTTPResponse& httpResponse,
 170             xmltooling::XMLObject* xmlObject,
 171             const char* destination,
 172             const char* recipientID=NULL,
 173             const char* relayState=NULL,
 174             const xmlsignature::CredentialResolver* credResolver=NULL,
 175             const XMLCh* sigAlgorithm=NULL
 176             ) const=0;
 177
 178     protected:
 179         MessageEncoder() : m_artifactGenerator(NULL) {}
 180
 181         /**
 182          * Helper function to build a new XML Signature with KeyInfo, based
 183          * on the supplied CredentialResolver.
 184          *
 185          * @param credResolver      CredentialResolver instance to supply signing material
 186          * @param sigAlgorithm      optional signature algorithm identifier
 187          * @return  a new Signature object
 188          */
 189         xmlsignature::Signature* buildSignature(
 190             const xmlsignature::CredentialResolver* credResolver,
 191             const XMLCh* sigAlgorithm=NULL
 192             ) const;
 193
 194         /** Pointer to an ArtifactGenerator implementation. */
 195         const ArtifactGenerator* m_artifactGenerator;
 196     };
 197
 198     /**
 199      * Registers MessageEncoder plugins into the runtime.
 200      */
 201     void SAML_API registerMessageEncoders();
 202 };
 203
 204 #endif /* __saml_encoder_h__ */