CPKIFCryptoMediator2 Class Reference

#include <CPKIFCryptoMediator2.h>

Inheritance diagram for CPKIFCryptoMediator2:

[legend]

Collaboration diagram for CPKIFCryptoMediator2:

[legend]

List of all members.

Detailed Description

As with all mediator objects, CPKIFCryptoMediator2 has two template parameters as shown in the following definition:

class CPKIFCryptoMediator2 : 
    public IPKIFMediator, 
    public IPKIFCryptoRawOperations, 
    public IPKIFCryptoKeyIDOperations, 
    public IPKIFCryptoMisc, 
    public IPKIFDefaultKeyManagement

When Boolean true is passed to CPKIFCryptoMediator2 constructor, CPKIFCryptoMediator2 is associated with the following colleagues:

    CPKIFCAPI2 
    CPKIFCAPIRaw

These colleagues provide functionality to retrieve trust roots, certificates and CRLs from the default Microsoft CAPI certificate stores. No mediators are associated with CPKIFCryptoMediator2 by default. See Associating an LDAP Directory with a CMS Object and Enabling OCSP for details on adding colleagues at runtime.

TSP-enforcing: Yes

Definition at line 57 of file CPKIFCryptoMediator2.h.


Public Member Functions
	CPKIFCryptoMediator2 (bool addDefaultColleagues=false)
virtual	~CPKIFCryptoMediator2 (void)
void	InitializeMediator (std::vector< CPKIFException * > *errorInfo)
void	Terminate ()
void	Initialize ()
void	GetColleagues (std::vector< IPKIFColleaguePtr > &v) const
void	AddColleague (IPKIFColleaguePtr &module)
const CPKIFCredentialPtr	SetDefaultKey (const std::string &asciiHexKeyID, PKIFCRYPTO::DefaultKeyType op)
CPKIFCredentialPtr	GetDefaultKey (PKIFCRYPTO::DefaultKeyType op)
void	GenRandom (unsigned char *buf, int len)
IPKIFHashContext *	HashInit (PKIFCRYPTO::HASH_ALG alg)
void	HashUpdate (IPKIFHashContext hash, unsigned char pData, int nDataLen)
void	HashFinal (IPKIFHashContext hash, unsigned char pResult, int *pnResultLen)
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)
void	GetKeyList (CPKIFCredentialList &v, std::bitset< 9 > *ku=NULL)
void	GetKeyList (CPKIFCredentialList &v, CPKIFKeyUsagePtr &ku)
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)
void	Sign (const CPKIFCredentialPtr &key, unsigned char pHashData, int nHashDataLen, unsigned char pSignature, int *nSignatureLen, PKIFCRYPTO::HASH_ALG hashAlg)
void	Decrypt (const CPKIFCredentialPtr &key, unsigned char pData, int nDataLen, unsigned char pResult, int *pnResultLen)
void	Encrypt (const CPKIFCredentialPtr &key, unsigned char pData, int nDataLen, unsigned char pResult, int *pnResultLen)
bool	Verify (const CPKIFCredentialPtr &key, unsigned char pHashData, int nHashDataLen, unsigned char pSignature, int nSignatureLen, PKIFCRYPTO::HASH_ALG hashAlg)
void	Sign (const CPKIFKeyMaterial &key, unsigned char pHashData, int nHashDataLen, unsigned char pSignature, int *nSignatureLen, PKIFCRYPTO::HASH_ALG hashAlg)
void	Encrypt (const CPKIFKeyMaterial &key, unsigned char pData, int nDataLen, unsigned char pResult, int *pnResultLen, bool pad=true)
void	Decrypt (const CPKIFKeyMaterial &key, unsigned char pData, int nDataLen, unsigned char pResult, int *pnResultLen, bool pad=true)
bool	Verify (const CPKIFKeyMaterial &key, unsigned char pHashData, int nHashDataLen, unsigned char pSignature, int nSignatureLen, PKIFCRYPTO::HASH_ALG hashAlg)
bool	VerifyCertificate (const CPKIFCertificate &issCert, const CPKIFCertificate &subCert)
IPKIFRawCryptContext *	CryptInit (const CPKIFKeyMaterial &key, bool pad=true)
void	Decrypt (IPKIFRawCryptContext cryptContext, unsigned char pData, int nDataLen, unsigned char pResult, int pnResultLen, bool final)
void	Encrypt (IPKIFRawCryptContext cryptContext, unsigned char pData, int nDataLen, unsigned char pResult, int pnResultLen, bool final)
IPKIFRawCryptContext *	HMACInit (const CPKIFKeyMaterial &key, PKIFCRYPTO::HASH_ALG ha)
void	HMACUpdate (IPKIFRawCryptContext ctx, unsigned char pData, int nDataLen)
void	HMACFinal (IPKIFRawCryptContext ctx, unsigned char pResult, int *pnResultLen)
virtual IPKIFKeyAgreeContextPtr	SecretAgree (CPKIFCredentialPtr &myPrivateKey, const CPKIFCertificatePtr &theirCert, const CPKIFAlgorithm *alg)
virtual IPKIFKeyAgreeContextPtr	SecretAgree (CPKIFCredentialPtr &myPrivateKey, const CPKIFBufferPtr &theirPublicKey, const CPKIFAlgorithm *alg)
virtual IPKIFKeyAgreeContextPtr	SecretAgree (const CPKIFCredentialPtr &myPrivateKey, CPKIFCredentialPtr &ephemeralKeyPair, const CPKIFCertificatePtr &theirCert, const CPKIFAlgorithm *alg)
virtual IPKIFKeyAgreeContextPtr	SecretAgree (const CPKIFCredentialPtr &myPrivateKey, CPKIFCredentialPtr &ephemeralKeyPair, const CPKIFBufferPtr &theirPublicKey, const CPKIFAlgorithm *alg)
virtual IPKIFKeyAgreeContextPtr	SecretAgree (const CPKIFCredentialPtr &myPrivateKey, const CPKIFBufferPtr &ephemeralPublicKey, const CPKIFCertificatePtr &theirCert, const CPKIFAlgorithm *alg)
virtual IPKIFKeyAgreeContextPtr	SecretAgree (const CPKIFCredentialPtr &myPrivateKey, const CPKIFBufferPtr &ephemeralPublicKey, const CPKIFBufferPtr &theirPublicKey, const CPKIFAlgorithm *alg)
virtual CPKIFKeyMaterialPtr	DeriveKey (const IPKIFKeyAgreeContextPtr &context, unsigned long keyLen)
virtual bool	SupportsAlgorithm (const CPKIFKeyMaterial &key)
Friends
struct	CPKIFCryptoMediator2Impl

Constructor & Destructor Documentation

CPKIFCryptoMediator2::CPKIFCryptoMediator2 ( bool addDefaultColleagues = false )

Interface: External

This function creates CPKIFCryptoMediator2 instances. If the addDefaultColleagues parameter is set to true the following colleagues CPKIFCAPI2 and CPKIFCAPIRaw will be added to the mediator upon initialization. Following construction, CPKIFCryptoMediator2 instances are not ready for use. It is necessary to call Initialize prior to exercising any functionality.

Returns:: None

Parameters:

addDefaultColleagues

[in] Boolean value, if true will force Initialize to add default colleagues to the mediator

Definition at line 94 of file CPKIFCryptoMediator2.cpp.

References LOG_STRING_DEBUG, PKIFCRYPTO::NUMDEFTYPES, PKIFCRYPTO::SIGNATURE, and TOOLKIT_CRYPTO_MEDIATOR.

CPKIFCryptoMediator2::~CPKIFCryptoMediator2 ( void ) [virtual]

Interface: External

This function destroys CPKIFCryptoMediator2 objects.

Returns:: None

Definition at line 116 of file CPKIFCryptoMediator2.cpp.

References LOG_STRING_DEBUG, Terminate(), and TOOLKIT_CRYPTO_MEDIATOR.

Member Function Documentation

void CPKIFCryptoMediator2::InitializeMediator ( std::vector< CPKIFException * > * errorInfo ) [virtual]

Interface: External

This function prepares an instance of CPKIFCryptoMediator2 for use, including initialization of all runtime-associated mediators and colleagues. If a boolean true was passed to CPKIFCryptoMediator2 constructor default colleagues CPKIFCAPI2 and CPKIFCAPIRaw will be added. By default, all mediators catch and discard these exceptions and ignore the offending colleague. Applications can review the list of exceptions that occurred during initialization by passing a non-NULL pointer to a vector of CPKIFException objects. Any exception objects returned in the vector must be freed by the application.

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_ALREADY_INITIALIZED)

Parameters:

errorInfo

[out] Pointer to a vector of exception objects to receive exceptions thrown during initialization by associated colleague objects

Reimplemented from IPKIFColleague.

Definition at line 235 of file CPKIFCryptoMediator2.cpp.

References AddColleague(), COMMON_ALREADY_INITIALIZED, LOG_STRING_DEBUG, MakeDefaultKeyIDColleague(), MakeDefaultRawColleague(), and TOOLKIT_CRYPTO_MEDIATOR.

Referenced by Initialize().

void CPKIFCryptoMediator2::Terminate ( ) [virtual]

Interface: External

This function de-initializes an instance of CPKIFCryptoMediator2 rendering it unusable until after a subsequent call to Initialize. Terminate will remove all mediator and colleague associations and will destroy any colleagues associated at runtime via AddColleague with transfer of ownership.

Returns:: None

Reimplemented from IPKIFColleague.

Definition at line 135 of file CPKIFCryptoMediator2.cpp.

References _ASSERT, COMMON_TERMINATION_ERROR, LOG_STRING_DEBUG, LOG_STRING_ERROR, LOG_STRING_FATAL, IPKIFColleague::RemoveMediatorAssociations(), RemoveParentRelationships(), IPKIFColleague::Terminate(), and TOOLKIT_CRYPTO_MEDIATOR.

Referenced by ~CPKIFCryptoMediator2().

void CPKIFCryptoMediator2::Initialize ( void ) [virtual]

Interface: External

This function prepares an instance of CPKIFCryptoMediator2 for use, including initialization of all runtime-associated mediators and colleagues. If a boolean true was passed to CPKIFCryptoMediator2 constructor default colleagues CPKIFCAPI2 and CPKIFCAPIRaw will be added.

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_ALREADY_INITIALIZED)

Reimplemented from IPKIFColleague.

Definition at line 216 of file CPKIFCryptoMediator2.cpp.

References InitializeMediator().

void CPKIFCryptoMediator2::GetColleagues ( std::vector< IPKIFColleaguePtr > & v ) const

Interface: External

This function is used retrive all the colleagues associated with this instance

Returns:: None

Parameters:

v	[out] std::vector that will contain all the colleagues assosiated with this instance

Definition at line 1824 of file CPKIFCryptoMediator2.cpp.

Referenced by GetCredential(), and SaveCryptoComponents().

void CPKIFCryptoMediator2::AddColleague ( IPKIFColleaguePtr & module )

Interface: External

This function associates a colleague at runtime. When invoked with transferOwnership equal to true, the colleague specified by the module parameter will be destroyed when Terminate is invoked.

Only colleagues that implement at least one interface of the associated mediator should be passed to AddColleague. Adding unrelated colleagues to a collection held by a mediator will decrease performance.

Returns:: None

Parameters:

module

[in] Pointer to an IPKIFColleague object

Definition at line 271 of file CPKIFCryptoMediator2.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

Referenced by InitializeMediator(), and LoadCryptoComponents().

const CPKIFCredentialPtr CPKIFCryptoMediator2::SetDefaultKey	(	const std::string &	asciiHexKeyID,
		PKIFCRYPTO::DefaultKeyType	op
	)			`[virtual]`

Interface: External

This function attempts to create a credential object corresponding to the ASCII Hex key identifier passed as asciiHexKeyID. If a credential can be created, i.e. if an associated colleague holds the key, and if the credential and operation are compatible, then the credential is set as the default for the specified operation. Possible DefaultKeyType values are SIGNATURE and DECRYPTION.

This function can be used to establish default keys for specific types of operations performed using an instance of CPKIFCryptoMediator2. Default key assignments are not persistent and do not apply across multiple instances of CPKIFCryptoMediator2.

Returns:: A smart pointer to a CPKIFCredential object is returned if a credential object corresponding the the ASCII hexadecimal key identifier passed as asciiHexKeyID can be created. Otherwise, NULL is returned.

Parameters:

asciiHexKeyID	[in] Reference to a std::string containing a NULL-terminated ASCII hexadecimal string representation of the key identifier associated with the key that should be used as the default key for the specified operation
op	[in] DefaultKeyType value indicating that type of operation for which the key identified by the asciiHexKeyID parameter should be used

Implements IPKIFDefaultKeyManagement.

Definition at line 332 of file CPKIFCryptoMediator2.cpp.

References AuditString, CAT_PKIF_CRYPTO, LOG_STRING_DEBUG, PKIF_DEFAULT_KEY_DESIGNATION, PKIFCRYPTO::SIGNATURE, and TOOLKIT_CRYPTO_MEDIATOR.

CPKIFCredentialPtr CPKIFCryptoMediator2::GetDefaultKey ( PKIFCRYPTO::DefaultKeyType op ) [virtual]

Interface: External

This function retrieves a pointer to a credential object containing the default key for the specified operation if a default key has been specified for that operation. If no default key has been specified NULL is returned. Possible DefaultKeyType values are: SIGNATURE and DECRYPTION.

Returns:: This function returns a pointer to a CPKIFCredential object containing the credential that was previously specified as the default key for the specified operation or NULL if no default key is available.

Parameters:

op	[in] DefaultKeyType value of the default credential to return

Implements IPKIFDefaultKeyManagement.

Definition at line 388 of file CPKIFCryptoMediator2.cpp.

References PKIFCRYPTO::DECRYPTION, LOG_STRING_DEBUG, PKIFCRYPTO::SIGNATURE, and TOOLKIT_CRYPTO_MEDIATOR.

void CPKIFCryptoMediator2::GenRandom	(	unsigned char *	buf,
		int	len
	)			`[virtual]`

Interface: External

This function will iterate over associated colleagues until a colleague that implements the IPKIFCryptoMisc interface is found. If a colleague is found, the GenRandom function on the colleague is invoked passing buf and len. The buf parameter must be at least len bytes in size. If a colleague is found that can fulfill the request, buf will be returned containing len bytes of random data. If no colleague is found an exception is thrown with the error code COMMON_OPERATION_NOT_HANDLED.

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED);

Implements IPKIFCryptoMisc.

Definition at line 425 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

IPKIFHashContext * CPKIFCryptoMediator2::HashInit ( PKIFCRYPTO::HASH_ALG alg ) [virtual]

Interface: External

This function will iterate over associated colleagues until a colleague that implements the IPKIFCryptoMisc interface and supports the specified hash algorithm is found. If a colleague is found, the HashInit function on the colleague is invoked passing alg and the resulting IPKIFHashContext object returned. If no colleague is found an exception is thrown with the error code COMMON_OPERATION_NOT_HANDLED. See the Performing Hash Operations sample or CPKIFCryptoMediator2::HashFinal.

Returns:: A pointer to IPKIFHashContext object

Exceptions:

CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED);

Parameters:

alg

[in] HASH_ALG value indicating the type of hash algorithm for which a hash context object should be created

Implements IPKIFCryptoMisc.

Definition at line 456 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

Referenced by CPKIFSCVPCertID::CalculateCertHash().

void CPKIFCryptoMediator2::HashUpdate	(	IPKIFHashContext *	hash,
		unsigned char *	pData,
		int	nDataLen
	)			`[virtual]`

Interface: External

This function should be invoked after calling HashInit to create a context for the target algorithm. This function may be invoked iteratively, for example, when hashing large amounts of data. See the Performing Hash Operations sample or CPKIFCryptoMediator2::HashFinal.

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

hash	[in] Pointers to an IPKIFHashContext object created by a previous call to HashInit
pData	[in] Pointer to a buffer containing data that should be hashed as part of the running hash operation
nDataLen	[in] Integer indicating the length of the buffer passed via the pData parameter

Implements IPKIFCryptoMisc.

Definition at line 492 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

Referenced by CPKIFSCVPCertID::CalculateCertHash().

void CPKIFCryptoMediator2::HashFinal	(	IPKIFHashContext *	hash,
		unsigned char *	pResult,
		int *	pnResultLen
	)			`[virtual]`

Interface: External

This function should be invoked after passing all of the desired data to HashUpdate. The pResult buffer must be at least pnResultLen bytes in size, and must be large enough to accommodate the size of the resulting hash. The hash value will be returned in pResult and the hash operation finalized, at which time the hash context is no longer valid and should be deleted. Below is an example demonstrating creation of a hash context, data updates via HashUpdate and result retrieval via HashFinal.

declare a crypto mediator and initialize it

 CPKIFCryptoMediator2 cm; 
 cm.Initialize();

create a hash context for SHA1 
 IPKIFHashContext* h = cm.HashInit(SHA1);

hash "abc" using two calls to HashUpdate 
 cm.HashUpdate(h, (unsigned char*)"a", 1); 
 cm.HashUpdate(h, (unsigned char*)"bc", 2);

get the result 
 unsigned char hashResult[20]; 
 int hashResultLen = 20; 
 cm.HashFinal(h, hashResult, &hashResultLen);

destroy the context 
 delete h;

result should be A9993E364706816ABA3E25717850C26C9CD0D89D

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

hash	[in] Pointers to an IPKIFHashContext object created by a previous call to HashInit
pResult	[out] Pointer to a buffer of sufficient size to receive the result of a hash operation
pnResultLen	[in/out] Pointer to an integer used to pass the length of the pResult parameter to HashFinal and to return the size of the hash result passed from HashFinal

Implements IPKIFCryptoMisc.

Definition at line 560 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

Referenced by CPKIFSCVPCertID::CalculateCertHash().

void CPKIFCryptoMediator2::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 the following error code CRYPTO_SIGN_FAILED.

Returns:: None

Exceptions:

	CPKIFCryptoException(CRYPTO_SIGN_FAILED)
	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

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 757 of file CPKIFCryptoMediator2.cpp.

References AuditString, CAT_PKIF_CRYPTO, COMMON_OPERATION_NOT_HANDLED, CRYPTO_SIGN_FAILED, CPKIFCredential::ID(), LOG_STRING_DEBUG, PKIF_PRIVATE_KEY_OPERATION_FAILED, PKIF_PRIVATE_KEY_OPERATION_PERFORMED, CPKIFException::print(), and TOOLKIT_CRYPTO_MEDIATOR.

Referenced by Sign().

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

Interface: External

As with most crypto-related functions there are multiple flavors of the Decrypt function: stored key material versions and raw key material versions. The stored key material version performs decryption using asymmetric key material and the raw key material version performs decryption using symmetric key material.

For each type of key material, two means of performing decryption operations are provided: calls that take key material info directly and calls that take a crypto context. The crypto context variants can be used when operating on large blocks of data. The smart pointer variant of the stored key material version can be used with a reference to a NULL pointer to use a previously specified default decryption key (see CPKIFCryptoMediator2::SetDefaultKey). This function may generate an exception containing the following error code CRYPTO_DECRYPT_FAILED.

See the Performing Symmetric Key Encryption Operations sample.

Returns:: None

Exceptions:

	CPKIFCryptoException(CRYPTO_DECRYPT_FAILED)
	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

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 Decrypt

Implements IPKIFCryptoKeyIDOperations.

Definition at line 1062 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

Referenced by Decrypt().

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

Interface: External

As with most crypto-related functions there are two flavors of the Encrypt function: a stored key material version and a raw key material version. The stored key material version performs encryption using asymmetric key material and the raw key material version performs encryption using symmetric or asymmetric key material.

For each type of key material two means of performing encryption operations are provided: calls that take key material info directly and calls that take a crypto context. The crypto context variants can be used when operating on large blocks of data.

See the Performing Symmetric Key Encryption Operations sample.

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

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 1151 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

Referenced by Encrypt().

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

Interface: External

As with most crypto-related functions, there are mutliple flavors of the Verify function: two stored key material versions and a raw key material version.

The two versions that operate on stored key materials differ only in that one takes a reference to a credential object and the other takes a reference to a credential smart pointer object.

All Verify functions assume the data passed is a hash of the data to be verified, i.e. these functions perform no hashing. This function may generate an exception containing the following error code CRYPTO_VERIFY_FAILED.

Returns:: This function returns true if the signature verifies and false otherwise. Some errors can result in exceptions.

Exceptions:

	CPKIFCryptoException(CRYPTO_VERIFY_FAILED)
	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

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 1244 of file CPKIFCryptoMediator2.cpp.

References AuditString, CAT_PKIF_CRYPTO, COMMON_OPERATION_NOT_HANDLED, CRYPTO_VERIFY_FAILED, CPKIFCredential::ID(), LOG_STRING_DEBUG, PKIF_SIGNATURE_VERIFICATION_FAILED, PKIF_SIGNATURE_VERIFICATION_SUCCEEDED, CPKIFException::print(), and TOOLKIT_CRYPTO_MEDIATOR.

Referenced by Verify().

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

Interface: External

This function will iterate over all colleagues that implement the IPKIFCryptoKeyID interface and populate the vector v with all available credentials, scoped by the optional key usage parameter ku, if present. Applications may then iterate over the list of credentials and display information about each to permit a user to select a key for use. The key usage extension of certificates associated with credentials must match at least one of the key usage bits identified by the ku parameter. Absence of a key usage extension is considered as a match.

The vector passed via v is not cleared prior to adding credentials to the list. The value passed via ku can be constructed by or�ing together values from the KeyUsage enumeration to create a std::bitset value. For example, to search for credentials that may be used for digital signature or non-repudiation purposes, ku may be set to the following:

DigitalSignature | NonRepudiation.

Returns:: None

Exceptions:

	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)
	CPKIFCryptoException(PKIFCAPI_FAILED_TO_OPEN_CERT_STORE)
	CPKIFCryptoException(COMMON_UNKNOWN_ERROR)
	CPKIFCryptoException(COMMON_MEMORY_ALLOC_FAILURE)

Parameters:

v	[out] Reference to a vector to receive smart pointers to CPKIFCredential objects
ku	[in] Pointer to a bitset indicating the types of keys to return

Implements IPKIFCryptoKeyIDOperations.

Definition at line 1779 of file CPKIFCryptoMediator2.cpp.

References AuditString, CAT_PKIF_CRYPTO, COMMON_OPERATION_NOT_HANDLED, COMMON_OPERATION_NOT_SUCCESSFUL, COMMON_UNKNOWN_ERROR, LOG_STRING_DEBUG, PKIF_UNEXPECTED_EXCEPTION, CPKIFException::print(), and TOOLKIT_CRYPTO_MEDIATOR.

Referenced by GetKeyList().

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

Interface: External

This function will iterate over all colleagues that implement the IPKIFCryptoKeyID interface and populate the vector v with all available credentials, scoped by the key usage parameter ku. Applications may then iterate over the list of credentials and display information about each to permit a user to select a key for use. The key usage extension of certificates associated with credentials must match at least one of the key usage bits identified by the ku parameter. Absence of a key usage extension is considered as a match.

Returns:: None

Exceptions:

	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)
	CPKIFCryptoException(PKIFCAPI_FAILED_TO_OPEN_CERT_STORE)
	CPKIFCryptoException(COMMON_UNKNOWN_ERROR)
	CPKIFCryptoException(COMMON_MEMORY_ALLOC_FAILURE)

Parameters:

v	[out] Reference to a vector to receive smart pointers to 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 1744 of file CPKIFCryptoMediator2.cpp.

References GetKeyList().

IPKIFCryptContext * CPKIFCryptoMediator2::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.

See the Performing Symmetric Key Encryption Operations sample.

Returns:: None

Exceptions:

	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)
	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

Implements IPKIFCryptoKeyIDOperations.

Definition at line 825 of file CPKIFCryptoMediator2.cpp.

References COMMON_INVALID_INPUT, COMMON_OPERATION_NOT_HANDLED, PKIFCRYPTO::DECRYPTION, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

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

Interface: External

As with most crypto-related functions there are multiple flavors of the Decrypt function: stored key material versions and raw key material versions. The stored key material version performs decryption using asymmetric key material and the raw key material version performs decryption using symmetric key material.

For each type of key material, two means of performing decryption operations are provided: calls that take key material info directly and calls that take a crypto context. The crypto context variants can be used when operating on large blocks of data. The smart pointer variant of the stored key material version can be used with a reference to a NULL pointer to use a previously specified default decryption key (see CPKIFCryptoMediator2::SetDefaultKey). This function may generate an exception containing the following error code CRYPTO_DECRYPT_FAILED.

See the Performing Symmetric Key Encryption Operations sample.

Returns:: None

Exceptions:

	CPKIFCryptoException(CRYPTO_DECRYPT_FAILED)
	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)
	CPKIFCryptoException(COMMON_INVALID_INPUT)

Parameters:

cryptContext	[in] Pointer to an IPKIFRawCryptContext or 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 Decrypt
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 875 of file CPKIFCryptoMediator2.cpp.

References AuditString, CAT_PKIF_CRYPTO, COMMON_INVALID_INPUT, COMMON_OPERATION_NOT_HANDLED, CRYPTO_DECRYPT_FAILED, IPKIFCryptContext::GetCredential(), LOG_STRING_DEBUG, PKIF_PRIVATE_KEY_OPERATION_FAILED, PKIF_PRIVATE_KEY_OPERATION_PERFORMED, and TOOLKIT_CRYPTO_MEDIATOR.

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

Interface: External

As with most crypto-related functions there are two flavors of the Encrypt function: a stored key material version and a raw key material version. The stored key material version performs encryption using asymmetric key material and the raw key material version performs encryption using symmetric or asymmetric key material.

For each type of key material two means of performing encryption operations are provided: calls that take key material info directly and calls that take a crypto context. The crypto context variants can be used when operating on large blocks of data.

See the Performing Symmetric Key Encryption Operations sample.

Returns:: None

Exceptions:

	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)
	CPKIFCryptoException(COMMON_INVALID_INPUT)

Parameters:

cryptContext	[in] Pointer to an IPKIFRawCryptContext or 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 950 of file CPKIFCryptoMediator2.cpp.

References COMMON_INVALID_INPUT, COMMON_OPERATION_NOT_HANDLED, IPKIFCryptContext::GetCredential(), LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

void CPKIFCryptoMediator2::Sign	(	const CPKIFCredentialPtr &	key,
		unsigned char *	pHashData,
		int	nHashDataLen,
		unsigned char *	pSignature,
		int *	nSignatureLen,
		PKIFCRYPTO::HASH_ALG	hashAlg
	)

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 smart pointer object. The smart pointer variant can be used with a reference to a NULL pointer to use a previously specified default signature key (see CPKIFCryptoMediator2::SetDefaultKey).

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 the following error code CRYPTO_SIGN_FAILED.

Returns:: None

Exceptions:

	CPKIFCryptoException(CRYPTO_SIGN_FAILED)
	CPKIFCryptoException(COMMON_INVALID_INPUT)

Parameters:

key	[in] Reference to a smart pointer 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

Definition at line 706 of file CPKIFCryptoMediator2.cpp.

References COMMON_INVALID_INPUT, LOG_STRING_DEBUG, Sign(), PKIFCRYPTO::SIGNATURE, and TOOLKIT_CRYPTO_MEDIATOR.

void CPKIFCryptoMediator2::Decrypt	(	const CPKIFCredentialPtr &	key,
		unsigned char *	pData,
		int	nDataLen,
		unsigned char *	pResult,
		int *	pnResultLen
	)

Interface: External

As with most crypto-related functions there are multiple flavors of the Decrypt function: stored key material versions and raw key material versions. The stored key material version performs decryption using asymmetric key material and the raw key material version performs decryption using symmetric key material.

For each type of key material, two means of performing decryption operations are provided: calls that take key material info directly and calls that take a crypto context. The crypto context variants can be used when operating on large blocks of data. The smart pointer variant of the stored key material version can be used with a reference to a NULL pointer to use a previously specified default decryption key (see CPKIFCryptoMediator2::SetDefaultKey). This function may generate an exception containing the following error code CRYPTO_DECRYPT_FAILED.

See the Performing Symmetric Key Encryption Operations sample.

Returns:: None

Exceptions:

	CPKIFCryptoException(CRYPTO_DECRYPT_FAILED)
	CPKIFCryptoException(COMMON_INVALID_INPUT)

Parameters:

key	[in] Reference to a smart pointer 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 Decrypt

Definition at line 1009 of file CPKIFCryptoMediator2.cpp.

References COMMON_INVALID_INPUT, Decrypt(), PKIFCRYPTO::DECRYPTION, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

void CPKIFCryptoMediator2::Encrypt	(	const CPKIFCredentialPtr &	key,
		unsigned char *	pData,
		int	nDataLen,
		unsigned char *	pResult,
		int *	pnResultLen
	)

Interface: External

As with most crypto-related functions there are two flavors of the Encrypt function: a stored key material version and a raw key material version. The stored key material version performs encryption using asymmetric key material and the raw key material version performs encryption using symmetric or asymmetric key material.

For each type of key material two means of performing encryption operations are provided: calls that take key material info directly and calls that take a crypto context. The crypto context variants can be used when operating on large blocks of data.

See the Performing Symmetric Key Encryption Operations sample.

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_INVALID_INPUT)

Parameters:

key	[in] Reference to a smart pointer 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

Definition at line 1110 of file CPKIFCryptoMediator2.cpp.

References COMMON_INVALID_INPUT, Encrypt(), LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

bool CPKIFCryptoMediator2::Verify	(	const CPKIFCredentialPtr &	key,
		unsigned char *	pHashData,
		int	nHashDataLen,
		unsigned char *	pSignature,
		int	nSignatureLen,
		PKIFCRYPTO::HASH_ALG	hashAlg
	)

Interface: External

As with most crypto-related functions, there are mutliple flavors of the Verify function: two stored key material versions and a raw key material version.

The two versions that operate on stored key materials differ only in that one takes a reference to a credential object and the other takes a reference to a credential smart pointer object.

All Verify functions assume the data passed is a hash of the data to be verified, i.e. these functions perform no hashing. This function may generate an exception containing the following error code CRYPTO_VERIFY_FAILED.

Returns:: This function returns true if the signature verifies and false otherwise. Some errors can result in exceptions.

Exceptions:

	CPKIFCryptoException(CRYPTO_VERIFY_FAILED)
	CPKIFCryptoException(COMMON_INVALID_INPUT)

Parameters:

key	[in] Reference to a smart pointer 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

Definition at line 1200 of file CPKIFCryptoMediator2.cpp.

References COMMON_INVALID_INPUT, LOG_STRING_DEBUG, TOOLKIT_CRYPTO_MEDIATOR, and Verify().

void CPKIFCryptoMediator2::Sign	(	const CPKIFKeyMaterial &	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 key material 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 the following error code CRYPTO_SIGN_FAILED.

Returns:: None

Exceptions:

	CPKIFCryptoException(CRYPTO_SIGN_FAILED)
	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

key	[in] Reference to a CPKIFKeyMaterial 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 IPKIFCryptoRawOperations.

Definition at line 1357 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

void CPKIFCryptoMediator2::Encrypt	(	const CPKIFKeyMaterial &	key,
		unsigned char *	pData,
		int	nDataLen,
		unsigned char *	pResult,
		int *	pnResultLen,
		bool	pad = `true`
	)			`[virtual]`

Interface: External

As with most crypto-related functions there are two flavors of the Encrypt function: a stored key material version and a raw key material version. The stored key material version performs encryption using asymmetric key material and the raw key material version performs encryption using symmetric or asymmetric key material.

For each type of key material two means of performing encryption operations are provided: calls that take key material info directly and calls that take a crypto context. The crypto context variants can be used when operating on large blocks of data.

See the Performing Symmetric Key Encryption Operations sample.

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

key	[in] Reference to a CPKIFKeyMaterial object containing 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
pad	[in] PADDING value that indicates the padding scheme that applies to the data. Currently the only support padding scheme is defined in PKCS #5

Implements IPKIFCryptoRawOperations.

Definition at line 1405 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

void CPKIFCryptoMediator2::Decrypt	(	const CPKIFKeyMaterial &	key,
		unsigned char *	pData,
		int	nDataLen,
		unsigned char *	pResult,
		int *	pnResultLen,
		bool	pad = `true`
	)			`[virtual]`

Interface: External

As with most crypto-related functions there are multiple flavors of the Decrypt function: stored key material versions and raw key material versions. The stored key material version performs decryption using asymmetric key material and the raw key material version performs decryption using symmetric key material.

For each type of key material, two means of performing decryption operations are provided: calls that take key material info directly and calls that take a crypto context. The crypto context variants can be used when operating on large blocks of data. The smart pointer variant of the stored key material version can be used with a reference to a NULL pointer to use a previously specified default decryption key (see CPKIFCryptoMediator2::SetDefaultKey). This function may generate an exception containing the following error code CRYPTO_DECRYPT_FAILED.

See the Performing Symmetric Key Encryption Operations sample.

Returns:: None

Exceptions:

	CPKIFCryptoException(CRYPTO_DECRYPT_FAILED)
	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

key	[in] Reference to a CPKIFKeyMaterial object containing 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 Decrypt
pad	[in] PADDING value that indicates the padding scheme that applies to the data. Currently the only support padding scheme is defined in PKCS #5

Implements IPKIFCryptoRawOperations.

Definition at line 1460 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

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

Interface: External

As with most crypto-related functions, there are mutliple flavors of the Verify function: two stored key material versions and a raw key material version.

The two versions that operate on stored key materials differ only in that one takes a reference to a credential object and the other takes a reference to a credential smart pointer object.

All Verify functions assume the data passed is a hash of the data to be verified, i.e. these functions perform no hashing. This function may generate an exception containing the following error code CRYPTO_VERIFY_FAILED.

Returns:: This function returns true if the signature verifies and false otherwise. Some errors can result in exceptions.

Exceptions:

	CPKIFCryptoException(CRYPTO_VERIFY_FAILED)
	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

key	[in] Reference to a CPKIFKeyMaterial object containing 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 with signature

Implements IPKIFCryptoRawOperations.

Definition at line 1662 of file CPKIFCryptoMediator2.cpp.

References AuditString, CAT_PKIF_CRYPTO, COMMON_OPERATION_NOT_HANDLED, CRYPTO_VERIFY_FAILED, LOG_STRING_DEBUG, PKIF_SIGNATURE_VERIFICATION_FAILED, PKIF_SIGNATURE_VERIFICATION_SUCCEEDED, and TOOLKIT_CRYPTO_MEDIATOR.

bool CPKIFCryptoMediator2::VerifyCertificate	(	const CPKIFCertificate &	issCert,
		const CPKIFCertificate &	subCert
	)			`[virtual]`

Interface: External

This convenience function can be used to verify signatures on a certificate given a subject certificate and the certificate of its issuer

Returns:: This function returns true if the signature on subCert can be verified using the public key material from issCert.

Exceptions:

CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

issCert	[in] Reference to a smart pointer to a CPKIFCertificate object containing the certificate to use when verifying the certificate passed via the subCert parameter
subCert	[in] Reference to a smart pointer to a CPKIFCertificate object containing the certificate to verify using the certificate passed via the issCert parameter

Implements IPKIFCryptoRawOperations.

Definition at line 1318 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

IPKIFRawCryptContext * CPKIFCryptoMediator2::CryptInit	(	const CPKIFKeyMaterial &	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.

See the Performing Symmetric Key Encryption Operations sample.

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

key

[in] Reference to a smart pointer to a CPKIFKeyMaterial object containing the key material to use for an Encryption or Decryption operation

Implements IPKIFCryptoRawOperations.

Definition at line 1507 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

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

Interface: External

As with most crypto-related functions there are multiple flavors of the Decrypt function: stored key material versions and raw key material versions. The stored key material version performs decryption using asymmetric key material and the raw key material version performs decryption using symmetric key material.

For each type of key material, two means of performing decryption operations are provided: calls that take key material info directly and calls that take a crypto context. The crypto context variants can be used when operating on large blocks of data. The smart pointer variant of the stored key material version can be used with a reference to a NULL pointer to use a previously specified default decryption key (see CPKIFCryptoMediator2::SetDefaultKey). This function may generate an exception containing the following error code CRYPTO_DECRYPT_FAILED.

See the Performing Symmetric Key Encryption Operations sample.

Returns:: None

Exceptions:

	CPKIFCryptoException(CRYPTO_DECRYPT_FAILED)
	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

cryptContext	[in] Pointer to an IPKIFRawCryptContext or 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 Decrypt
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 IPKIFCryptoRawOperations.

Definition at line 1550 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

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

Interface: External

As with most crypto-related functions there are two flavors of the Encrypt function: a stored key material version and a raw key material version. The stored key material version performs encryption using asymmetric key material and the raw key material version performs encryption using symmetric or asymmetric key material.

For each type of key material two means of performing encryption operations are provided: calls that take key material info directly and calls that take a crypto context. The crypto context variants can be used when operating on large blocks of data.

See the Performing Symmetric Key Encryption Operations sample.

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

cryptContext	[in] Pointer to an IPKIFRawCryptContext or 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 IPKIFCryptoRawOperations.

Definition at line 1606 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

IPKIFRawCryptContext * CPKIFCryptoMediator2::HMACInit	(	const CPKIFKeyMaterial &	key,
		PKIFCRYPTO::HASH_ALG	ha
	)			`[virtual]`

Interface: External

This function will iterate over associated colleagues until a colleague that implements the IPKIFCryptoRaw interface is found. If a colleague is found, the HMACInit function on the colleague is invoked passing alg and the resulting IPKIFRawCryptContext object returned. If no colleague is found an exception is thrown with the error code COMMON_OPERATION_NOT_HANDLED.

Returns:: A pointer to IPKIFRawCryptContext object

Exceptions:

CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED);

Parameters:

key	[in] reference to CPKIFKeyMaterial object containing the raw symmetric key to use for the MAC operation
ha	[in] HASH_ALG value indicating the type of hash algorithm for which a hash context object should be created

Implements IPKIFCryptoRawOperations.

Definition at line 602 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

void CPKIFCryptoMediator2::HMACUpdate	(	IPKIFRawCryptContext *	ctx,
		unsigned char *	pData,
		int	nDataLen
	)			`[virtual]`

Interface: External

This function should be invoked after calling HMACInit to create a context for the target algorithm. This function may be invoked iteratively, for example, when authenticating large amounts of data.

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

ctx	[in] Pointers to an IPKIFRawCryptContext object created by a previous call to HMACInit
pData	[in] Pointer to a buffer containing data that should be authenticated as part of the running HMAC operation
nDataLen	[in] Integer indicating the length of the buffer passed via the pData parameter

Implements IPKIFCryptoRawOperations.

Definition at line 632 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

void CPKIFCryptoMediator2::HMACFinal	(	IPKIFRawCryptContext *	ctx,
		unsigned char *	pResult,
		int *	pnResultLen
	)			`[virtual]`

Interface: External

This function should be invoked after passing all of the desired data to HMACUpdate. The pResult buffer must be at least pnResultLen bytes in size, and must be large enough to accommodate the size of the resulting HMAC. The HMAC value will be returned in pResult and the HMAC operation finalized, at which time the context is no longer valid and should be deleted.

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

ctx	[in] Pointers to an IPKIFHashContext object created by a previous call to HashInit
pResult	[out] Pointer to a buffer of sufficient size to receive the result of a hash operation
pnResultLen	[in/out] Pointer to an integer used to pass the length of the pResult parameter to HashFinal and to return the size of the hash result passed from HashFinal

Implements IPKIFCryptoRawOperations.

Definition at line 665 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

IPKIFKeyAgreeContextPtr CPKIFCryptoMediator2::SecretAgree	(	CPKIFCredentialPtr &	myPrivateKey,
		const CPKIFCertificatePtr &	theirCert,
		const CPKIFAlgorithm *	alg
	)			`[virtual]`

Interface: External

This function is used to agree on a shared secret using an unauthenticated key agreement scheme such as ECDH. It operates in both ephemeral-static mode and static-static mode.

If myPrivateKey is an invalid smart pointer, an ephemeral keypair will be generated and handed to the pointer.

If myPrivateKey is supplied, it must share appropriate domain parameters for the key agreement scheme specified.

Returns:: context to use with DeriveKey()

Parameters:

myPrivateKey	[IN/OUT] A key pair used for the key agreement operation. If this is NULL one will be generated using parameters from the other party's key
theirCert	[IN] A certificate containing the other party's public key.
alg	[IN] A pointer to the CPKIFAlgorithm object describing the agreement scheme

Implements IPKIFCryptoKeyAgree.

Definition at line 1844 of file CPKIFCryptoMediator2.cpp.

References AuditString, CAT_PKIF_CRYPTO, COMMON_OPERATION_NOT_HANDLED, COMMON_OPERATION_NOT_SUCCESSFUL, COMMON_UNKNOWN_ERROR, LOG_STRING_DEBUG, PKIF_UNEXPECTED_EXCEPTION, CPKIFException::print(), and TOOLKIT_CRYPTO_MEDIATOR.

IPKIFKeyAgreeContextPtr CPKIFCryptoMediator2::SecretAgree	(	CPKIFCredentialPtr &	myPrivateKey,
		const CPKIFBufferPtr &	theirPublicKey,
		const CPKIFAlgorithm *	alg
	)			`[virtual]`

Interface: External

This function is used to agree on a shared secret using an unauthenticated key agreement scheme such as ECDH. It operates in both ephemeral-static mode and static-static mode.

If myPrivateKey is an invalid smart pointer, an ephemeral keypair will be generated and handed to the pointer.

if myPrivateKey is supplied, it must share appropriate domain parameters for the key agreement scheme specified.

If no private key is supplied, theirPublicKey must point to an encoded subjectPublicKeyInfo structure containing parameters used for key generation. If a private key is supplied, theirPublicKey must contain only the public key bitstring extracted from that structure.

Returns:: context to use with DeriveKey()

Parameters:

myPrivateKey	[IN/OUT] A key pair used for the key agreement operation. If this is NULL one will be generated using parameters from the other party's key
theirPublicKey	[IN] A buffer containing the other party's public key. This must be a fully populated, encoded subjectPublicKeyInfo structure if myPrivateKey is NULL.
alg	[IN] A pointer to the CPKIFAlgorithm object describing the agreement scheme

Implements IPKIFCryptoKeyAgree.

Definition at line 1905 of file CPKIFCryptoMediator2.cpp.

References AuditString, CAT_PKIF_CRYPTO, COMMON_OPERATION_NOT_HANDLED, COMMON_OPERATION_NOT_SUCCESSFUL, COMMON_UNKNOWN_ERROR, LOG_STRING_DEBUG, PKIF_UNEXPECTED_EXCEPTION, CPKIFException::print(), and TOOLKIT_CRYPTO_MEDIATOR.

IPKIFKeyAgreeContextPtr CPKIFCryptoMediator2::SecretAgree	(	const CPKIFCredentialPtr &	myPrivateKey,
		CPKIFCredentialPtr &	ephemeralKeyPair,
		const CPKIFCertificatePtr &	theirCert,
		const CPKIFAlgorithm *	alg
	)			`[virtual]`

Interface: External

This function is used to agree on a shared secret using a one pass authenticated key agreement scheme such as ECMQV. This variant is called by the originator. Since this is only for one-pass schemes, there is no recipient ephemeral keypair.

If ephemeralKeyPair is not supplied, it will be generated and returned to the caller for possible re-use or additional encoding.

myPrivateKey, ephemeralKeyPair and theirCert must all share domain parameters for alg.

Returns:: context to use with DeriveKey()

Parameters:

myPrivateKey	[IN] originator's static keypair
ephemeralKeyPair	[IN/OUT] originator's ephemeral keypair
theirCert	[IN] a certificate containing the recipient's public key
alg	[IN] a pointer to a CPKIFAlgorithm object describing the key agreement scheme to use

Implements IPKIFCryptoKeyAgree.

Definition at line 1966 of file CPKIFCryptoMediator2.cpp.

References AuditString, CAT_PKIF_CRYPTO, COMMON_OPERATION_NOT_HANDLED, COMMON_OPERATION_NOT_SUCCESSFUL, COMMON_UNKNOWN_ERROR, LOG_STRING_DEBUG, PKIF_UNEXPECTED_EXCEPTION, CPKIFException::print(), and TOOLKIT_CRYPTO_MEDIATOR.

IPKIFKeyAgreeContextPtr CPKIFCryptoMediator2::SecretAgree	(	const CPKIFCredentialPtr &	myPrivateKey,
		CPKIFCredentialPtr &	ephemeralKeyPair,
		const CPKIFBufferPtr &	theirPublicKey,
		const CPKIFAlgorithm *	alg
	)			`[virtual]`

Interface: External

This function is used to agree on a shared secret using a one pass authenticated key agreement scheme such as ECMQV. This variant is called by the originator. Since this is only for one-pass schemes, there is no recipient ephemeral keypair.

If ephemeralKeyPair is not supplied, it will be generated and returned to the caller for possible re-use or additional encoding.

myPrivateKey, ephemeralKeyPair and theirPublicKey must all share domain parameters for alg.

theirPublicKey must be a buffer containing a bitstring which represents their key (extracted from a subjectPublicKeyInfo structure)

Returns:: context to use with DeriveKey()

Parameters:

myPrivateKey	[IN] originator's static keypair
ephemeralKeyPair	[IN/OUT] originator's ephemeral keypair
theirPublicKey	[IN] a buffer containing the recipient's public key
alg	[IN] a pointer to a CPKIFAlgorithm object describing the key agreement scheme to use

Implements IPKIFCryptoKeyAgree.

Definition at line 2029 of file CPKIFCryptoMediator2.cpp.

References AuditString, CAT_PKIF_CRYPTO, COMMON_OPERATION_NOT_HANDLED, COMMON_OPERATION_NOT_SUCCESSFUL, COMMON_UNKNOWN_ERROR, LOG_STRING_DEBUG, PKIF_UNEXPECTED_EXCEPTION, CPKIFException::print(), and TOOLKIT_CRYPTO_MEDIATOR.

IPKIFKeyAgreeContextPtr CPKIFCryptoMediator2::SecretAgree	(	const CPKIFCredentialPtr &	myPrivateKey,
		const CPKIFBufferPtr &	ephemeralPublicKey,
		const CPKIFCertificatePtr &	theirCert,
		const CPKIFAlgorithm *	alg
	)			`[virtual]`

Interface: External

This function is used to agree on a shared secret using a one pass authenticated key agreement scheme such as ECMQV. This variant is called by the recipient. Since this is only for one-pass schemes, there is no recipient ephemeral keypair.

ephemeralPublicKey must be a buffer containing a bitstring which corresponds the ephemeral private key used by the originator. As domain parameters will be taken from the recipient's static keypair, this MUST NOT be a full subjectPublicKeyInfo structure

myPrivateKey, ephemeralPublicKey and theirPublicKey must all share domain parameters for alg.

Returns:: context to use with DeriveKey()

Parameters:

myPrivateKey	[IN] recipient's keypair
ephemeralPublicKey	[IN] ephemeral public key corresponding to the ephemeral private key used by the originator
theirCert	[IN] a certificate containing the originator's static public key
alg	[IN] a pointer to a CPKIFAlgorithm object describing the key agreement scheme and KDF

Implements IPKIFCryptoKeyAgree.

Definition at line 2090 of file CPKIFCryptoMediator2.cpp.

References AuditString, CAT_PKIF_CRYPTO, COMMON_OPERATION_NOT_HANDLED, COMMON_OPERATION_NOT_SUCCESSFUL, COMMON_UNKNOWN_ERROR, LOG_STRING_DEBUG, PKIF_UNEXPECTED_EXCEPTION, CPKIFException::print(), and TOOLKIT_CRYPTO_MEDIATOR.

IPKIFKeyAgreeContextPtr CPKIFCryptoMediator2::SecretAgree	(	const CPKIFCredentialPtr &	myPrivateKey,
		const CPKIFBufferPtr &	ephemeralPublicKey,
		const CPKIFBufferPtr &	theirPublicKey,
		const CPKIFAlgorithm *	alg
	)			`[virtual]`

Interface: External

This function is used to agree on a shared secret using a one pass authenticated key agreement scheme such as ECMQV. This variant is called by the recipient. Since this is only for one-pass schemes, there is no recipient ephemeral keypair.

ephemeralPublicKey must be a buffer containing a bitstring which corresponds the ephemeral private key used by the originator. As domain parameters will be taken from the recipient's static keypair, this MUST NOT be a full subjectPublicKeyInfo structure

myPrivateKey, ephemeralPublicKey and theirPublicKey must all share domain parameters for alg.

theirPublicKey must be a buffer containing a bitstring which represents their key (extracted from a subjectPublicKeyInfo structure)

Returns:: context to use with DeriveKey()

Parameters:

myPrivateKey	[IN] recipient's keypair
ephemeralPublicKey	[IN] ephemeral public key corresponding to the ephemeral private key used by the originator
theirPublicKey	[IN] a certificate containing the originator's static public key
alg	[IN] a pointer to a CPKIFAlgorithm object describing the key agreement scheme to use

Implements IPKIFCryptoKeyAgree.

Definition at line 2155 of file CPKIFCryptoMediator2.cpp.

References AuditString, CAT_PKIF_CRYPTO, COMMON_OPERATION_NOT_HANDLED, COMMON_OPERATION_NOT_SUCCESSFUL, COMMON_UNKNOWN_ERROR, LOG_STRING_DEBUG, PKIF_UNEXPECTED_EXCEPTION, CPKIFException::print(), and TOOLKIT_CRYPTO_MEDIATOR.

CPKIFKeyMaterialPtr CPKIFCryptoMediator2::DeriveKey	(	const IPKIFKeyAgreeContextPtr &	context,
		unsigned long	keyLen
	)			`[virtual]`

Interface: External

This function is used to derive a key from an agreed-upon secret and other shared info dictated by a protocol. The context maintains both the secret and the shared info

Returns:: CPKIFKeyMaterialPtr to the key derived from information in context

Parameters:

context	[IN] context from SecretAgree()
keyLen	[IN] length of key to derive

Implements IPKIFCryptoKeyAgree.

Definition at line 2210 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, COMMON_OPERATION_NOT_SUCCESSFUL, and IPKIFCryptoKeyAgree::DeriveKey().

bool CPKIFCryptoMediator2::SupportsAlgorithm ( const CPKIFKeyMaterial & key ) [virtual]

Interface: External

Returns:: true if algorithm is supported by one of the colleagues, false if no colleague in the set supports the algorithm

Parameters:

key

[IN] Reference to a CPKIFKeyMaterial object containing at least an algorithm identifier

Implements IPKIFCryptoAlgSupport.

Definition at line 2231 of file CPKIFCryptoMediator2.cpp.

References COMMON_OPERATION_NOT_HANDLED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MEDIATOR.

Friends And Related Function Documentation

friend struct CPKIFCryptoMediator2Impl [friend]

Definition at line 59 of file CPKIFCryptoMediator2.h.

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

CPKIFCryptoMediator2 Class Reference

Detailed Description

Public Member Functions

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation