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