Doxygen source annotation added
This commit is contained in:
@@ -24,8 +24,18 @@
|
||||
#include <atlstr.h>
|
||||
#include <WinCrypt.h>
|
||||
|
||||
///
|
||||
/// \defgroup ATLCryptoAPI Cryptography API
|
||||
/// Integrates ATL classes with Microsoft Cryptography API
|
||||
///
|
||||
/// @{
|
||||
|
||||
inline DWORD CertGetNameStringA(PCCERT_CONTEXT pCertContext, DWORD dwType, DWORD dwFlags, void *pvTypePara, ATL::CAtlStringA &sNameString)
|
||||
///
|
||||
/// Obtains the subject or issuer name from a certificate [CERT_CONTEXT](https://msdn.microsoft.com/en-us/library/windows/desktop/aa377189.aspx) structure and stores it in a ATL::CAtlStringA string.
|
||||
///
|
||||
/// \sa [CertGetNameString function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376086.aspx)
|
||||
///
|
||||
inline DWORD CertGetNameStringA(_In_ PCCERT_CONTEXT pCertContext, _In_ DWORD dwType, _In_ DWORD dwFlags, _In_ void *pvTypePara, _Out_ ATL::CAtlStringA &sNameString)
|
||||
{
|
||||
// Query the final string length first.
|
||||
DWORD dwSize = ::CertGetNameStringA(pCertContext, dwType, dwFlags, pvTypePara, NULL, 0);
|
||||
@@ -39,7 +49,12 @@ inline DWORD CertGetNameStringA(PCCERT_CONTEXT pCertContext, DWORD dwType, DWORD
|
||||
}
|
||||
|
||||
|
||||
inline DWORD CertGetNameStringW(PCCERT_CONTEXT pCertContext, DWORD dwType, DWORD dwFlags, void *pvTypePara, ATL::CAtlStringW &sNameString)
|
||||
///
|
||||
/// Obtains the subject or issuer name from a certificate [CERT_CONTEXT](https://msdn.microsoft.com/en-us/library/windows/desktop/aa377189.aspx) structure and stores it in a ATL::CAtlStringW string.
|
||||
///
|
||||
/// \sa [CertGetNameString function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376086.aspx)
|
||||
///
|
||||
inline DWORD CertGetNameStringW(_In_ PCCERT_CONTEXT pCertContext, _In_ DWORD dwType, _In_ DWORD dwFlags, _In_ void *pvTypePara, _Out_ ATL::CAtlStringW &sNameString)
|
||||
{
|
||||
// Query the final string length first.
|
||||
DWORD dwSize = ::CertGetNameStringW(pCertContext, dwType, dwFlags, pvTypePara, NULL, 0);
|
||||
@@ -53,7 +68,12 @@ inline DWORD CertGetNameStringW(PCCERT_CONTEXT pCertContext, DWORD dwType, DWORD
|
||||
}
|
||||
|
||||
|
||||
inline BOOL CryptGetHashParam(__in HCRYPTHASH hHash, __in DWORD dwParam, __out ATL::CAtlArray<BYTE> &aData, __in DWORD dwFlags)
|
||||
///
|
||||
/// Retrieves data that governs the operations of a hash object. The actual hash value can be retrieved by using this function.
|
||||
///
|
||||
/// \sa [CryptGetHashParam function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379947.aspx)
|
||||
///
|
||||
inline BOOL CryptGetHashParam(_In_ HCRYPTHASH hHash, _In_ DWORD dwParam, _Out_ ATL::CAtlArray<BYTE> &aData, _In_ DWORD dwFlags)
|
||||
{
|
||||
DWORD dwHashSize;
|
||||
|
||||
@@ -74,7 +94,12 @@ inline BOOL CryptGetHashParam(__in HCRYPTHASH hHash, __in DWORD dwParam, __out
|
||||
}
|
||||
|
||||
|
||||
inline BOOL CryptExportKey(__in HCRYPTKEY hKey, __in HCRYPTKEY hExpKey, __in DWORD dwBlobType, __in DWORD dwFlags, __out ATL::CAtlArray<BYTE> &aData)
|
||||
///
|
||||
/// Exports a cryptographic key or a key pair from a cryptographic service provider (CSP) in a secure manner.
|
||||
///
|
||||
/// \sa [CryptExportKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379931.aspx)
|
||||
///
|
||||
inline BOOL CryptExportKey(_In_ HCRYPTKEY hKey, _In_ HCRYPTKEY hExpKey, _In_ DWORD dwBlobType, _In_ DWORD dwFlags, _Out_ ATL::CAtlArray<BYTE> &aData)
|
||||
{
|
||||
DWORD dwKeyBLOBSize;
|
||||
|
||||
@@ -94,24 +119,42 @@ inline BOOL CryptExportKey(__in HCRYPTKEY hKey, __in HCRYPTKEY hExpKey, __in DWO
|
||||
return FALSE;
|
||||
}
|
||||
|
||||
/// @}
|
||||
|
||||
|
||||
namespace ATL
|
||||
{
|
||||
namespace Crypt
|
||||
{
|
||||
//
|
||||
// CCertContext
|
||||
//
|
||||
/// \addtogroup ATLCryptoAPI
|
||||
/// @{
|
||||
|
||||
///
|
||||
/// PCCERT_CONTEXT wrapper class
|
||||
///
|
||||
class CCertContext : public ATL::CObjectWithHandleDuplT<PCCERT_CONTEXT>
|
||||
{
|
||||
public:
|
||||
virtual ~CCertContext() throw()
|
||||
///
|
||||
/// Destroys the certificate context.
|
||||
///
|
||||
/// \sa [CertFreeCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376075.aspx)
|
||||
///
|
||||
virtual ~CCertContext()
|
||||
{
|
||||
if (m_h)
|
||||
CertFreeCertificateContext(m_h);
|
||||
}
|
||||
|
||||
inline BOOL Create(_In_ DWORD dwCertEncodingType, _In_ const BYTE *pbCertEncoded, _In_ DWORD cbCertEncoded) throw()
|
||||
///
|
||||
/// Creates the certificate context.
|
||||
///
|
||||
/// \return
|
||||
/// - TRUE when creation succeeds;
|
||||
/// - FALSE when creation fails. For extended error information, call `GetLastError()`.
|
||||
/// \sa [CertCreateCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376033.aspx)
|
||||
///
|
||||
inline BOOL Create(_In_ DWORD dwCertEncodingType, _In_ const BYTE *pbCertEncoded, _In_ DWORD cbCertEncoded)
|
||||
{
|
||||
HANDLE h = CertCreateCertificateContext(dwCertEncodingType, pbCertEncoded, cbCertEncoded);
|
||||
if (h) {
|
||||
@@ -122,31 +165,56 @@ namespace ATL
|
||||
}
|
||||
|
||||
protected:
|
||||
///
|
||||
/// Destroys the certificate context.
|
||||
///
|
||||
/// \sa [CertFreeCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376075.aspx)
|
||||
///
|
||||
virtual void InternalFree()
|
||||
{
|
||||
CertFreeCertificateContext(m_h);
|
||||
}
|
||||
|
||||
virtual HANDLE InternalDuplicate(HANDLE h) const
|
||||
///
|
||||
/// Duplicates the certificate context.
|
||||
///
|
||||
/// \param[in] h Object handle of existing certificate context
|
||||
/// \return Duplicated certificate context handle
|
||||
/// \sa [CertDuplicateCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376045.aspx)
|
||||
///
|
||||
virtual HANDLE InternalDuplicate(_In_ HANDLE h) const
|
||||
{
|
||||
return CertDuplicateCertificateContext(h);
|
||||
}
|
||||
};
|
||||
|
||||
|
||||
//
|
||||
// CCertChainContext
|
||||
//
|
||||
///
|
||||
/// PCCERT_CHAIN_CONTEXT wrapper class
|
||||
///
|
||||
class CCertChainContext : public ATL::CObjectWithHandleDuplT<PCCERT_CHAIN_CONTEXT>
|
||||
{
|
||||
public:
|
||||
virtual ~CCertChainContext() throw()
|
||||
///
|
||||
/// Destroys the certificate chain context.
|
||||
///
|
||||
/// \sa [CertFreeCertificateChain function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376073.aspx)
|
||||
///
|
||||
virtual ~CCertChainContext()
|
||||
{
|
||||
if (m_h)
|
||||
CertFreeCertificateChain(m_h);
|
||||
}
|
||||
|
||||
inline BOOL Create(__in_opt HCERTCHAINENGINE hChainEngine, __in PCCERT_CONTEXT pCertContext, __in_opt LPFILETIME pTime, __in_opt HCERTSTORE hAdditionalStore, __in PCERT_CHAIN_PARA pChainPara, __in DWORD dwFlags, __reserved LPVOID pvReserved) throw()
|
||||
///
|
||||
/// Creates the certificate chain context.
|
||||
///
|
||||
/// \return
|
||||
/// - TRUE when creation succeeds;
|
||||
/// - FALSE when creation fails. For extended error information, call `GetLastError()`.
|
||||
/// \sa [CertGetCertificateChain function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376078.aspx)
|
||||
///
|
||||
inline BOOL Create(_In_opt_ HCERTCHAINENGINE hChainEngine, _In_ PCCERT_CONTEXT pCertContext, _In_opt_ LPFILETIME pTime, _In_opt_ HCERTSTORE hAdditionalStore, _In_ PCERT_CHAIN_PARA pChainPara, _In_ DWORD dwFlags, __reserved LPVOID pvReserved)
|
||||
{
|
||||
HANDLE h;
|
||||
if (CertGetCertificateChain(hChainEngine, pCertContext, pTime, hAdditionalStore, pChainPara, dwFlags, pvReserved, &h)) {
|
||||
@@ -157,31 +225,56 @@ namespace ATL
|
||||
}
|
||||
|
||||
protected:
|
||||
///
|
||||
/// Destroys the certificate chain context.
|
||||
///
|
||||
/// \sa [CertFreeCertificateChain function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376073.aspx)
|
||||
///
|
||||
virtual void InternalFree()
|
||||
{
|
||||
CertFreeCertificateChain(m_h);
|
||||
}
|
||||
|
||||
virtual HANDLE InternalDuplicate(HANDLE h) const
|
||||
///
|
||||
/// Duplicates the certificate chain context.
|
||||
///
|
||||
/// \param[in] h Object handle of existing certificate chain context
|
||||
/// \return Duplicated certificate chain context handle
|
||||
/// \sa [CertDuplicateCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376045.aspx)
|
||||
///
|
||||
virtual HANDLE InternalDuplicate(_In_ HANDLE h) const
|
||||
{
|
||||
return CertDuplicateCertificateChain(h);
|
||||
}
|
||||
};
|
||||
|
||||
|
||||
//
|
||||
// CCertStore
|
||||
//
|
||||
///
|
||||
/// HCERTSTORE wrapper class
|
||||
///
|
||||
class CCertStore : public ATL::CObjectWithHandleT<HCERTSTORE>
|
||||
{
|
||||
public:
|
||||
virtual ~CCertStore() throw()
|
||||
///
|
||||
/// Closes the certificate store.
|
||||
///
|
||||
/// \sa [CertCloseStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376026.aspx)
|
||||
///
|
||||
virtual ~CCertStore()
|
||||
{
|
||||
if (m_h)
|
||||
CertCloseStore(m_h, 0);
|
||||
}
|
||||
|
||||
inline BOOL Create(__in LPCSTR lpszStoreProvider, __in DWORD dwEncodingType, __in_opt HCRYPTPROV_LEGACY hCryptProv, __in DWORD dwFlags, __in_opt const void *pvPara) throw()
|
||||
///
|
||||
/// Opens the certificate store.
|
||||
///
|
||||
/// \return
|
||||
/// - TRUE when creation succeeds;
|
||||
/// - FALSE when creation fails. For extended error information, call `GetLastError()`.
|
||||
/// \sa [CertOpenStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376559.aspx)
|
||||
///
|
||||
inline BOOL Create(_In_ LPCSTR lpszStoreProvider, _In_ DWORD dwEncodingType, _In_opt_ HCRYPTPROV_LEGACY hCryptProv, _In_ DWORD dwFlags, _In_opt_ const void *pvPara)
|
||||
{
|
||||
HANDLE h = CertOpenStore(lpszStoreProvider, dwEncodingType, hCryptProv, dwFlags, pvPara);
|
||||
if (h) {
|
||||
@@ -192,6 +285,11 @@ namespace ATL
|
||||
}
|
||||
|
||||
protected:
|
||||
///
|
||||
/// Closes the certificate store.
|
||||
///
|
||||
/// \sa [CertCloseStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376026.aspx)
|
||||
///
|
||||
virtual void InternalFree()
|
||||
{
|
||||
CertCloseStore(m_h, 0);
|
||||
@@ -199,19 +297,32 @@ namespace ATL
|
||||
};
|
||||
|
||||
|
||||
//
|
||||
// CContext
|
||||
//
|
||||
///
|
||||
/// HCRYPTPROV wrapper class
|
||||
///
|
||||
class CContext : public ATL::CObjectWithHandleT<HCRYPTPROV>
|
||||
{
|
||||
public:
|
||||
virtual ~CContext() throw()
|
||||
///
|
||||
/// Releases the cryptographi context.
|
||||
///
|
||||
/// \sa [CryptReleaseContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380268.aspx)
|
||||
///
|
||||
virtual ~CContext()
|
||||
{
|
||||
if (m_h)
|
||||
CryptReleaseContext(m_h, 0);
|
||||
}
|
||||
|
||||
inline BOOL Create(__in_opt LPCTSTR szContainer, __in_opt LPCTSTR szProvider, __in DWORD dwProvType, __in DWORD dwFlags) throw()
|
||||
///
|
||||
/// Acquires the cryptographic context.
|
||||
///
|
||||
/// \return
|
||||
/// - TRUE when creation succeeds;
|
||||
/// - FALSE when creation fails. For extended error information, call `GetLastError()`.
|
||||
/// \sa [CryptAcquireContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379886.aspx)
|
||||
///
|
||||
inline BOOL Create(_In_opt_ LPCTSTR szContainer, _In_opt_ LPCTSTR szProvider, _In_ DWORD dwProvType, _In_ DWORD dwFlags)
|
||||
{
|
||||
HANDLE h;
|
||||
if (CryptAcquireContext(&h, szContainer, szProvider, dwProvType, dwFlags)) {
|
||||
@@ -222,6 +333,11 @@ namespace ATL
|
||||
}
|
||||
|
||||
protected:
|
||||
///
|
||||
/// Releases the cryptographic context.
|
||||
///
|
||||
/// \sa [CryptReleaseContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380268.aspx)
|
||||
///
|
||||
virtual void InternalFree()
|
||||
{
|
||||
CryptReleaseContext(m_h, 0);
|
||||
@@ -229,19 +345,32 @@ namespace ATL
|
||||
};
|
||||
|
||||
|
||||
//
|
||||
// CHash
|
||||
//
|
||||
class CHash : public ATL::CObjectWithHandleT<HCRYPTHASH>
|
||||
///
|
||||
/// HCRYPTHASH wrapper class
|
||||
///
|
||||
class CHash : public ATL::CObjectWithHandleDuplT<HCRYPTHASH>
|
||||
{
|
||||
public:
|
||||
virtual ~CHash() throw()
|
||||
///
|
||||
/// Destroys the hash context.
|
||||
///
|
||||
/// \sa [CryptDestroyHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379917.aspx)
|
||||
///
|
||||
virtual ~CHash()
|
||||
{
|
||||
if (m_h)
|
||||
CryptDestroyHash(m_h);
|
||||
}
|
||||
|
||||
inline BOOL Create(__in HCRYPTPROV hProv, __in ALG_ID Algid, __in HCRYPTKEY hKey, __in DWORD dwFlags) throw()
|
||||
///
|
||||
/// Creates the hash context.
|
||||
///
|
||||
/// \return
|
||||
/// - TRUE when creation succeeds;
|
||||
/// - FALSE when creation fails. For extended error information, call `GetLastError()`.
|
||||
/// \sa [CryptCreateHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379908.aspx)
|
||||
///
|
||||
inline BOOL Create(_In_ HCRYPTPROV hProv, _In_ ALG_ID Algid, _In_ HCRYPTKEY hKey, _In_ DWORD dwFlags)
|
||||
{
|
||||
HANDLE h;
|
||||
if (CryptCreateHash(hProv, Algid, hKey, dwFlags, &h)) {
|
||||
@@ -252,26 +381,54 @@ namespace ATL
|
||||
}
|
||||
|
||||
protected:
|
||||
///
|
||||
/// Destroys the hash context.
|
||||
///
|
||||
/// \sa [CryptDestroyHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379917.aspx)
|
||||
///
|
||||
virtual void InternalFree()
|
||||
{
|
||||
CryptDestroyHash(m_h);
|
||||
}
|
||||
|
||||
///
|
||||
/// Duplicates the hash context.
|
||||
///
|
||||
/// \param[in] h Object handle of existing hash context
|
||||
/// \return Duplicated hash context handle
|
||||
/// \sa [CryptDuplicateHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379919.aspx)
|
||||
///
|
||||
virtual HANDLE InternalDuplicate(_In_ HANDLE h) const
|
||||
{
|
||||
HANDLE hNew = NULL;
|
||||
return CryptDuplicateHash(h, NULL, 0, &hNew) ? hNew : NULL;
|
||||
}
|
||||
};
|
||||
|
||||
|
||||
//
|
||||
// CKey
|
||||
//
|
||||
class CKey : public ATL::CObjectWithHandleT<HCRYPTKEY>
|
||||
///
|
||||
/// HCRYPTKEY wrapper class
|
||||
///
|
||||
class CKey : public ATL::CObjectWithHandleDuplT<HCRYPTKEY>
|
||||
{
|
||||
public:
|
||||
virtual ~CKey() throw()
|
||||
///
|
||||
/// Destroys the key.
|
||||
///
|
||||
/// \sa [CryptDestroyKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379918.aspx)
|
||||
///
|
||||
virtual ~CKey()
|
||||
{
|
||||
if (m_h)
|
||||
CryptDestroyKey(m_h);
|
||||
}
|
||||
|
||||
inline BOOL Generate(__in HCRYPTPROV hProv, __in ALG_ID Algid, __in DWORD dwFlags) throw()
|
||||
///
|
||||
/// Generates the key.
|
||||
///
|
||||
/// \sa [CryptGenKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379941.aspx)
|
||||
///
|
||||
inline BOOL Generate(_In_ HCRYPTPROV hProv, _In_ ALG_ID Algid, _In_ DWORD dwFlags)
|
||||
{
|
||||
HANDLE h;
|
||||
if (CryptGenKey(hProv, Algid, dwFlags, &h)) {
|
||||
@@ -281,7 +438,12 @@ namespace ATL
|
||||
return FALSE;
|
||||
}
|
||||
|
||||
inline BOOL Import(__in HCRYPTPROV hProv, __in_bcount(dwDataLen) CONST BYTE *pbData, __in DWORD dwDataLen, __in HCRYPTKEY hPubKey, __in DWORD dwFlags) throw()
|
||||
///
|
||||
/// Imports the key.
|
||||
///
|
||||
/// \sa [CryptImportKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380207.aspx)
|
||||
///
|
||||
inline BOOL Import(_In_ HCRYPTPROV hProv, __in_bcount(dwDataLen) CONST BYTE *pbData, _In_ DWORD dwDataLen, _In_ HCRYPTKEY hPubKey, _In_ DWORD dwFlags)
|
||||
{
|
||||
HANDLE h;
|
||||
if (CryptImportKey(hProv, pbData, dwDataLen, hPubKey, dwFlags, &h)) {
|
||||
@@ -291,7 +453,12 @@ namespace ATL
|
||||
return FALSE;
|
||||
}
|
||||
|
||||
inline BOOL ImportPublic(__in HCRYPTPROV hCryptProv, __in DWORD dwCertEncodingType, __in PCERT_PUBLIC_KEY_INFO pInfo) throw()
|
||||
///
|
||||
/// Imports the public key.
|
||||
///
|
||||
/// \sa [CryptImportPublicKeyInfo function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380209.aspx)
|
||||
///
|
||||
inline BOOL ImportPublic(_In_ HCRYPTPROV hCryptProv, _In_ DWORD dwCertEncodingType, _In_ PCERT_PUBLIC_KEY_INFO pInfo)
|
||||
{
|
||||
HANDLE h;
|
||||
if (CryptImportPublicKeyInfo(hCryptProv, dwCertEncodingType, pInfo, &h)) {
|
||||
@@ -302,10 +469,30 @@ namespace ATL
|
||||
}
|
||||
|
||||
protected:
|
||||
///
|
||||
/// Destroys the key.
|
||||
///
|
||||
/// \sa [CryptDestroyKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379918.aspx)
|
||||
///
|
||||
virtual void InternalFree()
|
||||
{
|
||||
CryptDestroyKey(m_h);
|
||||
}
|
||||
|
||||
///
|
||||
/// Duplicates the key.
|
||||
///
|
||||
/// \param[in] h Object handle of existing key
|
||||
/// \return Duplicated key handle
|
||||
/// \sa [CryptDuplicateKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379920.aspx)
|
||||
///
|
||||
virtual HANDLE InternalDuplicate(_In_ HANDLE h) const
|
||||
{
|
||||
HANDLE hNew = NULL;
|
||||
return CryptDuplicateKey(h, NULL, 0, &hNew) ? hNew : NULL;
|
||||
}
|
||||
};
|
||||
|
||||
/// @}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user