CPKIFNSS Class Reference

#include <PKIFNSS.h>

Inheritance diagram for CPKIFNSS:

[legend]

Collaboration diagram for CPKIFNSS:

[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 constructor parameters or creating custom colleagues that implement similar functionality.

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

CPKIFNSS(const std::string & dbdir = "");

TSP-enforcing: No

Definition at line 33 of file PKIFNSS.h.


Public Types
enum	{ thisComponent = TOOLKIT_CRYPTO_NSS }
Public Member Functions
	CPKIFNSS (const std::string &dbdir="")
virtual	~CPKIFNSS (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)

Member Enumeration Documentation

anonymous enum

Enumerator:

thisComponent

Definition at line 60 of file PKIFNSS.h.

Constructor & Destructor Documentation

CPKIFNSS::CPKIFNSS ( const std::string & dbdir = "" )

Interface: External

This function creates CPKIFNSS 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:

dbdir

[in] Path to the NSS database directory

Definition at line 51 of file PKIFNSS.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_NSS.

CPKIFNSS::~CPKIFNSS ( void ) [virtual]

Interface: External

This function destroys CPKIFNSS objects.

Returns:: None

Definition at line 66 of file PKIFNSS.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_NSS.

Member Function Documentation

void CPKIFNSS::Initialize ( void ) [virtual]

Interface: External

This function initializes an instance of CPKIFNSS for use.

If NSS has not been initialized using the appropriate database directory an exception is thrown.

Returns:: None

Reimplemented from IPKIFColleague.

Definition at line 86 of file PKIFNSS.cpp.

References CPKIFNSSDatabase::GetInstance(), LOG_STRING_DEBUG, CPKIFNSSHelper::NSSAvaliable(), PKIFNSS_INIT_FAILED, RAISE_CRYPTO_EXCEPTION, thisComponent, and TOOLKIT_CRYPTO_NSS.

void CPKIFNSS::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. Credentials must match at least one of the key usage bits identified by the ku parameter.

Returns:: None

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 122 of file PKIFNSS.cpp.

References keyUsageTest(), LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_NSS.

Referenced by GetKeyList().

void CPKIFNSS::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. Credentials must match at least one of the key usage bits identified by the ku parameter.

Returns:: None

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 104 of file PKIFNSS.cpp.

References GetKeyList().

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

Parameters:

keyID

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

Implements IPKIFCryptoKeyManagement.

Definition at line 185 of file PKIFNSS.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_NSS.

CPKIFCredentialPtr CPKIFNSS::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.

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

Exceptions:

	CPKIFCryptoException(COMMON_NOT_INITIALIZED)
	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 206 of file PKIFNSS.cpp.

References atob(), COMMON_INVALID_INPUT, COMMON_NOT_INITIALIZED, LOG_STRING_DEBUG, RAISE_CRYPTO_EXCEPTION, thisComponent, TOOLKIT_CRYPTO, and TOOLKIT_CRYPTO_NSS.

void CPKIFNSS::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 CRYPTO_SIGN_FAILED, CRYPTO_UNRECOGNIZED_CREDENTIALD, and COMMON_INVALID_INPUT.

Returns:: None

Exceptions:

	CPKIFCryptoException(CRYPTO_SIGN_FAILED)
	CPKIFCryptoException(CRYPTO_UNRECOGNIZED_CREDENTIAL)
	CPKIFCryptoException(COMMON_INVALID_INPUT)

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 280 of file PKIFNSS.cpp.

References COMMON_INVALID_INPUT, CRYPTO_SIGN_FAILED, CRYPTO_UNRECOGNIZED_CREDENTIAL, LOG_STRING_DEBUG, CPKIFNSSCredential::m_privateKey, NSSHashAlg(), RAISE_CRYPTO_EXCEPTION, thisComponent, and TOOLKIT_CRYPTO_NSS.

void CPKIFNSS::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 CRYPTO_DECRYPT_FAILED and CRYPTO_UNRECOGNIZED_CREDENTIAL.

Returns:: None

Exceptions:

	CPKIFCryptoException(COMMON_NOT_IMPLEMENTED)
	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 357 of file PKIFNSS.cpp.

References CRYPTO_DECRYPT_FAILED, CRYPTO_UNRECOGNIZED_CREDENTIAL, LOG_STRING_DEBUG, CPKIFNSSCredential::m_privateKey, RAISE_CRYPTO_EXCEPTION, thisComponent, and TOOLKIT_CRYPTO_NSS.

void CPKIFNSS::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.

ENCRYPTION IS UNIMPLEMENTED FOR STORED KEY MATERIAL!

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 396 of file PKIFNSS.cpp.

References COMMON_NOT_IMPLEMENTED, RAISE_CRYPTO_EXCEPTION, and thisComponent.

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

VERIFICATION IS UNIMPLEMENTED FOR STORED KEY MATERIAL.

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 425 of file PKIFNSS.cpp.

References COMMON_NOT_IMPLEMENTED, RAISE_CRYPTO_EXCEPTION, and thisComponent.

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

CONTEXT-BASED OPERATIONS ARE UNIMPLEMENTED FOR NSS STORED KEY MATERIAL!

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_NOT_IMPLEMENTED)

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 458 of file PKIFNSS.cpp.

References COMMON_NOT_IMPLEMENTED, RAISE_CRYPTO_EXCEPTION, and thisComponent.

void CPKIFNSS::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.

CONTEXT-BASED DECRYPTION IS UNIMPLEMENTED FOR STORED KEY MATERIAL!

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 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 480 of file PKIFNSS.cpp.

References COMMON_NOT_IMPLEMENTED, RAISE_CRYPTO_EXCEPTION, and thisComponent.

void CPKIFNSS::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.

ENCRYPTION IS UNIMPLEMENTED FOR STORED KEY MATERIAL!

Returns:: None

Exceptions:

CPKIFCryptoException(COMMON_NOT_IMPLEMENTED)

Implements IPKIFCryptoKeyIDOperations.

Definition at line 511 of file PKIFNSS.cpp.

References COMMON_NOT_IMPLEMENTED, RAISE_CRYPTO_EXCEPTION, and thisComponent.

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

CPKIFNSS Class Reference

Detailed Description

Public Types

Public Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation