saml/binding/MessageEncoder.h

   1 /**
   2  * Licensed to the University Corporation for Advanced Internet
   3  * Development, Inc. (UCAID) under one or more contributor license
   4  * agreements. See the NOTICE file distributed with this work for
   5  * additional information regarding copyright ownership.
   6  *
   7  * UCAID licenses this file to you under the Apache License,
   8  * Version 2.0 (the "License"); you may not use this file except
   9  * in compliance with the License. You may obtain a copy of the
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
  17  * either express or implied. See the License for the specific
  18  * language governing permissions and limitations under the License.
  19  */
  20
  21 /**
  22  * @file saml/binding/MessageEncoder.h
  23  *
  24  * Interface to SAML protocol binding message encoders.
  25  */
  26
  27 #ifndef __saml_encoder_h__
  28 #define __saml_encoder_h__
  29
  30 #include <saml/base.h>
  31
  32 namespace xmltooling {
  33     class XMLTOOL_API Credential;
  34     class XMLTOOL_API GenericResponse;
  35     class XMLTOOL_API XMLObject;
  36 };
  37
  38 namespace opensaml {
  39
  40     class SAML_API SAMLArtifact;
  41     namespace saml2p {
  42         class SAML_API SAML2Artifact;
  43     };
  44     namespace saml2md {
  45         class SAML_API EntityDescriptor;
  46     };
  47
  48     /**
  49      * Interface to SAML protocol binding message encoders.
  50      */
  51     class SAML_API MessageEncoder
  52     {
  53         MAKE_NONCOPYABLE(MessageEncoder);
  54     public:
  55         virtual ~MessageEncoder();
  56
  57         /**
  58          * Indicates whether the encoding format requires that messages be as compact as possible.
  59          *
  60          * @return  true iff the encoding has size constraints
  61          */
  62         virtual bool isCompact() const;
  63
  64         /**
  65          * Indicates whether a web browser or similar user agent will receive the message.
  66          *
  67          * @return true iff the message will be handled by a user agent
  68          */
  69         virtual bool isUserAgentPresent() const;
  70
  71         /**
  72          * Returns identifier for the protocol family associated with the encoder.
  73          *
  74          * @return  a protocol family identifier, or nullptr
  75          */
  76         virtual const XMLCh* getProtocolFamily() const;
  77
  78         /**
  79          * Interface to caller-supplied artifact generation mechanism.
  80          *
  81          * Generating an artifact for storage and retrieval requires knowledge of
  82          * the sender's SourceID (or sometimes SourceLocation), and the relying party's
  83          * preferred artifact type. This information can be supplied using whatever
  84          * configuration or defaults are appropriate for the SAML application.
  85          * A MessageEncoder implementation will invoke the supplied generator interface
  86          * when it requires an artifact be created.
  87          */
  88         class SAML_API ArtifactGenerator {
  89             MAKE_NONCOPYABLE(ArtifactGenerator);
  90         protected:
  91             ArtifactGenerator();
  92         public:
  93             virtual ~ArtifactGenerator();
  94
  95             /**
  96              * Generate a SAML 1.x artifact suitable for consumption by the relying party.
  97              *
  98              * @param relyingParty  the party that will recieve the artifact
  99              * @return a SAML 1.x artifact with a random assertion handle
 100              */
 101             virtual SAMLArtifact* generateSAML1Artifact(const saml2md::EntityDescriptor* relyingParty) const=0;
 102
 103             /**
 104              * Generate a SAML 2.0 artifact suitable for consumption by the relying party.
 105              *
 106              * @param relyingParty  the party that will recieve the artifact
 107              * @return a SAML 2.0 artifact with a random message handle
 108              */
 109             virtual saml2p::SAML2Artifact* generateSAML2Artifact(const saml2md::EntityDescriptor* relyingParty) const=0;
 110         };
 111
 112         /**
 113          * Encodes an XML object/message into a binding- and transport-specific response.
 114          * The XML content cannot have a parent object, and any existing references to
 115          * the content will be invalidated if the encode method returns successfully.
 116          *
 117          * If a CredentialResolver is supplied, the message is also signed in a
 118          * binding-specific manner. The CredentialResolver <strong>MUST</strong>
 119          * be locked by the caller.
 120          *
 121          * <p>Artifact-based bindings require an ArtifactGenerator be set to
 122          * produce an artifact suitable for the intended recipient.
 123          *
 124          * @param genericResponse   reference to interface for sending transport response
 125          * @param xmlObject         XML message to encode
 126          * @param destination       destination URL for message
 127          * @param recipient         optional message recipient
 128          * @param relayState        optional RelayState value to accompany message
 129          * @param artifactGenerator optional interface for generation of artifacts
 130          * @param credential        optional Credential to supply signing key
 131          * @param signatureAlg      optional signature algorithm identifier
 132          * @param digestAlg         optional reference digest algorithm identifier
 133          */
 134         virtual long encode(
 135             xmltooling::GenericResponse& genericResponse,
 136             xmltooling::XMLObject* xmlObject,
 137             const char* destination,
 138             const saml2md::EntityDescriptor* recipient=nullptr,
 139             const char* relayState=nullptr,
 140             const ArtifactGenerator* artifactGenerator=nullptr,
 141             const xmltooling::Credential* credential=nullptr,
 142             const XMLCh* signatureAlg=nullptr,
 143             const XMLCh* digestAlg=nullptr
 144             ) const=0;
 145
 146     protected:
 147         MessageEncoder();
 148     };
 149
 150     /**
 151      * Registers MessageEncoder plugins into the runtime.
 152      */
 153     void SAML_API registerMessageEncoders();
 154 };
 155
 156 #endif /* __saml_encoder_h__ */