xmltooling/security/SecurityHelper.h

   1 /*
   2  *  Copyright 2001-2009 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 <vector>
  29
  30 class XSECCryptoKey;
  31 class XSECCryptoX509;
  32
  33 namespace xmltooling {
  34     class XMLTOOL_API Credential;
  35     class XMLTOOL_API SOAPTransport;
  36     class XMLTOOL_API XSECCryptoX509CRL;
  37
  38     /**
  39      * A helper class for working with keys, certificates, etc.
  40      */
  41     class XMLTOOL_API SecurityHelper
  42     {
  43     public:
  44         /**
  45          * Access a file to try and guess the encoding format used.
  46          *
  47          * @param pathname  path to file
  48          * @return  constant identifying encoding format
  49          */
  50         static const char* guessEncodingFormat(const char* pathname);
  51
  52         /**
  53          * Loads a private key from a local file.
  54          *
  55          * @param pathname  path to file containing key
  56          * @param format    optional constant identifying key encoding format
  57          * @param password  optional password to decrypt key
  58          * @return  a populated key object
  59          */
  60         static XSECCryptoKey* loadKeyFromFile(const char* pathname, const char* format=NULL, const char* password=NULL);
  61
  62         /**
  63          * Loads certificate(s) from a local file.
  64          *
  65          * @param certs     array to populate with certificate(s)
  66          * @param pathname  path to file containing certificate(s)
  67          * @param format    optional constant identifying certificate encoding format
  68          * @param password  optional password to decrypt certificate(s)
  69          * @return  size of the resulting array
  70          */
  71         static std::vector<XSECCryptoX509*>::size_type loadCertificatesFromFile(
  72             std::vector<XSECCryptoX509*>& certs, const char* pathname, const char* format=NULL, const char* password=NULL
  73             );
  74
  75         /**
  76          * Loads CRL(s) from a local file.
  77          *
  78          * @param crls      array to populate with CRL(s)
  79          * @param pathname  path to file containing CRL(s)
  80          * @param format    optional constant identifying CRL encoding format
  81          * @return  size of the resulting array
  82          */
  83         static std::vector<XSECCryptoX509CRL*>::size_type loadCRLsFromFile(
  84             std::vector<XSECCryptoX509CRL*>& crls, const char* pathname, const char* format=NULL
  85             );
  86
  87         /**
  88          * Loads a private key from a URL.
  89          *
  90          * @param transport object to use to acquire key
  91          * @param backing   backing file for key (written to or read from if download fails)
  92          * @param format    optional constant identifying key encoding format
  93          * @param password  optional password to decrypt key
  94          * @return  a populated key object
  95          */
  96         static XSECCryptoKey* loadKeyFromURL(SOAPTransport& transport, const char* backing, const char* format=NULL, const char* password=NULL);
  97
  98         /**
  99          * Loads certificate(s) from a URL.
 100          *
 101          * @param certs     array to populate with certificate(s)
 102          * @param transport object to use to acquire certificate(s)
 103          * @param backing   backing file for certificate(s) (written to or read from if download fails)
 104          * @param format    optional constant identifying certificate encoding format
 105          * @param password  optional password to decrypt certificate(s)
 106          * @return  size of the resulting array
 107          */
 108         static std::vector<XSECCryptoX509*>::size_type loadCertificatesFromURL(
 109             std::vector<XSECCryptoX509*>& certs, SOAPTransport& transport, const char* backing, const char* format=NULL, const char* password=NULL
 110             );
 111
 112         /**
 113          * Loads CRL(s) from a URL.
 114          *
 115          * @param crls      array to populate with CRL(s)
 116          * @param transport object to use to acquire CRL(s)
 117          * @param backing   backing file for CRL(s) (written to or read from if download fails)
 118          * @param format    optional constant identifying CRL encoding format
 119          * @return  size of the resulting array
 120          */
 121         static std::vector<XSECCryptoX509CRL*>::size_type loadCRLsFromURL(
 122             std::vector<XSECCryptoX509CRL*>& crls, SOAPTransport& transport, const char* backing, const char* format=NULL
 123             );
 124
 125         /**
 126          * Compares two keys for equality.
 127          *
 128          * @param key1 first key to compare
 129          * @param key2 second key to compare
 130          * @return  true iff the keys match
 131          */
 132         static bool matches(const XSECCryptoKey& key1, const XSECCryptoKey& key2);
 133
 134         /**
 135          * Returns the base64-encoded DER encoding of a public key in SubjectPublicKeyInfo format.
 136          *
 137          * @param cred      the credential containing the key to encode
 138          * @param hash      if true, the DER encoded data is hashed with SHA-1 before base64 encoding
 139          * @param nowrap    if true, any linefeeds will be stripped from the result
 140          * @return  the base64 encoded key value
 141          */
 142         static std::string getDEREncoding(const Credential& cred, bool hash=false, bool nowrap=true);
 143
 144         /**
 145          * Returns the base64-encoded DER encoding of a public key in SubjectPublicKeyInfo format.
 146          *
 147          * @param key       the key to encode
 148          * @param hash      if true, the DER encoded data is hashed with SHA-1 before base64 encoding
 149          * @param nowrap    if true, any linefeeds will be stripped from the result
 150          * @return  the base64 encoded key value
 151          */
 152         static std::string getDEREncoding(const XSECCryptoKey& key, bool hash=false, bool nowrap=true);
 153
 154         /**
 155          * Returns the base64-encoded DER encoding of a certifiate's public key in SubjectPublicKeyInfo format.
 156          *
 157          * @param cert      the certificate's key to encode
 158          * @param hash      if true, the DER encoded data is hashed with SHA-1 before base64 encoding
 159          * @param nowrap    if true, any linefeeds will be stripped from the result
 160          * @return  the base64 encoded key value
 161          */
 162         static std::string getDEREncoding(const XSECCryptoX509& cert, bool hash=false, bool nowrap=true);
 163     };
 164 };
 165
 166 #endif /* __xmltooling_sechelper_h__ */