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__ */ 157