com.entrust.toolkit.capi

Class CertContext

java.lang.Object

com.entrust.toolkit.credentials.Handle

com.entrust.toolkit.capi.CapiHandle

com.entrust.toolkit.capi.CertContext

public class CertContext
extends CapiHandle

This class encapsulates information about a handle to a CAPI Certificate Context. It is analogous the CAPI PC_CERTCONTEXT type, and is used for all situations where a PC_CERTCONTEXT is required for a native call. It also stores the ASN.1 encoded bytes of the certificate for convenience.

Since:

7.0

Field Summary

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

m_handle

Method Summary

Modifier and Type	Method and Description
void	clearHandle() Clears the handle to the CAPI object without actually de-allocating the native memory.
void	close() Close the certificate context, releasing the memory allocated by CAPI functions.
static CertContext	createCertificateContext(int encodingType, X509Certificate cert) Creates a CAPI CertContext object from the given certificate.
static CertContext	createCertificateContext(X509Certificate cert) Creates an MSCAPI certificate context for the given certificate.
void	deleteCertificateFromStore() Delete this certificate from its certificate store.
void	deleteCertificateProperty(CertPropertyId propertyId) Deletes the indicated certificate property.
CertContext	duplicate() Duplicates this certificate context by calling the CAPI function CertDuplicateCertificateContext.
byte[]	getCertBytes() Return the bytes of the ASN.1 encoding of this certificate.
CertChainContext	getCertificateChain(java.util.Date dateTime, CertStore additionalStore, int flags) Calls to CAPI to obtain a certificate chain from the certificate represented by this object to a trusted root.
java.lang.Object	getCertificateProperty(CertPropertyId propertyId) Gets the indicated certificate property.
void	setCertificateProperty(CertPropertyId propertyId, java.lang.Object property) Sets the indicated certificate property.

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

debugInfo, debugInfo, equals, setExtendedDebugging

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

finalize, getHandle, hashCode

Methods inherited from class java.lang.Object

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

Method Detail

clearHandle

public final void clearHandle()

Clears the handle to the CAPI object without actually de-allocating the native memory. Useful when the handle will be de-allocated by another call.

Overrides:

clearHandle in class Handle

createCertificateContext

public static CertContext createCertificateContext(int encodingType,
                                                   X509Certificate cert)
                                            throws CapiException

Creates a CAPI CertContext object from the given certificate. The

Parameters:

encodingType - the certificate encoding type to use. CapiConstants.X509_ASN_ENCODING should work for almost all cases.

cert - the certificate to create in CAPI.

Returns:

a handle to a certificate context in CAPI. The returned value must be closed when no longer required.

Throws:

CapiException - if the CAPI function CertCreateCertificateContext fails to create the certificate.

See Also:

MSDN library documentation for CertCreateCertificateContext

createCertificateContext

public static CertContext createCertificateContext(X509Certificate cert)
                                            throws CapiException

Creates an MSCAPI certificate context for the given certificate.

Uses the the CapiConstants.X509_ASN_ENCODING encoding.

Parameters:

cert - a certificate

Returns:

the MSCAPI certificate context for the given certificate

Throws:

CapiException - if the operation fails

Since:

8.0

close

public void close()

Close the certificate context, releasing the memory allocated by CAPI functions. After this call, the certificate context cannot be used for any more native calls.

Specified by:

close in class Handle

getCertBytes

public byte[] getCertBytes()

Return the bytes of the ASN.1 encoding of this certificate.

Returns:

the bytes of the ASN.1 encoding of this certificate

getCertificateChain

public CertChainContext getCertificateChain(java.util.Date dateTime,
                                            CertStore additionalStore,
                                            int flags)
                                     throws CapiException

Calls to CAPI to obtain a certificate chain from the certificate represented by this object to a trusted root. Currently only one of the chains returned by CAPI is accessible.

Parameters:

dateTime - the date and time for which the chain is to be validated. Pass in null to use the current time.

additionalStore - an additional certificate store to search for certificates, or null if no additional store is required.

flags - flags to be used when generating the chain. The flags are those in CapiConstants that start with CERT_CHAIN. See the MSDN documentation CertGetCertificateChain for a full description of the flags.

Returns:

a CertChainContext that contains a certificate chain from this certificate to a trusted root certificate.

Throws:

CapiException - if there is any error obtaining the certificate chain.

See Also:

MSDN library documentation for CertGetCertificateChain

getCertificateProperty

public java.lang.Object getCertificateProperty(CertPropertyId propertyId)
                                        throws CapiException

Gets the indicated certificate property.

For a list of supported certificate properties, refer to setCertificateProperty(CertPropertyId, Object).

Parameters:

propertyId - the certificate property ID

Returns:

the certificate property value

Throws:

CapiException - if an unsupported property ID was provided, or an error occurred retrieving the requested property

See Also:

MSDN library documentation for the CAPI function CertGetCertificateContextProperty

setCertificateProperty

public void setCertificateProperty(CertPropertyId propertyId,
                                   java.lang.Object property)
                            throws CapiException

Sets the indicated certificate property.

The following certificate properties are supported:

Property ID	Property Value Type
CertPropertyId.CERT_KEY_PROV_INFO_PROP_ID	CryptKeyProvInfo
CertPropertyId.CERT_SHA1_HASH_PROP_ID	byte[]
CertPropertyId.CERT_FRIENDLY_NAME_PROP_ID	String
CertPropertyId.CERT_ARCHIVED_PROP_ID	Boolean.TRUE
CertPropertyId.EE_CERT_PROP_POLICY_CERT	byte[]
CertPropertyId.EE_CERT_PROP_CERT_PUB_PENDING	Integer
CertPropertyId.EE_CERT_PROP_CERT_MANAGEMENT_STATE	EntrustCertManagementState
CertPropertyId.EE_CERT_PROP_NKEY_EVENT_IDENTIFIER	byte[]
CertPropertyId.EE_CERT_PROP_NKEY_EVENT_INDICATOR	Byte
CertPropertyId.EE_CERT_PROP_CERT_DEFINITION_POLICY_CERT	byte[]
CertPropertyId.EE_CERT_PROP_ROAMING	Boolean.TRUE
CertPropertyId.EE_CERT_PROP_ROLLOVER_NOT_ALLOWED	Boolean.TRUE
CertPropertyId.EE_CERT_PROP_NO_OCSP_CHECKING	Boolean.TRUE
CertPropertyId.EE_CERT_PROP_MISSING_CERT_HISTORY	Boolean.TRUE
CertPropertyId.EE_CERT_PROP_USER_ROLE_ID	byte[]
CertPropertyId.ENTRUST_CAPI_PROP_ID	Boolean

Parameters:

propertyId - the certificate property ID

property - the certificate property value

Throws:

CapiException - if an unsupported property ID was provided, or an error occurred setting the requested property

See Also:

MSDN library documentation for the CAPI function CertSetCertificateContextProperty

deleteCertificateProperty

public void deleteCertificateProperty(CertPropertyId propertyId)
                               throws CapiException

Deletes the indicated certificate property.

Parameters:

propertyId - the certificate property ID

Throws:

CapiException - if an unsupported property ID was provided, or an error occurred deleting the requested property

Since:

8.0

See Also:

MSDN library documentation for the CAPI function CertSetCertificateContextProperty

duplicate

public CertContext duplicate()
                      throws CapiException

Duplicates this certificate context by calling the CAPI function CertDuplicateCertificateContext. This is useful if the result of a call to CertStore.enumCertificatesInStore() needs to be kept.

Throws:

CapiException - if CertDuplicateCertificateContext fails, which can happen if this certificate context has been closed.

See Also:

MSDN library documentation for CertDuplicateCertificateContext

deleteCertificateFromStore

public void deleteCertificateFromStore()
                                throws CapiException

Delete this certificate from its certificate store. This also closes the handle to the certificate.

Throws:

CapiException - if there is an error deleting the certificate.

See Also:

MSDN library documentation for CertDeleteCertificateFromStore