saml/binding/MessageEncoder.h

   1 /*
   2  *  Copyright 2001-2010 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 namespace xmltooling {
  29     class XMLTOOL_API Credential;
  30     class XMLTOOL_API GenericResponse;
  31     class XMLTOOL_API XMLObject;
  32 };
  33
  34 namespace opensaml {
  35
  36     class SAML_API SAMLArtifact;
  37     namespace saml2p {
  38         class SAML_API SAML2Artifact;
  39     };
  40     namespace saml2md {
  41         class SAML_API EntityDescriptor;
  42     };
  43
  44     /**
  45      * Interface to SAML protocol binding message encoders.
  46      */
  47     class SAML_API MessageEncoder
  48     {
  49         MAKE_NONCOPYABLE(MessageEncoder);
  50     public:
  51         virtual ~MessageEncoder();
  52
  53         /**
  54          * Indicates whether the encoding format requires that messages be as compact as possible.
  55          *
  56          * @return  true iff the encoding has size constraints
  57          */
  58         virtual bool isCompact() const;
  59
  60         /**
  61          * Indicates whether a web browser or similar user agent will receive the message.
  62          *
  63          * @return true iff the message will be handled by a user agent
  64          */
  65         virtual bool isUserAgentPresent() const;
  66
  67         /**
  68          * Returns identifier for the protocol family associated with the encoder.
  69          *
  70          * @return  a protocol family identifier, or nullptr
  71          */
  72         virtual const XMLCh* getProtocolFamily() const;
  73
  74         /**
  75          * Returns a shorthand name for the binding/encoding supported by the encoder.
  76          *
  77          * @return  a short name for the binding/encoding, or nullptr
  78          */
  79         virtual const char* getShortName() const;
  80
  81         /**
  82          * Interface to caller-supplied artifact generation mechanism.
  83          *
  84          * Generating an artifact for storage and retrieval requires knowledge of
  85          * the sender's SourceID (or sometimes SourceLocation), and the relying party's
  86          * preferred artifact type. This information can be supplied using whatever
  87          * configuration or defaults are appropriate for the SAML application.
  88          * A MessageEncoder implementation will invoke the supplied generator interface
  89          * when it requires an artifact be created.
  90          */
  91         class SAML_API ArtifactGenerator {
  92             MAKE_NONCOPYABLE(ArtifactGenerator);
  93         protected:
  94             ArtifactGenerator();
  95         public:
  96             virtual ~ArtifactGenerator();
  97
  98             /**
  99              * Generate a SAML 1.x artifact suitable for consumption by the relying party.
 100              *
 101              * @param relyingParty  the party that will recieve the artifact
 102              * @return a SAML 1.x artifact with a random assertion handle
 103              */
 104             virtual SAMLArtifact* generateSAML1Artifact(const saml2md::EntityDescriptor* relyingParty) const=0;
 105
 106             /**
 107              * Generate a SAML 2.0 artifact suitable for consumption by the relying party.
 108              *
 109              * @param relyingParty  the party that will recieve the artifact
 110              * @return a SAML 2.0 artifact with a random message handle
 111              */
 112             virtual saml2p::SAML2Artifact* generateSAML2Artifact(const saml2md::EntityDescriptor* relyingParty) const=0;
 113         };
 114
 115         /**
 116          * Encodes an XML object/message into a binding- and transport-specific response.
 117          * The XML content cannot have a parent object, and any existing references to
 118          * the content will be invalidated if the encode method returns successfully.
 119          *
 120          * If a CredentialResolver is supplied, the message is also signed in a
 121          * binding-specific manner. The CredentialResolver <strong>MUST</strong>
 122          * be locked by the caller.
 123          *
 124          * <p>Artifact-based bindings require an ArtifactGenerator be set to
 125          * produce an artifact suitable for the intended recipient.
 126          *
 127          * @param genericResponse   reference to interface for sending transport response
 128          * @param xmlObject         XML message to encode
 129          * @param destination       destination URL for message
 130          * @param recipient         optional message recipient
 131          * @param relayState        optional RelayState value to accompany message
 132          * @param artifactGenerator optional interface for generation of artifacts
 133          * @param credential        optional Credential to supply signing key
 134          * @param signatureAlg      optional signature algorithm identifier
 135          * @param digestAlg         optional reference digest algorithm identifier
 136          */
 137         virtual long encode(
 138             xmltooling::GenericResponse& genericResponse,
 139             xmltooling::XMLObject* xmlObject,
 140             const char* destination,
 141             const saml2md::EntityDescriptor* recipient=nullptr,
 142             const char* relayState=nullptr,
 143             const ArtifactGenerator* artifactGenerator=nullptr,
 144             const xmltooling::Credential* credential=nullptr,
 145             const XMLCh* signatureAlg=nullptr,
 146             const XMLCh* digestAlg=nullptr
 147             ) const=0;
 148
 149     protected:
 150         MessageEncoder();
 151     };
 152
 153     /**
 154      * Registers MessageEncoder plugins into the runtime.
 155      */
 156     void SAML_API registerMessageEncoders();
 157 };
 158
 159 #endif /* __saml_encoder_h__ */