shib/shib.h

   1 /*
   2  * The Shibboleth License, Version 1.
   3  * Copyright (c) 2002
   4  * University Corporation for Advanced Internet Development, Inc.
   5  * All rights reserved
   6  *
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions are met:
  10  *
  11  * Redistributions of source code must retain the above copyright notice, this
  12  * list of conditions and the following disclaimer.
  13  *
  14  * Redistributions in binary form must reproduce the above copyright notice,
  15  * this list of conditions and the following disclaimer in the documentation
  16  * and/or other materials provided with the distribution, if any, must include
  17  * the following acknowledgment: "This product includes software developed by
  18  * the University Corporation for Advanced Internet Development
  19  * <http://www.ucaid.edu>Internet2 Project. Alternately, this acknowledegement
  20  * may appear in the software itself, if and wherever such third-party
  21  * acknowledgments normally appear.
  22  *
  23  * Neither the name of Shibboleth nor the names of its contributors, nor
  24  * Internet2, nor the University Corporation for Advanced Internet Development,
  25  * Inc., nor UCAID may be used to endorse or promote products derived from this
  26  * software without specific prior written permission. For written permission,
  27  * please contact shibboleth@shibboleth.org
  28  *
  29  * Products derived from this software may not be called Shibboleth, Internet2,
  30  * UCAID, or the University Corporation for Advanced Internet Development, nor
  31  * may Shibboleth appear in their name, without prior written permission of the
  32  * University Corporation for Advanced Internet Development.
  33  *
  34  *
  35  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  36  * AND WITH ALL FAULTS. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  37  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  38  * PARTICULAR PURPOSE, AND NON-INFRINGEMENT ARE DISCLAIMED AND THE ENTIRE RISK
  39  * OF SATISFACTORY QUALITY, PERFORMANCE, ACCURACY, AND EFFORT IS WITH LICENSEE.
  40  * IN NO EVENT SHALL THE COPYRIGHT OWNER, CONTRIBUTORS OR THE UNIVERSITY
  41  * CORPORATION FOR ADVANCED INTERNET DEVELOPMENT, INC. BE LIABLE FOR ANY DIRECT,
  42  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  43  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  44  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  45  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  46  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  47  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  48  */
  49
  50
  51 /* shib.h - Shibboleth header file
  52
  53    Scott Cantor
  54    6/4/02
  55
  56    $History:$
  57 */
  58
  59 #ifndef __shib_h__
  60 #define __shib_h__
  61
  62 #include <saml/saml.h>
  63 #include <shib/shib-threads.h>
  64 #include <xsec/xenc/XENCEncryptionMethod.hpp>
  65
  66 #ifdef WIN32
  67 # ifndef SHIB_EXPORTS
  68 #  define SHIB_EXPORTS __declspec(dllimport)
  69 # endif
  70 #else
  71 # define SHIB_EXPORTS
  72 #endif
  73
  74 namespace shibboleth
  75 {
  76     DECLARE_SAML_EXCEPTION(SHIB_EXPORTS,ResourceAccessException,SAMLException);
  77     DECLARE_SAML_EXCEPTION(SHIB_EXPORTS,MetadataException,SAMLException);
  78     DECLARE_SAML_EXCEPTION(SHIB_EXPORTS,CredentialException,SAMLException);
  79     DECLARE_SAML_EXCEPTION(SHIB_EXPORTS,InvalidHandleException,RetryableProfileException);
  80     DECLARE_SAML_EXCEPTION(SHIB_EXPORTS,InvalidSessionException,RetryableProfileException);
  81
  82     // Metadata abstract interfaces, based on SAML 2.0
  83
  84     struct SHIB_EXPORTS IContactPerson
  85     {
  86         enum ContactType { technical, support, administrative, billing, other };
  87         virtual ContactType getType() const=0;
  88         virtual const char* getCompany() const=0;
  89         virtual const char* getGivenName() const=0;
  90         virtual const char* getSurName() const=0;
  91         virtual saml::Iterator<std::string> getEmailAddresses() const=0;
  92         virtual saml::Iterator<std::string> getTelephoneNumbers() const=0;
  93         virtual const DOMElement* getElement() const=0;
  94         virtual ~IContactPerson() {}
  95     };
  96
  97     struct SHIB_EXPORTS IOrganization
  98     {
  99         virtual const char* getName(const char* lang="en") const=0;
 100         virtual const char* getDisplayName(const char* lang="en") const=0;
 101         virtual const char* getURL(const char* lang="en") const=0;
 102         virtual const DOMElement* getElement() const=0;
 103         virtual ~IOrganization() {}
 104     };
 105
 106     struct SHIB_EXPORTS IKeyDescriptor
 107     {
 108         enum KeyUse { unspecified, encryption, signing };
 109         virtual KeyUse getUse() const=0;
 110         virtual DSIGKeyInfoList* getKeyInfo() const=0;
 111         virtual saml::Iterator<const XENCEncryptionMethod*> getEncryptionMethods() const=0;
 112         virtual ~IKeyDescriptor() {}
 113     };
 114
 115     struct SHIB_EXPORTS IEndpoint
 116     {
 117         virtual const XMLCh* getBinding() const=0;
 118         virtual const XMLCh* getLocation() const=0;
 119         virtual const XMLCh* getResponseLocation() const=0;
 120         virtual const DOMElement* getElement() const=0;
 121         virtual ~IEndpoint() {}
 122     };
 123
 124     struct SHIB_EXPORTS IIndexedEndpoint : public virtual IEndpoint
 125     {
 126         virtual unsigned short getIndex() const=0;
 127         virtual ~IIndexedEndpoint() {}
 128     };
 129
 130     struct SHIB_EXPORTS IEndpointManager
 131     {
 132         virtual saml::Iterator<const IEndpoint*> getEndpoints() const=0;
 133         virtual const IEndpoint* getDefaultEndpoint() const=0;
 134         virtual const IEndpoint* getEndpointByIndex(unsigned short index) const=0;
 135         virtual const IEndpoint* getEndpointByBinding(const XMLCh* binding) const=0;
 136         virtual ~IEndpointManager() {}
 137     };
 138
 139     struct SHIB_EXPORTS IEntityDescriptor;
 140     struct SHIB_EXPORTS IRoleDescriptor
 141     {
 142         virtual const IEntityDescriptor* getEntityDescriptor() const=0;
 143         virtual saml::Iterator<const XMLCh*> getProtocolSupportEnumeration() const=0;
 144         virtual bool hasSupport(const XMLCh* protocol) const=0;
 145         virtual bool isValid() const=0;
 146         virtual const char* getErrorURL() const=0;
 147         virtual saml::Iterator<const IKeyDescriptor*> getKeyDescriptors() const=0;
 148         virtual const IOrganization* getOrganization() const=0;
 149         virtual saml::Iterator<const IContactPerson*> getContactPersons() const=0;
 150         virtual const DOMElement* getElement() const=0;
 151         virtual ~IRoleDescriptor() {}
 152     };
 153
 154     struct SHIB_EXPORTS ISSODescriptor : public virtual IRoleDescriptor
 155     {
 156         virtual const IEndpointManager* getArtifactResolutionServiceManager() const=0;
 157         virtual const IEndpointManager* getSingleLogoutServiceManager() const=0;
 158         virtual const IEndpointManager* getManageNameIDServiceManager() const=0;
 159         virtual saml::Iterator<const XMLCh*> getNameIDFormats() const=0;
 160         virtual ~ISSODescriptor() {}
 161     };
 162
 163     struct SHIB_EXPORTS IIDPSSODescriptor : public virtual ISSODescriptor
 164     {
 165         virtual bool getWantAuthnRequestsSigned() const=0;
 166         virtual const IEndpointManager* getSingleSignOnServiceManager() const=0;
 167         virtual const IEndpointManager* getNameIDMappingServiceManager() const=0;
 168         virtual const IEndpointManager* getAssertionIDRequestServiceManager() const=0;
 169         virtual saml::Iterator<const XMLCh*> getAttributeProfiles() const=0;
 170         virtual saml::Iterator<const saml::SAMLAttribute*> getAttributes() const=0;
 171         virtual ~IIDPSSODescriptor() {}
 172     };
 173
 174     struct SHIB_EXPORTS IAttributeConsumingService
 175     {
 176         virtual const XMLCh* getName(const char* lang="en") const=0;
 177         virtual const XMLCh* getDescription(const char* lang="en") const=0;
 178         virtual saml::Iterator<std::pair<const saml::SAMLAttribute*,bool> > getRequestedAttributes() const=0;
 179         virtual ~IAttributeConsumingService() {}
 180     };
 181
 182     struct SHIB_EXPORTS ISPSSODescriptor : public virtual ISSODescriptor
 183     {
 184         virtual bool getAuthnRequestsSigned() const=0;
 185         virtual bool getWantAssertionsSigned() const=0;
 186         virtual const IEndpointManager* getAssertionConsumerServiceManager() const=0;
 187         virtual saml::Iterator<const IAttributeConsumingService*> getAttributeConsumingServices() const=0;
 188         virtual const IAttributeConsumingService* getDefaultAttributeConsumingService() const=0;
 189         virtual const IAttributeConsumingService* getAttributeConsumingServiceByID(const XMLCh* id) const=0;
 190         virtual ~ISPSSODescriptor() {}
 191     };
 192
 193     struct SHIB_EXPORTS IAuthnAuthorityDescriptor : public virtual IRoleDescriptor
 194     {
 195         virtual const IEndpointManager* getAuthnQueryServiceManager() const=0;
 196         virtual const IEndpointManager* getAssertionIDRequestServiceManager() const=0;
 197         virtual saml::Iterator<const XMLCh*> getNameIDFormats() const=0;
 198         virtual ~IAuthnAuthorityDescriptor() {}
 199     };
 200
 201     struct SHIB_EXPORTS IPDPDescriptor : public virtual IRoleDescriptor
 202     {
 203         virtual const IEndpointManager* getAuthzServiceManager() const=0;
 204         virtual const IEndpointManager* getAssertionIDRequestServiceManager() const=0;
 205         virtual saml::Iterator<const XMLCh*> getNameIDFormats() const=0;
 206         virtual ~IPDPDescriptor() {}
 207     };
 208
 209     struct SHIB_EXPORTS IAttributeAuthorityDescriptor : public virtual IRoleDescriptor
 210     {
 211         virtual const IEndpointManager* getAttributeServiceManager() const=0;
 212         virtual const IEndpointManager* getAssertionIDRequestServiceManager() const=0;
 213         virtual saml::Iterator<const XMLCh*> getNameIDFormats() const=0;
 214         virtual saml::Iterator<const XMLCh*> getAttributeProfiles() const=0;
 215         virtual saml::Iterator<const saml::SAMLAttribute*> getAttributes() const=0;
 216         virtual ~IAttributeAuthorityDescriptor() {}
 217     };
 218
 219     struct SHIB_EXPORTS IAffiliationDescriptor
 220     {
 221         virtual const IEntityDescriptor* getEntityDescriptor() const=0;
 222         virtual const XMLCh* getOwnerID() const=0;
 223         virtual bool isValid() const=0;
 224         virtual saml::Iterator<const XMLCh*> getMembers() const=0;
 225         virtual bool isMember(const XMLCh* id) const=0;
 226         virtual saml::Iterator<const IKeyDescriptor*> getKeyDescriptors() const=0;
 227         virtual const DOMElement* getElement() const=0;
 228         virtual ~IAffiliationDescriptor() {}
 229     };
 230
 231     struct SHIB_EXPORTS IEntitiesDescriptor;
 232     struct SHIB_EXPORTS IEntityDescriptor
 233     {
 234         virtual const XMLCh* getId() const=0;
 235         virtual bool isValid() const=0;
 236         virtual saml::Iterator<const IRoleDescriptor*> getRoleDescriptors() const=0;
 237         virtual const IIDPSSODescriptor* getIDPSSODescriptor(const XMLCh* protocol) const=0;
 238         virtual const ISPSSODescriptor* getSPSSODescriptor(const XMLCh* protocol) const=0;
 239         virtual const IAuthnAuthorityDescriptor* getAuthnAuthorityDescriptor(const XMLCh* protocol) const=0;
 240         virtual const IAttributeAuthorityDescriptor* getAttributeAuthorityDescriptor(const XMLCh* protocol) const=0;
 241         virtual const IPDPDescriptor* getPDPDescriptor(const XMLCh* protocol) const=0;
 242         virtual const IAffiliationDescriptor* getAffiliationDescriptor() const=0;
 243         virtual const IOrganization* getOrganization() const=0;
 244         virtual saml::Iterator<const IContactPerson*> getContactPersons() const=0;
 245         virtual saml::Iterator<std::pair<const XMLCh*,const XMLCh*> > getAdditionalMetadataLocations() const=0;
 246         virtual const IEntitiesDescriptor* getEntitiesDescriptor() const=0;
 247         virtual const DOMElement* getElement() const=0;
 248         virtual ~IEntityDescriptor() {}
 249     };
 250
 251     struct SHIB_EXPORTS IEntitiesDescriptor
 252     {
 253         virtual const XMLCh* getName() const=0;
 254         virtual bool isValid() const=0;
 255         virtual const IEntitiesDescriptor* getEntitiesDescriptor() const=0;
 256         virtual saml::Iterator<const IEntitiesDescriptor*> getEntitiesDescriptors() const=0;
 257         virtual saml::Iterator<const IEntityDescriptor*> getEntityDescriptors() const=0;
 258         virtual const DOMElement* getElement() const=0;
 259         virtual ~IEntitiesDescriptor() {}
 260     };
 261
 262     // Supports Shib role extension describing attribute scoping rules
 263     struct SHIB_EXPORTS IScopedRoleDescriptor : public virtual IRoleDescriptor
 264     {
 265         virtual saml::Iterator<std::pair<const XMLCh*,bool> > getScopes() const=0;
 266         virtual ~IScopedRoleDescriptor() {}
 267     };
 268
 269     // Shib extension interfaces to key authority data
 270     struct SHIB_EXPORTS IKeyAuthority
 271     {
 272         virtual int getVerifyDepth() const=0;
 273         virtual saml::Iterator<DSIGKeyInfoList*> getKeyInfos() const=0;
 274         virtual ~IKeyAuthority() {}
 275     };
 276
 277     struct SHIB_EXPORTS IExtendedEntityDescriptor : public virtual IEntityDescriptor
 278     {
 279         virtual saml::Iterator<const IKeyAuthority*> getKeyAuthorities() const=0;
 280         virtual ~IExtendedEntityDescriptor() {}
 281     };
 282
 283     struct SHIB_EXPORTS IExtendedEntitiesDescriptor : public virtual IEntitiesDescriptor
 284     {
 285         virtual saml::Iterator<const IKeyAuthority*> getKeyAuthorities() const=0;
 286         virtual ~IExtendedEntitiesDescriptor() {}
 287     };
 288
 289     struct SHIB_EXPORTS IMetadata : public virtual saml::ILockable, public virtual saml::IPlugIn
 290     {
 291         virtual const IEntityDescriptor* lookup(const char* id, bool strict=true) const=0;
 292         virtual const IEntityDescriptor* lookup(const XMLCh* id, bool strict=true) const=0;
 293         virtual const IEntityDescriptor* lookup(const saml::SAMLArtifact* artifact) const=0;
 294         virtual const IEntitiesDescriptor* lookupGroup(const char* name, bool strict=true) const=0;
 295         virtual const IEntitiesDescriptor* lookupGroup(const XMLCh* name, bool strict=true) const=0;
 296         virtual std::pair<const IEntitiesDescriptor*,const IEntityDescriptor*> getRoot() const=0;
 297         virtual ~IMetadata() {}
 298     };
 299
 300     // Trust interface hides *all* details of signature and SSL validation.
 301     // Pluggable providers can fully override the Shibboleth trust model here.
 302
 303     struct SHIB_EXPORTS ITrust : public virtual saml::IPlugIn
 304     {
 305         // Performs certificate validation processing of an untrusted certificates
 306         // using a library-specific representation, in this case an OpenSSL X509*
 307         virtual bool validate(
 308             void* certEE,
 309             const saml::Iterator<void*>& certChain,
 310             const IRoleDescriptor* role,
 311             bool checkName=true
 312             )=0;
 313
 314         // Validates signed SAML messages and assertions sent by an entity acting in a specific role.
 315         // It may use the previous function if the token cannot be validated directly and certificates
 316         // are included in the signature.
 317         virtual bool validate(const saml::SAMLSignedObject& token, const IRoleDescriptor* role)=0;
 318
 319         virtual ~ITrust() {}
 320     };
 321
 322     // Credentials interface abstracts access to "owned" keys and certificates.
 323
 324     struct SHIB_EXPORTS ICredResolver : public virtual saml::IPlugIn
 325     {
 326         virtual void attach(void* ctx) const=0;
 327         virtual XSECCryptoKey* getKey() const=0;
 328         virtual saml::Iterator<XSECCryptoX509*> getCertificates() const=0;
 329         virtual void dump(FILE* f) const=0;
 330         virtual void dump() const { dump(stdout); }
 331         virtual ~ICredResolver() {}
 332     };
 333
 334     struct SHIB_EXPORTS ICredentials : public virtual saml::ILockable, public virtual saml::IPlugIn
 335     {
 336         virtual const ICredResolver* lookup(const char* id) const=0;
 337         virtual ~ICredentials() {}
 338     };
 339
 340     // Attribute acceptance processing interfaces, applied to incoming attributes.
 341
 342     struct SHIB_EXPORTS IAttributeRule
 343     {
 344         virtual const XMLCh* getName() const=0;
 345         virtual const XMLCh* getNamespace() const=0;
 346         virtual const char* getFactory() const=0;
 347         virtual const char* getAlias() const=0;
 348         virtual const char* getHeader() const=0;
 349         virtual bool getCaseSensitive() const=0;
 350         virtual void apply(saml::SAMLAttribute& attribute, const IRoleDescriptor* role=NULL) const=0;
 351         virtual ~IAttributeRule() {}
 352     };
 353
 354     struct SHIB_EXPORTS IAAP : public virtual saml::ILockable, public virtual saml::IPlugIn
 355     {
 356         virtual bool anyAttribute() const=0;
 357         virtual const IAttributeRule* lookup(const XMLCh* attrName, const XMLCh* attrNamespace=NULL) const=0;
 358         virtual const IAttributeRule* lookup(const char* alias) const=0;
 359         virtual saml::Iterator<const IAttributeRule*> getAttributeRules() const=0;
 360         virtual ~IAAP() {}
 361     };
 362
 363 #ifdef SHIB_INSTANTIATE
 364     template class SHIB_EXPORTS saml::Iterator<const IContactPerson*>;
 365     template class SHIB_EXPORTS saml::Iterator<const XENCEncryptionMethod*>;
 366     template class SHIB_EXPORTS saml::Iterator<const IKeyDescriptor*>;
 367     template class SHIB_EXPORTS saml::Iterator<const IAttributeConsumingService*>;
 368     template class SHIB_EXPORTS saml::Iterator<const IRoleDescriptor*>;
 369     template class SHIB_EXPORTS saml::Iterator<const IEntityDescriptor*>;
 370     template class SHIB_EXPORTS saml::Iterator<const IEntitiesDescriptor*>;
 371     template class SHIB_EXPORTS saml::Iterator<const IEndpoint*>;
 372     template class SHIB_EXPORTS saml::Iterator<const IAttributeRule*>;
 373     template class SHIB_EXPORTS saml::Iterator<const IKeyAuthority*>;
 374     template class SHIB_EXPORTS saml::Iterator<DSIGKeyInfoList*>;
 375     template class SHIB_EXPORTS saml::Iterator<IMetadata*>;
 376     template class SHIB_EXPORTS saml::ArrayIterator<IMetadata*>;
 377     template class SHIB_EXPORTS saml::Iterator<ITrust*>;
 378     template class SHIB_EXPORTS saml::ArrayIterator<ITrust*>;
 379     template class SHIB_EXPORTS saml::Iterator<ICredentials*>;
 380     template class SHIB_EXPORTS saml::ArrayIterator<ICredentials*>;
 381     template class SHIB_EXPORTS saml::Iterator<IAAP*>;
 382     template class SHIB_EXPORTS saml::ArrayIterator<IAAP*>;
 383 #endif
 384
 385     struct SHIB_EXPORTS Constants
 386     {
 387         static const XMLCh SHIB_ATTRIBUTE_NAMESPACE_URI[];
 388         static const XMLCh SHIB_NAMEID_FORMAT_URI[];
 389         static const XMLCh SHIB_AUTHNREQUEST_PROFILE_URI[];
 390         static const XMLCh SHIB_LEGACY_AUTHNREQUEST_PROFILE_URI[];
 391         static const XMLCh SHIB_SESSIONINIT_PROFILE_URI[];
 392         static const XMLCh SHIB_LOGOUT_PROFILE_URI[];
 393         static const XMLCh SHIB_NS[];
 394         static const XMLCh InvalidHandle[];
 395     };
 396
 397     // Glue classes between abstract metadata and concrete providers
 398
 399     class SHIB_EXPORTS Metadata
 400     {
 401     public:
 402         Metadata(const saml::Iterator<IMetadata*>& metadatas) : m_metadatas(metadatas), m_mapper(NULL) {}
 403         ~Metadata();
 404
 405         const IEntityDescriptor* lookup(const char* id, bool strict=true);
 406         const IEntityDescriptor* lookup(const XMLCh* id, bool strict=true);
 407         const IEntityDescriptor* lookup(const saml::SAMLArtifact* artifact);
 408
 409     private:
 410         Metadata(const Metadata&);
 411         void operator=(const Metadata&);
 412         IMetadata* m_mapper;
 413         const saml::Iterator<IMetadata*>& m_metadatas;
 414     };
 415
 416     class SHIB_EXPORTS Trust
 417     {
 418     public:
 419         Trust(const saml::Iterator<ITrust*>& trusts) : m_trusts(trusts) {}
 420         ~Trust() {}
 421
 422         bool validate(
 423             void* certEE,
 424             const saml::Iterator<void*>& certChain,
 425             const IRoleDescriptor* role,
 426             bool checkName=true
 427             ) const;
 428         bool validate(const saml::SAMLSignedObject& token, const IRoleDescriptor* role) const;
 429
 430     private:
 431         Trust(const Trust&);
 432         void operator=(const Trust&);
 433         const saml::Iterator<ITrust*>& m_trusts;
 434     };
 435
 436     class SHIB_EXPORTS Credentials
 437     {
 438     public:
 439         Credentials(const saml::Iterator<ICredentials*>& creds) : m_creds(creds), m_mapper(NULL) {}
 440         ~Credentials();
 441
 442         const ICredResolver* lookup(const char* id);
 443
 444     private:
 445         Credentials(const Credentials&);
 446         void operator=(const Credentials&);
 447         ICredentials* m_mapper;
 448         const saml::Iterator<ICredentials*>& m_creds;
 449     };
 450
 451     class SHIB_EXPORTS AAP
 452     {
 453     public:
 454         AAP(const saml::Iterator<IAAP*>& aaps, const XMLCh* attrName, const XMLCh* attrNamespace=NULL);
 455         AAP(const saml::Iterator<IAAP*>& aaps, const char* alias);
 456         ~AAP();
 457         bool fail() const {return m_mapper==NULL;}
 458         const IAttributeRule* operator->() const {return m_rule;}
 459         operator const IAttributeRule*() const {return m_rule;}
 460
 461         static void apply(const saml::Iterator<IAAP*>& aaps, saml::SAMLAssertion& assertion, const IRoleDescriptor* role=NULL);
 462
 463     private:
 464         AAP(const AAP&);
 465         void operator=(const AAP&);
 466         IAAP* m_mapper;
 467         const IAttributeRule* m_rule;
 468     };
 469
 470     // Subclass around the OpenSAML browser profile interface,
 471     // incoporates additional functionality using Shib-defined APIs.
 472     class SHIB_EXPORTS ShibBrowserProfile : virtual public saml::SAMLBrowserProfile
 473     {
 474     public:
 475         ShibBrowserProfile(
 476             const saml::Iterator<IMetadata*>& metadatas=EMPTY(IMetadata*),
 477             const saml::Iterator<ITrust*>& trusts=EMPTY(ITrust*)
 478             );
 479         virtual ~ShibBrowserProfile();
 480
 481         virtual void setVersion(int major, int minor);
 482         virtual saml::SAMLBrowserProfile::BrowserProfileResponse receive(
 483             const char* packet,
 484             const XMLCh* recipient,
 485             int supportedProfiles,
 486             saml::IReplayCache* replayCache=NULL,
 487             saml::SAMLBrowserProfile::ArtifactMapper* callback=NULL
 488             ) const;
 489
 490     private:
 491         saml::SAMLBrowserProfile* m_profile;
 492         saml::Iterator<IMetadata*> m_metadatas;
 493         saml::Iterator<ITrust*> m_trusts;
 494     };
 495
 496     // Instead of wrapping the binding to deal with mutual authentication, we
 497     // just use the HTTP hook functionality offered by OpenSAML. The hook will
 498     // register "itself" as a globalCtx pointer with the SAML binding and the caller
 499     // will declare and pass the embedded struct as callCtx for use by the hook.
 500     class SHIB_EXPORTS ShibHTTPHook : virtual public saml::SAMLSOAPHTTPBinding::HTTPHook
 501     {
 502     public:
 503         ShibHTTPHook(const saml::Iterator<ITrust*>& trusts, const saml::Iterator<ICredentials*>& creds)
 504             : m_trusts(trusts), m_creds(creds) {}
 505         virtual ~ShibHTTPHook() {}
 506
 507         // Only hook we need here is for outgoing connection to server.
 508         virtual bool outgoing(saml::HTTPClient* conn, void* globalCtx=NULL, void* callCtx=NULL);
 509
 510         // Client declares a context object and pass as callCtx to send() method.
 511         class SHIB_EXPORTS ShibHTTPHookCallContext {
 512         public:
 513             ShibHTTPHookCallContext(const char* credResolverId, const IRoleDescriptor* role)
 514                 : m_credResolverId(credResolverId), m_role(role), m_hook(NULL) {}
 515             const ShibHTTPHook* getHook() {return m_hook;}
 516             const char* getCredResolverId() {return m_credResolverId;}
 517             const IRoleDescriptor* getRoleDescriptor() {return m_role;}
 518
 519         private:
 520             const char* m_credResolverId;
 521             const IRoleDescriptor* m_role;
 522             ShibHTTPHook* m_hook;
 523             friend class ShibHTTPHook;
 524         };
 525
 526         const saml::Iterator<ITrust*>& getTrustProviders() const {return m_trusts;}
 527         const saml::Iterator<ICredentials*>& getCredentialProviders() const {return m_creds;}
 528     private:
 529         saml::Iterator<ITrust*> m_trusts;
 530         saml::Iterator<ICredentials*> m_creds;
 531     };
 532
 533     class SHIB_EXPORTS ShibConfig
 534     {
 535     public:
 536         ShibConfig() {}
 537         virtual ~ShibConfig() {}
 538
 539         // global per-process setup and shutdown of Shibboleth runtime
 540         virtual bool init();
 541         virtual void term();
 542
 543         // enables runtime and clients to access configuration
 544         static ShibConfig& getConfig();
 545     };
 546
 547     /* Helper classes for implementing reloadable XML-based config files
 548        The ILockable interface will usually be inherited twice, once as
 549        part of the external interface to clients and once as an implementation
 550        detail of the reloading class below.
 551      */
 552
 553     class SHIB_EXPORTS ReloadableXMLFileImpl
 554     {
 555     public:
 556         ReloadableXMLFileImpl(const char* pathname);
 557         ReloadableXMLFileImpl(const DOMElement* pathname);
 558         virtual ~ReloadableXMLFileImpl();
 559
 560     protected:
 561         DOMDocument* m_doc;
 562         const DOMElement* m_root;
 563     };
 564
 565     class SHIB_EXPORTS ReloadableXMLFile : protected virtual saml::ILockable
 566     {
 567     public:
 568         ReloadableXMLFile(const DOMElement* e);
 569         ~ReloadableXMLFile() { delete m_lock; delete m_impl; }
 570
 571         virtual void lock();
 572         virtual void unlock() { if (m_lock) m_lock->unlock(); }
 573
 574         ReloadableXMLFileImpl* getImplementation() const;
 575
 576     protected:
 577         virtual ReloadableXMLFileImpl* newImplementation(const char* pathname, bool first=true) const=0;
 578         virtual ReloadableXMLFileImpl* newImplementation(const DOMElement* e, bool first=true) const=0;
 579         mutable ReloadableXMLFileImpl* m_impl;
 580
 581     private:
 582         const DOMElement* m_root;
 583         std::string m_source;
 584         time_t m_filestamp;
 585         RWLock* m_lock;
 586     };
 587
 588     /* These helpers attach metadata-derived information as exception properties and then
 589      * rethrow the object. The following properties are attached, when possible:
 590      *
 591      *  providerId          The unique ID of the entity
 592      *  errorURL            The error support URL of the entity or role
 593      *  contactName         A formatted support or technical contact name
 594      *  contactEmail        A contact email address
 595      */
 596     SHIB_EXPORTS void annotateException(saml::SAMLException& e, const IEntityDescriptor* entity, bool rethrow=true);
 597     SHIB_EXPORTS void annotateException(saml::SAMLException& e, const IRoleDescriptor* role, bool rethrow=true);
 598 }
 599
 600 #endif