CPKIFCNGCAPI Class Reference

#include <PKIFCNGCAPI.h>

Inheritance diagram for CPKIFCNGCAPI:

[legend]

Collaboration diagram for CPKIFCNGCAPI:

[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):

CPKIFCNGCAPI(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 CPKIFCNGCAPI 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 CPKIFCNGCAPI:

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
    CPKIFCNGCAPI 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
    CPKIFCNGCAPI 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 83 of file PKIFCNGCAPI.h.


Public Member Functions
	CPKIFCNGCAPI (const char *provider=NULL, int provType=0, int sysStoRegLoc=CERT_SYSTEM_STORE_CURRENT_USER)
virtual	~CPKIFCNGCAPI (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)
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)
Friends
struct	CPKIFCNGCAPIImpl

Constructor & Destructor Documentation

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

Interface: External

This function creates CPKIFCNGCAPI 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 91 of file PKIFCNGCAPI.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_CAPI.

CPKIFCNGCAPI::~CPKIFCNGCAPI ( void ) [virtual]

Interface: External

This function destroys CPKIFCNGCAPI objects.

Returns:: None

Definition at line 132 of file PKIFCNGCAPI.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_CAPI.

Member Function Documentation

void CPKIFCNGCAPI::Initialize ( void ) [virtual]

Interface: External

This function initializes an instance of CPKIFCNGCAPI for use.

Returns:: None

Reimplemented from IPKIFColleague.

Definition at line 163 of file PKIFCNGCAPI.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_CAPI.

void CPKIFCNGCAPI::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 382 of file PKIFCNGCAPI.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 CPKIFCNGCAPI::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 359 of file PKIFCNGCAPI.cpp.

References GetKeyList().

bool CPKIFCNGCAPI::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 CPKIFCNGCAPI.

Parameters:

keyID

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

Implements IPKIFCryptoKeyManagement.

Definition at line 326 of file PKIFCNGCAPI.cpp.

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

CPKIFCredentialPtr CPKIFCNGCAPI::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 479 of file PKIFCNGCAPI.cpp.

References atob(), COMMON_INVALID_INPUT, FormatErrorMessage(), PKIFScopedArray< T >::get(), LOG_STRING_DEBUG, PKIFCAPI_FAILED_TO_OPEN_CERT_STORE, RAISE_CRYPTO_EXCEPTION, PKIFScopedArray< T >::reset(), TOOLKIT_CRYPTO, and TOOLKIT_CRYPTO_CAPI.

void CPKIFCNGCAPI::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 567 of file PKIFCNGCAPI.cpp.

References CRYPTO_ALG_NOT_SUPPORTED, CRYPTO_UNRECOGNIZED_CREDENTIAL, PKIFScopedArray< T >::get(), LOG_STRING_DEBUG, CPKIFCAPICredential2::m_certContext, CPKIFCAPICredential2::m_keyProviderInfo, CPKIFCAPICredential2::m_nPasswordLen, CPKIFCAPICredential2::m_password, PKIFCAPI_SET_PASSWORD_FAILED, PKIFCAPING_OPEN_KEY_FAILED, PKIFCAPING_OPEN_STORAGE_PROVIDER_FAILED, PKIFCAPING_SIGN_HASH_FAILED, RAISE_CRYPTO_EXCEPTION, CPKIFCAPICredential2::SetKeyProviderInfo(), PKIFCRYPTO::SHA1, PKIFCRYPTO::SHA256, PKIFCRYPTO::SHA384, PKIFCRYPTO::SHA512, TOOLKIT_CRYPTO, and TOOLKIT_CRYPTO_CAPI.

void CPKIFCNGCAPI::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 774 of file PKIFCNGCAPI.cpp.

References CRYPTO_UNRECOGNIZED_CREDENTIAL, LOG_STRING_DEBUG, CPKIFCAPICredential2::m_keyProviderInfo, PKIFCAPING_DECRYPT_FAILED, PKIFCAPING_OPEN_KEY_FAILED, PKIFCAPING_OPEN_STORAGE_PROVIDER_FAILED, RAISE_CRYPTO_EXCEPTION, CPKIFCAPICredential2::SetKeyProviderInfo(), TOOLKIT_CRYPTO, and TOOLKIT_CRYPTO_CAPI.

void CPKIFCNGCAPI::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 882 of file PKIFCNGCAPI.cpp.

References COMMON_NOT_IMPLEMENTED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_CAPI.

bool CPKIFCNGCAPI::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 912 of file PKIFCNGCAPI.cpp.

References COMMON_NOT_IMPLEMENTED, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_CAPI.

IPKIFCryptContext * CPKIFCNGCAPI::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 952 of file PKIFCNGCAPI.cpp.

References COMMON_NOT_IMPLEMENTED, LOG_STRING_DEBUG, RAISE_CRYPTO_EXCEPTION, and TOOLKIT_CRYPTO_CAPI.

void CPKIFCNGCAPI::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 982 of file PKIFCNGCAPI.cpp.

References COMMON_NOT_IMPLEMENTED, LOG_STRING_DEBUG, RAISE_CRYPTO_EXCEPTION, and TOOLKIT_CRYPTO_CAPI.

void CPKIFCNGCAPI::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 1013 of file PKIFCNGCAPI.cpp.

References COMMON_NOT_IMPLEMENTED, LOG_STRING_DEBUG, RAISE_CRYPTO_EXCEPTION, and TOOLKIT_CRYPTO_CAPI.

IPKIFKeyAgreeContextPtr CPKIFCNGCAPI::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 1049 of file PKIFCNGCAPI.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_CAPI.

IPKIFKeyAgreeContextPtr CPKIFCNGCAPI::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 1082 of file PKIFCNGCAPI.cpp.

References COMMON_NOT_IMPLEMENTED.

IPKIFKeyAgreeContextPtr CPKIFCNGCAPI::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 1113 of file PKIFCNGCAPI.cpp.

References COMMON_NOT_IMPLEMENTED.

IPKIFKeyAgreeContextPtr CPKIFCNGCAPI::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 1145 of file PKIFCNGCAPI.cpp.

References COMMON_NOT_IMPLEMENTED.

IPKIFKeyAgreeContextPtr CPKIFCNGCAPI::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 1177 of file PKIFCNGCAPI.cpp.

References COMMON_NOT_IMPLEMENTED.

IPKIFKeyAgreeContextPtr CPKIFCNGCAPI::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 1211 of file PKIFCNGCAPI.cpp.

References COMMON_NOT_IMPLEMENTED.

CPKIFKeyMaterialPtr CPKIFCNGCAPI::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 1235 of file PKIFCNGCAPI.cpp.

Friends And Related Function Documentation

friend struct CPKIFCNGCAPIImpl [friend]

Definition at line 85 of file PKIFCNGCAPI.h.

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

CPKIFCNGCAPI Class Reference

Detailed Description

Public Member Functions

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation