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/ssl.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     #define DECLARE_SHIB_EXCEPTION(name,base) \
  79         class SHIB_EXPORTS name : public saml::base \
  80         { \
  81         public: \
  82             name(const char* msg) : saml::base(msg) {RTTI(name);} \
  83             name(const std::string& msg) : saml::base(msg) {RTTI(name);} \
  84             name(const saml::Iterator<saml::QName>& codes, const char* msg) : saml::base(codes,msg) {RTTI(name);} \
  85             name(const saml::Iterator<saml::QName>& codes, const std::string& msg) : saml::base(codes, msg) {RTTI(name);} \
  86             name(const saml::QName& code, const char* msg) : saml::base(code,msg) {RTTI(name);} \
  87             name(const saml::QName& code, const std::string& msg) : saml::base(code, msg) {RTTI(name);} \
  88             name(DOMElement* e) : saml::base(e) {RTTI(name);} \
  89             name(std::istream& in) : saml::base(in) {RTTI(name);} \
  90             virtual ~name() throw () {} \
  91         }
  92
  93     DECLARE_SHIB_EXCEPTION(UnsupportedProtocolException,SAMLException);
  94     DECLARE_SHIB_EXCEPTION(MetadataException,SAMLException);
  95
  96     // Metadata abstract interfaces
  97
  98     struct SHIB_EXPORTS IContactInfo
  99     {
 100         enum ContactType { technical, administrative, billing, other };
 101         virtual ContactType getType() const=0;
 102         virtual const char* getName() const=0;
 103         virtual const char* getEmail() const=0;
 104         virtual ~IContactInfo() {}
 105     };
 106
 107     struct SHIB_EXPORTS ISite
 108     {
 109         virtual const XMLCh* getName() const=0;
 110         virtual saml::Iterator<const XMLCh*> getGroups() const=0;
 111         virtual saml::Iterator<const IContactInfo*> getContacts() const=0;
 112         virtual const char* getErrorURL() const=0;
 113         virtual bool validate(saml::Iterator<XSECCryptoX509*> certs) const=0;
 114         virtual bool validate(saml::Iterator<const XMLCh*> certs) const=0;
 115         virtual ~ISite() {}
 116     };
 117
 118     struct SHIB_EXPORTS IAuthority
 119     {
 120         virtual const XMLCh* getName() const=0;
 121         virtual const char* getURL() const=0;
 122         virtual ~IAuthority() {}
 123     };
 124
 125     struct SHIB_EXPORTS IOriginSite : public ISite
 126     {
 127         virtual saml::Iterator<const IAuthority*> getHandleServices() const=0;
 128         virtual saml::Iterator<const IAuthority*> getAttributeAuthorities() const=0;
 129         virtual saml::Iterator<std::pair<const XMLCh*,bool> > getSecurityDomains() const=0;
 130         virtual ~IOriginSite() {}
 131     };
 132
 133     struct SHIB_EXPORTS IMetadata
 134     {
 135         virtual void lock()=0;
 136         virtual void unlock()=0;
 137         virtual const ISite* lookup(const XMLCh* site) const=0;
 138         virtual ~IMetadata() {}
 139     };
 140
 141     struct SHIB_EXPORTS ITrust
 142     {
 143         virtual void lock()=0;
 144         virtual void unlock()=0;
 145         virtual saml::Iterator<XSECCryptoX509*> getCertificates(const XMLCh* subject) const=0;
 146         virtual bool validate(const ISite* site, saml::Iterator<XSECCryptoX509*> certs) const=0;
 147         virtual bool validate(const ISite* site, saml::Iterator<const XMLCh*> certs) const=0;
 148         virtual bool attach(const ISite* site, SSL_CTX* ctx) const=0;
 149         virtual ~ITrust() {}
 150     };
 151
 152     struct SHIB_EXPORTS ICredentials
 153     {
 154         virtual void lock()=0;
 155         virtual void unlock()=0;
 156         virtual bool attach(const XMLCh* subject, const ISite* relyingParty, SSL_CTX* ctx) const=0;
 157         virtual ~ICredentials() {}
 158     };
 159
 160     struct SHIB_EXPORTS ICredResolver
 161     {
 162         virtual void resolveKey(SSL_CTX* ctx) const=0;
 163         virtual void resolveCert(SSL_CTX* ctx) const=0;
 164         virtual void dump(FILE* f) const=0;
 165         virtual void dump() const { dump(stdout); }
 166         virtual ~ICredResolver() {}
 167     };
 168
 169     struct SHIB_EXPORTS IAttributeRule
 170     {
 171         virtual const XMLCh* getName() const=0;
 172         virtual const XMLCh* getNamespace() const=0;
 173         virtual const char* getFactory() const=0;
 174         virtual const char* getAlias() const=0;
 175         virtual const char* getHeader() const=0;
 176         virtual bool accept(const XMLCh* originSite, const DOMElement* e) const=0;
 177         virtual ~IAttributeRule() {}
 178     };
 179
 180     struct SHIB_EXPORTS IAAP
 181     {
 182         virtual void lock()=0;
 183         virtual void unlock()=0;
 184         virtual const IAttributeRule* lookup(const XMLCh* attrName, const XMLCh* attrNamespace=NULL) const=0;
 185         virtual const IAttributeRule* lookup(const char* alias) const=0;
 186         virtual saml::Iterator<const IAttributeRule*> getAttributeRules() const=0;
 187         virtual ~IAAP() {}
 188     };
 189
 190 #ifdef SHIB_INSTANTIATE
 191     template class SHIB_EXPORTS saml::Iterator<const IContactInfo*>;
 192     template class SHIB_EXPORTS saml::ArrayIterator<const IContactInfo*>;
 193     template class SHIB_EXPORTS saml::Iterator<const IAuthority*>;
 194     template class SHIB_EXPORTS saml::ArrayIterator<const IAuthority*>;
 195     template class SHIB_EXPORTS saml::Iterator<const IAttributeRule*>;
 196     template class SHIB_EXPORTS saml::ArrayIterator<const IAttributeRule*>;
 197     template class SHIB_EXPORTS saml::Iterator<IMetadata*>;
 198     template class SHIB_EXPORTS saml::ArrayIterator<IMetadata*>;
 199     template class SHIB_EXPORTS saml::Iterator<ITrust*>;
 200     template class SHIB_EXPORTS saml::ArrayIterator<ITrust*>;
 201     template class SHIB_EXPORTS saml::Iterator<ICredentials*>;
 202     template class SHIB_EXPORTS saml::ArrayIterator<ICredentials*>;
 203     template class SHIB_EXPORTS saml::Iterator<IAAP*>;
 204     template class SHIB_EXPORTS saml::ArrayIterator<IAAP*>;
 205 #endif
 206
 207     class SHIB_EXPORTS SimpleAttribute : public saml::SAMLAttribute
 208     {
 209     public:
 210         SimpleAttribute(const XMLCh* name, const XMLCh* ns, long lifetime=0,
 211                         const saml::Iterator<const XMLCh*>& values=EMPTY(const XMLCh*));
 212         SimpleAttribute(DOMElement* e);
 213         virtual saml::SAMLObject* clone() const;
 214         virtual ~SimpleAttribute();
 215
 216     protected:
 217         virtual bool accept(DOMElement* e) const;
 218
 219         const XMLCh* m_originSite;
 220     };
 221
 222     class SHIB_EXPORTS ScopedAttribute : public SimpleAttribute
 223     {
 224     public:
 225         ScopedAttribute(const XMLCh* name, const XMLCh* ns, long lifetime=0,
 226                         const saml::Iterator<const XMLCh*>& scopes=EMPTY(const XMLCh*),
 227                         const saml::Iterator<const XMLCh*>& values=EMPTY(const XMLCh*));
 228         ScopedAttribute(DOMElement* e);
 229         virtual ~ScopedAttribute();
 230
 231         virtual DOMNode* toDOM(DOMDocument* doc=NULL, bool xmlns=true) const;
 232         virtual saml::SAMLObject* clone() const;
 233
 234         virtual saml::Iterator<const XMLCh*> getValues() const;
 235         virtual saml::Iterator<std::string> getSingleByteValues() const;
 236
 237     protected:
 238         virtual bool addValue(DOMElement* e);
 239
 240         std::vector<const XMLCh*> m_scopes;
 241         mutable std::vector<const XMLCh*> m_scopedValues;
 242     };
 243
 244     class SHIB_EXPORTS ShibPOSTProfile
 245     {
 246     public:
 247         ShibPOSTProfile(const saml::Iterator<const XMLCh*>& policies, const XMLCh* receiver, int ttlSeconds);
 248         ShibPOSTProfile(const saml::Iterator<const XMLCh*>& policies, const XMLCh* issuer);
 249         virtual ~ShibPOSTProfile();
 250
 251         virtual const saml::SAMLAssertion* getSSOAssertion(const saml::SAMLResponse& r);
 252         virtual const saml::SAMLAuthenticationStatement* getSSOStatement(const saml::SAMLAssertion& a);
 253         virtual saml::SAMLResponse* accept(const XMLByte* buf, XMLCh** originSitePtr=NULL);
 254         virtual saml::SAMLResponse* prepare(
 255             const XMLCh* recipient,
 256             const XMLCh* name,
 257             const XMLCh* nameQualifier,
 258             const XMLCh* subjectIP,
 259             const XMLCh* authMethod,
 260             time_t authInstant,
 261             const saml::Iterator<saml::SAMLAuthorityBinding*>& bindings,
 262             XSECCryptoKey* responseKey,
 263             const saml::Iterator<XSECCryptoX509*>& responseCerts=EMPTY(XSECCryptoX509*),
 264             XSECCryptoKey* assertionKey=NULL,
 265             const saml::Iterator<XSECCryptoX509*>& assertionCerts=EMPTY(XSECCryptoX509*)
 266             );
 267         virtual bool checkReplayCache(const saml::SAMLAssertion& a);
 268
 269         virtual const XMLCh* getOriginSite(const saml::SAMLResponse& r);
 270
 271     protected:
 272         virtual void verifySignature(
 273             const saml::SAMLSignedObject& obj,
 274             const IOriginSite* originSite,
 275             const XMLCh* signerName,
 276             XSECCryptoKey* knownKey=NULL);
 277
 278         signatureMethod m_algorithm;
 279         std::vector<const XMLCh*> m_policies;
 280         XMLCh* m_issuer;
 281         XMLCh* m_receiver;
 282         int m_ttlSeconds;
 283
 284     private:
 285         ShibPOSTProfile(const ShibPOSTProfile&) {}
 286         ShibPOSTProfile& operator=(const ShibPOSTProfile&) {return *this;}
 287     };
 288
 289     class SHIB_EXPORTS ShibPOSTProfileFactory
 290     {
 291     public:
 292         static ShibPOSTProfile* getInstance(const saml::Iterator<const XMLCh*>& policies, const XMLCh* receiver, int ttlSeconds);
 293         static ShibPOSTProfile* getInstance(const saml::Iterator<const XMLCh*>& policies, const XMLCh* issuer);
 294     };
 295
 296     // Glue classes between abstract metadata and concrete providers
 297
 298     class SHIB_EXPORTS OriginMetadata
 299     {
 300     public:
 301         OriginMetadata(const XMLCh* site);
 302         ~OriginMetadata();
 303         bool fail() const {return m_mapper==NULL;}
 304         const IOriginSite* operator->() const {return m_site;}
 305         operator const IOriginSite*() const {return m_site;}
 306
 307     private:
 308         OriginMetadata(const OriginMetadata&);
 309         void operator=(const OriginMetadata&);
 310         IMetadata* m_mapper;
 311         const IOriginSite* m_site;
 312     };
 313
 314     class SHIB_EXPORTS Trust
 315     {
 316     public:
 317         Trust() : m_mapper(NULL) {}
 318         ~Trust();
 319         saml::Iterator<XSECCryptoX509*> getCertificates(const XMLCh* subject);
 320         bool validate(const ISite* site, saml::Iterator<XSECCryptoX509*> certs) const;
 321         bool validate(const ISite* site, saml::Iterator<const XMLCh*> certs) const;
 322         bool attach(const ISite* site, SSL_CTX* ctx) const;
 323
 324     private:
 325         Trust(const Trust&);
 326         void operator=(const Trust&);
 327         ITrust* m_mapper;
 328     };
 329
 330     class SHIB_EXPORTS Credentials
 331     {
 332     public:
 333         static bool attach(const XMLCh* subject, const ISite* relyingParty, SSL_CTX* ctx);
 334     };
 335
 336     class SHIB_EXPORTS AAP
 337     {
 338     public:
 339         AAP(const XMLCh* attrName, const XMLCh* attrNamespace=NULL);
 340         AAP(const char* alias);
 341         ~AAP();
 342         bool fail() const {return m_mapper==NULL;}
 343         const IAttributeRule* operator->() const {return m_rule;}
 344         operator const IAttributeRule*() const {return m_rule;}
 345
 346     private:
 347         AAP(const AAP&);
 348         void operator=(const AAP&);
 349         IAAP* m_mapper;
 350         const IAttributeRule* m_rule;
 351     };
 352
 353     extern "C" {
 354         typedef IMetadata* MetadataFactory(const char* source);
 355         typedef ITrust* TrustFactory(const char* source);
 356         typedef ICredentials* CredentialsFactory(const char* source);
 357         typedef ICredResolver* CredResolverFactory(const DOMElement* e);
 358         typedef IAAP* AAPFactory(const char* source);
 359     }
 360
 361     class SHIB_EXPORTS ShibConfig
 362     {
 363     public:
 364         ShibConfig() {}
 365         virtual ~ShibConfig();
 366
 367         // global per-process setup and shutdown of Shibboleth runtime
 368         virtual bool init()=0;
 369         virtual void term()=0;
 370
 371         // enables runtime and clients to access configuration
 372         static ShibConfig& getConfig();
 373
 374         // allows pluggable implementations of metadata
 375         virtual void regFactory(const char* type, MetadataFactory* factory)=0;
 376         virtual void regFactory(const char* type, TrustFactory* factory)=0;
 377         virtual void regFactory(const char* type, CredentialsFactory* factory)=0;
 378         virtual void regFactory(const char* type, CredResolverFactory* factory)=0;
 379         virtual void regFactory(const char* type, AAPFactory* factory)=0;
 380         virtual void regFactory(const char* type, saml::SAMLAttributeFactory* factory)=0;
 381         virtual void unregFactory(const char* type)=0;
 382
 383         // builds a specific metadata lookup object
 384         virtual bool addMetadata(const char* type, const char* source)=0;
 385
 386         virtual saml::Iterator<IMetadata*> getMetadataProviders() const=0;
 387         virtual saml::Iterator<ITrust*> getTrustProviders() const=0;
 388         virtual saml::Iterator<ICredentials*> getCredentialProviders() const=0;
 389         virtual CredResolverFactory* getCredResolverFactory(const char* type) const=0;
 390         virtual saml::Iterator<IAAP*> getAAPProviders() const=0;
 391         virtual saml::SAMLAttributeFactory* getAttributeFactory(const char* type) const=0;
 392     };
 393
 394     struct SHIB_EXPORTS Constants
 395     {
 396         static const XMLCh SHIB_ATTRIBUTE_NAMESPACE_URI[];
 397         static const XMLCh SHIB_NAMEID_FORMAT_URI[];
 398
 399         static const XMLCh XMLSIG_RETMETHOD_RAWX509[];  // DER X.509 defined by xmlsig
 400
 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 CertificateRef[];
 431             static const XMLCh Class[];
 432             static const XMLCh Credentials[];
 433             static const XMLCh CustomCredResolver[];
 434             static const XMLCh Exponent[];
 435             static const XMLCh FileCredResolver[];
 436             static const XMLCh Id[];
 437             static const XMLCh KeyAuthority[];
 438             static const XMLCh KeyRef[];
 439             static const XMLCh KeyUse[];
 440             static const XMLCh Modulus[];
 441             static const XMLCh Password[];
 442             static const XMLCh Path[];
 443             static const XMLCh RelyingParty[];
 444             static const XMLCh RetrievalMethod[];
 445             static const XMLCh RSAKeyValue[];
 446             static const XMLCh Trust[];
 447             static const XMLCh URI[];
 448             static const XMLCh VerifyDepth[];
 449
 450             static const XMLCh Accept[];
 451             static const XMLCh Alias[];
 452             static const XMLCh AnySite[];
 453             static const XMLCh AnyValue[];
 454             static const XMLCh AttributeAcceptancePolicy[];
 455             static const XMLCh AttributeRule[];
 456             static const XMLCh Factory[];
 457             static const XMLCh Header[];
 458             static const XMLCh Namespace[];
 459             static const XMLCh SiteRule[];
 460             static const XMLCh Type[];
 461             static const XMLCh Value[];
 462
 463             static const XMLCh literal[];
 464             static const XMLCh regexp[];
 465             static const XMLCh xpath[];
 466
 467             static const XMLCh technical[];
 468             static const XMLCh administrative[];
 469             static const XMLCh billing[];
 470             static const XMLCh other[];
 471
 472             // XML vocabulary
 473             static const XMLCh xmlns_shib[];
 474         };
 475     };
 476
 477     class SHIB_EXPORTS SAMLBindingFactory
 478     {
 479     public:
 480         static saml::SAMLBinding* getInstance(
 481             const XMLCh* subject,
 482             const ISite* relyingParty,
 483             const XMLCh* protocol=saml::SAMLBinding::SAML_SOAP_HTTPS);
 484     };
 485 }
 486
 487 #endif