1 /** 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20 /* 21 * XSEC 22 * 23 * XSECPlatformUtils:= To support the platform we run in 24 * 25 * Author(s): Berin Lautenbach 26 * 27 * $Id: XSECPlatformUtils.hpp 1808174 2017-09-12 21:50:30Z scantor $ 28 * 29 */ 30 31 #ifndef XSECPLATFORMUTILS_INCLUDE 32 #define XSECPLATFORMUTILS_INCLUDE 33 34 #include <xercesc/dom/DOM.hpp> 35 36 // XSEC 37 38 #include <xsec/framework/XSECDefs.hpp> 39 #include <xsec/enc/XSECCryptoProvider.hpp> 40 41 class TXFMBase; 42 class XSECAlgorithmMapper; 43 class XSECAlgorithmHandler; 44 45 #include <stdio.h> 46 47 /** 48 * \brief High level library interface class. 49 * @ingroup internal 50 * 51 * This class is used primarily to initialise the library and 52 * communicate high level parameters that will be common to all 53 * objects from the class in any given session. 54 * 55 * It is primarily a static class. 56 */ 57 58 class XSEC_EXPORT XSECPlatformUtils { 59 60 public : 61 62 /** 63 * \brief Number of times initialise has been called 64 * 65 * initCount can be read by any class or function to determine how 66 * many times the library has been initialised. 67 */ 68 69 static int initCount; 70 71 /** 72 * \brief The main cryptographic provider 73 * 74 * This pointer can be used to determine the primary crypto 75 * provider registered in the library. 76 * 77 * Individual signatures can over-ride this default. 78 * 79 */ 80 81 static XSECCryptoProvider * g_cryptoProvider; 82 83 /** 84 * \brief The global Algorithm Mapper 85 * 86 * The algorithm mapper is used to map algorithm type URI strings 87 * to algorithm implementations. Note that this is a level of 88 * indirection above actual cryptographic algorithms. For example: 89 * 90 * URI = http://www.w3.org/2001/04/xmlenc#tripledes-cbc 91 * 92 * is the URI for 3DES in CBC mode. The mapper will return an 93 * algorithm handler that understands what this means in terms of 94 * IVs and how to call the XSECCryptoKey interface. It then uses the 95 * cryptographic provider to actually perform the encryption. 96 * 97 * This allows applications to provide new algorithm types. The 98 * mapper is used to map the type string to the means of doing the 99 * encryption, and a new XSECCryptoKey derivative can be provided 100 * to perform the actual crypo work. 101 * 102 * @note The provider should only be added to via the 103 * XSECPlatformUtils::registerAlgorithmHandler() call. 104 * 105 * @see #addAlgorithmHandler() 106 */ 107 108 static const XSECAlgorithmMapper * g_algorithmMapper; 109 110 /** 111 * \brief Initialise the library 112 * 113 * <b>Must</b> be called prior to using any functions in the library. 114 * 115 * Primarily sets up static variables used by all classes in the 116 * library. 117 * 118 * @param p A pointer to a XSECCryptoProvider object that the library 119 * should use for cryptographic functions. If p == NULL, the library 120 * will instantiate an OpenSSLCryptoProvider object. 121 */ 122 123 static void Initialise(XSECCryptoProvider * p = NULL); 124 125 /** 126 * \brief Set a new crypto provider 127 * 128 * Set the crypto provider to the value passed in. Any current provider 129 * is deleted. 130 * 131 * @note This is not thread-safe. It should be called prior to any real 132 * usage of the library. 133 * 134 * @param p A pointer to a XSECCryptoProvider object that the library 135 * should use for cryptographic functions. 136 * @note Ownership of the provider is passed to the library, which will 137 * delete it at Termination. 138 */ 139 140 static void SetCryptoProvider(XSECCryptoProvider * p); 141 142 /** 143 * \brief Add a new algorithm Handler 144 * 145 * Application developers can extend the XSECAlgorithmHandler class to 146 * implement new cryptographic algorithms. This will then allow the 147 * library to call the provided handler whenever trying to process a 148 * type it doesn't understand. 149 * 150 * Any handler previously registered for this URI will be overwritten, 151 * allowing callers to overwrite the handlers for default URIs. 152 * 153 * @see XSECAlgorithmHandler 154 * @note This is <b>not</b> thread safe. Algorithm handlers should 155 * be added prior to any processing of signatures etc. 156 * @param uri Type URI that maps to this handler 157 * @param handler The handler to be used whenever this URI is seen by 158 * the library. 159 */ 160 161 static void registerAlgorithmHandler(const XMLCh * uri, const XSECAlgorithmHandler & handler); 162 163 /** 164 * \brief Indicate an algorithm is approved for use, implying others are not. 165 * 166 * @see XSECAlgorithmHandler 167 * @note This is <b>not</b> thread safe. Algorithms should 168 * be whitelisted prior to any processing of signatures etc. 169 * @param URI algorithm to whitelist 170 */ 171 172 static void whitelistAlgorithm(const XMLCh* URI); 173 174 /** 175 * \brief Indicate an algorithm is not approved for use, implying others are. 176 * 177 * @see XSECAlgorithmHandler 178 * @note This is <b>not</b> thread safe. Algorithms should 179 * be blacklisted prior to any processing of signatures etc. 180 * @param URI algorithm to blacklist 181 */ 182 183 static void blacklistAlgorithm(const XMLCh* URI); 184 185 typedef TXFMBase* TransformFactory(XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument*); 186 187 /** 188 * \brief Installs logging support during Reference processing 189 * 190 * The function provided will be called during Reference computation 191 * to obtain a transform interface to place at the end of the 192 * transform chain. It will be given the chance to log or preserve 193 * the result of applying transforms to References during signing 194 * and verification operations. 195 */ 196 static void SetReferenceLoggingSink(TransformFactory* factory); 197 198 /** 199 * \brief Returns a transform for logging of Reference processing 200 * 201 * @param doc the DOM document containing the data being processed 202 * @return a transform to install for logging of Reference data, or NULL 203 */ 204 static TXFMBase* GetReferenceLoggingSink(XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* doc); 205 206 /** 207 * \brief Terminate 208 * 209 * Should be called prior to any program exist to allow the library 210 * to cleanly delete any memory associated with the library as a whole. 211 * 212 * @note Do not call this function while any xml-security-c object 213 * remain instantiated. The results of doing so is undefined, and could 214 * cause bad results. 215 */ 216 217 static void Terminate(void); 218 219 private: 220 static TransformFactory* g_loggingSink; 221 }; 222 223 224 #endif /* XSECPLATFORMUTILS_INCLUDE */ 225 226