shib-target/shib-target.h

   1 /*
   2  *  Copyright 2001-2007 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /*
  18  * shib-target.h -- top-level header file for the SHIB Common Target Library
  19  *
  20  * Created by:  Derek Atkins <derek@ihtfp.com>
  21  *
  22  * $Id$
  23  */
  24
  25 #ifndef SHIB_TARGET_H
  26 #define SHIB_TARGET_H
  27
  28 // New headers
  29 #include <shibsp/Application.h>
  30 #include <shibsp/Handler.h>
  31 #include <shibsp/RequestMapper.h>
  32 #include <shibsp/ServiceProvider.h>
  33 #include <shibsp/SessionCache.h>
  34 #include <shibsp/remoting/ListenerService.h>
  35
  36 // Old headers
  37 #include <saml/saml.h>
  38 #include <shib/shib.h>
  39
  40 #ifdef WIN32
  41 # ifndef SHIBTARGET_EXPORTS
  42 #  define SHIBTARGET_EXPORTS __declspec(dllimport)
  43 # endif
  44 # define SHIB_SCHEMAS "/opt/shibboleth-sp/share/xml/shibboleth"
  45 # define SHIB_CONFIG "/opt/shibboleth-sp/etc/shibboleth/shibboleth.xml"
  46 #else
  47 # include <shib-target/shib-paths.h>
  48 # define SHIBTARGET_EXPORTS
  49 #endif
  50
  51 namespace shibtarget {
  52
  53     // Abstract APIs for access to configuration information
  54
  55     /**
  56      * Interface to Shibboleth Applications, which exposes most of the functionality
  57      * required to process web requests or security protocol messages for resources
  58      * associated with them.
  59      *
  60      * Applications are implementation-specific, but generally correspond to collections
  61      * of resources related to one another in logical ways, such as a virtual host or
  62      * a Java servlet context. Most complex configuration data is associated with an
  63      * Application. Implementations should always expose an application named "default"
  64      * as a last resort.
  65      */
  66     struct SHIBTARGET_EXPORTS IApplication : public virtual shibsp::Application,
  67         public virtual shibboleth::ShibBrowserProfile::ITokenValidator
  68     {
  69         // caller is borrowing object, must use within scope of config lock
  70         virtual const saml::SAMLBrowserProfile* getBrowserProfile() const=0;
  71         virtual const saml::SAMLBinding* getBinding(const XMLCh* binding) const=0;
  72
  73         // caller is given ownership of object, must use and delete within scope of config lock
  74         virtual saml::SAMLBrowserProfile::ArtifactMapper* getArtifactMapper() const=0;
  75
  76         // general token validation based on conditions, signatures, etc.
  77         virtual void validateToken(
  78             saml::SAMLAssertion* token,
  79             time_t t=0,
  80             const opensaml::saml2md::RoleDescriptor* role=NULL,
  81             const xmltooling::TrustEngine* trust=NULL
  82             ) const=0;
  83
  84         virtual ~IApplication() {}
  85     };
  86
  87     /**
  88      * OpenSAML binding hook
  89      *
  90      * Instead of wrapping the binding to deal with mutual authentication, we
  91      * just use the HTTP hook functionality offered by OpenSAML. The hook will
  92      * register "itself" as a globalCtx pointer with the SAML binding and the caller
  93      * will declare and pass the embedded struct as callCtx for use by the hook.
  94      */
  95     class ShibHTTPHook : virtual public saml::SAMLSOAPHTTPBinding::HTTPHook
  96     {
  97     public:
  98         ShibHTTPHook(const xmltooling::TrustEngine* trust) : m_trust(trust) {}
  99         virtual ~ShibHTTPHook() {}
 100
 101         // Only hook we need here is for outgoing connection to server.
 102         virtual bool outgoing(saml::HTTPClient* conn, void* globalCtx=NULL, void* callCtx=NULL);
 103
 104         // Client declares a context object and pass as callCtx to send() method.
 105         class ShibHTTPHookCallContext {
 106         public:
 107             ShibHTTPHookCallContext(const shibsp::PropertySet* credUse, const opensaml::saml2md::RoleDescriptor* role)
 108                 : m_credUse(credUse), m_role(role), m_hook(NULL), m_authenticated(false) {}
 109             const ShibHTTPHook* getHook() {return m_hook;}
 110             const shibsp::PropertySet* getCredentialUse() {return m_credUse;}
 111             const opensaml::saml2md::RoleDescriptor* getRoleDescriptor() {return m_role;}
 112             bool isAuthenticated() const {return m_authenticated;}
 113             void setAuthenticated() {m_authenticated=true;}
 114
 115         private:
 116             const shibsp::PropertySet* m_credUse;
 117             const opensaml::saml2md::RoleDescriptor* m_role;
 118             ShibHTTPHook* m_hook;
 119             bool m_authenticated;
 120             friend class ShibHTTPHook;
 121         };
 122
 123         const xmltooling::TrustEngine* getTrustEngine() const {return m_trust;}
 124     private:
 125         const xmltooling::TrustEngine* m_trust;
 126     };
 127
 128     /**
 129      * Interface to a cached user session.
 130      *
 131      * Cache entries provide implementations with access to the raw SAML information they
 132      * need to publish or provide access to the data for applications to use. All creation
 133      * or access to entries is through the ISessionCache interface, and callers must unlock
 134      * the entry when finished using it, rather than explicitly freeing them.
 135      */
 136     struct SHIBTARGET_EXPORTS ISessionCacheEntry : public virtual saml::ILockable
 137     {
 138         virtual const char* getClientAddress() const=0;
 139         virtual const char* getProviderId() const=0;
 140         virtual std::pair<const char*,const saml::SAMLSubject*> getSubject(bool xml=true, bool obj=false) const=0;
 141         virtual const char* getAuthnContext() const=0;
 142         virtual std::pair<const char*,const saml::SAMLResponse*> getTokens(bool xml=true, bool obj=false) const=0;
 143         virtual std::pair<const char*,const saml::SAMLResponse*> getFilteredTokens(bool xml=true, bool obj=false) const=0;
 144         virtual ~ISessionCacheEntry() {}
 145     };
 146
 147     /**
 148      * Interface to a sink for session cache events.
 149      *
 150      * All caches support registration of a backing store that can be informed
 151      * of significant events in the lifecycle of a cache entry.
 152      */
 153     struct SHIBTARGET_EXPORTS ISessionCacheStore
 154     {
 155         virtual HRESULT onCreate(
 156             const char* key,
 157             const IApplication* application,
 158             const ISessionCacheEntry* entry,
 159             int majorVersion,
 160             int minorVersion,
 161             time_t created
 162             )=0;
 163         virtual HRESULT onRead(
 164             const char* key,
 165             std::string& applicationId,
 166             std::string& clientAddress,
 167             std::string& providerId,
 168             std::string& subject,
 169             std::string& authnContext,
 170             std::string& tokens,
 171             int& majorVersion,
 172             int& minorVersion,
 173             time_t& created,
 174             time_t& accessed
 175             )=0;
 176         virtual HRESULT onRead(const char* key, time_t& accessed)=0;
 177         virtual HRESULT onRead(const char* key, std::string& tokens)=0;
 178         virtual HRESULT onUpdate(const char* key, const char* tokens=NULL, time_t lastAccess=0)=0;
 179         virtual HRESULT onDelete(const char* key)=0;
 180         virtual ~ISessionCacheStore() {}
 181     };
 182
 183     /**
 184      * Interface to the session cache.
 185      *
 186      * The session cache abstracts a persistent (meaning across requests) cache of
 187      * instances of the ISessionCacheEntry interface. Creation of new entries and entry
 188      * lookup are confined to this interface to enable implementations to flexibly
 189      * remote and/or optimize calls by implementing custom versions of the
 190      * ISessionCacheEntry interface as required.
 191      */
 192     struct SHIBTARGET_EXPORTS ISessionCache : virtual public shibsp::SessionCache
 193     {
 194         virtual std::string insert(
 195             const IApplication* application,
 196             const opensaml::saml2md::RoleDescriptor* source,
 197             const char* client_addr,
 198             const saml::SAMLSubject* subject,
 199             const char* authnContext,
 200             const saml::SAMLResponse* tokens
 201             )=0;
 202         virtual ISessionCacheEntry* find(
 203             const char* key, const IApplication* application, const char* client_addr
 204             )=0;
 205         virtual void remove(
 206             const char* key, const IApplication* application, const char* client_addr
 207             )=0;
 208
 209         virtual bool setBackingStore(ISessionCacheStore* store)=0;
 210         virtual ~ISessionCache() {}
 211     };
 212
 213     #define MEMORY_SESSIONCACHE "edu.internet2.middleware.shibboleth.sp.provider.MemorySessionCacheProvider"
 214     #define MYSQL_SESSIONCACHE  "edu.internet2.middleware.shibboleth.sp.provider.MySQLSessionCacheProvider"
 215     #define ODBC_SESSIONCACHE   "edu.internet2.middleware.shibboleth.sp.provider.ODBCSessionCacheProvider"
 216
 217     #define MYSQL_REPLAYCACHE   "edu.internet2.middleware.shibboleth.sp.provider.MySQLReplayCacheProvider"
 218     #define ODBC_REPLAYCACHE    "edu.internet2.middleware.shibboleth.sp.provider.ODBCReplayCacheProvider"
 219
 220
 221     class SHIBTARGET_EXPORTS ShibTargetConfig
 222     {
 223     public:
 224         ShibTargetConfig() {}
 225         virtual ~ShibTargetConfig() {}
 226
 227         virtual bool init(const char* schemadir) = 0;
 228         virtual bool load(const char* config) = 0;
 229         virtual void shutdown() = 0;
 230
 231         static ShibTargetConfig& getConfig();
 232     };
 233
 234 }
 235
 236 #endif /* SHIB_TARGET_H */