com.entrust.toolkit.credentials

Class PKCS12Writer

java.lang.Object

com.entrust.toolkit.credentials.CredentialWriter

com.entrust.toolkit.credentials.PKCS12Writer

public class PKCS12Writer
extends CredentialWriter

A credential writer for writing a digital identity in the form of a PKCS#12 key file.

Note: Export of a user private key from an Entrust digital identity to PKCS#12 is only permitted if PKCS#12 export is enabled for the digital identity (the 'entrustAllowPKCS12Export' role policy is set) and PKCS#12 export is enabled for the private key (the corresponding user certificate contains the 'PKCS12ExportPermission' extension or the 'entrustAllExportable' role policy is set).

See Also:

PKCS12ExportPermission, ClientSettings.isAllExportable()

Field Summary

Fields

Modifier and Type	Field and Description
static int	ALL_KEYS Key export mode indicating that all keys and associated certificates be exported (includes key history).
static int	ALL_LATEST_KEYS Key export mode indicating that the latest key and associated certificate in each certificate stream hould be exported (no key history).
static int	DECRYPTION_KEY Key export mode indicating the latest decryption key and encryption certificate should be exported (no decryption key history).
static int	SIGNING_AND_DECRYPTION_KEYS Key export mode indicating both latest decryption and signing keys and their associated certificates should be exported (no decryption key history).
static int	SIGNING_KEY Key export mode indicating the latest signing key and verification certificate should be exported.

Constructor Summary

Constructors

Constructor and Description
PKCS12Writer(java.io.OutputStream outputStream, int hashCount) A constructor; creates a new PKCS12Writer object used to write a Digital Identity in the form of a PKCS#12 key file where the latest key and certificate from each certificate stream is written.
PKCS12Writer(java.io.OutputStream outputStream, int keyExportMode, int hashCount) A constructor; creates a new PKCS12Writer object used to write a Digital Identity in the form of a PKCS#12 key file where the keys and certificates that are written are controlled by the key export mode

Method Summary

Modifier and Type	Method and Description
java.lang.String	getType() Returns the type, or name, of CredentialWriter used to call the method.
void	setCertificatesToExport(CertificateSet certificatesToExport) Set the list of certificates to export when User.write() is called.
void	setExportCaCertificates(boolean exportCaCertificates) Sets a flag indicating whether or not the CA certificate(s) associated with the user's digital identity will be exported to PKCS12 during the digital identity write operation.
void	setFriendlyName(java.lang.String name, boolean useKeyUsage) This method is used to override the default Friendly Name used for the KeyBag and Certificate Bags when exporting to the PKCS#12 format.
void	setUseLegacyEcKeyFormat(boolean useLegacy) Set a flag indicating if private elliptic curve (EC) keys should be written out in a legacy format used by older toolkit versions or if the standard PKCS8 encoding for EC private keys should be used.

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

Field Detail

SIGNING_KEY

public static final int SIGNING_KEY

Key export mode indicating the latest signing key and verification certificate should be exported.

See Also:

Constant Field Values

DECRYPTION_KEY

public static final int DECRYPTION_KEY

Key export mode indicating the latest decryption key and encryption certificate should be exported (no decryption key history).

See Also:

Constant Field Values

SIGNING_AND_DECRYPTION_KEYS

public static final int SIGNING_AND_DECRYPTION_KEYS

Key export mode indicating both latest decryption and signing keys and their associated certificates should be exported (no decryption key history).

See Also:

Constant Field Values

ALL_LATEST_KEYS

public static final int ALL_LATEST_KEYS

Key export mode indicating that the latest key and associated certificate in each certificate stream hould be exported (no key history).

Since:

7.2 SP2 Patch

See Also:

Constant Field Values

ALL_KEYS

public static final int ALL_KEYS

Key export mode indicating that all keys and associated certificates be exported (includes key history).

Since:

7.2 SP2 Patch

See Also:

Constant Field Values

Constructor Detail

PKCS12Writer

public PKCS12Writer(java.io.OutputStream outputStream,
                    int keyExportMode,
                    int hashCount)

A constructor; creates a new PKCS12Writer object used to write a Digital Identity in the form of a PKCS#12 key file where the keys and certificates that are written are controlled by the key export mode

When exporting an Entrust User to PKCS#12 (from an EPF), the user's role policy must indicate "Allow PKCS#12 Export" is enabled (entrustAllowPKCS12Export - 1.2.840.113533.7.77); otherwise the write operation will fail.

One or more of a user's keys are written to the specified output stream. Use the keyExportMode argument to specify the key, or keys, to be exported. keyExportMode must be one of the following:

• SIGNING_KEY — the signing key
• DECRYPTION_KEY — the decryption key
• SIGNING_AND_DECRYPTION_KEYS — the signing key and the decryption key
• ALL_LATEST_KEYS — the latest key from each certificate stream
• ALL_KEYS — all keys (includes key history)

Set the hash count to one of two values: 1, or 2000, unless you have specific reasons for setting a different hash count value.

If you plan to use the PKCS#12 file only with recent browsers (Netscape 4.5+, Internet Explorer 5.0+), or you just plan to read the file into the Toolkit, you should set the hash count to 2000. If you plan to use the PKCS#12 file in legacy browsers, you should set the hash count to 1.

Parameters:

outputStream - the output stream to the store the Digital Identity. This stream will not be closed.

keyExportMode - specifies the key to export

hashCount - specifies the number of hash iterations used to protect the PKCS#12 file

PKCS12Writer

public PKCS12Writer(java.io.OutputStream outputStream,
                    int hashCount)

A constructor; creates a new PKCS12Writer object used to write a Digital Identity in the form of a PKCS#12 key file where the latest key and certificate from each certificate stream is written.

For additional details, refer to PKCS12Writer(OutputStream, int, int) when operated in the ALL_LATEST_KEYS key export mode.

Parameters:

outputStream - the output stream to the store the Digital Identity. This stream will not be closed.

hashCount - specifies the number of hash iterations used to protect the PKCS#12 file

Since:

7.0

Method Detail

getType

public java.lang.String getType()

Returns the type, or name, of CredentialWriter used to call the method.

Specified by:

getType in class CredentialWriter

Returns:

the type, or name, of the CredentialWriter

setCertificatesToExport

public void setCertificatesToExport(CertificateSet certificatesToExport)

Set the list of certificates to export when User.write() is called.

This setting overrides any selection made by setting the export mode in the constructor.

Parameters:

certificatesToExport - The certificates to be exported.

Since:

7.0

setUseLegacyEcKeyFormat

public void setUseLegacyEcKeyFormat(boolean useLegacy)

Set a flag indicating if private elliptic curve (EC) keys should be written out in a legacy format used by older toolkit versions or if the standard PKCS8 encoding for EC private keys should be used.

The default behaviour is to export EC keys using the standard PKCS8 encoding.

Parameters:

useLegacy - Set to true to use the legacy EC encoding format that is compatible with older toolkit versions, or false to use the standard PKCS8 encoding.

Since:

7.2 SP2

See Also:

EcPrivateKey.FORMAT_PKCS8_ENTRUST, EcPrivateKey.FORMAT_PKCS8

setExportCaCertificates

public void setExportCaCertificates(boolean exportCaCertificates)

Sets a flag indicating whether or not the CA certificate(s) associated with the user's digital identity will be exported to PKCS12 during the digital identity write operation.

By default, CA certificates (the user's CA certificate chain) are exported.

Warning: All Entrust digital identities require a root of trust; if the CA certificate(s) are not exported to PKCS12 then the resulting PKCS12 store cannot be logged into again using a User object and a PKCS12Reader. Instead, the low-level PKCS12 utilities classes found in the iaik.pkcs.pkcs12 package must be used for accessing the keys and certificates in the PKCS12 store.

Parameters:

exportCaCertificates - true if the CA certificate(s) are to be exported to the PKCS12 store; false otherwise

Since:

7.2 SP2 Patch

setFriendlyName

public void setFriendlyName(java.lang.String name,
                            boolean useKeyUsage)

This method is used to override the default Friendly Name used for the KeyBag and Certificate Bags when exporting to the PKCS#12 format. By default, the toolkit uses the following Friendly Name convention:

 DN + KeyUsage
 

For example, if the User's DN is "cn=user,ou=myCompany,c=ca", and the KeyUsage for the Certificate is "Encryption" then by default the friendly name would become:

 "cn=user,ou=myCompany,c=ca Encryption Certificate".   
 

If it were a Key, it would become:

 "cn=user,ou=myCompany,c=ca Encryption key"
 

This API overrides the default, and allows the user to specify any String value in place of the DN. If this API is called and null is passed in, the DN from the User's certificate will be used.

If the value of the useKeyUsage parameter is true, then the KeyUsage will be appended to the String part of the FriendlyName. If the value is false, the KeyUsage will not be added to the String part of the Friendly Name.

Parameters:

name - The Friendly Name to use for CertificateBag and KeyBags. This overrides the default which is the User's DN.

useKeyUsage - True to indicate the KeyUsage should be added to the Friendly Name, false to indicate it should not be added to the FriendlyName.

Since:

8.0 patch