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