saml/saml2/metadata/MetadataProvider.h

   1 /*
   2  *  Copyright 2001-2006 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file saml/saml2/metadata/MetadataProvider.h
  19  *
  20  * Supplies an individual source of metadata.
  21  */
  22
  23 #ifndef __saml2_metadataprov_h__
  24 #define __saml2_metadataprov_h__
  25
  26 #include <xmltooling/Lockable.h>
  27 #include <saml/saml2/metadata/MetadataFilter.h>
  28
  29 namespace opensaml {
  30
  31     class SAML_API SAMLArtifact;
  32
  33     namespace saml2md {
  34
  35         /**
  36          * Supplies an individual source of metadata.
  37          *
  38          * The source can be a local file, remote service, or the result of a
  39          * dynamic lookup, can include local caching, etc. Providers
  40          * <strong>MUST</strong> be locked before any lookup operations.
  41          */
  42         class SAML_API MetadataProvider : public virtual xmltooling::Lockable
  43         {
  44             MAKE_NONCOPYABLE(MetadataProvider);
  45
  46         protected:
  47             /**
  48              * Constructor. If a DOM is supplied, a set of default logic will be
  49              * used to identify and build MetadataFilter plugins and install them
  50              * into the provider. The following XML content is supported:
  51              *
  52              * <ul>
  53              *  <li>&lt;MetadataFilter&gt; elements with a type attribute
  54              *  <li>&lt;Exclude&gt; elements representing a BlacklistMetadataFilter
  55              *  <li>&lt;BlacklistMetadataFilter&gt; element containing &lt;Exclude&gt; elements
  56              *  <li>&lt;Include&gt; elements representing a WhitelistMetadataFilter
  57              *  <li>&lt;WhitelistMetadataFilter&gt; element containing &lt;Include&gt; elements
  58              * </ul>
  59              *
  60              * XML namespaces are ignored in the processing of these elements.
  61              *
  62              * @param e DOM to supply configuration for provider
  63              */
  64             MetadataProvider(const DOMElement* e=NULL);
  65
  66         public:
  67             /**
  68              * Destructor will delete any installed filters.
  69              */
  70             virtual ~MetadataProvider();
  71
  72             /**
  73              * Adds a metadata filter to apply to any resolved metadata. Will not be applied
  74              * to metadata that is already loaded.
  75              *
  76              * @param newFilter metadata filter to add
  77              */
  78             virtual void addMetadataFilter(MetadataFilter* newFilter) {
  79                 m_filters.push_back(newFilter);
  80             }
  81
  82             /**
  83              * Removes a metadata filter. The caller must delete the filter if necessary.
  84              *
  85              * @param oldFilter metadata filter to remove
  86              * @return  the old filter
  87              */
  88             virtual MetadataFilter* removeMetadataFilter(MetadataFilter* oldFilter) {
  89                 for (std::vector<MetadataFilter*>::iterator i=m_filters.begin(); i!=m_filters.end(); i++) {
  90                     if (oldFilter==(*i)) {
  91                         m_filters.erase(i);
  92                         return oldFilter;
  93                     }
  94                 }
  95                 return NULL;
  96             }
  97
  98             /**
  99              * Should be called after instantiating provider and adding filters, but before
 100              * performing any lookup operations. Allows the provider to defer initialization
 101              * processes that are likely to result in exceptions until after the provider is
 102              * safely created. Providers SHOULD perform as much processing as possible in
 103              * this method so as to report/log any errors that would affect later processing.
 104              */
 105             virtual void init()=0;
 106
 107             /**
 108              * Gets the entire metadata tree, after the registered filter has been applied.
 109              * The caller MUST unlock the provider when finished with the data.
 110              *
 111              * @return the entire metadata tree
 112              */
 113             virtual const xmltooling::XMLObject* getMetadata() const=0;
 114
 115             /**
 116              * Gets the metadata for a given entity. If a valid entity is returned,
 117              * the provider will be left in a locked state. The caller MUST unlock the
 118              * provider when finished with the entity.
 119              *
 120              * @param id                    the ID of the entity
 121              * @param requireValidMetadata  indicates whether the metadata for the entity must be valid/current
 122              *
 123              * @return the entity's metadata or NULL if there is no metadata or no valid metadata
 124              */
 125             virtual const EntityDescriptor* getEntityDescriptor(const XMLCh* id, bool requireValidMetadata=true) const;
 126
 127             /**
 128              * Gets the metadata for a given entity. If a valid entity is returned,
 129              * the provider will be left in a locked state. The caller MUST unlock the
 130              * provider when finished with the entity.
 131              *
 132              * @param id                    the ID of the entity
 133              * @param requireValidMetadata  indicates whether the metadata for the entity must be valid/current
 134              *
 135              * @return the entity's metadata or NULL if there is no metadata or no valid metadata
 136              */
 137             virtual const EntityDescriptor* getEntityDescriptor(const char* id, bool requireValidMetadata=true) const;
 138
 139             /**
 140              * Gets the metadata for an entity that issued a SAML artifact. If a valid entity is returned,
 141              * the provider will be left in a locked state. The caller MUST unlock the
 142              * provider when finished with the entity.
 143              *
 144              * @param artifact              a SAML artifact to find the issuer of
 145              *
 146              * @return the entity's metadata or NULL if there is no valid metadata
 147              */
 148             virtual const EntityDescriptor* getEntityDescriptor(const SAMLArtifact* artifact) const;
 149
 150             /**
 151              * Gets the metadata for a given group of entities. If a valid group is returned,
 152              * the resolver will be left in a locked state. The caller MUST unlock the
 153              * resolver when finished with the group.
 154              *
 155              * @param name                  the name of the group
 156              * @param requireValidMetadata  indicates whether the metadata for the group must be valid/current
 157              *
 158              * @return the group's metadata or NULL if there is no metadata or no valid metadata
 159              */
 160             virtual const EntitiesDescriptor* getEntitiesDescriptor(const XMLCh* name, bool requireValidMetadata=true) const;
 161
 162             /**
 163              * Gets the metadata for a given group of entities. If a valid group is returned,
 164              * the resolver will be left in a locked state. The caller MUST unlock the
 165              * resolver when finished with the group.
 166              *
 167              * @param name                  the name of the group
 168              * @param requireValidMetadata  indicates whether the metadata for the group must be valid/current
 169              *
 170              * @return the group's metadata or NULL if there is no metadata or no valid metadata
 171              */
 172             virtual const EntitiesDescriptor* getEntitiesDescriptor(const char* name, bool requireValidMetadata=true) const;
 173
 174         protected:
 175             /**
 176              * Applies any installed filters to a metadata instance.
 177              *
 178              * @param xmlObject the metadata to be filtered
 179              */
 180             void doFilters(xmltooling::XMLObject& xmlObject) const;
 181
 182             /**
 183              * Loads an entity into the cache for faster lookup. This includes
 184              * processing known reverse lookup strategies for artifacts.
 185              *
 186              * @param site          entity definition
 187              * @param validUntil    expiration time of the entity definition
 188              */
 189             virtual void index(EntityDescriptor* site, time_t validUntil);
 190
 191             /**
 192              * Loads a group of entities into the cache for faster lookup.
 193              *
 194              * @param group         group definition
 195              * @param validUntil    expiration time of the group definition
 196              */
 197             virtual void index(EntitiesDescriptor* group, time_t validUntil);
 198
 199             /**
 200              * Clear the cache of known entities and groups.
 201              */
 202             virtual void clearDescriptorIndex();
 203
 204         private:
 205             std::vector<MetadataFilter*> m_filters;
 206
 207             typedef std::multimap<std::string,const EntityDescriptor*> sitemap_t;
 208             typedef std::multimap<std::string,const EntitiesDescriptor*> groupmap_t;
 209             sitemap_t m_sites;
 210             sitemap_t m_sources;
 211             groupmap_t m_groups;
 212         };
 213
 214         /**
 215          * Registers MetadataProvider classes into the runtime.
 216          */
 217         void SAML_API registerMetadataProviders();
 218
 219         /** MetadataProvider based on local XML files */
 220         #define FILESYSTEM_METADATA_PROVIDER  "org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider"
 221     };
 222 };
 223
 224 #endif /* __saml2_metadataprov_h__ */