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