src/shibresolver/resolver.h

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