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         // If certificate validation is required, the trust provider used can be overridden using
 316         // the last parameter, or left null and the provider will rely on itself.
 317         virtual bool validate(
 318             const saml::SAMLSignedObject& token,
 319             const IRoleDescriptor* role,
 320             ITrust* certValidator=NULL
 321             )=0;
 322
 323         virtual ~ITrust() {}
 324     };
 325
 326     // Credentials interface abstracts access to "owned" keys and certificates.
 327
 328     struct SHIB_EXPORTS ICredResolver : public virtual saml::IPlugIn
 329     {
 330         virtual void attach(void* ctx) const=0;
 331         virtual XSECCryptoKey* getKey() const=0;
 332         virtual saml::Iterator<XSECCryptoX509*> getCertificates() const=0;
 333         virtual void dump(FILE* f) const=0;
 334         virtual void dump() const { dump(stdout); }
 335         virtual ~ICredResolver() {}
 336     };
 337
 338     struct SHIB_EXPORTS ICredentials : public virtual saml::ILockable, public virtual saml::IPlugIn
 339     {
 340         virtual const ICredResolver* lookup(const char* id) const=0;
 341         virtual ~ICredentials() {}
 342     };
 343
 344     // Attribute acceptance processing interfaces, applied to incoming attributes.
 345
 346     struct SHIB_EXPORTS IAttributeRule
 347     {
 348         virtual const XMLCh* getName() const=0;
 349         virtual const XMLCh* getNamespace() const=0;
 350         virtual const char* getAlias() const=0;
 351         virtual const char* getHeader() const=0;
 352         virtual bool getCaseSensitive() const=0;
 353         virtual void apply(saml::SAMLAttribute& attribute, const IRoleDescriptor* role=NULL) const=0;
 354         virtual ~IAttributeRule() {}
 355     };
 356
 357     struct SHIB_EXPORTS IAAP : public virtual saml::ILockable, public virtual saml::IPlugIn
 358     {
 359         virtual bool anyAttribute() const=0;
 360         virtual const IAttributeRule* lookup(const XMLCh* attrName, const XMLCh* attrNamespace=NULL) const=0;
 361         virtual const IAttributeRule* lookup(const char* alias) const=0;
 362         virtual saml::Iterator<const IAttributeRule*> getAttributeRules() const=0;
 363         virtual ~IAAP() {}
 364     };
 365
 366 #ifdef SHIB_INSTANTIATE
 367     template class SHIB_EXPORTS saml::Iterator<const IContactPerson*>;
 368     template class SHIB_EXPORTS saml::Iterator<const XENCEncryptionMethod*>;
 369     template class SHIB_EXPORTS saml::Iterator<const IKeyDescriptor*>;
 370     template class SHIB_EXPORTS saml::Iterator<const IAttributeConsumingService*>;
 371     template class SHIB_EXPORTS saml::Iterator<const IRoleDescriptor*>;
 372     template class SHIB_EXPORTS saml::Iterator<const IEntityDescriptor*>;
 373     template class SHIB_EXPORTS saml::Iterator<const IEntitiesDescriptor*>;
 374     template class SHIB_EXPORTS saml::Iterator<const IEndpoint*>;
 375     template class SHIB_EXPORTS saml::Iterator<const IAttributeRule*>;
 376     template class SHIB_EXPORTS saml::Iterator<const IKeyAuthority*>;
 377     template class SHIB_EXPORTS saml::Iterator<DSIGKeyInfoList*>;
 378     template class SHIB_EXPORTS saml::Iterator<IMetadata*>;
 379     template class SHIB_EXPORTS saml::ArrayIterator<IMetadata*>;
 380     template class SHIB_EXPORTS saml::Iterator<ITrust*>;
 381     template class SHIB_EXPORTS saml::ArrayIterator<ITrust*>;
 382     template class SHIB_EXPORTS saml::Iterator<ICredentials*>;
 383     template class SHIB_EXPORTS saml::ArrayIterator<ICredentials*>;
 384     template class SHIB_EXPORTS saml::Iterator<IAAP*>;
 385     template class SHIB_EXPORTS saml::ArrayIterator<IAAP*>;
 386 #endif
 387
 388     struct SHIB_EXPORTS Constants
 389     {
 390         static const XMLCh SHIB_ATTRIBUTE_NAMESPACE_URI[];
 391         static const XMLCh SHIB_NAMEID_FORMAT_URI[];
 392         static const XMLCh SHIB_AUTHNREQUEST_PROFILE_URI[];
 393         static const XMLCh SHIB_LEGACY_AUTHNREQUEST_PROFILE_URI[];
 394         static const XMLCh SHIB_SESSIONINIT_PROFILE_URI[];
 395         static const XMLCh SHIB_LOGOUT_PROFILE_URI[];
 396         static const XMLCh SHIB_NS[];
 397         static const XMLCh InvalidHandle[];
 398     };
 399
 400     // Glue classes between abstract metadata and concrete providers
 401
 402     class SHIB_EXPORTS Metadata
 403     {
 404     public:
 405         Metadata(const saml::Iterator<IMetadata*>& metadatas) : m_metadatas(metadatas), m_mapper(NULL) {}
 406         ~Metadata();
 407
 408         const IEntityDescriptor* lookup(const char* id, bool strict=true);
 409         const IEntityDescriptor* lookup(const XMLCh* id, bool strict=true);
 410         const IEntityDescriptor* lookup(const saml::SAMLArtifact* artifact);
 411
 412     private:
 413         Metadata(const Metadata&);
 414         void operator=(const Metadata&);
 415         IMetadata* m_mapper;
 416         const saml::Iterator<IMetadata*>& m_metadatas;
 417     };
 418
 419     class SHIB_EXPORTS Trust
 420     {
 421     public:
 422         Trust(const saml::Iterator<ITrust*>& trusts) : m_trusts(trusts) {}
 423         ~Trust() {}
 424
 425         bool validate(
 426             void* certEE,
 427             const saml::Iterator<void*>& certChain,
 428             const IRoleDescriptor* role,
 429             bool checkName=true
 430             ) const;
 431         bool validate(const saml::SAMLSignedObject& token, const IRoleDescriptor* role) const;
 432
 433     private:
 434         Trust(const Trust&);
 435         void operator=(const Trust&);
 436         const saml::Iterator<ITrust*>& m_trusts;
 437     };
 438
 439     class SHIB_EXPORTS Credentials
 440     {
 441     public:
 442         Credentials(const saml::Iterator<ICredentials*>& creds) : m_creds(creds), m_mapper(NULL) {}
 443         ~Credentials();
 444
 445         const ICredResolver* lookup(const char* id);
 446
 447     private:
 448         Credentials(const Credentials&);
 449         void operator=(const Credentials&);
 450         ICredentials* m_mapper;
 451         const saml::Iterator<ICredentials*>& m_creds;
 452     };
 453
 454     class SHIB_EXPORTS AAP
 455     {
 456     public:
 457         AAP(const saml::Iterator<IAAP*>& aaps, const XMLCh* attrName, const XMLCh* attrNamespace=NULL);
 458         AAP(const saml::Iterator<IAAP*>& aaps, const char* alias);
 459         ~AAP();
 460         bool fail() const {return m_mapper==NULL;}
 461         const IAttributeRule* operator->() const {return m_rule;}
 462         operator const IAttributeRule*() const {return m_rule;}
 463
 464         static void apply(const saml::Iterator<IAAP*>& aaps, saml::SAMLAssertion& assertion, const IRoleDescriptor* role=NULL);
 465
 466     private:
 467         AAP(const AAP&);
 468         void operator=(const AAP&);
 469         IAAP* m_mapper;
 470         const IAttributeRule* m_rule;
 471     };
 472
 473     // Subclass around the OpenSAML browser profile interface,
 474     // incoporates additional functionality using Shib-defined APIs.
 475     class SHIB_EXPORTS ShibBrowserProfile : virtual public saml::SAMLBrowserProfile
 476     {
 477     public:
 478         ShibBrowserProfile(
 479             const saml::Iterator<IMetadata*>& metadatas=EMPTY(IMetadata*),
 480             const saml::Iterator<ITrust*>& trusts=EMPTY(ITrust*)
 481             );
 482         virtual ~ShibBrowserProfile();
 483
 484         virtual void setVersion(int major, int minor);
 485         virtual saml::SAMLBrowserProfile::BrowserProfileResponse receive(
 486             const char* packet,
 487             const XMLCh* recipient,
 488             int supportedProfiles,
 489             saml::IReplayCache* replayCache=NULL,
 490             saml::SAMLBrowserProfile::ArtifactMapper* callback=NULL
 491             ) const;
 492
 493     private:
 494         saml::SAMLBrowserProfile* m_profile;
 495         saml::Iterator<IMetadata*> m_metadatas;
 496         saml::Iterator<ITrust*> m_trusts;
 497     };
 498
 499     // Instead of wrapping the binding to deal with mutual authentication, we
 500     // just use the HTTP hook functionality offered by OpenSAML. The hook will
 501     // register "itself" as a globalCtx pointer with the SAML binding and the caller
 502     // will declare and pass the embedded struct as callCtx for use by the hook.
 503     class SHIB_EXPORTS ShibHTTPHook : virtual public saml::SAMLSOAPHTTPBinding::HTTPHook
 504     {
 505     public:
 506         ShibHTTPHook(const saml::Iterator<ITrust*>& trusts, const saml::Iterator<ICredentials*>& creds)
 507             : m_trusts(trusts), m_creds(creds) {}
 508         virtual ~ShibHTTPHook() {}
 509
 510         // Only hook we need here is for outgoing connection to server.
 511         virtual bool outgoing(saml::HTTPClient* conn, void* globalCtx=NULL, void* callCtx=NULL);
 512
 513         // Client declares a context object and pass as callCtx to send() method.
 514         class SHIB_EXPORTS ShibHTTPHookCallContext {
 515         public:
 516             ShibHTTPHookCallContext(const char* credResolverId, const IRoleDescriptor* role)
 517                 : m_credResolverId(credResolverId), m_role(role), m_hook(NULL) {}
 518             const ShibHTTPHook* getHook() {return m_hook;}
 519             const char* getCredResolverId() {return m_credResolverId;}
 520             const IRoleDescriptor* getRoleDescriptor() {return m_role;}
 521
 522         private:
 523             const char* m_credResolverId;
 524             const IRoleDescriptor* m_role;
 525             ShibHTTPHook* m_hook;
 526             friend class ShibHTTPHook;
 527         };
 528
 529         const saml::Iterator<ITrust*>& getTrustProviders() const {return m_trusts;}
 530         const saml::Iterator<ICredentials*>& getCredentialProviders() const {return m_creds;}
 531     private:
 532         saml::Iterator<ITrust*> m_trusts;
 533         saml::Iterator<ICredentials*> m_creds;
 534     };
 535
 536     class SHIB_EXPORTS ShibConfig
 537     {
 538     public:
 539         ShibConfig() {}
 540         virtual ~ShibConfig() {}
 541
 542         // global per-process setup and shutdown of Shibboleth runtime
 543         virtual bool init();
 544         virtual void term();
 545
 546         // enables runtime and clients to access configuration
 547         static ShibConfig& getConfig();
 548     };
 549
 550     /* Helper classes for implementing reloadable XML-based config files
 551        The ILockable interface will usually be inherited twice, once as
 552        part of the external interface to clients and once as an implementation
 553        detail of the reloading class below.
 554      */
 555
 556     class SHIB_EXPORTS ReloadableXMLFileImpl
 557     {
 558     public:
 559         ReloadableXMLFileImpl(const char* pathname);
 560         ReloadableXMLFileImpl(const DOMElement* pathname);
 561         virtual ~ReloadableXMLFileImpl();
 562
 563     protected:
 564         DOMDocument* m_doc;
 565         const DOMElement* m_root;
 566     };
 567
 568     class SHIB_EXPORTS ReloadableXMLFile : protected virtual saml::ILockable
 569     {
 570     public:
 571         ReloadableXMLFile(const DOMElement* e);
 572         ~ReloadableXMLFile() { delete m_lock; delete m_impl; }
 573
 574         virtual void lock();
 575         virtual void unlock() { if (m_lock) m_lock->unlock(); }
 576
 577         ReloadableXMLFileImpl* getImplementation() const;
 578
 579     protected:
 580         virtual ReloadableXMLFileImpl* newImplementation(const char* pathname, bool first=true) const=0;
 581         virtual ReloadableXMLFileImpl* newImplementation(const DOMElement* e, bool first=true) const=0;
 582         mutable ReloadableXMLFileImpl* m_impl;
 583
 584     private:
 585         const DOMElement* m_root;
 586         std::string m_source;
 587         time_t m_filestamp;
 588         RWLock* m_lock;
 589     };
 590
 591     /* These helpers attach metadata-derived information as exception properties and then
 592      * rethrow the object. The following properties are attached, when possible:
 593      *
 594      *  providerId          The unique ID of the entity
 595      *  errorURL            The error support URL of the entity or role
 596      *  contactName         A formatted support or technical contact name
 597      *  contactEmail        A contact email address
 598      */
 599     SHIB_EXPORTS void annotateException(saml::SAMLException& e, const IEntityDescriptor* entity, bool rethrow=true);
 600     SHIB_EXPORTS void annotateException(saml::SAMLException& e, const IRoleDescriptor* role, bool rethrow=true);
 601 }
 602
 603 #endif