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