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