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