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 xmltooling/XMLToolingConfig.h 23 * 24 * Library configuration. 25 */ 26 27 #ifndef __xmltooling_config_h__ 28 #define __xmltooling_config_h__ 29 30 #include <xmltooling/Lockable.h> 31 #include <xmltooling/PluginManager.h> 32 #include <xmltooling/soap/SOAPTransport.h> 33 34 #include <memory> 35 #include <string> 36 #include <boost/scoped_ptr.hpp> 37 #include <xercesc/dom/DOM.hpp> 38 39 #if defined (_MSC_VER) 40 #pragma warning( push ) 41 #pragma warning( disable : 4251 ) 42 #endif 43 44 namespace xmltooling { 45 46 class XMLTOOL_API Mutex; 47 class XMLTOOL_API ParserPool; 48 class XMLTOOL_API PathResolver; 49 class XMLTOOL_API TemplateEngine; 50 class XMLTOOL_API URLEncoder; 51 #ifndef XMLTOOLING_LITE 52 class XMLTOOL_API ReplayCache; 53 class XMLTOOL_API StorageService; 54 #endif 55 #ifndef XMLTOOLING_NO_XMLSEC 56 class XMLTOOL_API CredentialResolver; 57 class XMLTOOL_API DataSealer; 58 class XMLTOOL_API DataSealerKeyStrategy; 59 class XMLTOOL_API KeyInfoResolver; 60 class XMLTOOL_API PathValidator; 61 class XMLTOOL_API TrustEngine; 62 class XMLTOOL_API XSECCryptoX509CRL; 63 #endif 64 65 /** 66 * Singleton object that manages library startup/shutdown.configuration. 67 * 68 * <p>A locking interface is supplied as a convenience for code that wants to 69 * obtain a global system lock, but the actual configuration itself is not 70 * synchronized. 71 */ 72 class XMLTOOL_API XMLToolingConfig : public virtual Lockable 73 { 74 MAKE_NONCOPYABLE(XMLToolingConfig); 75 protected: 76 XMLToolingConfig(); 77 78 #ifndef XMLTOOLING_NO_XMLSEC 79 /** Global KeyInfoResolver instance. */ 80 boost::scoped_ptr<KeyInfoResolver> m_keyInfoResolver; 81 82 /** Global ReplayCache instance. */ 83 boost::scoped_ptr<ReplayCache> m_replayCache; 84 85 /* Global DataSealer instance. */ 86 boost::scoped_ptr<DataSealer> m_dataSealer; 87 #endif 88 89 /** Global PathResolver instance. */ 90 boost::scoped_ptr<PathResolver> m_pathResolver; 91 92 /** Global TemplateEngine instance. */ 93 boost::scoped_ptr<TemplateEngine> m_templateEngine; 94 95 /** Global URLEncoder instance for use by URL-related functions. */ 96 boost::scoped_ptr<URLEncoder> m_urlEncoder; 97 98 public: 99 virtual ~XMLToolingConfig(); 100 101 /** 102 * Returns the global configuration object for the library. 103 * 104 * @return reference to the global library configuration object 105 */ 106 static XMLToolingConfig& getConfig(); 107 108 /** 109 * Initializes library 110 * 111 * Each process using the library MUST call this function exactly once 112 * before using any library classes except for the LogConfig method. 113 * 114 * @param deprecationSupport true iff plugins should support any deprecated features 115 * 116 * @return true iff initialization was successful 117 */ 118 virtual bool init(bool deprecationSupport=true)=0; 119 120 /** 121 * Shuts down library 122 * <p>Each process using the library SHOULD call this function exactly once 123 * before terminating itself 124 */ 125 virtual void term()=0; 126 127 /** 128 * Loads a shared/dynamic library extension. 129 * 130 * <p>Extension libraries are managed using a pair of "C" linkage functions:<br> 131 * extern "C" int xmltooling_extension_init(void* context);<br> 132 * extern "C" void xmltooling_extension_term(); 133 * 134 * <p>This method is internally synchronized. 135 * 136 * @param path pathname of shared library to load into process 137 * @param context arbitrary data to pass to library initialization hook 138 * @return true iff library was loaded successfully 139 */ 140 virtual bool load_library(const char* path, void* context=nullptr)=0; 141 142 /** 143 * Configure logging system. 144 * <p>May be called first, before initializing the library. Other calls to it 145 * must be externally synchronized. 146 * 147 * @param config either a logging configuration file, or a level from the set 148 * (DEBUG, INFO, NOTICE, WARN, ERROR, CRIT, ALERT, FATAL, EMERG) 149 * @return true iff configuration was successful 150 */ 151 virtual bool log_config(const char* config=nullptr)=0; 152 153 /** 154 * Obtains a non-validating parser pool. 155 * <p>Library must be initialized first. 156 * 157 * @return reference to a non-validating parser pool. 158 */ 159 virtual ParserPool& getParser() const=0; 160 161 /** 162 * Obtains a validating parser pool. 163 * <p>Library must be initialized first. Schema/catalog registration must be 164 * externally synchronized. 165 * 166 * @return reference to a validating parser pool. 167 */ 168 virtual ParserPool& getValidatingParser() const=0; 169 170 /** 171 * Returns a reference to a named mutex. 172 * <p>The first access to a given name will create the object. 173 * 174 * @param name name of mutex to access 175 * @return reference to a mutex object 176 */ 177 virtual Mutex& getNamedMutex(const char* name)=0; 178 179 #ifndef XMLTOOLING_NO_XMLSEC 180 /** 181 * Returns the global KeyInfoResolver instance. 182 * 183 * @return global KeyInfoResolver or nullptr 184 */ 185 const KeyInfoResolver* getKeyInfoResolver() const; 186 187 /** 188 * Returns the global ReplayCache instance. 189 * 190 * @return global ReplayCache or nullptr 191 */ 192 ReplayCache* getReplayCache() const; 193 194 /** 195 * Returns the global DataSealer instance. 196 * 197 * @return global DataSealer or nullptr 198 */ 199 const DataSealer* getDataSealer() const; 200 201 /** 202 * Sets the global KeyInfoResolver instance. 203 * <p>This method must be externally synchronized with any code that uses the object. 204 * Any previously set object is destroyed. 205 * 206 * @param keyInfoResolver new KeyInfoResolver instance to store 207 */ 208 void setKeyInfoResolver(KeyInfoResolver* keyInfoResolver); 209 210 /** 211 * Sets the global ReplayCache instance. 212 * <p>This method must be externally synchronized with any code that uses the object. 213 * Any previously set object is destroyed. 214 * 215 * @param replayCache new ReplayCache instance to store 216 */ 217 void setReplayCache(ReplayCache* replayCache); 218 219 /** 220 * Sets the global DataSealer instance. 221 * <p>This method must be externally synchronized with any code that uses the object. 222 * Any previously set object is destroyed. 223 * 224 * @param dataSealer new DataSealer instance to store 225 */ 226 void setDataSealer(DataSealer* dataSealer); 227 #endif 228 229 /** 230 * Returns the global PathResolver instance. 231 * 232 * @return global PathResolver or nullptr 233 */ 234 PathResolver* getPathResolver() const; 235 236 /** 237 * Returns the global TemplateEngine instance. 238 * 239 * @return global TemplateEngine or nullptr 240 */ 241 TemplateEngine* getTemplateEngine() const; 242 243 /** 244 * Returns the global URLEncoder instance. 245 * 246 * @return global URLEncoder or nullptr 247 */ 248 const URLEncoder* getURLEncoder() const; 249 250 /** 251 * Sets the global PathResolver instance. 252 * <p>This method must be externally synchronized with any code that uses the object. 253 * Any previously set object is destroyed. 254 * 255 * @param pathResolver new PathResolver instance to store 256 */ 257 void setPathResolver(PathResolver* pathResolver); 258 259 /** 260 * Sets the global TemplateEngine instance. 261 * <p>This method must be externally synchronized with any code that uses the object. 262 * Any previously set object is destroyed. 263 * 264 * @param templateEngine new TemplateEngine instance to store 265 */ 266 void setTemplateEngine(TemplateEngine* templateEngine); 267 268 /** 269 * Sets the global URLEncoder instance. 270 * <p>This method must be externally synchronized with any code that uses the object. 271 * Any previously set object is destroyed. 272 * 273 * @param urlEncoder new URLEncoder instance to store 274 */ 275 void setURLEncoder(URLEncoder* urlEncoder); 276 277 /** A User-Agent header to include in HTTP client requests. */ 278 std::string user_agent; 279 280 /** 281 * Adjusts any clock comparisons to be more liberal/permissive by the 282 * indicated number of seconds. 283 */ 284 unsigned int clock_skew_secs; 285 286 #ifndef XMLTOOLING_LITE 287 /** 288 * Manages factories for StorageService plugins. 289 */ 290 PluginManager<StorageService,std::string,const xercesc::DOMElement*> StorageServiceManager; 291 #endif 292 293 #ifndef XMLTOOLING_NO_XMLSEC 294 /** 295 * Returns an X.509 CRL implementation object. 296 */ 297 virtual XSECCryptoX509CRL* X509CRL() const=0; 298 299 /** 300 * Manages factories for CredentialResolver plugins. 301 */ 302 PluginManager<CredentialResolver,std::string,const xercesc::DOMElement*> CredentialResolverManager; 303 304 /** 305 * Manages factories for KeyInfoResolver plugins. 306 */ 307 PluginManager<KeyInfoResolver,std::string,const xercesc::DOMElement*> KeyInfoResolverManager; 308 309 /** 310 * Manages factories for PathValidator plugins. 311 */ 312 PluginManager<PathValidator,std::string,const xercesc::DOMElement*> PathValidatorManager; 313 314 /** 315 * Manages factories for TrustEngine plugins. 316 */ 317 PluginManager<TrustEngine,std::string,const xercesc::DOMElement*> TrustEngineManager; 318 319 /** 320 * Manages factories for DataSealerKeyStrategy plugins. 321 */ 322 PluginManager<DataSealerKeyStrategy, std::string, const xercesc::DOMElement*> DataSealerKeyStrategyManager; 323 324 /** 325 * Maps an XML Signature/Encryption algorithm identifier to a library-specific 326 * key algorithm and size for use in resolving credentials. 327 * 328 * @param xmlAlgorithm XML Signature/Encryption algorithm identifier 329 * @return a general key algorithm and key size (or 0 if the size is irrelevant) 330 */ 331 virtual std::pair<const char*,unsigned int> mapXMLAlgorithmToKeyAlgorithm(const XMLCh* xmlAlgorithm) const=0; 332 333 /** 334 * Types of XML Security algorithms. 335 */ 336 enum XMLSecurityAlgorithmType { 337 ALGTYPE_UNK, 338 ALGTYPE_DIGEST, 339 ALGTYPE_SIGN, 340 ALGTYPE_ENCRYPT, 341 ALGTYPE_KEYENCRYPT, 342 ALGTYPE_KEYAGREE, 343 ALGTYPE_AUTHNENCRYPT 344 }; 345 346 /** 347 * Registers an XML Signature/Encryption algorithm identifier against a library-specific 348 * key algorithm and size for use in resolving credentials. 349 * 350 * @param xmlAlgorithm XML Signature/Encryption algorithm identifier 351 * @param keyAlgorithm a key algorithm 352 * @param size a key size (or 0 if the size is irrelevant) 353 * @param type type of algorithm, if known 354 */ 355 virtual void registerXMLAlgorithm( 356 const XMLCh* xmlAlgorithm, const char* keyAlgorithm, unsigned int size=0, XMLSecurityAlgorithmType type=ALGTYPE_UNK 357 )=0; 358 359 /** 360 * Checks for implementation support of a particular XML Security algorithm. 361 * 362 * @param xmlAlgorithm XML Signature/Encryption algorithm identifier 363 * @param type type of algorithm, or ALGTYPE_UNK to ignore 364 * @return true iff the algorithm is supported by the underlying libraries 365 */ 366 virtual bool isXMLAlgorithmSupported(const XMLCh* xmlAlgorithm, XMLSecurityAlgorithmType type=ALGTYPE_UNK)=0; 367 #endif 368 369 /** 370 * Manages factories for SOAPTransport plugins. 371 * 372 * <p>The factory interface takes a peer name/endpoint pair. 373 */ 374 PluginManager<SOAPTransport,std::string,SOAPTransport::Address> SOAPTransportManager; 375 }; 376 377 }; 378 379 #if defined (_MSC_VER) 380 #pragma warning( pop ) 381 #endif 382 383 #endif /* __xmltooling_config_h__ */ 384