saml/SAMLConfig.h

   1 /*
   2  *  Copyright 2001-2006 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  * @file saml/SAMLConfig.h
  19  *
  20  * Library configuration
  21  */
  22
  23 #ifndef __saml_config_h__
  24 #define __saml_config_h__
  25
  26 #include <saml/base.h>
  27
  28 #include <xmltooling/PluginManager.h>
  29 #include <xmltooling/XMLToolingConfig.h>
  30
  31 #include <string>
  32
  33 /**
  34  * @namespace opensaml
  35  * Common classes for OpenSAML library
  36  */
  37 namespace opensaml {
  38
  39     class SAML_API ArtifactMap;
  40     class SAML_API MessageEncoder;
  41     class SAML_API MessageDecoder;
  42     class SAML_API SAMLArtifact;
  43     class SAML_API SecurityPolicyRule;
  44     class SAML_API TrustEngine;
  45     class SAML_API URLEncoder;
  46
  47     namespace saml2md {
  48         class SAML_API MetadataProvider;
  49         class SAML_API MetadataFilter;
  50     };
  51
  52 #if defined (_MSC_VER)
  53     #pragma warning( push )
  54     #pragma warning( disable : 4250 4251 )
  55 #endif
  56
  57     /**
  58      * Singleton object that manages library startup/shutdown.configuration.
  59      */
  60     class SAML_API SAMLConfig
  61     {
  62     MAKE_NONCOPYABLE(SAMLConfig);
  63     public:
  64         virtual ~SAMLConfig() {}
  65
  66         /**
  67          * Returns the global configuration object for the library.
  68          *
  69          * @return reference to the global library configuration object
  70          */
  71         static SAMLConfig& getConfig();
  72
  73         /**
  74          * Initializes library
  75          *
  76          * Each process using the library MUST call this function exactly once
  77          * before using any library classes. The flag controls whether this is the
  78          * "dominant" library or not and can allow the SAML library to be loaded
  79          * as an extension of XMLTooling rather than subsuming it.
  80          *
  81          * @param initXMLTooling true iff this method should initialize the XMLTooling layer
  82          * @return true iff initialization was successful
  83          */
  84         virtual bool init(bool initXMLTooling=true)=0;
  85
  86         /**
  87          * Shuts down library
  88          *
  89          * Each process using the library SHOULD call this function exactly once
  90          * before terminating itself. The flag controls whether this is the
  91          * "dominant" library or not and can allow the SAML library to be loaded
  92          * as an extension of XMLTooling rather than subsuming it.
  93          *
  94          * @param termXMLTooling true iff this method should shutdown the XMLTooling layer
  95          */
  96         virtual void term(bool termXMLTooling=true)=0;
  97
  98         /**
  99          * Sets the global ArtifactMap instance.
 100          * This method must be externally synchronized with any code that uses the object.
 101          * Any previously set object is destroyed.
 102          *
 103          * @param artifactMap   new ArtifactMap instance to store
 104          */
 105         void setArtifactMap(ArtifactMap* artifactMap);
 106
 107         /**
 108          * Returns the global ArtifactMap instance.
 109          *
 110          * @return  global ArtifactMap or NULL
 111          */
 112         ArtifactMap* getArtifactMap() const {
 113             return m_artifactMap;
 114         }
 115
 116         /**
 117          * Sets the global URLEncoder instance.
 118          * This method must be externally synchronized with any code that uses the object.
 119          * Any previously set object is destroyed.
 120          *
 121          * @param urlEncoder   new URLEncoder instance to store
 122          */
 123         void setURLEncoder(URLEncoder* urlEncoder);
 124
 125         /**
 126          * Returns the global URLEncoder instance.
 127          *
 128          * @return  global URLEncoder or NULL
 129          */
 130         URLEncoder* getURLEncoder() const {
 131             return m_urlEncoder;
 132         }
 133
 134         /**
 135          * Generate random information using the underlying security library
 136          *
 137          * @param buf   buffer for the information
 138          * @param len   number of bytes to write into buffer
 139          */
 140         virtual void generateRandomBytes(void* buf, unsigned int len)=0;
 141
 142         /**
 143          * Generate random information using the underlying security library
 144          *
 145          * @param buf   string buffer for the information
 146          * @param len   number of bytes to write into buffer
 147          */
 148         virtual void generateRandomBytes(std::string& buf, unsigned int len)=0;
 149
 150         /**
 151          * Generate a valid XML identifier of the form _X{32} where X is a
 152          * random hex character. The caller is responsible for freeing the result.
 153          *
 154          * @return a valid null-terminated XML ID
 155          */
 156         virtual XMLCh* generateIdentifier()=0;
 157
 158         /**
 159          * Generate the SHA-1 hash of a string
 160          *
 161          * @param s     NULL-terminated string to hash
 162          * @param toHex true iff the result should be encoded in hexadecimal form or left as raw bytes
 163          *
 164          * @return  SHA-1 hash of the data
 165          */
 166         virtual std::string hashSHA1(const char* s, bool toHex=false)=0;
 167
 168         /** Manages factories for MessageDecoder plugins. */
 169         xmltooling::PluginManager<MessageDecoder,const DOMElement*> MessageDecoderManager;
 170
 171         /** Manages factories for MessageEncoder plugins. */
 172         xmltooling::PluginManager<MessageEncoder,const DOMElement*> MessageEncoderManager;
 173
 174         /** Manages factories for SAMLArtifact plugins. */
 175         xmltooling::PluginManager<SAMLArtifact,const char*> SAMLArtifactManager;
 176
 177         /** Manages factories for SecurityPolicyRule plugins. */
 178         xmltooling::PluginManager<SecurityPolicyRule,const DOMElement*> SecurityPolicyRuleManager;
 179
 180         /** Manages factories for TrustEngine plugins. */
 181         xmltooling::PluginManager<TrustEngine,const DOMElement*> TrustEngineManager;
 182
 183         /** Manages factories for MetadataProvider plugins. */
 184         xmltooling::PluginManager<saml2md::MetadataProvider,const DOMElement*> MetadataProviderManager;
 185
 186         /** Manages factories for MetadataFilter plugins. */
 187         xmltooling::PluginManager<saml2md::MetadataFilter,const DOMElement*> MetadataFilterManager;
 188
 189     protected:
 190         SAMLConfig() : m_artifactMap(NULL), m_urlEncoder(NULL) {}
 191
 192         /** Global ArtifactMap instance for use by artifact-related functions. */
 193         ArtifactMap* m_artifactMap;
 194
 195         /** Global URLEncoder instance for use by URL-related functions. */
 196         URLEncoder* m_urlEncoder;
 197     };
 198
 199 #if defined (_MSC_VER)
 200     #pragma warning( pop )
 201 #endif
 202
 203 };
 204
 205 #endif /* __saml_config_h__ */