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 <xmltooling/XMLObject.h>
  31 #include <xmltooling/signature/CredentialResolver.h>
  32
  33 namespace opensaml {
  34
  35     class SAML_API SAMLArtifact;
  36     namespace saml2p {
  37         class SAML_API SAML2Artifact;
  38     };
  39
  40     /**
  41      * Interface to SAML protocol binding message encoders.
  42      */
  43     class SAML_API MessageEncoder
  44     {
  45         MAKE_NONCOPYABLE(MessageEncoder);
  46     public:
  47         virtual ~MessageEncoder() {}
  48
  49         /**
  50          * Interface to caller-supplied artifact generation mechanism.
  51          *
  52          * Generating an artifact for storage and retrieval requires knowledge of
  53          * the sender's SourceID (or sometimes SourceLocation), and the relying party's
  54          * preferred artifact type. This information can be supplied using whatever
  55          * configuration or defaults are appropriate for the SAML application.
  56          * A MessageEncoder implementation will invoke the supplied generator interface
  57          * when it requires an artifact be created.
  58          */
  59         class SAML_API ArtifactGenerator {
  60             MAKE_NONCOPYABLE(ArtifactGenerator);
  61         protected:
  62             ArtifactGenerator() {}
  63         public:
  64             virtual ~ArtifactGenerator() {}
  65
  66             /**
  67              * Generate a SAML 1.x artifact suitable for consumption by the relying party.
  68              *
  69              * @param relyingParty  the party that will recieve the artifact
  70              * @return a SAML 1.x artifact with a random assertion handle
  71              */
  72             virtual SAMLArtifact* generateSAML1Artifact(const char* relyingParty) const=0;
  73
  74             /**
  75              * Generate a SAML 2.0 artifact suitable for consumption by the relying party.
  76              *
  77              * @param relyingParty  the party that will recieve the artifact
  78              * @return a SAML 2.0 artifact with a random message handle
  79              */
  80             virtual saml2p::SAML2Artifact* generateSAML2Artifact(const char* relyingParty) const=0;
  81         };
  82
  83         /**
  84          * Provides an ArtifactGenerator implementation for the MessageEncoder to use.
  85          * The implementation's lifetime must be longer than the lifetime of this object.
  86          * This method must be externally synchronized.
  87          *
  88          * @param artifactGenerator   an ArtifactGenerator implementation to use
  89          */
  90         void setArtifactGenerator(ArtifactGenerator* artifactGenerator) {
  91             m_artifactGenerator = artifactGenerator;
  92         }
  93
  94         /**
  95          * Encodes an XML object/message into a set of binding-specific data "fields".
  96          * The XML content cannot have a parent object, and any existing references to
  97          * the content will be invalidated if the encode method returns successfully.
  98          *
  99          * If a CredentialResolver is supplied, the message is also signed in a
 100          * binding-specific manner. The CredentialResolver <strong>MUST</strong>
 101          * be locked by the caller.
 102          *
 103          * <p>An embedded URLEncoder instance may be required by some bindings
 104          * in order to produce predictable signature input.
 105          *
 106          * <p>Artifact-based bindings require an ArtifactGenerator be set to
 107          * produce an artifact suitable for the intended recipient.
 108          *
 109          * <p>Note that the name/value pairs resulting from the encoding operation are
 110          * <strong>NOT</strong> URL-encoded or otherwise transformed. It is the caller's
 111          * responsibility to apply any necessary encoding when preparing the data for
 112          * transport.
 113          *
 114          * @param outputFields      name/value pairs containing the results of encoding the message
 115          * @param xmlObject         XML object/message to encode
 116          * @param recipientID       optional entityID of message recipient
 117          * @param relayState        optional RelayState value to accompany message
 118          * @param credResolver      optional CredentialResolver instance to supply signing material
 119          * @param sigAlgorithm      optional signature algorithm identifier
 120          */
 121         virtual void encode(
 122             std::map<std::string,std::string>& outputFields,
 123             xmltooling::XMLObject* xmlObject,
 124             const char* recipientID=NULL,
 125             const char* relayState=NULL,
 126             const xmlsignature::CredentialResolver* credResolver=NULL,
 127             const XMLCh* sigAlgorithm=NULL
 128             ) const=0;
 129
 130     protected:
 131         MessageEncoder() : m_artifactGenerator(NULL) {}
 132
 133         /**
 134          * Helper function to build a new XML Signature with KeyInfo, based
 135          * on the supplied CredentialResolver.
 136          *
 137          * @param credResolver      CredentialResolver instance to supply signing material
 138          * @param sigAlgorithm      optional signature algorithm identifier
 139          * @return  a new Signature object
 140          */
 141         xmlsignature::Signature* buildSignature(
 142             const xmlsignature::CredentialResolver* credResolver,
 143             const XMLCh* sigAlgorithm=NULL
 144             ) const;
 145
 146         /** Pointer to an ArtifactGenerator implementation. */
 147         const ArtifactGenerator* m_artifactGenerator;
 148     };
 149
 150     /**
 151      * Registers MessageEncoder plugins into the runtime.
 152      */
 153     void SAML_API registerMessageEncoders();
 154 };
 155
 156 #endif /* __saml_encoder_h__ */