src/shibresolver/resolver.h

   1 /*
   2  *  Copyright 2010-2011 JANET(UK)
   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  * @file shibresolver/resolver.h
  19  *
  20  * An embeddable component interface to Shibboleth SP attribute processing.
  21  */
  22
  23 #ifndef __shibresolver_h__
  24 #define __shibresolver_h__
  25
  26 #include <shibresolver/base.h>
  27
  28 #include <shibsp/RequestMapper.h>
  29 #include <shibsp/SPConfig.h>
  30
  31 #include <string>
  32 #include <vector>
  33
  34 #ifdef SHIBRESOLVER_HAVE_GSSGNU
  35 # include <gss.h>
  36 #elif defined SHIBRESOLVER_HAVE_GSSMIT
  37 # include <gssapi/gssapi.h>
  38 # include <gssapi/gssapi_generic.h>
  39 #else
  40 # include <gssapi.h>
  41 #endif
  42
  43 namespace xmltooling {
  44     class XMLTOOL_API XMLObject;
  45 };
  46
  47 namespace shibsp {
  48     class SHIBSP_API Attribute;
  49     class SHIBSP_API SPRequest;
  50 };
  51
  52 namespace shibresolver {
  53
  54 #if defined (_MSC_VER)
  55     #pragma warning( push )
  56     #pragma warning( disable : 4250 4251 )
  57 #endif
  58
  59     /**
  60      * An embeddable component interface to Shibboleth SP attribute processing.
  61      */
  62     class SHIBRESOLVER_API ShibbolethResolver
  63     {
  64         MAKE_NONCOPYABLE(ShibbolethResolver);
  65     protected:
  66         ShibbolethResolver();
  67     public:
  68         virtual ~ShibbolethResolver();
  69
  70         /**
  71          * Sets the calling service request, making the Shibboleth SP responsible for
  72          * mapping the service to an Application instance.
  73          *
  74          * @param request identifies the service request performing attribute resolution
  75          */
  76         void setRequest(const shibsp::SPRequest* request);
  77
  78         /**
  79          * Sets the application ID to use for resolution, bypassing the mapping
  80          * function of the Shibboleth SP.
  81          *
  82          * @param appID identifies an application in the SP configuration
  83          */
  84         void setApplicationID(const char* appID);
  85
  86         /**
  87          * Sets the identity issuer to use for resolution.
  88          *
  89          * @param issuer    entityID of the identity "source", if known
  90          */
  91         void setIssuer(const char* issuer);
  92
  93         /**
  94          * Adds an XML token as input to the resolver, generally a SAML assertion.
  95          * <p>The caller retains ownership of the object.
  96          *
  97          * @param token an input token to evaluate
  98          */
  99         void addToken(const xmltooling::XMLObject* token);
 100
 101 #ifdef SHIBRESOLVER_HAVE_GSSAPI
 102         /**
 103          * Adds a GSS-API exported mechanism name as input to
 104          * the resolver.
 105          * <p>The caller retains ownership of the buffer.
 106          *
 107          * @param ctx an input exported mechanism name to evaluate
 108          */
 109         void addToken(const gss_buffer_t name);
 110
 111 # ifdef SHIBRESOLVER_HAVE_GSSAPI_NAMINGEXTS
 112         /**
 113          * Adds a GSS-API mechanism name as input to the resolver.
 114          * <p>The caller retains ownership of the name.
 115          *
 116          * @param name an input mechanism name to evaluate
 117          */
 118         void addToken(gss_name_t name);
 119 # endif
 120
 121         /**
 122          * Adds a GSS-API security context as input to the resolver.
 123          * <p>The caller loses ownership of the context.
 124          *
 125          * @param ctx an input context to evaluate
 126          */
 127         void addToken(gss_ctx_id_t* ctx);
 128 #endif
 129
 130         /**
 131          * Adds an Attribute as input to the resolver.
 132          * <p>The caller retains ownership of the object.
 133          *
 134          * @param attr  an input Attribute
 135          */
 136         void addAttribute(shibsp::Attribute* attr);
 137
 138         /**
 139          * Resolves Attributes and attaches them to the resolver object.
 140          * <p>The caller is responsible for transferring any Attributes it wishes to
 141          * retain out of the resolver.
 142          */
 143         virtual void resolve();
 144
 145         /**
 146          * Returns a modifiable array of resolved Attribute objects.
 147          * <p>The caller may take ownership of any or all by removing them
 148          * from the array.
 149          *
 150          * @return  array of resolved Attributes
 151          */
 152         std::vector<shibsp::Attribute*>& getResolvedAttributes();
 153
 154         /**
 155          * Returns mapped PropertySet and AccessControl objects, if any.
 156          *
 157          * @return  mapped PropertySet/AccesssControl pair
 158          */
 159         shibsp::RequestMapper::Settings getSettings() const;
 160
 161         /**
 162          * Initializes SP runtime objects based on an XML configuration string or a configuration pathname.
 163          * <p>Each process using the library MUST call this function exactly once before using any library classes.
 164          *
 165          * @param features  bitmask of SP components to enable
 166          * @param config    a snippet of XML to parse (it <strong>MUST</strong> contain a type attribute) or a pathname
 167          * @param rethrow   true iff caught exceptions should be rethrown instead of just returning a true/false result
 168          * @return true iff initialization was successful
 169          */
 170         static bool init(
 171 #ifdef SHIBSP_LITE
 172             unsigned long features = (shibsp::SPConfig::Listener|shibsp::SPConfig::InProcess),
 173 #else
 174             unsigned long features = shibsp::SPConfig::OutOfProcess,
 175 #endif
 176             const char* config = NULL,
 177             bool rethrow = false
 178             );
 179
 180         /**
 181          * Shuts down runtime.
 182          *
 183          * Each process using the library SHOULD call this function exactly once before terminating itself.
 184          */
 185         static void term();
 186
 187         /**
 188          * Returns a ShibbolethResolver instance.
 189          *
 190          * @return  a ShibbolethResolver instance, must be freed by the caller.
 191          */
 192         static ShibbolethResolver* create();
 193
 194     protected:
 195         /** Service request. */
 196         const shibsp::SPRequest* m_request;
 197
 198         /** Application ID. */
 199         std::string m_appID;
 200
 201         /** Source of identity, if known. */
 202         std::string m_issuer;
 203
 204         /** Input tokens. */
 205         std::vector<const xmltooling::XMLObject*> m_tokens;
 206
 207         /** Input attributes. */
 208         std::vector<shibsp::Attribute*> m_inputAttributes;
 209
 210     private:
 211         shibsp::ServiceProvider* m_sp;
 212 #ifdef SHIBRESOLVER_HAVE_GSSAPI
 213         xmltooling::XMLObject* m_gsswrapper;
 214 #endif
 215         std::vector<shibsp::Attribute*> m_resolvedAttributes;
 216     };
 217
 218 #if defined (_MSC_VER)
 219     #pragma warning( pop )
 220 #endif
 221
 222 };
 223
 224 #endif /* __shibresolver_h__ */