com.entrust.toolkit.capi

Class CertStore

java.lang.Object

com.entrust.toolkit.credentials.Handle

com.entrust.toolkit.capi.CapiHandle

com.entrust.toolkit.capi.CertStore

public class CertStore
extends CapiHandle

This class encapsulates information about a handle to a CAPI Certificate Store. It is analogous the CAPI HCERTSTORE type, and is used for all situations where an HCERTSTORE is required for a native call.

Since:

7.0

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	INTERMEDIATE
static java.lang.String	PERSONAL
static java.lang.String	TRUSTED_ROOT

Fields inherited from class com.entrust.toolkit.credentials.Handle

m_handle

Method Summary

Modifier and Type	Method and Description
void	addCertificateContextToStore(CertContext certContext, CertStoreAddDisposition addDisposition) Adds the given certificate to this store.
void	close() Closes the handle to the certificate store, freeing memory and resources.
CertContext	enumCertificatesInStore(CertContext previousContext) Enumerates the certificates contained in this certificate store.
CertContext	findCertificateInStore(CertContext certToFind) Attempt to find the given certificate in this store, and return a read-only copy of it if it is.
CertContext	findCertificateInStore(int findFlags, CertFindType findType, java.lang.Object findParameter, CertContext previousCertContext) Attempt to find a certificate in this store matching the given parameters, and return a read-only copy of it if it is.
static CertStore	openStore(CertStoreProvType storeProviderType, int encodingType, CryptProvider cryptProvider, int flags, java.lang.String parameter) Opens a certificate store and returns a handle to the newly opened store.
static CertStore	openSystemStore(CryptProvider cryptProvider, java.lang.String storeName) Opens a system certificate store and returns a handle to the newly opened store.

Methods inherited from class com.entrust.toolkit.capi.CapiHandle

debugInfo, debugInfo, equals, setExtendedDebugging

Methods inherited from class com.entrust.toolkit.credentials.Handle

clearHandle, finalize, getHandle, hashCode

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

PERSONAL

public static final java.lang.String PERSONAL

See Also:

Constant Field Values

TRUSTED_ROOT

public static final java.lang.String TRUSTED_ROOT

See Also:

Constant Field Values

INTERMEDIATE

public static final java.lang.String INTERMEDIATE

See Also:

Constant Field Values

Method Detail

openStore

public static CertStore openStore(CertStoreProvType storeProviderType,
                                  int encodingType,
                                  CryptProvider cryptProvider,
                                  int flags,
                                  java.lang.String parameter)
                           throws CapiException

Opens a certificate store and returns a handle to the newly opened store.

Parameters:

storeProviderType - the store provider type. Only the store types that take string parameters when opening can currently be used, those that require handles to Windows objects such as registry keys cannot. Also, this class does not support modification of certificate stores, so store types that are transient, e.g. CERT_STORE_PROV_MEMORY, can be opened but are of little use.

encodingType - the certificate and message encoding type. Only applicable to the CERT_STORE_PROV_FILENAME provider type, where it will most commonly be CapiConstants.X509_ASN_ENCODING | CapiConstants.PKCS_7_ASN_ENCODING

cryptProvider - a cryptographic service provider which is used to verify signatures. Passing null for this parameter causes a default provider to be used, which should be suitable for almost all uses.

flags - flags to pass to CertOpenStore. These flags are in CapiConstants, beginning with CERT_STORE. See the MSDN documentation for full details.

parameter - the parameter to pass to CertOpenStore. The contents of the string will depend of the choice of storeProviderType.

Returns:

a handle to the newly opened store, or null if the store does not exist.

Throws:

CapiException - if there is any problem opening the store.

See Also:

MSDN library documentation for CertOpenStore

openSystemStore

public static CertStore openSystemStore(CryptProvider cryptProvider,
                                        java.lang.String storeName)
                                 throws CapiException

Opens a system certificate store and returns a handle to the newly opened store. Not as flexible as openStore, but is suitable for most non-specialized access to certificate stores.

Note that this call may create the given certificate store if it does not exist. If this behaviour is not desired, call openStore instead, using the CERT_STORE_OPEN_EXISTING_FLAG flag.

Parameters:

cryptProvider - A handle to a CSP. This can be null to use the default CSP. If it is not null, it must be a CryptProvider obtained by a call to CryptProvider.cryptAcquireContext()

storeName - The name of the store to open. Some commonly used names are

• "ROOT" - root certificates
• "MY" - a certificate store holding certificates with associated private keys
• "CA" - certification authority certificates

Returns:

a handle to the newly opened store, or null if the store does not exist.

Throws:

CapiException - if there is any problem opening the specified certificate store.

See Also:

MSDN library documentation for CertOpenSystemStore

close

public void close()

Closes the handle to the certificate store, freeing memory and resources. No methods of this object will give results after calling this method.

Specified by:

close in class Handle

enumCertificatesInStore

public CertContext enumCertificatesInStore(CertContext previousContext)
                                    throws CapiException

Enumerates the certificates contained in this certificate store.

Parameters:

previousContext - the result of a previous call to this method. The first time this method is called, null should be used. previousContext is no longer usable after this call, so if it is still required, it should be duplicated and the duplicate used for further function calls. The duplicate must be explicitly closed when no longer needed.

Returns:

a handle to a certificate contained within this store, or null if all certificates have been enumerated.

Throws:

CapiException - if this certificate store is no longer valid, or if the given certificate does not belong to the certificate store.

See Also:

MSDN library documentation for CertEnumCertificatesInStore

addCertificateContextToStore

public void addCertificateContextToStore(CertContext certContext,
                                         CertStoreAddDisposition addDisposition)
                                  throws CapiException

Adds the given certificate to this store.

Parameters:

certContext - A handle to an open PCCERT_CONTEXT object in CAPI that will be added to this certificate store.

addDisposition - The Specifies the action to take if a matching certificate or a link to a matching certificate already exists in the store.

Throws:

CapiException - if the certificate cannot be added.

See Also:

MSDN library documentation for CertAddCertificateContextToStore

findCertificateInStore

public CertContext findCertificateInStore(CertContext certToFind)
                                   throws CapiException

Attempt to find the given certificate in this store, and return a read-only copy of it if it is.

Parameters:

certToFind - the certificate to find.

Returns:

null if the certificate is not found, or a read-only CertContext object if it is. The returned object must be explicitly closed.

Throws:

CapiException - if there is a problem searching for the certificate.

See Also:

MSDN library documentation for CertFindCertificateInStore

findCertificateInStore

public CertContext findCertificateInStore(int findFlags,
                                          CertFindType findType,
                                          java.lang.Object findParameter,
                                          CertContext previousCertContext)
                                   throws CapiException

Attempt to find a certificate in this store matching the given parameters, and return a read-only copy of it if it is.

Parameters:

findFlags - flags to use when searching for the certificate.

findType - the type of search to perform. Currently only CERT_FIND_SHA1_HASH and CERT_FIND_PROPERTY are supported.

findParameter - must be an instance of byte[] for all currently supported find types.

previousCertContext - the result of a previous call to this method if this method is being called multiple times. Set to null the first time this method is called. Any non-null value passed in is always released, regardless of whether this method is successful or throws an Exception.

Returns:

null if the certificate is not found, or a read-only CertContext object if it is. The returned object must be explicitly closed.

Throws:

CapiException - if the given property is not supported, or there is a problem with the parameters that causes the search to fail.

See Also:

MSDN library documentation for CertFindCertificateInStore