saml/binding/MessageEncoder.h

   1 /*
   2  *  Copyright 2001-2007 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 <istream>
  29 #include <xmltooling/XMLObject.h>
  30 #include <xmltooling/io/GenericResponse.h>
  31 #include <xmltooling/security/Credential.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          * Indicates whether the encoding format requires that messages be as compact as possible.
  51          *
  52          * @return  true iff the encoding has size constraints
  53          */
  54         virtual bool isCompact() const {
  55             return false;
  56         }
  57
  58         /**
  59          * Interface to caller-supplied artifact generation mechanism.
  60          *
  61          * Generating an artifact for storage and retrieval requires knowledge of
  62          * the sender's SourceID (or sometimes SourceLocation), and the relying party's
  63          * preferred artifact type. This information can be supplied using whatever
  64          * configuration or defaults are appropriate for the SAML application.
  65          * A MessageEncoder implementation will invoke the supplied generator interface
  66          * when it requires an artifact be created.
  67          */
  68         class SAML_API ArtifactGenerator {
  69             MAKE_NONCOPYABLE(ArtifactGenerator);
  70         protected:
  71             ArtifactGenerator() {}
  72         public:
  73             virtual ~ArtifactGenerator() {}
  74
  75             /**
  76              * Generate a SAML 1.x artifact suitable for consumption by the relying party.
  77              *
  78              * @param relyingParty  the party that will recieve the artifact
  79              * @return a SAML 1.x artifact with a random assertion handle
  80              */
  81             virtual SAMLArtifact* generateSAML1Artifact(const char* relyingParty) const=0;
  82
  83             /**
  84              * Generate a SAML 2.0 artifact suitable for consumption by the relying party.
  85              *
  86              * @param relyingParty  the party that will recieve the artifact
  87              * @return a SAML 2.0 artifact with a random message handle
  88              */
  89             virtual saml2p::SAML2Artifact* generateSAML2Artifact(const char* relyingParty) const=0;
  90         };
  91
  92         /**
  93          * Provides an ArtifactGenerator implementation for the MessageEncoder to use.
  94          * The implementation's lifetime must be longer than the lifetime of this object.
  95          * This method must be externally synchronized.
  96          *
  97          * @param artifactGenerator   an ArtifactGenerator implementation to use
  98          */
  99         void setArtifactGenerator(ArtifactGenerator* artifactGenerator) {
 100             m_artifactGenerator = artifactGenerator;
 101         }
 102
 103         /**
 104          * Encodes an XML object/message into a binding- and transport-specific response.
 105          * The XML content cannot have a parent object, and any existing references to
 106          * the content will be invalidated if the encode method returns successfully.
 107          *
 108          * If a CredentialResolver is supplied, the message is also signed in a
 109          * binding-specific manner. The CredentialResolver <strong>MUST</strong>
 110          * be locked by the caller.
 111          *
 112          * <p>Artifact-based bindings require an ArtifactGenerator be set to
 113          * produce an artifact suitable for the intended recipient.
 114          *
 115          * @param genericResponse   reference to interface for sending transport response
 116          * @param xmlObject         XML message to encode
 117          * @param destination       destination URL for message
 118          * @param recipientID       optional entityID of message recipient
 119          * @param relayState        optional RelayState value to accompany message
 120          * @param credential        optional Credential to supply signing key
 121          * @param signatureAlg      optional signature algorithm identifier
 122          * @param digestAlg         optional reference digest algorithm identifier
 123          */
 124         virtual long encode(
 125             xmltooling::GenericResponse& genericResponse,
 126             xmltooling::XMLObject* xmlObject,
 127             const char* destination,
 128             const char* recipientID=NULL,
 129             const char* relayState=NULL,
 130             const xmltooling::Credential* credential=NULL,
 131             const XMLCh* signatureAlg=NULL,
 132             const XMLCh* digestAlg=NULL
 133             ) const=0;
 134
 135     protected:
 136         MessageEncoder() : m_artifactGenerator(NULL) {}
 137
 138         /** Pointer to an ArtifactGenerator implementation. */
 139         const ArtifactGenerator* m_artifactGenerator;
 140     };
 141
 142     /**
 143      * Registers MessageEncoder plugins into the runtime.
 144      */
 145     void SAML_API registerMessageEncoders();
 146 };
 147
 148 #endif /* __saml_encoder_h__ */