com.entrust.toolkit.credentials

Class CapiCredentialWriter

java.lang.Object

com.entrust.toolkit.credentials.CredentialWriter

com.entrust.toolkit.credentials.CapiCredentialWriter

public class CapiCredentialWriter
extends CredentialWriter

A CredentialWriter to write certificates and private keys to Microsoft CAPI.

Since:

8.0

Constructor Summary

Constructors

Constructor and Description
CapiCredentialWriter() This is the default constructor.
CapiCredentialWriter(boolean writeCACerts) This constructor is used to determine whether CA certificates will be written to CAPI when writing the profile.
CapiCredentialWriter(boolean writeCACerts, CapiCSPConfig anyCSP) The CapiCredentialWriter constructor.

Method Summary

Methods

Modifier and Type	Method and Description
static void	eraseIdentity(CapiIdentity identityToErase) Remove all certificates and keys associated with the given identity from CAPI.
boolean	getForceSecureKeyImport() Return whether or not secure key import is enforced when importing the private key into CAPI.
java.lang.String	getType() Returns the type of this credential writer.
boolean	getWriteCACertificates()
boolean	isDeleteUnusedKeysAndCertsEnabled() Indicates whether the deletion of unused keys and certificates is disabled
boolean	isSilentDeleteEnabled() Indicates whether deleting key containers from CAPI silently is enabled
boolean	isWriteToCertStoreEnabled() Indicates whether or not writing to the CAPI Certificate store is enabled
void	setDeleteUnusedKeysAndCerts(boolean enableDelete) Control deletion of unused keys and certificates.
void	setForceSecureKeyImport(boolean forceSecurKeyImport) Forces Secure Key Import to be used when importing keys into CAPI.
void	setSilentDeleteEnabled(boolean silentDelete) Delete keys from CAPI silently.
void	setWriteToCertStoreEnabled(boolean writeToCertStore) Determines whether Certificates will be written to the CAPI CertStore

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

addConfiguration, writePossible

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CapiCredentialWriter

public CapiCredentialWriter()

This is the default constructor. It will use the following defaults

• WriteCACertificates = true

CapiCredentialWriter

public CapiCredentialWriter(boolean writeCACerts)

This constructor is used to determine whether CA certificates will be written to CAPI when writing the profile. The default is true, meaning certificates will be written to CAPI. Set the API to false to indicate CA certificates should not be written.

A profile that does not contain CA certificates in CAPI is considered an "unverified" profile. To be able to login and use this type of user, the CA certificates will need to be injected into the CapiIdentity before it is logged in.

Parameters:

writeCACerts - true (the default) to indicate CA certificates will be written to CAPI, false to indicate CA certificate should not to be written in CAPI.

See Also:

CapiIdentity, CapiIdentities, CapiSearchFilter

CapiCredentialWriter

public CapiCredentialWriter(boolean writeCACerts,
                    CapiCSPConfig anyCSP)

The CapiCredentialWriter constructor. This constructor can be used to set whether CA certificates will be written to CAPI when writing the profile. It is also used to set the CAPI CSP configuration parameters.

Parameters:

writeCACerts - true (the default) to indicate CA certificates will be written to CAPI, false to indicate CA certificate should not to be written in CAPI.

anyCSP - The CapiCSPConfig which is used to determine CSP configuration parameters

See Also:

CapiIdentity, CapiIdentities, CapiSearchFilter, CapiCSPConfig

Method Detail

getType

public java.lang.String getType()

Returns the type of this credential writer.

Specified by:

getType in class CredentialWriter

Returns:

"CapiCredentialWriter";

eraseIdentity

public static void eraseIdentity(CapiIdentity identityToErase)
                          throws CapiException

Remove all certificates and keys associated with the given identity from CAPI.

Note

This method is dangerous! There is no way to recover it if is called accidentally. It is primarily for testing purposes, to stop CAPI becoming cluttered with many useless certificates and keys.

Parameters:

identityToErase - The identity for which to remove keys and certificates.

Throws:

CapiException - If there is any error removing the keys and certificates, such as insufficient permissions.

See Also:

CertContext.deleteCertificateFromStore()

getWriteCACertificates

public boolean getWriteCACertificates()

Returns:

true if CACertificates will be written to CAPI, false if they will not be written to CAPI

isWriteToCertStoreEnabled

public boolean isWriteToCertStoreEnabled()

Indicates whether or not writing to the CAPI Certificate store is enabled

Returns:

true if writing to CAPI Certificate store is enabled false if certificates will not be written to CAPI

See Also:

setWriteToCertStoreEnabled(boolean)

setWriteToCertStoreEnabled

public void setWriteToCertStoreEnabled(boolean writeToCertStore)

Determines whether Certificates will be written to the CAPI CertStore

The default setting is true, which means all certificates are written to the MS-CAPI Certificate Store. This configuration is the most common scenario when writing an identity to MS_CAPI, and will allow for the searching of identities on the same machine at a later time.

When set to false, the certificates are not written to the MS-CAPI Certificate store. This usage is for machines whose purpose is issuance of MS-CAPI identities on smart cards. In this mode, keys are still generated in MS-CAPI and certificates are attached to those keys as key properties, but certificates (CA or End Entity) are not written to the MS-CAPI certificate store. The result is keys/certificates are written to the smart card, but these certificates do not appear in the MS-CAPI certificate store. Therefore, the MS-CAPI certificate store will not be able to be used to find an identity at a later time when this mode is set.

Parameters:

writeToCertStore - true to write certificates to the Capi CertStore false to indicate certificates will not be written to the Capi CertStore

setForceSecureKeyImport

public void setForceSecureKeyImport(boolean forceSecurKeyImport)

Forces Secure Key Import to be used when importing keys into CAPI.

When set to true (the default), the key must be secured (encrypted) when it is imported into CAPI. If the secure key import operation fails, the key will not be imported into CAPI and an Exception will be thrown. When set to false, the secure key import will be attempted first, but if this operation fails the import will be retried in an unsecured format (unencrypted).

Note: Secure key import is only supported for RSA private keys. This is because the Microsoft Cryptographic Service Providers only support RSA private keys.

Parameters:

forceSecurKeyImport - true to indicate only secure key import is allowed, false to indicate unsecured import can be attempted only when the secure key import fails.

getForceSecureKeyImport

public boolean getForceSecureKeyImport()

Return whether or not secure key import is enforced when importing the private key into CAPI.

See Also:

setForceSecureKeyImport(boolean)

setSilentDeleteEnabled

public void setSilentDeleteEnabled(boolean silentDelete)

Delete keys from CAPI silently.

When attempting to delete keys in a key container in CAPI, use the CryptAcquireContext CRYPT_SILENT mode to determine if the key container is accessable before deleting the key. This will prevent UI dialogs for key containers that no longer exist from being displayed. This may be useful when recovering or updating a user from a SmartCard CSP to an alternate CSP. It this case, the SmartCard may not be available, so the attempt to delete the key may trigger the CSP to pop open a user interface dialog requesting that the Smart Card be inserted. This setting will prevent that dialog from appearing, and will silently fail if the key container cannot be found.

Set this setting to false to allow the CSP to delete the key in a way determined by the CSP in used. This may include a UI dialog to request additional information.

Parameters:

silentDelete - true (the default) to indicate keys will be deleted silently (if possible) false to indicate the CSP will attempt to delete keys in a way determined by the CSP.

isSilentDeleteEnabled

public boolean isSilentDeleteEnabled()

Indicates whether deleting key containers from CAPI silently is enabled

Returns:

true if silent delete is enabled false if silent delete is disabled

See Also:

setSilentDeleteEnabled(boolean)

setDeleteUnusedKeysAndCerts

public void setDeleteUnusedKeysAndCerts(boolean enableDelete)

Control deletion of unused keys and certificates. This applies to superseded signing keys and certs as well as any keys and certs that belong to the user but are stored under a superseded user ID. By default these are deleted.

NOTE: Setting this value to false will result in a credential that will require special handling. Key update operations will result in the credential containing multiple signing keys. Recovery operations will result in multiple credentials. Setting this value back to true will cause all of the extraneous keys and certificates to be deleted once key management occurs.

Parameters:

enableDelete - Set to true (the default) to indicate that the unused keys and certificates should be deleted. False to disable the delete.

isDeleteUnusedKeysAndCertsEnabled

public boolean isDeleteUnusedKeysAndCertsEnabled()

Indicates whether the deletion of unused keys and certificates is disabled

Returns:

true if delete is enabled and false if delete is disabled

See Also:

setDeleteUnusedKeysAndCerts(boolean)