saml/saml2/metadata/MetadataProvider.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/saml2/metadata/MetadataProvider.h
  23  *
  24  * Supplies an individual source of metadata.
  25  */
  26
  27 #ifndef __saml2_metadataprov_h__
  28 #define __saml2_metadataprov_h__
  29
  30 #include <saml/base.h>
  31
  32 #include <vector>
  33 #include <iostream>
  34 #include <boost/shared_ptr.hpp>
  35 #include <boost/ptr_container/ptr_vector.hpp>
  36 #include <xmltooling/exceptions.h>
  37 #include <xmltooling/security/CredentialResolver.h>
  38
  39 namespace xmltooling {
  40     class XMLTOOL_API QName;
  41     class XMLTOOL_API XMLObject;
  42 };
  43
  44 namespace opensaml {
  45
  46     class SAML_API SAMLArtifact;
  47
  48     namespace saml2md {
  49
  50         class SAML_API EntityDescriptor;
  51         class SAML_API EntitiesDescriptor;
  52         class SAML_API RoleDescriptor;
  53         class SAML_API MetadataCredentialResolver;
  54         class SAML_API MetadataFilter;
  55         class SAML_API MetadataFilterContext;
  56
  57 #if defined (_MSC_VER)
  58         #pragma warning( push )
  59         #pragma warning( disable : 4251 )
  60 #endif
  61
  62         /**
  63          * Supplies an individual source of metadata.
  64          *
  65          * The source can be a local file, remote service, or the result of a
  66          * dynamic lookup, can include local caching, etc. Providers
  67          * <strong>MUST</strong> be locked before any lookup operations.
  68          */
  69         class SAML_API MetadataProvider : public virtual xmltooling::CredentialResolver
  70         {
  71             MAKE_NONCOPYABLE(MetadataProvider);
  72         protected:
  73             /**
  74              * Constructor.
  75              *
  76              * If a DOM is supplied, a set of default logic will be used to identify
  77              * and build MetadataFilter plugins and install them into the provider.
  78              *
  79              * The following XML content is supported:
  80              *
  81              * <ul>
  82              *  <li>&lt;MetadataFilter&gt; elements with a type attribute and type-specific content
  83              *  <li>&lt;Exclude&gt; elements representing a BlacklistMetadataFilter
  84              *  <li>&lt;BlacklistMetadataFilter&gt; element containing &lt;Exclude&gt; elements
  85              *  <li>&lt;Include&gt; elements representing a WhitelistMetadataFilter
  86              *  <li>&lt;SignatureMetadataFilter&gt; element containing a &lt;KeyResolver&gt; element
  87              *  <li>&lt;WhitelistMetadataFilter&gt; element containing &lt;Include&gt; elements
  88              * </ul>
  89              *
  90              * XML namespaces are ignored in the processing of these elements.
  91              *
  92              * @param e DOM to supply configuration for provider
  93              */
  94             MetadataProvider(const xercesc::DOMElement* e=nullptr);
  95
  96         public:
  97             /**
  98              * Destructor will delete any installed filters.
  99              */
 100             virtual ~MetadataProvider();
 101
 102             /**
 103              * Returns an identifier for the provider for logging/status purposes.
 104              *
 105              * @return an identifier, or null
 106              */
 107             virtual const char* getId() const;
 108
 109             /**
 110              * Adds a metadata filter to apply to any resolved metadata. Will not be applied
 111              * to metadata that is already loaded.
 112              *
 113              * @param newFilter metadata filter to add
 114              */
 115             virtual void addMetadataFilter(MetadataFilter* newFilter);
 116
 117             /**
 118              * Removes a metadata filter. The caller must delete the filter if necessary.
 119              *
 120              * @param oldFilter metadata filter to remove
 121              * @return  the old filter
 122              */
 123             virtual MetadataFilter* removeMetadataFilter(MetadataFilter* oldFilter);
 124
 125             /**
 126              * Sets a filtering context object for use by the filtering process.
 127              * <p>The MetadataProvider takes ownership of the object. Any existing
 128              * object is cleared.
 129              *
 130              * @param ctx   a context object
 131              */
 132             void setContext(MetadataFilterContext* ctx);
 133
 134             /**
 135              * Should be called after instantiating provider and adding filters, but before
 136              * performing any lookup operations. Allows the provider to defer initialization
 137              * processes that are likely to result in exceptions until after the provider is
 138              * safely created. Providers SHOULD perform as much processing as possible in
 139              * this method so as to report/log any errors that would affect later processing.
 140              */
 141             virtual void init()=0;
 142
 143             /**
 144              * Generate an XML representation of the provider's status. The XML must be
 145              * well-formed, but is otherwise arbitrary.
 146              *
 147              * @param os    stream to write status information to
 148              */
 149             virtual void outputStatus(std::ostream& os) const;
 150
 151             /**
 152              * Gets the entire metadata tree, after the registered filter has been applied.
 153              * The caller MUST unlock the provider when finished with the data.
 154              *
 155              * @return the entire metadata tree
 156              */
 157             virtual const xmltooling::XMLObject* getMetadata() const=0;
 158
 159             /**
 160              * Gets the metadata for a given group of entities. If a valid group is returned,
 161              * the resolver will be left in a locked state. The caller MUST unlock the
 162              * resolver when finished with the group.
 163              *
 164              * @param name                  the name of the group
 165              * @param requireValidMetadata  indicates whether the metadata for the group must be valid/current
 166              *
 167              * @return the group's metadata or nullptr if there is no metadata or no valid metadata
 168              */
 169             virtual const EntitiesDescriptor* getEntitiesDescriptor(const XMLCh* name, bool requireValidMetadata=true) const;
 170
 171             /**
 172              * Gets the metadata for a given group of entities. If a valid group is returned,
 173              * the resolver will be left in a locked state. The caller MUST unlock the
 174              * resolver when finished with the group.
 175              *
 176              * @param name                  the name of the group
 177              * @param requireValidMetadata  indicates whether the metadata for the group must be valid/current
 178              *
 179              * @return the group's metadata or nullptr if there is no metadata or no valid metadata
 180              */
 181             virtual const EntitiesDescriptor* getEntitiesDescriptor(const char* name, bool requireValidMetadata=true) const=0;
 182
 183             /**
 184              * Batches up criteria for entity lookup.
 185              */
 186             struct SAML_API Criteria {
 187                 /**
 188                  * Default constructor.
 189                  */
 190                 Criteria();
 191
 192                 /**
 193                  * Constructor.
 194                  *
 195                  * @param id    entityID to lookup
 196                  * @param q     element/type of role, if any
 197                  * @param prot  protocol support constant, if any
 198                  * @param valid true iff stale metadata should be ignored
 199                  */
 200                 Criteria(const XMLCh* id, const xmltooling::QName* q=nullptr, const XMLCh* prot=nullptr, bool valid=true);
 201
 202                 /**
 203                  * Constructor.
 204                  *
 205                  * @param id    entityID to lookup
 206                  * @param q     element/type of role, if any
 207                  * @param prot  protocol support constant, if any
 208                  * @param valid true iff stale metadata should be ignored
 209                  */
 210                 Criteria(const char* id, const xmltooling::QName* q=nullptr, const XMLCh* prot=nullptr, bool valid=true);
 211
 212                 /**
 213                  * Constructor.
 214                  *
 215                  * @param a     artifact to lookup
 216                  * @param q     element/type of role, if any
 217                  * @param prot  protocol support constant, if any
 218                  * @param valid true iff stale metadata should be ignored
 219                  */
 220                 Criteria(const SAMLArtifact* a, const xmltooling::QName* q=nullptr, const XMLCh* prot=nullptr, bool valid=true);
 221
 222                 virtual ~Criteria();
 223
 224                 /**
 225                  * Restores the object to its default state.
 226                  */
 227                 virtual void reset();
 228
 229                 /** Unique ID of entity. */
 230                 const XMLCh* entityID_unicode;
 231                 /** Unique ID of entity. */
 232                 const char* entityID_ascii;
 233                 /** SAML artifact */
 234                 const SAMLArtifact* artifact;
 235                 /** Element or schema type QName of metadata role. */
 236                 const xmltooling::QName* role;
 237                 /** Protocol support constant. */
 238                 const XMLCh* protocol;
 239                 /** Backup protocol support constant. */
 240                 const XMLCh* protocol2;
 241                 /** Controls whether stale metadata is ignored. */
 242                 bool validOnly;
 243             };
 244
 245             /**
 246              * Gets entity metadata based on supplied criteria. If a valid entity is returned,
 247              * the provider will be left in a locked state. The caller MUST unlock the
 248              * provider when finished with the entity.
 249              *
 250              * @param criteria  lookup criteria
 251              *
 252              * @return the entity's metadata (and optionally a role) or nullptr if there is no qualifying metadata
 253              */
 254             virtual std::pair<const EntityDescriptor*,const RoleDescriptor*> getEntityDescriptor(const Criteria& criteria) const=0;
 255
 256         protected:
 257             /**
 258              * Applies any installed filters to a metadata instance.
 259              *
 260              * @param xmlObject the metadata to be filtered
 261              */
 262             void doFilters(xmltooling::XMLObject& xmlObject) const;
 263
 264         private:
 265             boost::shared_ptr<MetadataFilterContext> m_filterContext;
 266             boost::ptr_vector<MetadataFilter> m_filters;
 267         };
 268
 269 #if defined (_MSC_VER)
 270         #pragma warning( pop )
 271 #endif
 272
 273         /**
 274          * Registers MetadataProvider classes into the runtime.
 275          */
 276         void SAML_API registerMetadataProviders();
 277
 278         /** MetadataProvider based on local or remote XML file */
 279         #define XML_METADATA_PROVIDER  "XML"
 280
 281         /** MetadataProvider based on dynamic resolution */
 282         #define DYNAMIC_METADATA_PROVIDER  "Dynamic"
 283
 284         /** MetadataProvider that wraps a sequence of metadata providers. */
 285         #define CHAINING_METADATA_PROVIDER  "Chaining"
 286
 287         /** MetadataProvider that loads a directory of files. */
 288         #define FOLDER_METADATA_PROVIDER  "Folder"
 289
 290         /** MetadataProvider that returns an empty "dummy" entity descriptor. */
 291         #define NULL_METADATA_PROVIDER  "Null"
 292
 293         DECL_XMLTOOLING_EXCEPTION(MetadataException,SAML_EXCEPTIONAPI(SAML_API),opensaml::saml2md,xmltooling::XMLToolingException,Exceptions related to metadata use);
 294     };
 295 };
 296
 297 #endif /* __saml2_metadataprov_h__ */