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         virtual saml::Iterator<shibboleth::IAAP*> getAAPProviders() const=0;
  70
  71         // caller is borrowing object, must use within scope of config lock
  72         virtual const saml::SAMLBrowserProfile* getBrowserProfile() const=0;
  73         virtual const saml::SAMLBinding* getBinding(const XMLCh* binding) const=0;
  74
  75         // caller is given ownership of object, must use and delete within scope of config lock
  76         virtual saml::SAMLBrowserProfile::ArtifactMapper* getArtifactMapper() const=0;
  77
  78         // general token validation based on conditions, signatures, etc.
  79         virtual void validateToken(
  80             saml::SAMLAssertion* token,
  81             time_t t=0,
  82             const opensaml::saml2md::RoleDescriptor* role=NULL,
  83             const xmltooling::TrustEngine* trust=NULL
  84             ) const=0;
  85
  86         virtual ~IApplication() {}
  87     };
  88
  89     /**
  90      * OpenSAML binding hook
  91      *
  92      * Instead of wrapping the binding to deal with mutual authentication, we
  93      * just use the HTTP hook functionality offered by OpenSAML. The hook will
  94      * register "itself" as a globalCtx pointer with the SAML binding and the caller
  95      * will declare and pass the embedded struct as callCtx for use by the hook.
  96      */
  97     class ShibHTTPHook : virtual public saml::SAMLSOAPHTTPBinding::HTTPHook
  98     {
  99     public:
 100         ShibHTTPHook(const xmltooling::TrustEngine* trust) : m_trust(trust) {}
 101         virtual ~ShibHTTPHook() {}
 102
 103         // Only hook we need here is for outgoing connection to server.
 104         virtual bool outgoing(saml::HTTPClient* conn, void* globalCtx=NULL, void* callCtx=NULL);
 105
 106         // Client declares a context object and pass as callCtx to send() method.
 107         class ShibHTTPHookCallContext {
 108         public:
 109             ShibHTTPHookCallContext(const shibsp::PropertySet* credUse, const opensaml::saml2md::RoleDescriptor* role)
 110                 : m_credUse(credUse), m_role(role), m_hook(NULL), m_authenticated(false) {}
 111             const ShibHTTPHook* getHook() {return m_hook;}
 112             const shibsp::PropertySet* getCredentialUse() {return m_credUse;}
 113             const opensaml::saml2md::RoleDescriptor* getRoleDescriptor() {return m_role;}
 114             bool isAuthenticated() const {return m_authenticated;}
 115             void setAuthenticated() {m_authenticated=true;}
 116
 117         private:
 118             const shibsp::PropertySet* m_credUse;
 119             const opensaml::saml2md::RoleDescriptor* m_role;
 120             ShibHTTPHook* m_hook;
 121             bool m_authenticated;
 122             friend class ShibHTTPHook;
 123         };
 124
 125         const xmltooling::TrustEngine* getTrustEngine() const {return m_trust;}
 126     private:
 127         const xmltooling::TrustEngine* m_trust;
 128     };
 129
 130     /**
 131      * Interface to a cached user session.
 132      *
 133      * Cache entries provide implementations with access to the raw SAML information they
 134      * need to publish or provide access to the data for applications to use. All creation
 135      * or access to entries is through the ISessionCache interface, and callers must unlock
 136      * the entry when finished using it, rather than explicitly freeing them.
 137      */
 138     struct SHIBTARGET_EXPORTS ISessionCacheEntry : public virtual saml::ILockable
 139     {
 140         virtual const char* getClientAddress() const=0;
 141         virtual const char* getProviderId() const=0;
 142         virtual std::pair<const char*,const saml::SAMLSubject*> getSubject(bool xml=true, bool obj=false) const=0;
 143         virtual const char* getAuthnContext() const=0;
 144         virtual std::pair<const char*,const saml::SAMLResponse*> getTokens(bool xml=true, bool obj=false) const=0;
 145         virtual std::pair<const char*,const saml::SAMLResponse*> getFilteredTokens(bool xml=true, bool obj=false) const=0;
 146         virtual ~ISessionCacheEntry() {}
 147     };
 148
 149     /**
 150      * Interface to a sink for session cache events.
 151      *
 152      * All caches support registration of a backing store that can be informed
 153      * of significant events in the lifecycle of a cache entry.
 154      */
 155     struct SHIBTARGET_EXPORTS ISessionCacheStore
 156     {
 157         virtual HRESULT onCreate(
 158             const char* key,
 159             const IApplication* application,
 160             const ISessionCacheEntry* entry,
 161             int majorVersion,
 162             int minorVersion,
 163             time_t created
 164             )=0;
 165         virtual HRESULT onRead(
 166             const char* key,
 167             std::string& applicationId,
 168             std::string& clientAddress,
 169             std::string& providerId,
 170             std::string& subject,
 171             std::string& authnContext,
 172             std::string& tokens,
 173             int& majorVersion,
 174             int& minorVersion,
 175             time_t& created,
 176             time_t& accessed
 177             )=0;
 178         virtual HRESULT onRead(const char* key, time_t& accessed)=0;
 179         virtual HRESULT onRead(const char* key, std::string& tokens)=0;
 180         virtual HRESULT onUpdate(const char* key, const char* tokens=NULL, time_t lastAccess=0)=0;
 181         virtual HRESULT onDelete(const char* key)=0;
 182         virtual ~ISessionCacheStore() {}
 183     };
 184
 185     /**
 186      * Interface to the session cache.
 187      *
 188      * The session cache abstracts a persistent (meaning across requests) cache of
 189      * instances of the ISessionCacheEntry interface. Creation of new entries and entry
 190      * lookup are confined to this interface to enable implementations to flexibly
 191      * remote and/or optimize calls by implementing custom versions of the
 192      * ISessionCacheEntry interface as required.
 193      */
 194     struct SHIBTARGET_EXPORTS ISessionCache : virtual public shibsp::SessionCache
 195     {
 196         virtual std::string insert(
 197             const IApplication* application,
 198             const opensaml::saml2md::RoleDescriptor* source,
 199             const char* client_addr,
 200             const saml::SAMLSubject* subject,
 201             const char* authnContext,
 202             const saml::SAMLResponse* tokens
 203             )=0;
 204         virtual ISessionCacheEntry* find(
 205             const char* key, const IApplication* application, const char* client_addr
 206             )=0;
 207         virtual void remove(
 208             const char* key, const IApplication* application, const char* client_addr
 209             )=0;
 210
 211         virtual bool setBackingStore(ISessionCacheStore* store)=0;
 212         virtual ~ISessionCache() {}
 213     };
 214
 215     #define MEMORY_SESSIONCACHE "edu.internet2.middleware.shibboleth.sp.provider.MemorySessionCacheProvider"
 216     #define MYSQL_SESSIONCACHE  "edu.internet2.middleware.shibboleth.sp.provider.MySQLSessionCacheProvider"
 217     #define ODBC_SESSIONCACHE   "edu.internet2.middleware.shibboleth.sp.provider.ODBCSessionCacheProvider"
 218
 219     #define MYSQL_REPLAYCACHE   "edu.internet2.middleware.shibboleth.sp.provider.MySQLReplayCacheProvider"
 220     #define ODBC_REPLAYCACHE    "edu.internet2.middleware.shibboleth.sp.provider.ODBCReplayCacheProvider"
 221
 222
 223     class SHIBTARGET_EXPORTS ShibTargetConfig
 224     {
 225     public:
 226         ShibTargetConfig() {}
 227         virtual ~ShibTargetConfig() {}
 228
 229         virtual bool init(const char* schemadir) = 0;
 230         virtual bool load(const char* config) = 0;
 231         virtual void shutdown() = 0;
 232
 233         static ShibTargetConfig& getConfig();
 234     };
 235
 236 }
 237
 238 #endif /* SHIB_TARGET_H */