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 <openssl/x509.h>
  64
  65 #ifdef WIN32
  66 # ifndef SHIB_EXPORTS
  67 #  define SHIB_EXPORTS __declspec(dllimport)
  68 # endif
  69 #else
  70 # define SHIB_EXPORTS
  71 #endif
  72
  73 #define SHIB_L(s) shibboleth::XML::Literals::s
  74 #define SHIB_L_QNAME(p,s) shibboleth::XML::Literals::p##_##s
  75
  76 namespace shibboleth
  77 {
  78 #ifdef NO_RTTI
  79   extern SHIB_EXPORTS const unsigned short RTTI_UnsupportedProtocolException;
  80   extern SHIB_EXPORTS const unsigned short RTTI_OriginSiteMapperException;
  81 #endif
  82
  83     #define DECLARE_SHIB_EXCEPTION(name,base) \
  84         class SHIB_EXPORTS name : public saml::base \
  85         { \
  86         public: \
  87             name(const char* msg) : saml::base(msg) {RTTI(name); m_typename=#name;} \
  88             name(const std::string& msg) : saml::base(msg) {RTTI(name); m_typename=#name;} \
  89             name(const saml::Iterator<saml::QName>& codes, const char* msg) : saml::base(codes,msg) {RTTI(name); m_typename=#name;} \
  90             name(const saml::Iterator<saml::QName>& codes, const std::string& msg) : saml::base(codes, msg) {RTTI(name); m_typename=#name;} \
  91             name(const saml::QName& code, const char* msg) : saml::base(code,msg) {RTTI(name); m_typename=#name;} \
  92             name(const saml::QName& code, const std::string& msg) : saml::base(code, msg) {RTTI(name); m_typename=#name;} \
  93             name(DOMElement* e) : saml::base(e) {RTTI(name); m_typename=#name;} \
  94             name(std::istream& in) : saml::base(in) {RTTI(name); m_typename=#name;} \
  95             virtual ~name() throw () {} \
  96         }
  97
  98     DECLARE_SHIB_EXCEPTION(UnsupportedProtocolException,SAMLException);
  99     DECLARE_SHIB_EXCEPTION(MetadataException,SAMLException);
 100
 101     // Metadata abstract interfaces
 102
 103     struct SHIB_EXPORTS IContactInfo
 104     {
 105         enum ContactType { technical, administrative, billing, other };
 106         virtual ContactType getType() const=0;
 107         virtual const char* getName() const=0;
 108         virtual const char* getEmail() const=0;
 109         virtual ~IContactInfo() {}
 110     };
 111
 112     struct SHIB_EXPORTS ISite
 113     {
 114         virtual const XMLCh* getName() const=0;
 115         virtual saml::Iterator<const XMLCh*> getGroups() const=0;
 116         virtual saml::Iterator<const IContactInfo*> getContacts() const=0;
 117         virtual const char* getErrorURL() const=0;
 118         virtual bool validate(saml::Iterator<XSECCryptoX509*> certs) const=0;
 119         virtual bool validate(saml::Iterator<const XMLCh*> certs) const=0;
 120         virtual ~ISite() {}
 121     };
 122
 123     struct SHIB_EXPORTS IAuthority
 124     {
 125         virtual const XMLCh* getName() const=0;
 126         virtual const char* getURL() const=0;
 127         virtual ~IAuthority() {}
 128     };
 129
 130     struct SHIB_EXPORTS IOriginSite : public ISite
 131     {
 132         virtual saml::Iterator<const IAuthority*> getHandleServices() const=0;
 133         virtual saml::Iterator<const IAuthority*> getAttributeAuthorities() const=0;
 134         virtual saml::Iterator<std::pair<const XMLCh*,bool> > getSecurityDomains() const=0;
 135         virtual ~IOriginSite() {}
 136     };
 137
 138     struct SHIB_EXPORTS IMetadata
 139     {
 140         virtual void lock()=0;
 141         virtual void unlock()=0;
 142         virtual const ISite* lookup(const XMLCh* site) const=0;
 143         virtual ~IMetadata() {}
 144     };
 145
 146     struct SHIB_EXPORTS ITrust
 147     {
 148         virtual void lock()=0;
 149         virtual void unlock()=0;
 150         virtual saml::Iterator<XSECCryptoX509*> getCertificates(const XMLCh* subject) const=0;
 151         virtual bool validate(const ISite* site, saml::Iterator<XSECCryptoX509*> certs) const=0;
 152         virtual bool validate(const ISite* site, saml::Iterator<const XMLCh*> certs) const=0;
 153         virtual ~ITrust() {}
 154     };
 155
 156     struct SHIB_EXPORTS IAttributeRule
 157     {
 158         virtual const XMLCh* getName() const=0;
 159         virtual const XMLCh* getNamespace() const=0;
 160         virtual const char* getFactory() const=0;
 161         virtual const char* getAlias() const=0;
 162         virtual const char* getHeader() const=0;
 163         virtual bool accept(const XMLCh* originSite, const DOMElement* e) const=0;
 164         virtual ~IAttributeRule() {}
 165     };
 166
 167     struct SHIB_EXPORTS IAAP
 168     {
 169         virtual void lock()=0;
 170         virtual void unlock()=0;
 171         virtual const IAttributeRule* lookup(const XMLCh* attrName, const XMLCh* attrNamespace=NULL) const=0;
 172         virtual const IAttributeRule* lookup(const char* alias) const=0;
 173         virtual saml::Iterator<const IAttributeRule*> getAttributeRules() const=0;
 174         virtual ~IAAP() {}
 175     };
 176
 177 #ifdef SHIB_INSTANTIATE
 178 # ifdef NO_RTTI
 179     const unsigned short RTTI_UnsupportedProtocolException=     RTTI_EXTENSION_BASE;
 180     const unsigned short RTTI_MetadataException=                RTTI_EXTENSION_BASE+1;
 181 # endif
 182     template class SHIB_EXPORTS saml::Iterator<std::pair<saml::xstring,bool> >;
 183     template class SHIB_EXPORTS saml::ArrayIterator<std::pair<saml::xstring,bool> >;
 184     template class SHIB_EXPORTS saml::Iterator<const IContactInfo*>;
 185     template class SHIB_EXPORTS saml::ArrayIterator<const IContactInfo*>;
 186     template class SHIB_EXPORTS saml::Iterator<const IAuthority*>;
 187     template class SHIB_EXPORTS saml::ArrayIterator<const IAuthority*>;
 188     template class SHIB_EXPORTS saml::Iterator<const IAttributeRule*>;
 189     template class SHIB_EXPORTS saml::ArrayIterator<const IAttributeRule*>;
 190     template class SHIB_EXPORTS saml::Iterator<IMetadata*>;
 191     template class SHIB_EXPORTS saml::ArrayIterator<IMetadata*>;
 192     template class SHIB_EXPORTS saml::Iterator<ITrust*>;
 193     template class SHIB_EXPORTS saml::ArrayIterator<ITrust*>;
 194     template class SHIB_EXPORTS saml::Iterator<IAAP*>;
 195     template class SHIB_EXPORTS saml::ArrayIterator<IAAP*>;
 196 #endif
 197
 198     class SHIB_EXPORTS SimpleAttribute : public saml::SAMLAttribute
 199     {
 200     public:
 201         SimpleAttribute(const XMLCh* name, const XMLCh* ns, long lifetime=0,
 202                         const saml::Iterator<const XMLCh*>& values=EMPTY(const XMLCh*));
 203         SimpleAttribute(DOMElement* e);
 204         virtual saml::SAMLObject* clone() const;
 205         virtual ~SimpleAttribute();
 206
 207     protected:
 208         virtual bool accept(DOMElement* e) const;
 209
 210         const XMLCh* m_originSite;
 211     };
 212
 213     class SHIB_EXPORTS ScopedAttribute : public SimpleAttribute
 214     {
 215     public:
 216         ScopedAttribute(const XMLCh* name, const XMLCh* ns, long lifetime=0,
 217                         const saml::Iterator<const XMLCh*>& scopes=EMPTY(const XMLCh*),
 218                         const saml::Iterator<const XMLCh*>& values=EMPTY(const XMLCh*));
 219         ScopedAttribute(DOMElement* e);
 220         virtual ~ScopedAttribute();
 221
 222         virtual DOMNode* toDOM(DOMDocument* doc=NULL, bool xmlns=true) const;
 223         virtual saml::SAMLObject* clone() const;
 224
 225         virtual saml::Iterator<saml::xstring> getValues() const;
 226         virtual saml::Iterator<std::string> getSingleByteValues() const;
 227
 228     protected:
 229         virtual bool addValue(DOMElement* e);
 230
 231         std::vector<saml::xstring> m_scopes;
 232         mutable std::vector<saml::xstring> m_scopedValues;
 233     };
 234
 235     class SHIB_EXPORTS ShibPOSTProfile
 236     {
 237     public:
 238         ShibPOSTProfile(const saml::Iterator<const XMLCh*>& policies, const XMLCh* receiver, int ttlSeconds);
 239         ShibPOSTProfile(const saml::Iterator<const XMLCh*>& policies, const XMLCh* issuer);
 240         virtual ~ShibPOSTProfile();
 241
 242         virtual const saml::SAMLAssertion* getSSOAssertion(const saml::SAMLResponse& r);
 243         virtual const saml::SAMLAuthenticationStatement* getSSOStatement(const saml::SAMLAssertion& a);
 244         virtual saml::SAMLResponse* accept(const XMLByte* buf, XMLCh** originSitePtr=NULL);
 245         virtual saml::SAMLResponse* prepare(
 246             const XMLCh* recipient,
 247             const XMLCh* name,
 248             const XMLCh* nameQualifier,
 249             const XMLCh* subjectIP,
 250             const XMLCh* authMethod,
 251             time_t authInstant,
 252             const saml::Iterator<saml::SAMLAuthorityBinding*>& bindings,
 253             XSECCryptoKey* responseKey,
 254             const saml::Iterator<XSECCryptoX509*>& responseCerts=EMPTY(XSECCryptoX509*),
 255             XSECCryptoKey* assertionKey=NULL,
 256             const saml::Iterator<XSECCryptoX509*>& assertionCerts=EMPTY(XSECCryptoX509*)
 257             );
 258         virtual bool checkReplayCache(const saml::SAMLAssertion& a);
 259
 260         virtual const XMLCh* getOriginSite(const saml::SAMLResponse& r);
 261
 262     protected:
 263         virtual void verifySignature(
 264             const saml::SAMLSignedObject& obj,
 265             const IOriginSite* originSite,
 266             const XMLCh* signerName,
 267             XSECCryptoKey* knownKey=NULL);
 268
 269         signatureMethod m_algorithm;
 270         std::vector<const XMLCh*> m_policies;
 271         XMLCh* m_issuer;
 272         XMLCh* m_receiver;
 273         int m_ttlSeconds;
 274
 275     private:
 276         ShibPOSTProfile(const ShibPOSTProfile&) {}
 277         ShibPOSTProfile& operator=(const ShibPOSTProfile&) {return *this;}
 278     };
 279
 280     class SHIB_EXPORTS ClubShibPOSTProfile : public ShibPOSTProfile
 281     {
 282     public:
 283         ClubShibPOSTProfile(const saml::Iterator<const XMLCh*>& policies, const XMLCh* receiver, int ttlSeconds);
 284         ClubShibPOSTProfile(const saml::Iterator<const XMLCh*>& policies, const XMLCh* issuer);
 285         virtual ~ClubShibPOSTProfile();
 286
 287         virtual saml::SAMLResponse* prepare(
 288             const XMLCh* recipient,
 289             const XMLCh* name,
 290             const XMLCh* nameQualifier,
 291             const XMLCh* subjectIP,
 292             const XMLCh* authMethod,
 293             time_t authInstant,
 294             const saml::Iterator<saml::SAMLAuthorityBinding*>& bindings,
 295             XSECCryptoKey* responseKey,
 296             const saml::Iterator<XSECCryptoX509*>& responseCerts=EMPTY(XSECCryptoX509*),
 297             XSECCryptoKey* assertionKey=NULL,
 298             const saml::Iterator<XSECCryptoX509*>& assertionCerts=EMPTY(XSECCryptoX509*)
 299             );
 300
 301     protected:
 302         virtual void verifySignature(
 303             const saml::SAMLSignedObject& obj,
 304             const IOriginSite* originSite,
 305             const XMLCh* signerName,
 306             XSECCryptoKey* knownKey=NULL);
 307     };
 308
 309     class SHIB_EXPORTS ShibPOSTProfileFactory
 310     {
 311     public:
 312         static ShibPOSTProfile* getInstance(const saml::Iterator<const XMLCh*>& policies, const XMLCh* receiver, int ttlSeconds);
 313         static ShibPOSTProfile* getInstance(const saml::Iterator<const XMLCh*>& policies, const XMLCh* issuer);
 314     };
 315
 316     // Glue classes between abstract metadata and concrete providers
 317
 318     class SHIB_EXPORTS OriginMetadata
 319     {
 320     public:
 321         OriginMetadata(const XMLCh* site);
 322         ~OriginMetadata();
 323         bool fail() const {return m_mapper==NULL;}
 324         const IOriginSite* operator->() const {return m_site;}
 325         operator const IOriginSite*() const {return m_site;}
 326
 327     private:
 328         OriginMetadata(const OriginMetadata&);
 329         void operator=(const OriginMetadata&);
 330         IMetadata* m_mapper;
 331         const IOriginSite* m_site;
 332     };
 333
 334     class SHIB_EXPORTS Trust
 335     {
 336     public:
 337         Trust() : m_mapper(NULL) {}
 338         ~Trust();
 339         saml::Iterator<XSECCryptoX509*> getCertificates(const XMLCh* subject);
 340         bool validate(const ISite* site, saml::Iterator<XSECCryptoX509*> certs) const;
 341         bool validate(const ISite* site, saml::Iterator<const XMLCh*> certs) const;
 342
 343     private:
 344         Trust(const Trust&);
 345         void operator=(const Trust&);
 346         ITrust* m_mapper;
 347     };
 348
 349     class SHIB_EXPORTS AAP
 350     {
 351     public:
 352         AAP(const XMLCh* attrName, const XMLCh* attrNamespace=NULL);
 353         AAP(const char* alias);
 354         ~AAP();
 355         bool fail() const {return m_mapper==NULL;}
 356         const IAttributeRule* operator->() const {return m_rule;}
 357         operator const IAttributeRule*() const {return m_rule;}
 358
 359     private:
 360         AAP(const AAP&);
 361         void operator=(const AAP&);
 362         IAAP* m_mapper;
 363         const IAttributeRule* m_rule;
 364     };
 365
 366     extern "C" { typedef IMetadata* MetadataFactory(const char* source); }
 367     extern "C" { typedef ITrust* TrustFactory(const char* source); }
 368     extern "C" { typedef IAAP* AAPFactory(const char* source); }
 369
 370     class SHIB_EXPORTS ShibConfig
 371     {
 372     public:
 373         ShibConfig() {}
 374         virtual ~ShibConfig();
 375
 376         // global per-process setup and shutdown of Shibboleth runtime
 377         virtual bool init()=0;
 378         virtual void term()=0;
 379
 380         // enables runtime and clients to access configuration
 381         static ShibConfig& getConfig();
 382
 383         // allows pluggable implementations of metadata
 384         virtual void regFactory(const char* type, MetadataFactory* factory)=0;
 385         virtual void regFactory(const char* type, TrustFactory* factory)=0;
 386         virtual void regFactory(const char* type, AAPFactory* factory)=0;
 387         virtual void unregFactory(const char* type)=0;
 388
 389         // builds a specific metadata lookup object
 390         virtual bool addMetadata(const char* type, const char* source)=0;
 391
 392         virtual saml::Iterator<IMetadata*> getMetadataProviders() const=0;
 393         virtual saml::Iterator<ITrust*> getTrustProviders() const=0;
 394         virtual saml::Iterator<IAAP*> getAAPProviders() const=0;
 395     };
 396
 397     struct SHIB_EXPORTS Constants
 398     {
 399         static const XMLCh SHIB_ATTRIBUTE_NAMESPACE_URI[];
 400         static const XMLCh SHIB_NAMEID_FORMAT_URI[];
 401         static saml::QName SHIB_ATTRIBUTE_VALUE_TYPE;
 402     };
 403
 404     class SHIB_EXPORTS XML
 405     {
 406     public:
 407         // URI constants
 408         static const XMLCh SHIB_NS[];
 409         static const XMLCh SHIB_SCHEMA_ID[];
 410
 411         struct SHIB_EXPORTS Literals
 412         {
 413             // Shibboleth vocabulary
 414             static const XMLCh AttributeValueType[];
 415
 416             static const XMLCh Scope[];
 417
 418             static const XMLCh AttributeAuthority[];
 419             static const XMLCh Contact[];
 420             static const XMLCh Domain[];
 421             static const XMLCh Email[];
 422             static const XMLCh ErrorURL[];
 423             static const XMLCh HandleService[];
 424             static const XMLCh InvalidHandle[];
 425             static const XMLCh Location[];
 426             static const XMLCh Name[];
 427             static const XMLCh OriginSite[];
 428             static const XMLCh SiteGroup[];
 429
 430             static const XMLCh KeyAuthority[];
 431             static const XMLCh Trust[];
 432
 433             static const XMLCh Accept[];
 434             static const XMLCh Alias[];
 435             static const XMLCh AnySite[];
 436             static const XMLCh AnyValue[];
 437             static const XMLCh AttributeAcceptancePolicy[];
 438             static const XMLCh AttributeRule[];
 439             static const XMLCh Factory[];
 440             static const XMLCh Header[];
 441             static const XMLCh Namespace[];
 442             static const XMLCh SiteRule[];
 443             static const XMLCh Type[];
 444             static const XMLCh Value[];
 445
 446             static const XMLCh literal[];
 447             static const XMLCh regexp[];
 448             static const XMLCh xpath[];
 449
 450             static const XMLCh technical[];
 451             static const XMLCh administrative[];
 452             static const XMLCh billing[];
 453             static const XMLCh other[];
 454
 455             // XML vocabulary
 456             static const XMLCh xmlns_shib[];
 457         };
 458     };
 459
 460
 461     class SHIB_EXPORTS SAMLBindingFactory
 462     {
 463     public:
 464         static saml::SAMLBinding* getInstance(const XMLCh* protocol=saml::SAMLBinding::SAML_SOAP_HTTPS);
 465     };
 466
 467     // OpenSSL Utilities
 468
 469     // Log errors from OpenSSL error queue.
 470     void log_openssl();
 471
 472     // build an OpenSSL cert out of a base-64 encoded DER buffer (XML style)
 473     X509* B64_to_X509(const char* buf);
 474 }
 475
 476 #endif