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