CPKIFLDAPRepository Class Reference

#include <PKIFLDAPRepository.h>

Inheritance diagram for CPKIFLDAPRepository:

[legend]

Collaboration diagram for CPKIFLDAPRepository:

[legend]

List of all members.

Detailed Description

This class provides an interface to an LDAP-accessible directory. Instances of this class are associated with mediator objects at run-time following specification of information necessary to connect to the directory server, e.g. host name and port. CPKIFLDAPRepository implements the IPKIFPKIRepository interface, which includes the IPKIFCertRepository and IPKIFCRLRepository interfaces. This enables applications to retrieve certificates and CRLs from an LDAP-accessible directory server. This class does not provide means to update or modify the contents of a directory.

The GetCertificates method will attempt to retrieve certificates from the following directory attributes:

	caCertificate and caCertificate;binary
	userCertificate and userCertificate;binary
	crossCertificatePair and crossCertificatePair;binary

The GetCRLs method will attempt to retrieve CRLs from the following directory attributes:

	certificateRevocationList and certificateRevocationList;binary
	authorityRevocationList and authorityRevocationList;binary
	deltaRevocationList and deltaRevocationList;binary

Certificates greater than 20,000 bytes in size and CRLs greater than 100,000,000 bytes in size will not be retrieved. Referral handling is turned on by default and cannot be disabled. All directory operations performed by this class are synchronous.

TSP-enforcing: Yes

Definition at line 57 of file PKIFLDAPRepository.h.


Public Member Functions
	CPKIFLDAPRepository (void)
virtual	~CPKIFLDAPRepository (void)
void	Initialize ()
void	GetCertificates (const CPKIFNamePtr &subDN, CPKIFCertificateList &certList, PKIInfoSource source=ALL)
void	GetCertificates (const CPKIFCertificatePtr &cert, CPKIFCertificateList &certList, PKIInfoSource source=ALL, PathBuildingDirection pbd=PBD_FORWARD)
void	GetCRLs (const CPKIFCertificatePtr &cert, CPKIFCRLList &crlList, PKIInfoSource source=ALL)
int	GetPort () const
void	Set_Port (int port)
const char *	GetHost () const
void	SetHost (const char *host)
const char *	GetUsername () const
void	SetUsername (const char *username)
void	SetPassword (const char *password)
void	SetSuppressConnectionErrors (bool b)
bool	GetSuppressConnectionErrors () const
void	GetCRLSources (const CPKIFCertificatePtr &cert, CPKIFCrlSourceList &crlNodeList, PKIInfoSource source=ALL)
void	GetCertificateSources (const CPKIFCertificatePtr &cert, CPKIFCertificateSourceList &certs, PathBuildingDirection pbd=PBD_FORWARD)
void	GetCRLs (const CPKIFNamePtr &entry, std::vector< std::string > &attributes, CPKIFCRLNodeList &crlList)
void	GetCertificates (const CPKIFNamePtr &entry, std::vector< std::string > &attributes, CPKIFCertificateNodeList &certList, PathBuildingDirection pbd)
void	AddNamespace (CPKIFGeneralSubtreePtr &name)
CPKIFGeneralSubtreeList	GetNamespaces ()
PKIInfoSource	GetSourceType ()

Constructor & Destructor Documentation

CPKIFLDAPRepository::CPKIFLDAPRepository ( void )

Interface: External

This function creates and initializes CPKIFLDAPRepository objects. The following properties are initialized to the specified default values:

�    Port: 389 
�    SuppressConnectionErrors: false

Following creation of a CPKIFLDAPRepository, it is necessary to specify the host name and port, if other than the default value, prior to adding the object to the collection of colleagues managed by an instance of CPKIFCacheMediator2.

Returns:: None

Definition at line 155 of file CACLDAPRepository.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_SR_LDAPREPOSITORY.

CPKIFLDAPRepository::~CPKIFLDAPRepository ( void ) [virtual]

Interface: External

This function destroys CPKIFLDAPRepository objects.

Returns:: None

Definition at line 178 of file CACLDAPRepository.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_SR_LDAPREPOSITORY.

Member Function Documentation

void CPKIFLDAPRepository::Initialize ( void ) [virtual]

Interface: External

This function initializes an instance for use in a collection of IPKIFColleague objects held by a mediator

Returns:: None

Reimplemented from IPKIFColleague.

Definition at line 200 of file CACLDAPRepository.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_SR_LDAPREPOSITORY.

void CPKIFLDAPRepository::GetCertificates	(	const CPKIFNamePtr &	subDN,
		CPKIFCertificateList &	certList,
		PKIInfoSource	source = `ALL`
	)			`[virtual]`

Interface: External

This function appends pointers to certificates found in the directory entry identified by the subDN parameter to certList. This function does not ensure that all certificates are issued to the name identified in the subDN parameter. If the directory entry contains extraneous certificates those certificates will be returned. Any non-certificate material found in a certificate attribute will be discarded without raising an exception. This function searches the caCertificate;binary and crossCertificatePair;binary attributes with a search filter of "objectclass=*". The function simply returns without searching when source is equal to LOCAL. This function may generate an exception containing the following error codes CACHE_LDAP_ERROR, and CACHE_PARSE_ERROR.

Returns:: None

Exceptions:

	CPKIFCacheException(CACHE_LDAP_CONNECT_AND_BIND_FAILED)
	CPKIFCacheException(CACHE_LDAP_ERROR)

Parameters:

subDN	[in] Pointer to a distinguished name corresponding to the subject distinguished name in the desired certificates
certList	[out] List of pointers to certificates with a subject distinguished name equal to the value passed via the subDN parameter
source	[in] PKIInfoSource value indicating the types of locations that should be searched for certificates

Implements IPKIFCertRepository.

Definition at line 514 of file CACLDAPRepository.cpp.

References PKIFENUMS::PBD_FORWARD.

void CPKIFLDAPRepository::GetCertificates	(	const CPKIFCertificatePtr &	cert,
		CPKIFCertificateList &	certList,
		PKIInfoSource	source = `ALL`,
		PathBuildingDirection	pbd = `PBD_FORWARD`
	)			`[virtual]`

Interface: External

This function retrives certificate from LDAP

Returns:: None

Reimplemented from IPKIFCertRepository.

Definition at line 859 of file CACLDAPRepository.cpp.

References PKIFENUMS::PBD_FORWARD.

void CPKIFLDAPRepository::GetCRLs	(	const CPKIFCertificatePtr &	cert,
		CPKIFCRLList &	crlList,
		PKIInfoSource	source = `ALL`
	)			`[virtual]`

Interface: External

This function appends pointers to CRLs found that may be applicable to cert to crlList. This function does not ensure that all CRLs are applicable. If the directory entry contains extraneous CRLs those CRLs will be returned. Any non-CRL material found in a CRL attribute will be discarded without raising an exception. This function searches the certificateRevocationList;binary and authorityRevocationList;binary attributes with a search filter of "objectclass=*". The function simply returns without searching when source is equal to LOCAL. This function will search directory entries identified in CRL DP extensions, if present. This function may generate an exception containing the following error codes CACHE_LDAP_ERROR, and CACHE_PARSE_ERROR.

Returns:: None

Exceptions:

	CPKIFCacheException(-1)
	CPKIFCacheException(CACHE_LDAP_CONNECT_AND_BIND_FAILED)
	CPKIFCacheException(CACHE_LDAP_ERROR)

Parameters:

cert	[in] Pointer to a certificate for which revocation status is to be checked
crlList	[out] Reference to a CRL list to receive CRLs that may be associated with the specified certificate
source	[in] PKIInfoSource indicating the locations to search for CRLs

Implements IPKIFCRLRepository.

Definition at line 905 of file CACLDAPRepository.cpp.

References CACHE_LDAP_CONNECT_AND_BIND_FAILED, CACHE_PARSE_ERROR, CLEANUP, CollectNamesFromCRLDP(), IsNonDirName(), PKIFENUMS::LOCAL, LOG_STRING_DEBUG, LOG_STRING_ERROR, LOG_STRING_INFO, RAISE_CACHE_EXCEPTION, GottaMatch< T >::SetRHS(), stricmp, and TOOLKIT_SR_LDAPREPOSITORY.

int CPKIFLDAPRepository::GetPort ( ) const

Interface: External

This function returns an integer containing the value of the Port property. By default, the Port property is set to 389. The value can be set to a different value by invoking the Set_Port method

Returns:: An integer containing the value of the Port property

Exceptions:

CPKIFCacheException(COMMON_INVALID_INPUT)

Definition at line 216 of file CACLDAPRepository.cpp.

void CPKIFLDAPRepository::Set_Port ( int port )

Interface: External

This function is used to specify the port used to access the target LDAP-accessible directory. By default, the port value is set to 389. This function should be called prior to using the object, i.e. prior to associating the object with a mediator/colleague collection. Once opened, LDAP connections remain open for the lifetime of an instance of CPKIFLDAPRepository. Specifying the port on an object that has an open connection will not take effect unless the connection is broken and reestablished.

Specification of a port value greater than 65535 will result in a CPKIFCacheException indicating COMMON_INVALID_INPUT.

Returns:: None

Exceptions:

CPKIFCacheException(COMMON_INVALID_INPUT)

Parameters:

port

[in] Integer containing the new value for the port property

Definition at line 237 of file CACLDAPRepository.cpp.

References COMMON_INVALID_INPUT, and RAISE_CACHE_EXCEPTION.

const char * CPKIFLDAPRepository::GetHost ( ) const

Interface: External

This function is used to retrieve the name of the target LDAP-accessible directory host (DNS name or IP address).

Returns:: A pointer to a NULL-terminated string containing the value of the Host property or NULL, if no host has been specified. The pointer is valid for the life of the associated CPKIFLDAPRepository object or until a subsequent call to SetHost.
None

Definition at line 259 of file CACLDAPRepository.cpp.

void CPKIFLDAPRepository::SetHost ( const char * host )

Interface: External

This function is used to specify the hostname of an LDAP-accessible directory server. The name should be expressed as an IP address or DNS name. Specification of an unreachable host will not manifest itself as an error until an attempt is made to contact the server. Once opened, LDAP connections remain open for the lifetime of an instance of CPKIFLDAPRepository. Specifying the host for an object that has an open connection will not take effect unless the connection is broken and reestablished.

Passing NULL as the host parameter will result in a CPKIFCacheException indicating COMMON_INVALID_INPUT.

Returns:: None

Exceptions:

CPKIFCacheException(COMMON_INVALID_INPUT)

Parameters:

host

[in] Pointer to a NULL-terminated array of characters containing the name of the target LDAP-accessible directory

Definition at line 279 of file CACLDAPRepository.cpp.

References COMMON_INVALID_INPUT, and RAISE_CACHE_EXCEPTION.

const char * CPKIFLDAPRepository::GetUsername ( ) const

Interface: External

The function GetUsername is used to retrieve the username used to bind to the target LDAP-accessible directory. Typically, anonymous bind operations are performed and GetUsername is not called.

Returns:: A pointer to a NULL-terminated string containing the value of the Username property or NULL, if no username has been specified. The pointer is valid for the life of the associated CPKIFLDAPRepository object or until a subsequent call to SetUsername.
None

Definition at line 303 of file CACLDAPRepository.cpp.

void CPKIFLDAPRepository::SetUsername ( const char * username )

Interface: External

The function SetUsername is used to specify the usernameused to bind to the target LDAP-accessible directory. Typically, anonymous bind operations are performed and SetUsername is not called.

Returns:: None

Parameters:

username

[in] Pointer to a NULL terminated array of characters containing the username to use during subsequent bind operations

Definition at line 316 of file CACLDAPRepository.cpp.

void CPKIFLDAPRepository::SetPassword ( const char * password )

Interface: External

This function is used to specify the password used to bind to the target LDAP-accessible directory. Typically, anonymous bind operations are performed and this function need not be called.

Returns:: None

Parameters:

password

[in] Pointer to a NULL terminated array of characters containing the password to use during subsequent bind operations

Definition at line 331 of file CACLDAPRepository.cpp.

void CPKIFLDAPRepository::SetSuppressConnectionErrors ( bool b )

Interface: External

This function is used to turn on/off suppression of connection-related errors. By default, connection-related errors are not suppressed, i.e. an exception is raised when either a connection or bind failure occurs. When connection-related errors are suppressed, no exception is thrown and the object silently fails without searching for the requested information.

Returns:: None

Parameters:

b	[in] Boolean value used to set the SuppressConnectionErrors property

Definition at line 348 of file CACLDAPRepository.cpp.

bool CPKIFLDAPRepository::GetSuppressConnectionErrors ( ) const

Interface: External

This function is used to retrive error suppression indicator. By default, connection-related errors are not suppressed, i.e. an exception is raised when either a connection or bind failure occurs. When connection-related errors are suppressed, no exception is thrown and the object silently fails without searching for the requested information.

Returns:: A Boolean value containing the value of the SuppressConnectionErrors property.

Definition at line 365 of file CACLDAPRepository.cpp.

void CPKIFLDAPRepository::GetCRLSources	(	const CPKIFCertificatePtr &	cert,
		CPKIFCrlSourceList &	crlList,
		PKIInfoSource	source = `ALL`
	)

Interface: External

This function retrives CRL sources

Returns:: None

Parameters:

cert	[in] Pointer to a certificate for which revocation status is to be checked
crlList	[out] Reference to a CRL list to receive CRLs that may be associated with the specified certificate
source	[in] Enum indicating type of source being sought (i.e., local or remote)

Definition at line 1279 of file CACLDAPRepository.cpp.

References CollectNamesFromCRLDP(), CPKIFCacheMediator2::GetColleagues(), GetLdapUriMultiAttr(), IsNonDirName(), PKIFENUMS::LOCAL, LOG_STRING_DEBUG, IPKIFColleague::m_parents, GottaMatch< T >::SetRHS(), TOOLKIT_SR_LDAPREPOSITORY, and UriAlreadyInList().

void CPKIFLDAPRepository::GetCertificateSources	(	const CPKIFCertificatePtr &	cert,
		CPKIFCertificateSourceList &	certs,
		PathBuildingDirection	pbd = `PBD_FORWARD`
	)

Interface: External

This function retrives certificate sources

Returns:: None

Parameters:

cert	[in] A reference to a smart pointer to CPKIFCertificate object
certs	[out] A reference to CPKIFCertificateSourceList object
pbd	[in] enum indicating build direction

Definition at line 1964 of file CACLDAPRepository.cpp.

References CPKIFCacheMediator2::GetColleagues(), GetLdapUriMultiAttr(), IPKIFColleague::m_parents, PKIFENUMS::PBD_FORWARD, and UriAlreadyInList().

void CPKIFLDAPRepository::GetCRLs	(	const CPKIFNamePtr &	issDN,
		std::vector< std::string > &	attributes,
		CPKIFCRLNodeList &	crlList
	)

Interface: External

This function retrives CRLs from LDAP repository

Returns:: None

Definition at line 1758 of file CACLDAPRepository.cpp.

References CACHE_LDAP_CONNECT_AND_BIND_FAILED, CACHE_PARSE_ERROR, CLEANUP, GetLdapUriMultiAttr(), LOG_STRING_DEBUG, LOG_STRING_ERROR, LOG_STRING_INFO, RAISE_CACHE_EXCEPTION, GottaMatch< T >::SetRHS(), and TOOLKIT_SR_LDAPREPOSITORY.

void CPKIFLDAPRepository::GetCertificates	(	const CPKIFNamePtr &	issDN,
		std::vector< std::string > &	attributes,
		CPKIFCertificateNodeList &	certNodeList,
		PathBuildingDirection	pbd
	)