CPKIFCAPI2 Class Reference

#include <PKIFCAPI2.h>

Inheritance diagram for CPKIFCAPI2:

[legend]

Collaboration diagram for CPKIFCAPI2:

[legend]

List of all members.

Detailed Description

Applications do not typically operate directly on colleague objects. Information provided in this section is intended for developers exercising this class with non-default template parameters or creating custom colleagues that implement similar functionality.

This colleague class provides a PKIF interface to Microsoft CAPI functionality for stored key operations. The class takes following constructor parameters (default values are indicated):

CPKIFCAPI2(const char* provider = NULL, int provType = 0,

int sysStoRegLoc = CERT_SYSTEM_STORE_CURRENT_USER);

The provider and provType parameters can be used to lock an instance of CPKIFCAPI2 to a specific cryptographic provider. These parameters are used to invoke the CAPI function CryptAcquireContext. For information on CAPI functions consult MSDN:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/security/security/cryptography_reference.asp

The sysStoRegLoc function is used to identify the certificate store location used when generating a list of available keys. The "MY" store is always opened in the location specified by the template parameter via a call to CertOpenStore. As above, consult MSDN for further information regarding any CAPI calls.

The default constructor parameters result in an instance that will support any cryptographic service provider using keys located in the "MY" certificate store of the current user registry location. Below are some example alternative uses of CPKIFCAPI2:

const char* g_csp = "ActivCard Gold Cryptographic Service Provider"; 
void somefunc()
{
    vector<CPKIFCredentialPtr> v;
    vector<CPKIFCredentialPtr>::iterator pos;
    vector<CPKIFCredentialPtr>::iterator end;v

    //create an instance targeting local machine cert store
    //then get credential list and display credential names
    CPKIFCAPI2 localStore(NULL,NULL,CERT_SYSTEM_STORE_LOCAL_MACHINE);
    localStore.GetKeyList(v);
    for(pos = v.begin(), end = v.end(); pos != end; ++pos)v
        cout << (*pos)->Name() << endl;

    //empty the list
    v.clear();

    //create an instance targeting ActivCard CSP based keys only
    //then get credential list and display credential names
    CPKIFCAPI2 curUserActivCardOnly(g_csp, PROV_RSA_FULL);
    curUserActivCardOnly.GetKeyList(v);
    for(pos = v.begin(), end = v.end(); pos != end; ++pos)
        cout << (*pos)->Name() << endl;
}

TSP-enforcing: No

Definition at line 92 of file PKIFCAPI2.h.


Public Member Functions
	CPKIFCAPI2 (const char *provider=NULL, int provType=0, int sysStoRegLoc=CERT_SYSTEM_STORE_CURRENT_USER)
virtual	~CPKIFCAPI2 (void)
void	Initialize ()
void	GetKeyList (CPKIFCredentialList &v, std::bitset< 9 > *=NULL)
void	GetKeyList (CPKIFCredentialList &v, CPKIFKeyUsagePtr &ku)
bool	OwnsKey (const CPKIFCredential &keyID) const
CPKIFCredentialPtr	MakeKeyID (const std::string &asciiHexKeyID)
void	Sign (const CPKIFCredential &key, unsigned char pHashData, int nHashDataLen, unsigned char pSignature, int *nSignatureLen, PKIFCRYPTO::HASH_ALG hashAlg)
void	Decrypt (const CPKIFCredential &key, unsigned char pData, int nDataLen, unsigned char pResult, int *pnResultLen)
void	Encrypt (const CPKIFCredential &key, unsigned char pData, int nDataLen, unsigned char pResult, int *pnResultLen)
bool	Verify (const CPKIFCredential &key, unsigned char pHashData, int nHashDataLen, unsigned char pSignature, int nSignatureLen, PKIFCRYPTO::HASH_ALG hashAlg)
IPKIFCryptContext *	CryptInit (CPKIFCredentialPtr &key, bool pad=true)
void	Decrypt (IPKIFCryptContext cryptContext, unsigned char pData, int nDataLen, unsigned char pResult, int pnResultLen, bool final)
void	Encrypt (IPKIFCryptContext cryptContext, unsigned char pData, int nDataLen, unsigned char pResult, int pnResultLen, bool final)
Friends
struct	CPKIFCAPI2Impl

Constructor & Destructor Documentation

CPKIFCAPI2::CPKIFCAPI2	(	const char *	provider = `NULL`,
		int	provType = `0`,
		int	sysStoRegLoc = `CERT_SYSTEM_STORE_CURRENT_USER`
	)

Interface: External

This function creates CPKIFCAPI2 objects. As with all colleague objects, a call to Initialize is necessary before using instances of this class, i.e. construction and initialization requires two steps.

Returns:: None

Parameters:

provider	[in] Specifies specific cryptographic provider.
provType	[in] Specifies the type of the cryptographic provider.
sysStoRegLoc	[in] Identifies the certificate store location.

Definition at line 88 of file PKIFCAPI2.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_CAPI.

CPKIFCAPI2::~CPKIFCAPI2 ( void ) [virtual]

Interface: External

This function destroys CPKIFCAPI2 objects.

Returns:: None

Definition at line 129 of file PKIFCAPI2.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_CAPI.

Member Function Documentation

void CPKIFCAPI2::Initialize ( void ) [virtual]

Interface: External

This function initializes an instance of CPKIFCAPI2 for use.

Returns:: None

Reimplemented from IPKIFColleague.

Definition at line 163 of file PKIFCAPI2.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_CAPI.

void CPKIFCAPI2::GetKeyList	(	CPKIFCredentialList &	v,
		std::bitset< 9 > *	ku = `NULL`
	)			`[virtual]`

Interface: External

This function returns a list of available credentials. The returned list is scoped by the ku parameter passed to this function and the constructor parameters associated with the instance on which this function is invoked. Credentials must match at least one of the key usage bits identified by the ku parameter. This function may generate an exception containing the following error code PKIFCAPI_FAILED_TO_OPEN_CERT_STORE.

Returns:: None

Exceptions:

	CPKIFCryptoException(PKIFCAPI_FAILED_TO_OPEN_CERT_STORE)
	CPKIFCryptoException(COMMON_UNKNOWN_ERROR)

Parameters:

v	[out] Reference to a list of CPKIFCredential objects
ku	[in] Pointer to a bitset indicating the types of keys to return

Implements IPKIFCryptoKeyIDOperations.

Definition at line 473 of file PKIFCAPI2.cpp.

References CertHasKey(), COMMON_UNKNOWN_ERROR, keyUsageTest(), LOG_STRING_DEBUG, PKIFCAPI_FAILED_TO_OPEN_CERT_STORE, RAISE_CRYPTO_EXCEPTION, and TOOLKIT_CRYPTO_CAPI.

Referenced by GetKeyList().

void CPKIFCAPI2::GetKeyList	(	CPKIFCredentialList &	v,
		CPKIFKeyUsagePtr &	ku
	)			`[virtual]`

Interface: External

This function returns a list of available credentials. The returned list is scoped by the ku parameter passed to this function and the constructor parameters associated with the instance on which this function is invoked. Credentials must match at least one of the key usage bits identified by the ku parameter.

Returns:: None

Exceptions:

	CPKIFCryptoException(PKIFCAPI_FAILED_TO_OPEN_CERT_STORE)
	CPKIFCryptoException(COMMON_UNKNOWN_ERROR)

Parameters:

v	[out] Reference to a list of CPKIFCredential objects
ku	[in] Areference to a smart pointer to a CPKIFKeyUsage object indicating the types of keys to return

Implements IPKIFCryptoKeyIDOperations.

Definition at line 450 of file PKIFCAPI2.cpp.

References GetKeyList().

bool CPKIFCAPI2::OwnsKey ( const CPKIFCredential & keyID ) const [virtual]

Interface: External

This function is not typically invoked by applications. Mediators use this function to determine if a specific colleague is associated with a given credential prior to invoking a operation on the colleague using the credential.

Returns:: This function returns true if the credential passed via the keyID parameter is compatible with an instance of CPKIFCAPI2.

Parameters:

keyID

[in] Reference to a smart pointer to a CPKIFCredential object to check

Implements IPKIFCryptoKeyManagement.

Definition at line 417 of file PKIFCAPI2.cpp.

References LOG_STRING_DEBUG, CPKIFCAPICredential2::ProviderInfoMatches(), and TOOLKIT_CRYPTO_CAPI.

CPKIFCredentialPtr CPKIFCAPI2::MakeKeyID ( const std::string & asciiHexKeyID ) [virtual]

Interface: External

This function is not typically invoked by applications. Mediators use this function to create a credential object given an ASCII Hex key identifier string. This function may generate an exception containing the following error code PKIFCAPI_FAILED_TO_OPEN_CERT_STORE.

Returns:: This function returns a smart pointer to CPKIFCredential containing the created credential object.

Exceptions:

	CPKIFCryptoException(PKIFCAPI_FAILED_TO_OPEN_CERT_STORE)
	CPKIFCryptoException(COMMON_INVALID_INPUT)

Parameters:

asciiHexKeyID

[in] Reference to a std::string object containing a NULL-terminated ASCII hexadecimal representation of a key identifier

Implements IPKIFCryptoKeyManagement.

Definition at line 569 of file PKIFCAPI2.cpp.

References atob(), CLEANUP, COMMON_INVALID_INPUT, FormatErrorMessage(), LOG_STRING_DEBUG, PKIFCAPI_FAILED_TO_OPEN_CERT_STORE, RAISE_CRYPTO_EXCEPTION, TOOLKIT_CRYPTO, and TOOLKIT_CRYPTO_CAPI.

void CPKIFCAPI2::Sign	(	const CPKIFCredential &	key,
		unsigned char *	pHashData,
		int	nHashDataLen,
		unsigned char *	pSignature,
		int *	nSignatureLen,
		PKIFCRYPTO::HASH_ALG	hashAlg
	)			`[virtual]`

Interface: External

PKIF was designed to function with common access cards. No support has been provided for signature generation using raw key material.

This function takes a reference to a credential object.

All Sign functions assume the data passed is a hash of the data to be signed, i.e. these functions perform no hashing.

This function may generate an exception containing one of the following error codes PKIFCAPI_SIGN _FAILED, PKIFCAPI_GET_USER_KEY _FAILED, PKIFCAPI_SET_PASSWORD_FAILED and CRYPTO_UNRECOGNIZED_CREDENTIAL.

Returns:: None

Exceptions:

	CPKIFCryptoException(PKIFCAPI_SIGN	_FAILED)
	CPKIFCryptoException(PKIFCAPI_GET_USER_KEY_FAILED)
	CPKIFCryptoException(PKIFCAPI_SET_PASSWORD_FAILED)
	CPKIFCryptoException(CRYPTO_UNRECOGNIZED_CREDENTIAL)
	CPKIFCryptoException(PKIFCAPI_MISC_HASH_CALL_FAILED)
	CPKIFCryptoException(PKIFCAPI_CREATE_HASH_FAILED)
	CPKIFCryptoException(PKIFCAPI_SIGN_FAILED)
	CPKIFCryptoException(PKIFCAPI_ACQUIRE_CONTEXT_FAILED)

Parameters:

key	[in] Reference to a CPKIFCredential object containing key material to use for signature generation
pHashData	[in] Pointer to a buffer containing the message digest to sign
nHashDataLen	[in] Integer indicating the length of the buffer passed via the pHashData parameter
pSignature	[out] Pointer to a buffer to receive the generated digital signature
nSignatureLen	[in/out] Pointer to a integer used to pass the size of the pSignature buffer to Sign and to return the size of the generated signature from Sign
hashAlg	[in] Hash algorithm used in the signature

Implements IPKIFCryptoKeyIDOperations.

Definition at line 684 of file PKIFCAPI2.cpp.

References CLEANUP, CRYPTO_UNRECOGNIZED_CREDENTIAL, DSA_CLASS, FormatErrorMessage(), GetAlgClass(), CPKIFCredential::GetCertificate(), GetHashAlg(), LOG_STRING_DEBUG, CPKIFCAPICredential2::m_keyProviderInfo, CPKIFCAPICredential2::m_password, PKIFCAPI_ACQUIRE_CONTEXT_FAILED, PKIFCAPI_CREATE_HASH_FAILED, PKIFCAPI_GET_USER_KEY_FAILED, PKIFCAPI_MISC_HASH_CALL_FAILED, PKIFCAPI_SET_PASSWORD_FAILED, PKIFCAPI_SIGN_FAILED, RAISE_CRYPTO_EXCEPTION, ReverseBytes(), CPKIFCAPICredential2::SetKeyProviderInfo(), and TOOLKIT_CRYPTO_CAPI.

void CPKIFCAPI2::Decrypt	(	const CPKIFCredential &	key,
		unsigned char *	pData,
		int	nDataLen,
		unsigned char *	pResult,
		int *	pnResultLen
	)			`[virtual]`

Interface: External

This function performs decryption using asymmetric key material.

This function may generate an exception containing one of the following error codes PKIFCAPI_DECRYPT _FAILED, PKIFCAPI_GET_USER_KEY _FAILED, PKIFCAPI_SET_PASSWORD_FAILED and CRYPTO_UNRECOGNIZED_CREDENTIAL.

Returns:: None

Exceptions:

	CPKIFCryptoException(PKIFCAPI_DECRYPT_FAILED)
	CPKIFCryptoException(PKIFCAPI_GET_USER_KEY_FAILED)
	CPKIFCryptoException(PKIFCAPI_SET_PASSWORD_FAILED)
	CPKIFCryptoException(CRYPTO_UNRECOGNIZED_CREDENTIAL)
	CPKIFCryptoException(PKIFCAPI_ACQUIRE_CONTEXT_FAILED)

Parameters:

key	[in] Reference to a CPKIFCredential object associated with the key material to use when decrypting the data
pData	[in] Pointer to a buffer containing ciphertext to decrypt
nDataLen	[in] Integer indicating the size of the buffer passed via the pData parameter
pResult	[out] Pointer to a buffer to receive the decrypted data
pnResultLen	[in/out] Pointer to an integer used to pass the size of the pResult parameter to Decrypt and to return the size of the decrypted data from

Implements IPKIFCryptoKeyIDOperations.

Definition at line 854 of file PKIFCAPI2.cpp.

References CLEANUP, CRYPTO_UNRECOGNIZED_CREDENTIAL, g_bytesReversed, LOG_STRING_DEBUG, CPKIFCAPICredential2::m_certContext, CPKIFCAPICredential2::m_keyProviderInfo, CPKIFCAPICredential2::m_password, PKIFCAPI_ACQUIRE_CONTEXT_FAILED, PKIFCAPI_DECRYPT_FAILED, PKIFCAPI_GET_USER_KEY_FAILED, PKIFCAPI_SET_PASSWORD_FAILED, RAISE_CRYPTO_EXCEPTION, REV, ReverseBytes(), CPKIFCAPICredential2::SetKeyProviderInfo(), stricmp, TOOLKIT_CRYPTO_CAPI, and UNSET.

void CPKIFCAPI2::Encrypt	(	const CPKIFCredential &	key,
		unsigned char *	pData,
		int	nDataLen,
		unsigned char *	pResult,
		int *	pnResultLen
	)			`[virtual]`

Interface: External

This function performs encryption using asymmetric key material. Two versions are provided: a call that takes a credential and a call that takes a crypto context. The crypto context variant can be used when operating on large blocks of data. THIS FUNCTION IS NOT IMPLEMENTED

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_NOT_IMPLEMENTED)

Parameters:

key	[in] Reference to a CPKIFCredential object associated with the key material to use when encrypting the data
pData	[in] Pointer to a buffer containing plaintext to encrypt
nDataLen	[in] Integer indicating the size of the buffer passed via the pData parameter
pResult	[out] Pointer to a buffer to receive the encrypted data
pnResultLen	[in/out] Pointer to an integer used to pass the size of the pResult parameter to Encrypt and to return the size of the encrypted data from Encrypt

Implements IPKIFCryptoKeyIDOperations.

Definition at line 981 of file PKIFCAPI2.cpp.

References COMMON_NOT_IMPLEMENTED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_CAPI.

bool CPKIFCAPI2::Verify	(	const CPKIFCredential &	key,
		unsigned char *	pHashData,
		int	nHashDataLen,
		unsigned char *	pSignature,
		int	nSignatureLen,
		PKIFCRYPTO::HASH_ALG	hashAlg
	)			`[virtual]`

Interface: External

This function verifies a digital signature over the given data using the public key from the specified credential. All Verify functions assume the data passed is a hash of the data to be verified, i.e. this function perform no hashing. THIS FUNCTION IS NOT IMPLEMENTED

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_NOT_IMPLEMENTED)

Parameters:

key	[in] Reference to a CPKIFCredential object associated with the key material to use when verifying the signature
pHashData	[in] Pointer to a buffer containing the message digest that was signed to produce the signature conveyed via the pSignature parameter
nHashDataLen	[in] Integer indicating the length of the value passed via the pHashData parameter
pSignature	[in] Pointer to a buffer containing the signature to verify
nSignatureLen	[in] Integer indicating the size of the value passed via the pSignature parameter
hashAlg	[in] Hash algorithm used in the signature

Implements IPKIFCryptoKeyIDOperations.

Definition at line 1011 of file PKIFCAPI2.cpp.

References COMMON_NOT_IMPLEMENTED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_CAPI.

IPKIFCryptContext * CPKIFCAPI2::CryptInit	(	CPKIFCredentialPtr &	key,
		bool	pad = `true`
	)			`[virtual]`

Interface: External

This function is used to prepare a crypt context object with presented key material. The crypt context object may then be passed to operations that perform cryptographic operations using the key material. This function is typically used to prepare for operations on large amounts of data. This function may generate an exception containing one of the following error codes PKIFCAPI_GET_USER_KEY_FAILED, PKIFCAPI_SET_PASSWORD_FAILED and CRYPTO_UNRECOGNIZED_CREDENTIAL.

Returns:: None

Exceptions:

	CPKIFCryptoException(PKIFCAPI_GET_USER_KEY_FAILED)
	CPKIFCryptoException(PKIFCAPI_SET_PASSWORD_FAILED)
	CPKIFCryptoException(CRYPTO_UNRECOGNIZED_CREDENTIAL)
	CPKIFCryptoException(COMMON_INVALID_INPUT)
	CPKIFCryptoException(PKIFCAPI_ACQUIRE_CONTEXT_FAILED)
	CPKIFCryptoException(COMMON_INVALID_INPUT)

Parameters:

key	[in] Reference to a smart pointer to a CPKIFCredential object associated with stored key material to use for a cryptographic operation
pad	[in] Boolean value indicating if padding will be applied

Implements IPKIFCryptoKeyIDOperations.

Definition at line 1051 of file PKIFCAPI2.cpp.

References COMMON_INVALID_INPUT, CRYPTO_UNRECOGNIZED_CREDENTIAL, LOG_STRING_DEBUG, CPKIFCAPICredential2::m_certContext, CPKIFCAPICryptContext2::m_cred, CPKIFCAPICryptContext2::m_cryptContext, CPKIFCAPICredential2::m_keyProviderInfo, CPKIFCAPICredential2::m_password, CPKIFCAPICryptContext2::m_userKey, PKIFCAPI_ACQUIRE_CONTEXT_FAILED, PKIFCAPI_GET_USER_KEY_FAILED, PKIFCAPI_SET_PASSWORD_FAILED, RAISE_CRYPTO_EXCEPTION, CPKIFCAPICredential2::SetKeyProviderInfo(), and TOOLKIT_CRYPTO_CAPI.

void CPKIFCAPI2::Decrypt	(	IPKIFCryptContext *	cryptContext,
		unsigned char *	pData,
		int	nDataLen,
		unsigned char *	pResult,
		int *	pnResultLen,
		bool	final
	)			`[virtual]`

Interface: External

This function performs decryption using asymmetric key material.This function takes a crypto context and can be used when operating on large blocks of data. This function may generate an exception containing one of the following error codes PKIFCAPI_DECRYPT _FAILED, PKIFCAPI_GET_USER_KEY _FAILED, PKIFCAPI_SET_PASSWORD_FAILED and CRYPTO_UNRECOGNIZED_CREDENTIAL.

Returns:: None

Exceptions:

	CPKIFCryptoException(PKIFCAPI_DECRYPT	_FAILED)
	CPKIFCryptoException(PKIFCAPI_GET_USER_KEY	_FAILED)
	CPKIFCryptoException(PKIFCAPI_SET_PASSWORD_FAILED)
	CPKIFCryptoException(CRYPTO_UNRECOGNIZED_CREDENTIAL)
	CPKIFCryptoException(COMMON_INVALID_INPUT)

Parameters:

cryptContext	[in] Pointer to an IPKIFCryptContext object created via a call to CryptInit and containing the key material to use when decrypting the data
pData	[in] Pointer to a buffer containing ciphertext to decrypt
nDataLen	[in] Integer indicating the size of the buffer passed via the pData parameter
pResult	[out] Pointer to a buffer to receive the decrypted data
pnResultLen	[in/out] Pointer to an integer used to pass the size of the pResult parameter to Decrypt and to return the size of the decrypted data from
final	[in] Boolean that indicates if more data will be passed via a subsequent call to Decrypt (false if more data will be passed and true if this is the final call to Decrypt for this ciphertext)

Implements IPKIFCryptoKeyIDOperations.

Definition at line 1135 of file PKIFCAPI2.cpp.

References COMMON_INVALID_INPUT, CRYPTO_UNRECOGNIZED_CREDENTIAL, g_bytesReversed, IPKIFCryptContext::GetCredential(), LOG_STRING_DEBUG, CPKIFCAPICredential2::m_keyProviderInfo, CPKIFCAPICryptContext2::m_userKey, PKIFCAPI_DECRYPT_FAILED, RAISE_CRYPTO_EXCEPTION, REV, ReverseBytes(), stricmp, TOOLKIT_CRYPTO_CAPI, and UNSET.

void CPKIFCAPI2::Encrypt	(	IPKIFCryptContext *	cryptContext,
		unsigned char *	pData,
		int	nDataLen,
		unsigned char *	pResult,
		int *	pnResultLen,
		bool	final
	)			`[virtual]`

Interface: External

This function performs encryption using asymmetric key material. This function takes a crypto context and can be used when operating on large blocks of data. THIS FUNCTION IS NOT IMPLEMENTED

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_NOT_IMPLEMENTED)

Parameters:

cryptContext	[in] Pointer to an IPKIFCryptContext object created via a call to CryptInit and containing the key material to use when encrypting the data
pData	[in] Pointer to a buffer containing plaintext to encrypt
nDataLen	[in] Integer indicating the size of the buffer passed via the pData parameter
pResult	[out] Pointer to a buffer to receive the encrypted data
pnResultLen	[in/out] Pointer to an integer used to pass the size of the pResult parameter to Encrypt and to return the size of the encrypted data from Encrypt
final	[in] Boolean that indicates if more data will be passed via a subsequent call to Encrypt (false if more data will be passed and true if this is the final call to Encrypt for this ciphertext)

Implements IPKIFCryptoKeyIDOperations.

Definition at line 1208 of file PKIFCAPI2.cpp.

References COMMON_NOT_IMPLEMENTED.

Friends And Related Function Documentation

friend struct CPKIFCAPI2Impl [friend]

Definition at line 94 of file PKIFCAPI2.h.

The documentation for this class was generated from the following files:

CPKIFCAPI2 Class Reference

Detailed Description

Public Member Functions

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation