xmltooling/security/SecurityHelper.h

   1 /*
   2  *  Copyright 2001-2010 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 xmltooling/security/SecurityHelper.h
  19  *
  20  * A helper class for working with keys, certificates, etc.
  21  */
  22
  23 #if !defined(__xmltooling_sechelper_h__) && !defined(XMLTOOLING_NO_XMLSEC)
  24 #define __xmltooling_sechelper_h__
  25
  26 #include <xmltooling/base.h>
  27
  28 #include <string>
  29 #include <vector>
  30
  31 class XSECCryptoKey;
  32 class XSECCryptoX509;
  33
  34 namespace xmltooling {
  35     class XMLTOOL_API Credential;
  36     class XMLTOOL_API SOAPTransport;
  37     class XMLTOOL_API XSECCryptoX509CRL;
  38
  39     /**
  40      * A helper class for working with keys, certificates, etc.
  41      */
  42     class XMLTOOL_API SecurityHelper
  43     {
  44     public:
  45         /**
  46          * Access a file to try and guess the encoding format used.
  47          *
  48          * @param pathname  path to file
  49          * @return  constant identifying encoding format
  50          */
  51         static const char* guessEncodingFormat(const char* pathname);
  52
  53         /**
  54          * Loads a private key from a local file.
  55          *
  56          * @param pathname  path to file containing key
  57          * @param format    optional constant identifying key encoding format
  58          * @param password  optional password to decrypt key
  59          * @return  a populated key object
  60          */
  61         static XSECCryptoKey* loadKeyFromFile(const char* pathname, const char* format=nullptr, const char* password=nullptr);
  62
  63         /**
  64          * Loads certificate(s) from a local file.
  65          *
  66          * @param certs     array to populate with certificate(s)
  67          * @param pathname  path to file containing certificate(s)
  68          * @param format    optional constant identifying certificate encoding format
  69          * @param password  optional password to decrypt certificate(s)
  70          * @return  size of the resulting array
  71          */
  72         static std::vector<XSECCryptoX509*>::size_type loadCertificatesFromFile(
  73             std::vector<XSECCryptoX509*>& certs, const char* pathname, const char* format=nullptr, const char* password=nullptr
  74             );
  75
  76         /**
  77          * Loads CRL(s) from a local file.
  78          *
  79          * @param crls      array to populate with CRL(s)
  80          * @param pathname  path to file containing CRL(s)
  81          * @param format    optional constant identifying CRL encoding format
  82          * @return  size of the resulting array
  83          */
  84         static std::vector<XSECCryptoX509CRL*>::size_type loadCRLsFromFile(
  85             std::vector<XSECCryptoX509CRL*>& crls, const char* pathname, const char* format=nullptr
  86             );
  87
  88         /**
  89          * Loads a private key from a URL.
  90          *
  91          * @param transport object to use to acquire key
  92          * @param backing   backing file for key (written to or read from if download fails)
  93          * @param format    optional constant identifying key encoding format
  94          * @param password  optional password to decrypt key
  95          * @return  a populated key object
  96          */
  97         static XSECCryptoKey* loadKeyFromURL(SOAPTransport& transport, const char* backing, const char* format=nullptr, const char* password=nullptr);
  98
  99         /**
 100          * Loads certificate(s) from a URL.
 101          *
 102          * @param certs     array to populate with certificate(s)
 103          * @param transport object to use to acquire certificate(s)
 104          * @param backing   backing file for certificate(s) (written to or read from if download fails)
 105          * @param format    optional constant identifying certificate encoding format
 106          * @param password  optional password to decrypt certificate(s)
 107          * @return  size of the resulting array
 108          */
 109         static std::vector<XSECCryptoX509*>::size_type loadCertificatesFromURL(
 110             std::vector<XSECCryptoX509*>& certs, SOAPTransport& transport, const char* backing, const char* format=nullptr, const char* password=nullptr
 111             );
 112
 113         /**
 114          * Loads CRL(s) from a URL.
 115          *
 116          * @param crls      array to populate with CRL(s)
 117          * @param transport object to use to acquire CRL(s)
 118          * @param backing   backing file for CRL(s) (written to or read from if download fails)
 119          * @param format    optional constant identifying CRL encoding format
 120          * @return  size of the resulting array
 121          */
 122         static std::vector<XSECCryptoX509CRL*>::size_type loadCRLsFromURL(
 123             std::vector<XSECCryptoX509CRL*>& crls, SOAPTransport& transport, const char* backing, const char* format=nullptr
 124             );
 125
 126         /**
 127          * Compares two keys for equality.
 128          *
 129          * @param key1 first key to compare
 130          * @param key2 second key to compare
 131          * @return  true iff the keys match
 132          */
 133         static bool matches(const XSECCryptoKey& key1, const XSECCryptoKey& key2);
 134
 135         /**
 136          * Performs a hash operation over the supplied data.
 137          *
 138          * @param hashAlg   name of hash algorithm, syntax specific to crypto provider
 139          * @param buf       input data to hash
 140          * @param buflen    length of input data
 141          * @param toHex     if true, hex-encodes the resulting raw bytes
 142          * @return  result of hash operation, or an empty string
 143          */
 144         static std::string doHash(const char* hashAlg, const char* buf, unsigned long buflen, bool toHex=true);
 145
 146         /**
 147          * Returns the base64-encoded DER encoding of a public key in SubjectPublicKeyInfo format.
 148          * <p>If a hash algorithm is provided, the data is digested before being base64-encoded.
 149          *
 150          * @param cred      the credential containing the key to encode
 151          * @param hash      optional name of hash algorithm, syntax specific to crypto provider
 152          * @param nowrap    if true, any linefeeds will be stripped from the result
 153          * @return  the base64 encoded key value
 154          */
 155         static std::string getDEREncoding(const Credential& cred, const char* hash, bool nowrap=true);
 156
 157         /**
 158          * Returns the base64-encoded DER encoding of a public key in SubjectPublicKeyInfo format.
 159          * <p>If a hash algorithm is provided, the data is digested before being base64-encoded.
 160          *
 161          * @param key       the key to encode
 162          * @param hash      optional name of hash algorithm, syntax specific to crypto provider
 163          * @param nowrap    if true, any linefeeds will be stripped from the result
 164          * @return  the base64 encoded key value
 165          */
 166         static std::string getDEREncoding(const XSECCryptoKey& key, const char* hash, bool nowrap=true);
 167
 168         /**
 169          * Returns the base64-encoded DER encoding of a certifiate's public key in SubjectPublicKeyInfo format.
 170          * <p>If a hash algorithm is provided, the data is digested before being base64-encoded.
 171          *
 172          * @param cert      the certificate's key to encode
 173          * @param hash      optional name of hash algorithm, syntax specific to crypto provider
 174          * @param nowrap    if true, any linefeeds will be stripped from the result
 175          * @return  the base64 encoded key value
 176          */
 177         static std::string getDEREncoding(const XSECCryptoX509& cert, const char* hash, bool nowrap=true);
 178
 179         /**
 180          * @deprecated
 181          * Returns the base64-encoded DER encoding of a public key in SubjectPublicKeyInfo format.
 182          *
 183          * @param cred      the credential containing the key to encode
 184          * @param hash      if true, the DER encoded data is hashed with SHA-1 before base64 encoding
 185          * @param nowrap    if true, any linefeeds will be stripped from the result
 186          * @return  the base64 encoded key value
 187          */
 188         static std::string getDEREncoding(const Credential& cred, bool hash=false, bool nowrap=true);
 189
 190         /**
 191          * @deprecated
 192          * Returns the base64-encoded DER encoding of a public key in SubjectPublicKeyInfo format.
 193          *
 194          * @param key       the key to encode
 195          * @param hash      if true, the DER encoded data is hashed with SHA-1 before base64 encoding
 196          * @param nowrap    if true, any linefeeds will be stripped from the result
 197          * @return  the base64 encoded key value
 198          */
 199         static std::string getDEREncoding(const XSECCryptoKey& key, bool hash=false, bool nowrap=true);
 200
 201         /**
 202          * @deprecated
 203          * Returns the base64-encoded DER encoding of a certificate's public key in SubjectPublicKeyInfo format.
 204          *
 205          * @param cert      the certificate's key to encode
 206          * @param hash      if true, the DER encoded data is hashed with SHA-1 before base64 encoding
 207          * @param nowrap    if true, any linefeeds will be stripped from the result
 208          * @return  the base64 encoded key value
 209          */
 210         static std::string getDEREncoding(const XSECCryptoX509& cert, bool hash=false, bool nowrap=true);
 211
 212         /**
 213          * Decodes a DER-encoded public key.
 214          *
 215          * @param buf       DER encoded data
 216          * @param buflen    length of data in bytes
 217          * @param base64    true iff DER is base64-encoded
 218          * @return  the decoded public key, or nullptr
 219          */
 220         static XSECCryptoKey* fromDEREncoding(const char* buf, unsigned long buflen, bool base64=true);
 221
 222         /**
 223          * Decodes a base64-encoded and DER-encoded public key.
 224          *
 225          * @param buf       base64 and DER encoded data
 226          * @return  the decoded public key, or nullptr
 227          */
 228         static XSECCryptoKey* fromDEREncoding(const XMLCh* buf);
 229     };
 230 };
 231
 232 #endif /* __xmltooling_sechelper_h__ */