shib/shib.h

   1 /*
   2  *  Copyright 2001-2005 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 /* shib.h - Shibboleth header file
  18
  19    Scott Cantor
  20    6/4/02
  21
  22    $History:$
  23 */
  24
  25 #ifndef __shib_h__
  26 #define __shib_h__
  27
  28 #include <xmltooling/util/Threads.h>
  29
  30 #include <saml/saml.h>
  31 #include <xsec/xenc/XENCEncryptionMethod.hpp>
  32
  33 #ifdef WIN32
  34 # ifndef SHIB_EXPORTS
  35 #  define SHIB_EXPORTS __declspec(dllimport)
  36 # endif
  37 #else
  38 # define SHIB_EXPORTS
  39 #endif
  40
  41 namespace shibboleth
  42 {
  43     DECLARE_SAML_EXCEPTION(SHIB_EXPORTS,ResourceAccessException,SAMLException);
  44     DECLARE_SAML_EXCEPTION(SHIB_EXPORTS,MetadataException,SAMLException);
  45     DECLARE_SAML_EXCEPTION(SHIB_EXPORTS,CredentialException,SAMLException);
  46     DECLARE_SAML_EXCEPTION(SHIB_EXPORTS,InvalidHandleException,SAMLException);
  47     DECLARE_SAML_EXCEPTION(SHIB_EXPORTS,InvalidSessionException,RetryableProfileException);
  48
  49     // Metadata abstract interfaces, based on SAML 2.0
  50
  51     struct SHIB_EXPORTS IContactPerson
  52     {
  53         enum ContactType { technical, support, administrative, billing, other };
  54         virtual ContactType getType() const=0;
  55         virtual const char* getCompany() const=0;
  56         virtual const char* getGivenName() const=0;
  57         virtual const char* getSurName() const=0;
  58         virtual saml::Iterator<std::string> getEmailAddresses() const=0;
  59         virtual saml::Iterator<std::string> getTelephoneNumbers() const=0;
  60         virtual const DOMElement* getElement() const=0;
  61         virtual ~IContactPerson() {}
  62     };
  63
  64     struct SHIB_EXPORTS IOrganization
  65     {
  66         virtual const char* getName(const char* lang="en") const=0;
  67         virtual const char* getDisplayName(const char* lang="en") const=0;
  68         virtual const char* getURL(const char* lang="en") const=0;
  69         virtual const DOMElement* getElement() const=0;
  70         virtual ~IOrganization() {}
  71     };
  72
  73     struct SHIB_EXPORTS IKeyDescriptor
  74     {
  75         enum KeyUse { unspecified, encryption, signing };
  76         virtual KeyUse getUse() const=0;
  77         virtual DSIGKeyInfoList* getKeyInfo() const=0;
  78         virtual saml::Iterator<const XENCEncryptionMethod*> getEncryptionMethods() const=0;
  79         virtual ~IKeyDescriptor() {}
  80     };
  81
  82     struct SHIB_EXPORTS IEndpoint
  83     {
  84         virtual const XMLCh* getBinding() const=0;
  85         virtual const XMLCh* getLocation() const=0;
  86         virtual const XMLCh* getResponseLocation() const=0;
  87         virtual const DOMElement* getElement() const=0;
  88         virtual ~IEndpoint() {}
  89     };
  90
  91     struct SHIB_EXPORTS IIndexedEndpoint : public virtual IEndpoint
  92     {
  93         virtual unsigned short getIndex() const=0;
  94         virtual ~IIndexedEndpoint() {}
  95     };
  96
  97     struct SHIB_EXPORTS IEndpointManager
  98     {
  99         virtual saml::Iterator<const IEndpoint*> getEndpoints() const=0;
 100         virtual const IEndpoint* getDefaultEndpoint() const=0;
 101         virtual const IEndpoint* getEndpointByIndex(unsigned short index) const=0;
 102         virtual const IEndpoint* getEndpointByBinding(const XMLCh* binding) const=0;
 103         virtual ~IEndpointManager() {}
 104     };
 105
 106     struct SHIB_EXPORTS IEntityDescriptor;
 107     struct SHIB_EXPORTS IRoleDescriptor
 108     {
 109         virtual const IEntityDescriptor* getEntityDescriptor() const=0;
 110         virtual saml::Iterator<const XMLCh*> getProtocolSupportEnumeration() const=0;
 111         virtual bool hasSupport(const XMLCh* protocol) const=0;
 112         virtual bool isValid() const=0;
 113         virtual const char* getErrorURL() const=0;
 114         virtual saml::Iterator<const IKeyDescriptor*> getKeyDescriptors() const=0;
 115         virtual const IOrganization* getOrganization() const=0;
 116         virtual saml::Iterator<const IContactPerson*> getContactPersons() const=0;
 117         virtual const DOMElement* getElement() const=0;
 118         virtual ~IRoleDescriptor() {}
 119     };
 120
 121     struct SHIB_EXPORTS ISSODescriptor : public virtual IRoleDescriptor
 122     {
 123         virtual const IEndpointManager* getArtifactResolutionServiceManager() const=0;
 124         virtual const IEndpointManager* getSingleLogoutServiceManager() const=0;
 125         virtual const IEndpointManager* getManageNameIDServiceManager() const=0;
 126         virtual saml::Iterator<const XMLCh*> getNameIDFormats() const=0;
 127         virtual ~ISSODescriptor() {}
 128     };
 129
 130     struct SHIB_EXPORTS IIDPSSODescriptor : public virtual ISSODescriptor
 131     {
 132         virtual bool getWantAuthnRequestsSigned() const=0;
 133         virtual const IEndpointManager* getSingleSignOnServiceManager() const=0;
 134         virtual const IEndpointManager* getNameIDMappingServiceManager() const=0;
 135         virtual const IEndpointManager* getAssertionIDRequestServiceManager() const=0;
 136         virtual saml::Iterator<const XMLCh*> getAttributeProfiles() const=0;
 137         virtual saml::Iterator<const saml::SAMLAttribute*> getAttributes() const=0;
 138         virtual ~IIDPSSODescriptor() {}
 139     };
 140
 141     struct SHIB_EXPORTS IAttributeConsumingService
 142     {
 143         virtual const XMLCh* getName(const char* lang="en") const=0;
 144         virtual const XMLCh* getDescription(const char* lang="en") const=0;
 145         virtual saml::Iterator<std::pair<const saml::SAMLAttribute*,bool> > getRequestedAttributes() const=0;
 146         virtual ~IAttributeConsumingService() {}
 147     };
 148
 149     struct SHIB_EXPORTS ISPSSODescriptor : public virtual ISSODescriptor
 150     {
 151         virtual bool getAuthnRequestsSigned() const=0;
 152         virtual bool getWantAssertionsSigned() const=0;
 153         virtual const IEndpointManager* getAssertionConsumerServiceManager() const=0;
 154         virtual saml::Iterator<const IAttributeConsumingService*> getAttributeConsumingServices() const=0;
 155         virtual const IAttributeConsumingService* getDefaultAttributeConsumingService() const=0;
 156         virtual const IAttributeConsumingService* getAttributeConsumingServiceByID(const XMLCh* id) const=0;
 157         virtual ~ISPSSODescriptor() {}
 158     };
 159
 160     struct SHIB_EXPORTS IAuthnAuthorityDescriptor : public virtual IRoleDescriptor
 161     {
 162         virtual const IEndpointManager* getAuthnQueryServiceManager() const=0;
 163         virtual const IEndpointManager* getAssertionIDRequestServiceManager() const=0;
 164         virtual saml::Iterator<const XMLCh*> getNameIDFormats() const=0;
 165         virtual ~IAuthnAuthorityDescriptor() {}
 166     };
 167
 168     struct SHIB_EXPORTS IPDPDescriptor : public virtual IRoleDescriptor
 169     {
 170         virtual const IEndpointManager* getAuthzServiceManager() const=0;
 171         virtual const IEndpointManager* getAssertionIDRequestServiceManager() const=0;
 172         virtual saml::Iterator<const XMLCh*> getNameIDFormats() const=0;
 173         virtual ~IPDPDescriptor() {}
 174     };
 175
 176     struct SHIB_EXPORTS IAttributeAuthorityDescriptor : public virtual IRoleDescriptor
 177     {
 178         virtual const IEndpointManager* getAttributeServiceManager() const=0;
 179         virtual const IEndpointManager* getAssertionIDRequestServiceManager() const=0;
 180         virtual saml::Iterator<const XMLCh*> getNameIDFormats() const=0;
 181         virtual saml::Iterator<const XMLCh*> getAttributeProfiles() const=0;
 182         virtual saml::Iterator<const saml::SAMLAttribute*> getAttributes() const=0;
 183         virtual ~IAttributeAuthorityDescriptor() {}
 184     };
 185
 186     struct SHIB_EXPORTS IAffiliationDescriptor
 187     {
 188         virtual const IEntityDescriptor* getEntityDescriptor() const=0;
 189         virtual const XMLCh* getOwnerID() const=0;
 190         virtual bool isValid() const=0;
 191         virtual saml::Iterator<const XMLCh*> getMembers() const=0;
 192         virtual bool isMember(const XMLCh* id) const=0;
 193         virtual saml::Iterator<const IKeyDescriptor*> getKeyDescriptors() const=0;
 194         virtual const DOMElement* getElement() const=0;
 195         virtual ~IAffiliationDescriptor() {}
 196     };
 197
 198     struct SHIB_EXPORTS IEntitiesDescriptor;
 199     struct SHIB_EXPORTS IEntityDescriptor
 200     {
 201         virtual const XMLCh* getId() const=0;
 202         virtual bool isValid() const=0;
 203         virtual saml::Iterator<const IRoleDescriptor*> getRoleDescriptors() const=0;
 204         virtual const IIDPSSODescriptor* getIDPSSODescriptor(const XMLCh* protocol) const=0;
 205         virtual const ISPSSODescriptor* getSPSSODescriptor(const XMLCh* protocol) const=0;
 206         virtual const IAuthnAuthorityDescriptor* getAuthnAuthorityDescriptor(const XMLCh* protocol) const=0;
 207         virtual const IAttributeAuthorityDescriptor* getAttributeAuthorityDescriptor(const XMLCh* protocol) const=0;
 208         virtual const IPDPDescriptor* getPDPDescriptor(const XMLCh* protocol) const=0;
 209         virtual const IAffiliationDescriptor* getAffiliationDescriptor() const=0;
 210         virtual const IOrganization* getOrganization() const=0;
 211         virtual saml::Iterator<const IContactPerson*> getContactPersons() const=0;
 212         virtual saml::Iterator<std::pair<const XMLCh*,const XMLCh*> > getAdditionalMetadataLocations() const=0;
 213         virtual const IEntitiesDescriptor* getEntitiesDescriptor() const=0;
 214         virtual const DOMElement* getElement() const=0;
 215         virtual ~IEntityDescriptor() {}
 216     };
 217
 218     struct SHIB_EXPORTS IEntitiesDescriptor
 219     {
 220         virtual const XMLCh* getName() const=0;
 221         virtual bool isValid() const=0;
 222         virtual const IEntitiesDescriptor* getEntitiesDescriptor() const=0;
 223         virtual saml::Iterator<const IEntitiesDescriptor*> getEntitiesDescriptors() const=0;
 224         virtual saml::Iterator<const IEntityDescriptor*> getEntityDescriptors() const=0;
 225         virtual const DOMElement* getElement() const=0;
 226         virtual ~IEntitiesDescriptor() {}
 227     };
 228
 229     // Shib extension interfaces
 230     struct SHIB_EXPORTS IKeyAuthority
 231     {
 232         virtual int getVerifyDepth() const=0;
 233         virtual saml::Iterator<DSIGKeyInfoList*> getKeyInfos() const=0;
 234         virtual ~IKeyAuthority() {}
 235     };
 236
 237     struct SHIB_EXPORTS IExtendedEntityDescriptor : public virtual IEntityDescriptor
 238     {
 239         virtual saml::Iterator<const IKeyAuthority*> getKeyAuthorities() const=0;
 240         virtual saml::Iterator<std::pair<const XMLCh*,bool> > getScopes() const=0;
 241         virtual ~IExtendedEntityDescriptor() {}
 242     };
 243
 244     struct SHIB_EXPORTS IExtendedEntitiesDescriptor : public virtual IEntitiesDescriptor
 245     {
 246         virtual saml::Iterator<const IKeyAuthority*> getKeyAuthorities() const=0;
 247         virtual ~IExtendedEntitiesDescriptor() {}
 248     };
 249
 250     struct SHIB_EXPORTS IMetadata : public virtual saml::ILockable, public virtual saml::IPlugIn
 251     {
 252         virtual const IEntityDescriptor* lookup(const char* id, bool strict=true) const=0;
 253         virtual const IEntityDescriptor* lookup(const XMLCh* id, bool strict=true) const=0;
 254         virtual const IEntityDescriptor* lookup(const saml::SAMLArtifact* artifact) const=0;
 255         virtual const IEntitiesDescriptor* lookupGroup(const char* name, bool strict=true) const=0;
 256         virtual const IEntitiesDescriptor* lookupGroup(const XMLCh* name, bool strict=true) const=0;
 257         virtual std::pair<const IEntitiesDescriptor*,const IEntityDescriptor*> getRoot() const=0;
 258         virtual ~IMetadata() {}
 259     };
 260
 261     // Trust interface hides *all* details of signature and SSL validation.
 262     // Pluggable providers can fully override the Shibboleth trust model here.
 263
 264     struct SHIB_EXPORTS ITrust : public virtual saml::IPlugIn
 265     {
 266         // Performs certificate validation processing of an untrusted certificates
 267         // using a library-specific representation, in this case an OpenSSL X509*
 268         virtual bool validate(
 269             void* certEE,
 270             const saml::Iterator<void*>& certChain,
 271             const IRoleDescriptor* role,
 272             bool checkName=true
 273             )=0;
 274
 275         // Validates signed SAML messages and assertions sent by an entity acting in a specific role.
 276         // If certificate validation is required, the trust provider used can be overridden using
 277         // the last parameter, or left null and the provider will rely on itself.
 278         virtual bool validate(
 279             const saml::SAMLSignedObject& token,
 280             const IRoleDescriptor* role,
 281             ITrust* certValidator=NULL
 282             )=0;
 283
 284         virtual ~ITrust() {}
 285     };
 286
 287     // Credentials interface abstracts access to "owned" keys and certificates.
 288
 289     struct SHIB_EXPORTS ICredResolver : public virtual saml::IPlugIn
 290     {
 291         virtual void attach(void* ctx) const=0;
 292         virtual XSECCryptoKey* getKey() const=0;
 293         virtual saml::Iterator<XSECCryptoX509*> getCertificates() const=0;
 294         virtual void dump(FILE* f) const=0;
 295         virtual void dump() const { dump(stdout); }
 296         virtual ~ICredResolver() {}
 297     };
 298
 299     struct SHIB_EXPORTS ICredentials : public virtual saml::ILockable, public virtual saml::IPlugIn
 300     {
 301         virtual const ICredResolver* lookup(const char* id) const=0;
 302         virtual ~ICredentials() {}
 303     };
 304
 305     // Attribute acceptance processing interfaces, applied to incoming attributes.
 306
 307     struct SHIB_EXPORTS IAttributeRule
 308     {
 309         virtual const XMLCh* getName() const=0;
 310         virtual const XMLCh* getNamespace() const=0;
 311         virtual const char* getAlias() const=0;
 312         virtual const char* getHeader() const=0;
 313         virtual bool getCaseSensitive() const=0;
 314         virtual void apply(saml::SAMLAttribute& attribute, const IEntityDescriptor* source=NULL) const=0;
 315         virtual ~IAttributeRule() {}
 316     };
 317
 318     struct SHIB_EXPORTS IAAP : public virtual saml::ILockable, public virtual saml::IPlugIn
 319     {
 320         virtual bool anyAttribute() const=0;
 321         virtual const IAttributeRule* lookup(const XMLCh* attrName, const XMLCh* attrNamespace=NULL) const=0;
 322         virtual const IAttributeRule* lookup(const char* alias) const=0;
 323         virtual saml::Iterator<const IAttributeRule*> getAttributeRules() const=0;
 324         virtual ~IAAP() {}
 325     };
 326
 327     struct SHIB_EXPORTS IAttributeFactory : public virtual saml::IPlugIn
 328     {
 329         virtual saml::SAMLAttribute* build(DOMElement* e) const=0;
 330         virtual ~IAttributeFactory() {}
 331     };
 332
 333 #ifdef SHIB_INSTANTIATE
 334     template class SHIB_EXPORTS saml::Iterator<const IContactPerson*>;
 335     template class SHIB_EXPORTS saml::Iterator<const XENCEncryptionMethod*>;
 336     template class SHIB_EXPORTS saml::Iterator<const IKeyDescriptor*>;
 337     template class SHIB_EXPORTS saml::Iterator<const IAttributeConsumingService*>;
 338     template class SHIB_EXPORTS saml::Iterator<const IRoleDescriptor*>;
 339     template class SHIB_EXPORTS saml::Iterator<const IEntityDescriptor*>;
 340     template class SHIB_EXPORTS saml::Iterator<const IEntitiesDescriptor*>;
 341     template class SHIB_EXPORTS saml::Iterator<const IEndpoint*>;
 342     template class SHIB_EXPORTS saml::Iterator<const IAttributeRule*>;
 343     template class SHIB_EXPORTS saml::Iterator<const IKeyAuthority*>;
 344     template class SHIB_EXPORTS saml::Iterator<DSIGKeyInfoList*>;
 345     template class SHIB_EXPORTS saml::Iterator<IMetadata*>;
 346     template class SHIB_EXPORTS saml::ArrayIterator<IMetadata*>;
 347     template class SHIB_EXPORTS saml::Iterator<ITrust*>;
 348     template class SHIB_EXPORTS saml::ArrayIterator<ITrust*>;
 349     template class SHIB_EXPORTS saml::Iterator<ICredentials*>;
 350     template class SHIB_EXPORTS saml::ArrayIterator<ICredentials*>;
 351     template class SHIB_EXPORTS saml::Iterator<IAAP*>;
 352     template class SHIB_EXPORTS saml::ArrayIterator<IAAP*>;
 353 #endif
 354
 355     // Glue classes between abstract metadata and concrete providers
 356
 357     class SHIB_EXPORTS Metadata
 358     {
 359     public:
 360         Metadata(const saml::Iterator<IMetadata*>& metadatas) : m_metadatas(metadatas), m_mapper(NULL) {}
 361         ~Metadata();
 362
 363         const IEntityDescriptor* lookup(const char* id, bool strict=true);
 364         const IEntityDescriptor* lookup(const XMLCh* id, bool strict=true);
 365         const IEntityDescriptor* lookup(const saml::SAMLArtifact* artifact);
 366
 367     private:
 368         Metadata(const Metadata&);
 369         void operator=(const Metadata&);
 370         IMetadata* m_mapper;
 371         saml::Iterator<IMetadata*> m_metadatas;
 372     };
 373
 374     class SHIB_EXPORTS Trust
 375     {
 376     public:
 377         Trust(const saml::Iterator<ITrust*>& trusts) : m_trusts(trusts) {}
 378         ~Trust() {}
 379
 380         bool validate(
 381             void* certEE,
 382             const saml::Iterator<void*>& certChain,
 383             const IRoleDescriptor* role,
 384             bool checkName=true
 385             ) const;
 386         bool validate(const saml::SAMLSignedObject& token, const IRoleDescriptor* role) const;
 387
 388     private:
 389         Trust(const Trust&);
 390         void operator=(const Trust&);
 391         saml::Iterator<ITrust*> m_trusts;
 392     };
 393
 394     class SHIB_EXPORTS Credentials
 395     {
 396     public:
 397         Credentials(const saml::Iterator<ICredentials*>& creds) : m_creds(creds), m_mapper(NULL) {}
 398         ~Credentials();
 399
 400         const ICredResolver* lookup(const char* id);
 401
 402     private:
 403         Credentials(const Credentials&);
 404         void operator=(const Credentials&);
 405         ICredentials* m_mapper;
 406         saml::Iterator<ICredentials*> m_creds;
 407     };
 408
 409     class SHIB_EXPORTS AAP
 410     {
 411     public:
 412         AAP(const saml::Iterator<IAAP*>& aaps, const XMLCh* attrName, const XMLCh* attrNamespace=NULL);
 413         AAP(const saml::Iterator<IAAP*>& aaps, const char* alias);
 414         ~AAP();
 415         bool fail() const {return m_mapper==NULL;}
 416         const IAttributeRule* operator->() const {return m_rule;}
 417         operator const IAttributeRule*() const {return m_rule;}
 418
 419         static void apply(const saml::Iterator<IAAP*>& aaps, saml::SAMLAssertion& assertion, const IEntityDescriptor* source=NULL);
 420
 421     private:
 422         AAP(const AAP&);
 423         void operator=(const AAP&);
 424         IAAP* m_mapper;
 425         const IAttributeRule* m_rule;
 426     };
 427
 428     // Subclass around the OpenSAML browser profile interface,
 429     // incoporates additional functionality using Shib-defined APIs.
 430     class SHIB_EXPORTS ShibBrowserProfile : virtual public saml::SAMLBrowserProfile
 431     {
 432     public:
 433         struct SHIB_EXPORTS ITokenValidator {
 434             virtual void validateToken(
 435                 saml::SAMLAssertion* token,
 436                 time_t=0,
 437                 const IRoleDescriptor* role=NULL,
 438                 const saml::Iterator<ITrust*>& trusts=EMPTY(ITrust*)
 439                 ) const=0;
 440             virtual ~ITokenValidator() {}
 441         };
 442
 443         ShibBrowserProfile(
 444             const ITokenValidator* validator,
 445             const saml::Iterator<IMetadata*>& metadatas=EMPTY(IMetadata*),
 446             const saml::Iterator<ITrust*>& trusts=EMPTY(ITrust*)
 447             );
 448         virtual ~ShibBrowserProfile();
 449
 450         virtual saml::SAMLBrowserProfile::BrowserProfileResponse receive(
 451             const char* samlResponse,
 452             const XMLCh* recipient,
 453             saml::IReplayCache* replayCache,
 454             int minorVersion=1
 455             ) const;
 456         virtual saml::SAMLBrowserProfile::BrowserProfileResponse receive(
 457             saml::Iterator<const char*> artifacts,
 458             const XMLCh* recipient,
 459             saml::SAMLBrowserProfile::ArtifactMapper* artifactMapper,
 460             saml::IReplayCache* replayCache,
 461             int minorVersion=1
 462             ) const;
 463
 464     private:
 465         void postprocess(saml::SAMLBrowserProfile::BrowserProfileResponse& bpr, int minorVersion=1) const;
 466
 467         saml::SAMLBrowserProfile* m_profile;
 468         saml::Iterator<IMetadata*> m_metadatas;
 469         saml::Iterator<ITrust*> m_trusts;
 470         const ITokenValidator* m_validator;
 471     };
 472
 473     class SHIB_EXPORTS ShibConfig
 474     {
 475     public:
 476         ShibConfig() {}
 477         virtual ~ShibConfig() {}
 478
 479         // global per-process setup and shutdown of Shibboleth runtime
 480         virtual bool init();
 481         virtual void term();
 482
 483         // manages specific attribute name to factory mappings
 484         void regAttributeMapping(const XMLCh* name, const IAttributeFactory* factory);
 485         void unregAttributeMapping(const XMLCh* name);
 486         void clearAttributeMappings();
 487
 488         // enables runtime and clients to access configuration
 489         static ShibConfig& getConfig();
 490     };
 491
 492     /* Helper classes for implementing reloadable XML-based config files
 493        The ILockable interface will usually be inherited twice, once as
 494        part of the external interface to clients and once as an implementation
 495        detail of the reloading class below.
 496      */
 497
 498     class SHIB_EXPORTS ReloadableXMLFileImpl
 499     {
 500     public:
 501         ReloadableXMLFileImpl(const char* pathname);
 502         ReloadableXMLFileImpl(const DOMElement* pathname);
 503         virtual ~ReloadableXMLFileImpl();
 504
 505     protected:
 506         DOMDocument* m_doc;
 507         const DOMElement* m_root;
 508     };
 509
 510     class SHIB_EXPORTS ReloadableXMLFile : protected virtual saml::ILockable
 511     {
 512     public:
 513         ReloadableXMLFile(const DOMElement* e);
 514         ~ReloadableXMLFile() { delete m_lock; delete m_impl; }
 515
 516         virtual void lock();
 517         virtual void unlock() { if (m_lock) m_lock->unlock(); }
 518
 519         ReloadableXMLFileImpl* getImplementation() const;
 520
 521     protected:
 522         virtual ReloadableXMLFileImpl* newImplementation(const char* pathname, bool first=true) const=0;
 523         virtual ReloadableXMLFileImpl* newImplementation(const DOMElement* e, bool first=true) const=0;
 524         mutable ReloadableXMLFileImpl* m_impl;
 525
 526     private:
 527         const DOMElement* m_root;
 528         std::string m_source;
 529         time_t m_filestamp;
 530         xmltooling::RWLock* m_lock;
 531     };
 532
 533     /* These helpers attach metadata-derived information as exception properties and then
 534      * rethrow the object. The following properties are attached, when possible:
 535      *
 536      *  providerId          The unique ID of the entity
 537      *  errorURL            The error support URL of the entity or role
 538      *  contactName         A formatted support or technical contact name
 539      *  contactEmail        A contact email address
 540      */
 541     SHIB_EXPORTS void annotateException(saml::SAMLException* e, const IEntityDescriptor* entity, bool rethrow=true);
 542     SHIB_EXPORTS void annotateException(saml::SAMLException* e, const IRoleDescriptor* role, bool rethrow=true);
 543 }
 544
 545 #endif