saml/SAMLConfig.h

   1 /**
   2  * Licensed to the University Corporation for Advanced Internet
   3  * Development, Inc. (UCAID) under one or more contributor license
   4  * agreements. See the NOTICE file distributed with this work for
   5  * additional information regarding copyright ownership.
   6  *
   7  * UCAID licenses this file to you under the Apache License,
   8  * Version 2.0 (the "License"); you may not use this file except
   9  * in compliance with the License. You may obtain a copy of the
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
  17  * either express or implied. See the License for the specific
  18  * language governing permissions and limitations under the License.
  19  */
  20
  21 /**
  22  * @file saml/SAMLConfig.h
  23  *
  24  * Library configuration.
  25  */
  26
  27 #ifndef __saml_config_h__
  28 #define __saml_config_h__
  29
  30 #include <saml/base.h>
  31
  32 #include <string>
  33 #include <xercesc/dom/DOM.hpp>
  34 #include <xmltooling/PluginManager.h>
  35
  36 /**
  37  * @namespace opensaml
  38  * Common classes for OpenSAML library
  39  */
  40 namespace opensaml {
  41
  42     class SAML_API ArtifactMap;
  43     class SAML_API MessageEncoder;
  44     class SAML_API MessageDecoder;
  45     class SAML_API SAMLArtifact;
  46     class SAML_API SecurityPolicyRule;
  47
  48     namespace saml2md {
  49         class SAML_API ContactPerson;
  50         class SAML_API EntityDescriptor;
  51         class SAML_API EntityMatcher;
  52         class SAML_API MetadataProvider;
  53         class SAML_API MetadataFilter;
  54         class SAML_API RoleDescriptor;
  55     };
  56
  57 #if defined (_MSC_VER)
  58     #pragma warning( push )
  59     #pragma warning( disable : 4250 4251 )
  60 #endif
  61
  62     /**
  63      * Singleton object that manages library startup/shutdown.configuration.
  64      */
  65     class SAML_API SAMLConfig
  66     {
  67     MAKE_NONCOPYABLE(SAMLConfig);
  68     public:
  69         virtual ~SAMLConfig();
  70
  71         /**
  72          * Returns the global configuration object for the library.
  73          *
  74          * @return reference to the global library configuration object
  75          */
  76         static SAMLConfig& getConfig();
  77
  78         /**
  79          * Initializes library
  80          *
  81          * Each process using the library MUST call this function exactly once
  82          * before using any library classes. The flag controls whether this is the
  83          * "dominant" library or not and can allow the SAML library to be loaded
  84          * as an extension of XMLTooling rather than subsuming it.
  85          *
  86          * @param initXMLTooling true iff this method should initialize the XMLTooling layer
  87          * @return true iff initialization was successful
  88          */
  89         virtual bool init(bool initXMLTooling=true)=0;
  90
  91         /**
  92          * Shuts down library
  93          *
  94          * Each process using the library SHOULD call this function exactly once
  95          * before terminating itself. The flag controls whether this is the
  96          * "dominant" library or not and can allow the SAML library to be loaded
  97          * as an extension of XMLTooling rather than subsuming it.
  98          *
  99          * @param termXMLTooling true iff this method should shutdown the XMLTooling layer
 100          */
 101         virtual void term(bool termXMLTooling=true)=0;
 102
 103         /**
 104          * Sets the global ArtifactMap instance.
 105          * This method must be externally synchronized with any code that uses the object.
 106          * Any previously set object is destroyed.
 107          *
 108          * @param artifactMap   new ArtifactMap instance to store
 109          */
 110         void setArtifactMap(ArtifactMap* artifactMap);
 111
 112         /**
 113          * Returns the global ArtifactMap instance.
 114          *
 115          * @return  global ArtifactMap or nullptr
 116          */
 117         ArtifactMap* getArtifactMap() const;
 118
 119         /**
 120          * Generate random information using the underlying security library
 121          *
 122          * @param buf   buffer for the information
 123          * @param len   number of bytes to write into buffer
 124          */
 125         virtual void generateRandomBytes(void* buf, unsigned int len)=0;
 126
 127         /**
 128          * Generate random information using the underlying security library
 129          *
 130          * @param buf   string buffer for the information
 131          * @param len   number of bytes to write into buffer
 132          */
 133         virtual void generateRandomBytes(std::string& buf, unsigned int len)=0;
 134
 135         /**
 136          * Generate a valid XML identifier of the form _X{32} where X is a
 137          * random hex character. The caller is responsible for freeing the result.
 138          *
 139          * @return a valid null-terminated XML ID
 140          */
 141         virtual XMLCh* generateIdentifier()=0;
 142
 143         /**
 144          * @deprecated
 145          * Generate the SHA-1 hash of a string
 146          *
 147          * @param s     NULL-terminated string to hash
 148          * @param toHex true iff the result should be encoded in hexadecimal form or left as raw bytes
 149          *
 150          * @return  SHA-1 hash of the data
 151          */
 152         virtual std::string hashSHA1(const char* s, bool toHex=false)=0;
 153
 154         /**
 155          * Sets the order of contact types to use in annotating exceptions with contact information.
 156          *
 157          * @param contactTypes  whitespace-delimited list of contact types
 158          */
 159         virtual void setContactPriority(const XMLCh* contactTypes)=0;
 160
 161         /**
 162          * Returns the appropriate contact to use for the entity.
 163          *
 164          * @param entity    the entity to search
 165          * @return  a contact to use, or nullptr
 166          */
 167         virtual const saml2md::ContactPerson* getContactPerson(const saml2md::EntityDescriptor& entity) const=0;
 168
 169         /**
 170          * Returns the appropriate contact to use for the role.
 171          *
 172          * @param entity    the role to search
 173          * @return  a contact to use, or nullptr
 174          */
 175         virtual const saml2md::ContactPerson* getContactPerson(const saml2md::RoleDescriptor& role) const=0;
 176
 177         /** Manages factories for MessageDecoder plugins. */
 178         xmltooling::PluginManager< MessageDecoder,std::string,std::pair<const xercesc::DOMElement*,const XMLCh*> > MessageDecoderManager;
 179
 180         /** Manages factories for MessageEncoder plugins. */
 181         xmltooling::PluginManager< MessageEncoder,std::string,std::pair<const xercesc::DOMElement*,const XMLCh*> > MessageEncoderManager;
 182
 183         /** Manages factories for SAMLArtifact plugins. */
 184         xmltooling::PluginManager<SAMLArtifact,std::string,const char*> SAMLArtifactManager;
 185
 186         /** Manages factories for SecurityPolicyRule plugins. */
 187         xmltooling::PluginManager<SecurityPolicyRule,std::string,const xercesc::DOMElement*> SecurityPolicyRuleManager;
 188
 189         /** Manages factories for MetadataProvider plugins. */
 190         xmltooling::PluginManager<saml2md::MetadataProvider,std::string,const xercesc::DOMElement*> MetadataProviderManager;
 191
 192         /** Manages factories for MetadataFilter plugins. */
 193         xmltooling::PluginManager<saml2md::MetadataFilter,std::string,const xercesc::DOMElement*> MetadataFilterManager;
 194
 195         /** Manages factories for EntityMatcher plugins. */
 196         xmltooling::PluginManager<saml2md::EntityMatcher,std::string,const xercesc::DOMElement*> EntityMatcherManager;
 197
 198     protected:
 199         SAMLConfig();
 200
 201         /** Global ArtifactMap instance for use by artifact-related functions. */
 202         ArtifactMap* m_artifactMap;
 203     };
 204
 205 #if defined (_MSC_VER)
 206     #pragma warning( pop )
 207 #endif
 208
 209 };
 210
 211 #endif /* __saml_config_h__ */