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 #include <xmltooling/unicode.h>
  30
  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 #elif defined SHIBRESOLVER_HAVE_GSSAPI
  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          * Sets the metadata protocol constant to use for resolution.
  94          *
  95          * @param protocol  metadata protocol constant
  96          */
  97         void setProtocol(const XMLCh* protocol);
  98
  99         /**
 100          * Adds an XML token as input to the resolver, generally a SAML assertion.
 101          * <p>The caller retains ownership of the object.
 102          *
 103          * @param token an input token to evaluate
 104          */
 105         void addToken(const xmltooling::XMLObject* token);
 106
 107 #ifdef SHIBRESOLVER_HAVE_GSSAPI
 108         /**
 109          * Adds a GSS-API exported mechanism name as input to
 110          * the resolver.
 111          * <p>The caller retains ownership of the buffer.
 112          *
 113          * @param ctx an input exported mechanism name to evaluate
 114          */
 115         void addToken(const gss_buffer_t name);
 116
 117 # ifdef SHIBRESOLVER_HAVE_GSSAPI_NAMINGEXTS
 118         /**
 119          * Adds a GSS-API mechanism name as input to the resolver.
 120          * <p>The caller retains ownership of the name.
 121          *
 122          * @param name an input mechanism name to evaluate
 123          */
 124         void addToken(gss_name_t name);
 125 # endif
 126
 127         /**
 128          * Adds a GSS-API security context as input to the resolver.
 129          * <p>The caller loses ownership of the context.
 130          *
 131          * @param ctx an input context to evaluate
 132          */
 133         void addToken(gss_ctx_id_t* ctx);
 134 #endif
 135
 136         /**
 137          * Adds an Attribute as input to the resolver.
 138          * <p>The caller retains ownership of the object.
 139          *
 140          * @param attr  an input Attribute
 141          */
 142         void addAttribute(shibsp::Attribute* attr);
 143
 144         /**
 145          * Resolves Attributes and attaches them to the resolver object.
 146          * <p>The caller is responsible for transferring any Attributes it wishes to
 147          * retain out of the resolver.
 148          */
 149         virtual void resolve();
 150
 151         /**
 152          * Returns a modifiable array of resolved Attribute objects.
 153          * <p>The caller may take ownership of any or all by removing them
 154          * from the array.
 155          *
 156          * @return  array of resolved Attributes
 157          */
 158         std::vector<shibsp::Attribute*>& getResolvedAttributes();
 159
 160         /**
 161          * Returns mapped PropertySet and AccessControl objects, if any.
 162          *
 163          * @return  mapped PropertySet/AccesssControl pair
 164          */
 165         shibsp::RequestMapper::Settings getSettings() const;
 166
 167         /**
 168          * Initializes SP runtime objects based on an XML configuration string or a configuration pathname.
 169          * <p>Each process using the library MUST call this function exactly once before using any library classes.
 170          *
 171          * @param features  bitmask of SP components to enable
 172          * @param config    a snippet of XML to parse (it <strong>MUST</strong> contain a type attribute) or a pathname
 173          * @param rethrow   true iff caught exceptions should be rethrown instead of just returning a true/false result
 174          * @return true iff initialization was successful
 175          */
 176         static bool init(
 177 #ifdef SHIBSP_LITE
 178             unsigned long features = (shibsp::SPConfig::Listener|shibsp::SPConfig::InProcess),
 179 #else
 180             unsigned long features = shibsp::SPConfig::OutOfProcess,
 181 #endif
 182             const char* config = NULL,
 183             bool rethrow = false
 184             );
 185
 186         /**
 187          * Shuts down runtime.
 188          *
 189          * Each process using the library SHOULD call this function exactly once before terminating itself.
 190          */
 191         static void term();
 192
 193         /**
 194          * Returns a ShibbolethResolver instance.
 195          *
 196          * @return  a ShibbolethResolver instance, must be freed by the caller.
 197          */
 198         static ShibbolethResolver* create();
 199
 200     protected:
 201         /** Service request. */
 202         const shibsp::SPRequest* m_request;
 203
 204         /** Application ID. */
 205         std::string m_appID;
 206
 207         /** Source of identity, if known. */
 208         std::string m_issuer;
 209
 210         /** Metadata protocol constant to use. */
 211         xmltooling::xstring m_protocol;
 212
 213         /** Input tokens. */
 214         std::vector<const xmltooling::XMLObject*> m_tokens;
 215
 216         /** Input attributes. */
 217         std::vector<shibsp::Attribute*> m_inputAttributes;
 218
 219     private:
 220         shibsp::ServiceProvider* m_sp;
 221 #ifdef SHIBRESOLVER_HAVE_GSSAPI
 222         xmltooling::XMLObject* m_gsswrapper;
 223 #endif
 224         std::vector<shibsp::Attribute*> m_resolvedAttributes;
 225     };
 226
 227 #if defined (_MSC_VER)
 228     #pragma warning( pop )
 229 #endif
 230
 231 };
 232
 233 #endif /* __shibresolver_h__ */