-/*\r
- * Copyright 2001-2006 Internet2\r
- * \r
- * Licensed under the Apache License, Version 2.0 (the "License");\r
- * you may not use this file except in compliance with the License.\r
- * You may obtain a copy of the License at\r
- *\r
- * http://www.apache.org/licenses/LICENSE-2.0\r
- *\r
- * Unless required by applicable law or agreed to in writing, software\r
- * distributed under the License is distributed on an "AS IS" BASIS,\r
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
- * See the License for the specific language governing permissions and\r
- * limitations under the License.\r
- */\r
-\r
-/**\r
- * @file saml/binding/MessageEncoder.h\r
- * \r
- * Interface to SAML protocol binding message encoders. \r
- */\r
-\r
-#ifndef __saml_encoder_h__\r
-#define __saml_encoder_h__\r
-\r
-#include <saml/base.h>\r
-\r
-#include <map>\r
-#include <string>\r
-#include <xmltooling/XMLObject.h>\r
-#include <xmltooling/signature/CredentialResolver.h>\r
-#include <xmltooling/util/StorageService.h>\r
-\r
-namespace opensaml {\r
-\r
- class SAML_API SAMLArtifact;\r
- namespace saml2p {\r
- class SAML_API SAML2Artifact;\r
- };\r
-\r
- /**\r
- * Interface to SAML protocol binding message encoders.\r
- */\r
- class SAML_API MessageEncoder\r
- {\r
- MAKE_NONCOPYABLE(MessageEncoder);\r
- public:\r
- virtual ~MessageEncoder() {}\r
-\r
- /**\r
- * Interface to caller-supplied URL-encoding mechanism.\r
- * \r
- * Since URL-encoding is not canonical, it's important that the same\r
- * encoder is used during some binding-specific signature operations.\r
- */\r
- class SAML_API URLEncoder {\r
- MAKE_NONCOPYABLE(URLEncoder);\r
- protected:\r
- URLEncoder() {}\r
- public:\r
- virtual ~URLEncoder() {}\r
- \r
- /**\r
- * Produce a URL-safe but equivalent version of the input string.\r
- * \r
- * @param s input string to encode\r
- * @return a string object containing the result of encoding the input\r
- */\r
- virtual std::string encode(const char* s) const=0;\r
- };\r
- \r
- /**\r
- * Provides a URLEncoder implementation for the MessageEncoder to use.\r
- * The implementation's lifetime must be longer than the lifetime of this object.\r
- * This method must be externally synchronized. \r
- * \r
- * @param urlEncoder a URLEncoder implementation to use\r
- */\r
- void setURLEncoder(const URLEncoder* urlEncoder) {\r
- m_urlEncoder = urlEncoder;\r
- }\r
-\r
- /**\r
- * Interface to caller-supplied artifact generation mechanism.\r
- * \r
- * Generating an artifact for storage and retrieval requires knowledge of\r
- * the sender's SourceID (or sometimes SourceLocation), and the relying party's\r
- * preferred artifact type. This information can be supplied using whatever\r
- * configuration or defaults are appropriate for the SAML application.\r
- * An ArtifactMap implementation will invoke the supplied generator interface\r
- * when it requires an artifact be created.\r
- */\r
- class SAML_API ArtifactGenerator {\r
- MAKE_NONCOPYABLE(ArtifactGenerator);\r
- protected:\r
- ArtifactGenerator() {}\r
- public:\r
- virtual ~ArtifactGenerator() {}\r
- \r
- /**\r
- * Generate a SAML 1.x artifact suitable for consumption by the relying party.\r
- * \r
- * @param relyingParty the party that will recieve the artifact\r
- * @return a SAML 1.x artifact with a random assertion handle\r
- */\r
- virtual SAMLArtifact* generateSAML1Artifact(const char* relyingParty) const=0;\r
-\r
- /**\r
- * Generate a SAML 2.0 artifact suitable for consumption by the relying party.\r
- * \r
- * @param relyingParty the party that will recieve the artifact\r
- * @return a SAML 2.0 artifact with a random message handle\r
- */\r
- virtual saml2p::SAML2Artifact* generateSAML2Artifact(const char* relyingParty) const=0;\r
- };\r
-\r
- /**\r
- * Provides an ArtifactGenerator implementation for the MessageEncoder to use.\r
- * The implementation's lifetime must be longer than the lifetime of this object. \r
- * This method must be externally synchronized. \r
- * \r
- * @param artifactGenerator an ArtifactGenerator implementation to use\r
- */\r
- void setArtifactGenerator(ArtifactGenerator* artifactGenerator) {\r
- m_artifactGenerator = artifactGenerator;\r
- }\r
- \r
- /**\r
- * Encodes an XML object/message into a set of binding-specific data "fields".\r
- * The XML content cannot have a parent object, and any existing references to\r
- * the content will be invalidated if the encode method returns successfully.\r
- * \r
- * If a CredentialResolver is supplied, the message is also signed in a\r
- * binding-specific manner. The CredentialResolver <strong>MUST</strong>\r
- * be locked by the caller. \r
- * \r
- * <p>An embedded URLEncoder instance may be required by some bindings\r
- * in order to produce predictable signature input.\r
- * \r
- * <p>Artifact-based bindings require an ArtifactGenerator be set to\r
- * produce an artifact suitable for the intended recipient.\r
- * \r
- * <p>Note that the name/value pairs resulting from the encoding operation are\r
- * <strong>NOT</strong> URL-encoded or otherwise transformed. It is the caller's\r
- * responsibility to apply any necessary encoding when preparing the data for\r
- * transport.\r
- * \r
- * @param outputFields name/value pairs containing the results of encoding the message\r
- * @param xmlObject XML object/message to encode\r
- * @param recipientID optional entityID of message recipient\r
- * @param relayState optional RelayState value to accompany message\r
- * @param credResolver optional CredentialResolver instance to supply signing material\r
- * @param sigAlgorithm optional signature algorithm identifier\r
- */\r
- virtual void encode(\r
- std::map<std::string,std::string>& outputFields,\r
- xmltooling::XMLObject* xmlObject,\r
- const char* recipientID=NULL,\r
- const char* relayState=NULL,\r
- const xmlsignature::CredentialResolver* credResolver=NULL,\r
- const XMLCh* sigAlgorithm=NULL\r
- ) const=0;\r
-\r
- protected:\r
- MessageEncoder() : m_urlEncoder(NULL), m_artifactGenerator(NULL) {}\r
- \r
- /**\r
- * Helper function to build a new XML Signature with KeyInfo, based\r
- * on the supplied CredentialResolver.\r
- * \r
- * @param credResolver CredentialResolver instance to supply signing material\r
- * @param sigAlgorithm optional signature algorithm identifier\r
- * @return a new Signature object\r
- */\r
- xmlsignature::Signature* buildSignature(\r
- const xmlsignature::CredentialResolver* credResolver,\r
- const XMLCh* sigAlgorithm=NULL\r
- ) const;\r
- \r
- /** Pointer to a URLEncoder implementation. */\r
- const URLEncoder* m_urlEncoder;\r
- \r
- /** Pointer to an ArtifactGenerator implementation. */\r
- const ArtifactGenerator* m_artifactGenerator;\r
- };\r
-\r
- /**\r
- * Registers MessageEncoder plugins into the runtime.\r
- */\r
- void SAML_API registerMessageEncoders();\r
-\r
- /** MessageEncoder for SAML 1.x Browser/Artifact "binding" (really part of profile) */\r
- #define SAML1_ARTIFACT_ENCODER "urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"\r
-\r
- /** MessageEncoder for SAML 1.x Browser/POST "binding" (really part of profile) */\r
- #define SAML1_POST_ENCODER "urn:oasis:names:tc:SAML:1.0:profiles:browser-post"\r
- \r
- /** MessageEncoder for SAML 2.0 HTTP-Artifact binding */\r
- #define SAML2_ARTIFACT_ENCODER "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"\r
-\r
- /** MessageEncoder for SAML 2.0 HTTP-POST binding */\r
- #define SAML2_POST_ENCODER "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"\r
-\r
- /** MessageEncoder for SAML 2.0 HTTP-Redirect binding */\r
- #define SAML2_REDIRECT_ENCODER "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"\r
-};\r
-\r
-#endif /* __saml_encoder_h__ */\r
+/**
+ * Licensed to the University Corporation for Advanced Internet
+ * Development, Inc. (UCAID) under one or more contributor license
+ * agreements. See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.
+ *
+ * UCAID licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the
+ * License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied. See the License for the specific
+ * language governing permissions and limitations under the License.
+ */
+
+/**
+ * @file saml/binding/MessageEncoder.h
+ *
+ * Interface to SAML protocol binding message encoders.
+ */
+
+#ifndef __saml_encoder_h__
+#define __saml_encoder_h__
+
+#include <saml/base.h>
+
+namespace xmltooling {
+ class XMLTOOL_API Credential;
+ class XMLTOOL_API GenericResponse;
+ class XMLTOOL_API XMLObject;
+};
+
+namespace opensaml {
+
+ class SAML_API SAMLArtifact;
+ namespace saml2p {
+ class SAML_API SAML2Artifact;
+ };
+ namespace saml2md {
+ class SAML_API EntityDescriptor;
+ };
+
+ /**
+ * Interface to SAML protocol binding message encoders.
+ */
+ class SAML_API MessageEncoder
+ {
+ MAKE_NONCOPYABLE(MessageEncoder);
+ public:
+ virtual ~MessageEncoder();
+
+ /**
+ * Indicates whether the encoding format requires that messages be as compact as possible.
+ *
+ * @return true iff the encoding has size constraints
+ */
+ virtual bool isCompact() const;
+
+ /**
+ * Indicates whether a web browser or similar user agent will receive the message.
+ *
+ * @return true iff the message will be handled by a user agent
+ */
+ virtual bool isUserAgentPresent() const;
+
+ /**
+ * Returns identifier for the protocol family associated with the encoder.
+ *
+ * @return a protocol family identifier, or nullptr
+ */
+ virtual const XMLCh* getProtocolFamily() const;
+
+ /**
+ * Interface to caller-supplied artifact generation mechanism.
+ *
+ * Generating an artifact for storage and retrieval requires knowledge of
+ * the sender's SourceID (or sometimes SourceLocation), and the relying party's
+ * preferred artifact type. This information can be supplied using whatever
+ * configuration or defaults are appropriate for the SAML application.
+ * A MessageEncoder implementation will invoke the supplied generator interface
+ * when it requires an artifact be created.
+ */
+ class SAML_API ArtifactGenerator {
+ MAKE_NONCOPYABLE(ArtifactGenerator);
+ protected:
+ ArtifactGenerator();
+ public:
+ virtual ~ArtifactGenerator();
+
+ /**
+ * Generate a SAML 1.x artifact suitable for consumption by the relying party.
+ *
+ * @param relyingParty the party that will recieve the artifact
+ * @return a SAML 1.x artifact with a random assertion handle
+ */
+ virtual SAMLArtifact* generateSAML1Artifact(const saml2md::EntityDescriptor* relyingParty) const=0;
+
+ /**
+ * Generate a SAML 2.0 artifact suitable for consumption by the relying party.
+ *
+ * @param relyingParty the party that will recieve the artifact
+ * @return a SAML 2.0 artifact with a random message handle
+ */
+ virtual saml2p::SAML2Artifact* generateSAML2Artifact(const saml2md::EntityDescriptor* relyingParty) const=0;
+ };
+
+ /**
+ * Encodes an XML object/message into a binding- and transport-specific response.
+ * The XML content cannot have a parent object, and any existing references to
+ * the content will be invalidated if the encode method returns successfully.
+ *
+ * If a CredentialResolver is supplied, the message is also signed in a
+ * binding-specific manner. The CredentialResolver <strong>MUST</strong>
+ * be locked by the caller.
+ *
+ * <p>Artifact-based bindings require an ArtifactGenerator be set to
+ * produce an artifact suitable for the intended recipient.
+ *
+ * @param genericResponse reference to interface for sending transport response
+ * @param xmlObject XML message to encode
+ * @param destination destination URL for message
+ * @param recipient optional message recipient
+ * @param relayState optional RelayState value to accompany message
+ * @param artifactGenerator optional interface for generation of artifacts
+ * @param credential optional Credential to supply signing key
+ * @param signatureAlg optional signature algorithm identifier
+ * @param digestAlg optional reference digest algorithm identifier
+ */
+ virtual long encode(
+ xmltooling::GenericResponse& genericResponse,
+ xmltooling::XMLObject* xmlObject,
+ const char* destination,
+ const saml2md::EntityDescriptor* recipient=nullptr,
+ const char* relayState=nullptr,
+ const ArtifactGenerator* artifactGenerator=nullptr,
+ const xmltooling::Credential* credential=nullptr,
+ const XMLCh* signatureAlg=nullptr,
+ const XMLCh* digestAlg=nullptr
+ ) const=0;
+
+ protected:
+ MessageEncoder();
+ };
+
+ /**
+ * Registers MessageEncoder plugins into the runtime.
+ */
+ void SAML_API registerMessageEncoders();
+};
+
+#endif /* __saml_encoder_h__ */