saml/binding/MessageEncoder.h

   1 /*\r
   2  *  Copyright 2001-2006 Internet2\r
   3  * \r
   4  * Licensed under the Apache License, Version 2.0 (the "License");\r
   5  * you may not use this file except in compliance with the License.\r
   6  * You may obtain a copy of the License at\r
   7  *\r
   8  *     http://www.apache.org/licenses/LICENSE-2.0\r
   9  *\r
  10  * Unless required by applicable law or agreed to in writing, software\r
  11  * distributed under the License is distributed on an "AS IS" BASIS,\r
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  13  * See the License for the specific language governing permissions and\r
  14  * limitations under the License.\r
  15  */\r
  16 \r
  17 /**\r
  18  * @file saml/binding/MessageEncoder.h\r
  19  * \r
  20  * Interface to SAML protocol binding message encoders. \r
  21  */\r
  22 \r
  23 #ifndef __saml_encoder_h__\r
  24 #define __saml_encoder_h__\r
  25 \r
  26 #include <saml/base.h>\r
  27 \r
  28 #include <map>\r
  29 #include <string>\r
  30 #include <xmltooling/XMLObject.h>\r
  31 #include <xmltooling/signature/CredentialResolver.h>\r
  32 #include <xmltooling/util/StorageService.h>\r
  33 \r
  34 namespace opensaml {\r
  35 \r
  36     class SAML_API SAMLArtifact;\r
  37     namespace saml2p {\r
  38         class SAML_API SAML2Artifact;\r
  39     };\r
  40 \r
  41     /**\r
  42      * Interface to SAML protocol binding message encoders.\r
  43      */\r
  44     class SAML_API MessageEncoder\r
  45     {\r
  46         MAKE_NONCOPYABLE(MessageEncoder);\r
  47     public:\r
  48         virtual ~MessageEncoder() {}\r
  49 \r
  50         /**\r
  51          * Interface to caller-supplied URL-encoding mechanism.\r
  52          * \r
  53          * Since URL-encoding is not canonical, it's important that the same\r
  54          * encoder is used during some binding-specific signature operations.\r
  55          */\r
  56         class SAML_API URLEncoder {\r
  57             MAKE_NONCOPYABLE(URLEncoder);\r
  58         protected:\r
  59             URLEncoder() {}\r
  60         public:\r
  61             virtual ~URLEncoder() {}\r
  62             \r
  63             /**\r
  64              * Produce a URL-safe but equivalent version of the input string.\r
  65              * \r
  66              * @param s input string to encode\r
  67              * @return a string object containing the result of encoding the input\r
  68              */\r
  69             virtual std::string encode(const char* s) const=0;\r
  70         };\r
  71         \r
  72         /**\r
  73          * Provides a URLEncoder implementation for the MessageEncoder to use.\r
  74          * The implementation's lifetime must be longer than the lifetime of this object.\r
  75          * This method must be externally synchronized. \r
  76          * \r
  77          * @param urlEncoder    a URLEncoder implementation to use\r
  78          */\r
  79         void setURLEncoder(const URLEncoder* urlEncoder) {\r
  80             m_urlEncoder = urlEncoder;\r
  81         }\r
  82 \r
  83         /**\r
  84          * Interface to caller-supplied artifact generation mechanism.\r
  85          * \r
  86          * Generating an artifact for storage and retrieval requires knowledge of\r
  87          * the sender's SourceID (or sometimes SourceLocation), and the relying party's\r
  88          * preferred artifact type. This information can be supplied using whatever\r
  89          * configuration or defaults are appropriate for the SAML application.\r
  90          * An ArtifactMap implementation will invoke the supplied generator interface\r
  91          * when it requires an artifact be created.\r
  92          */\r
  93         class SAML_API ArtifactGenerator {\r
  94             MAKE_NONCOPYABLE(ArtifactGenerator);\r
  95         protected:\r
  96             ArtifactGenerator() {}\r
  97         public:\r
  98             virtual ~ArtifactGenerator() {}\r
  99             \r
 100             /**\r
 101              * Generate a SAML 1.x artifact suitable for consumption by the relying party.\r
 102              * \r
 103              * @param relyingParty  the party that will recieve the artifact\r
 104              * @return a SAML 1.x artifact with a random assertion handle\r
 105              */\r
 106             virtual SAMLArtifact* generateSAML1Artifact(const char* relyingParty) const=0;\r
 107 \r
 108             /**\r
 109              * Generate a SAML 2.0 artifact suitable for consumption by the relying party.\r
 110              * \r
 111              * @param relyingParty  the party that will recieve the artifact\r
 112              * @return a SAML 2.0 artifact with a random message handle\r
 113              */\r
 114             virtual saml2p::SAML2Artifact* generateSAML2Artifact(const char* relyingParty) const=0;\r
 115         };\r
 116 \r
 117         /**\r
 118          * Provides an ArtifactGenerator implementation for the MessageEncoder to use.\r
 119          * The implementation's lifetime must be longer than the lifetime of this object. \r
 120          * This method must be externally synchronized. \r
 121          * \r
 122          * @param artifactGenerator   an ArtifactGenerator implementation to use\r
 123          */\r
 124         void setArtifactGenerator(ArtifactGenerator* artifactGenerator) {\r
 125             m_artifactGenerator = artifactGenerator;\r
 126         }\r
 127         \r
 128         /**\r
 129          * Encodes an XML object/message into a set of binding-specific data "fields".\r
 130          * The XML content cannot have a parent object, and any existing references to\r
 131          * the content will be invalidated if the encode method returns successfully.\r
 132          * \r
 133          * If a CredentialResolver is supplied, the message is also signed in a\r
 134          * binding-specific manner. The CredentialResolver <strong>MUST</strong>\r
 135          * be locked by the caller. \r
 136          * \r
 137          * <p>An embedded URLEncoder instance may be required by some bindings\r
 138          * in order to produce predictable signature input.\r
 139          * \r
 140          * <p>Artifact-based bindings require an ArtifactGenerator be set to\r
 141          * produce an artifact suitable for the intended recipient.\r
 142          * \r
 143          * <p>Note that the name/value pairs resulting from the encoding operation are\r
 144          * <strong>NOT</strong> URL-encoded or otherwise transformed. It is the caller's\r
 145          * responsibility to apply any necessary encoding when preparing the data for\r
 146          * transport.\r
 147          * \r
 148          * @param outputFields      name/value pairs containing the results of encoding the message\r
 149          * @param xmlObject         XML object/message to encode\r
 150          * @param recipientID       optional entityID of message recipient\r
 151          * @param relayState        optional RelayState value to accompany message\r
 152          * @param credResolver      optional CredentialResolver instance to supply signing material\r
 153          * @param sigAlgorithm      optional signature algorithm identifier\r
 154          */\r
 155         virtual void encode(\r
 156             std::map<std::string,std::string>& outputFields,\r
 157             xmltooling::XMLObject* xmlObject,\r
 158             const char* recipientID=NULL,\r
 159             const char* relayState=NULL,\r
 160             const xmlsignature::CredentialResolver* credResolver=NULL,\r
 161             const XMLCh* sigAlgorithm=NULL\r
 162             ) const=0;\r
 163 \r
 164     protected:\r
 165         MessageEncoder() : m_urlEncoder(NULL), m_artifactGenerator(NULL) {}\r
 166         \r
 167         /** Pointer to a URLEncoder implementation. */\r
 168         const URLEncoder* m_urlEncoder;\r
 169         \r
 170         /** Pointer to an ArtifactGenerator implementation. */\r
 171         const ArtifactGenerator* m_artifactGenerator;\r
 172     };\r
 173 \r
 174     /**\r
 175      * Registers MessageEncoder plugins into the runtime.\r
 176      */\r
 177     void SAML_API registerMessageEncoders();\r
 178 \r
 179     /** MessageEncoder for SAML 1.x Browser/Artifact "binding" (really part of profile) */\r
 180     #define SAML1_ARTIFACT_ENCODER  "org.opensaml.saml1.binding.SAML1ArtifactEncoder"\r
 181 \r
 182     /** MessageEncoder for SAML 1.x Browser/POST "binding" (really part of profile) */\r
 183     #define SAML1_POST_ENCODER  "org.opensaml.saml1.binding.SAML1POSTEncoder"\r
 184 };\r
 185 \r
 186 #endif /* __saml_encoder_h__ */\r