com.entrust.toolkit.capi

Class CryptKey

java.lang.Object

com.entrust.toolkit.credentials.Handle

com.entrust.toolkit.capi.CapiHandle

com.entrust.toolkit.capi.CryptKey

public class CryptKey
extends CapiHandle

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

FIPS 140-2:

This class is part of the Toolkit's FIPS 140-2 cryptographic module and contains APIs that are considered part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; refer to the API documentation for further details

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	close() Close the handle to the native key object, releasing memory.
static java.security.PrivateKey	decodePrivateKey(byte[] keyBlob) Decodes a software-based private key from MSCAPI key blob representation.
byte[]	decrypt(boolean isFinal, byte[] data, int offset, int length) Decrypt data previously encrypted using encrypt.
static byte[]	encodePrivateKey(java.security.PrivateKey privateKey, KeySpec keySpec) Encodes a software-based private key to MSCAPI key blob representation.
byte[]	encrypt(boolean isFinal, byte[] data, int offset, int length) Encrypts data.
java.security.PublicKey	exportPublicKey() Exports the public key from MSCAPI to software-based representation.
static java.security.KeyPair	generateKeyPair(CryptProvider provider, EntrustAsymKeyType keyType, KeySpec keySpec, int flags) Generates a key pair in MSCAPI.
KeyAlgorithms	getAlgorithm() Returns the algorithm associated with this key, or null if the algorithm is not recognized.
CryptProvider	getCryptProvider() Returns the CryptProvider used when creating this key.
static CryptKey	getInstance(CryptProvider provider, KeySpec keySpec) Creates and returns a CryptKey object associated with a public/private key pair that already exists in CAPI.
byte[]	getKeyParam(KeyParam keyParamId) Gets the value of a parameter associated with this key in MSCAPI.
byte[]	getKeyParameter(KeyParam parameter) Deprecated. use getKeyParam(KeyParam) instead; since 8.0
KeySpec	getKeySpec() Gets the key specifier associated with this key.
static CryptKey	importKey(CryptProvider provider, byte[] key, CryptKey hPubKey, int flags) Imports a key in to CAPI and returns a handle to the newly imported key.
static CapiPrivateKey	importPrivateKey(CryptProvider provider, java.security.PrivateKey privateKey, KeySpec keySpec, int flags, boolean forceSecureKeyImport) Imports the provided software-based private key into MSCAPI, using the provided key specifier to determine the MSCAPI key algorithm for the key.
static CapiPrivateKey	importPrivateKey(CryptProvider provider, java.security.PrivateKey privateKey, KeyUsage keyUsage, int flags, boolean forceSecureKeyImport) Imports the provided software-based private key into MSCAPI, using the provided key usage to determine the MSCAPI key algorithm for the key.
void	setKeyParam(KeyParam keyParamId, byte[] keyParamValue) Sets the value of a parameter associated with this key in MSCAPI.

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

Method Detail

getInstance

public static CryptKey getInstance(CryptProvider provider,
                                   KeySpec keySpec)
                            throws CapiException

Creates and returns a CryptKey object associated with a public/private key pair that already exists in CAPI.

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• status output interface (exceptions)

Parameters:

provider - [FIPS 140-2 control input] the CSP from which to get the key.

keySpec - [FIPS 140-2 control input] the key specifier, either AT_KEYEXCHANGE or AT_SIGNATURE.

Returns:

[FIPS 140-2 status output] an initialized CryptKey object.

Throws:

CapiException - [FIPS 140-2 status output] if the key could not be created.

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

See Also:

MSDN library documentation for CryptGetUserKey

importKey

public static CryptKey importKey(CryptProvider provider,
                                 byte[] key,
                                 CryptKey hPubKey,
                                 int flags)
                          throws CapiException

Imports a key in to CAPI and returns a handle to the newly imported key. For importing private keys, the class CapiKeyFormatter can be used to convert from the ASN.1 encoding of a private key to a format that will be accepted by CAPI.

FIPS 140-2:

FIPS Service: Key Input/Output (logical port)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

provider - [FIPS 140-2 control input] the provider that will own the imported key. This provider must be able to support the key algorithm.

key - [FIPS 140-2 data input] [FIPS 140-2 CSP] the key to import.

hPubKey - [FIPS 140-2 data input] a handle to a key to be used to decrypt the key being imported, or null if the key being imported is not protected.

flags - [FIPS 140-2 control input] the MSCAPI flags; all 32-bits are used

Returns:

[FIPS 140-2 data output] a handle to the imported key.

Throws:

CapiException - [FIPS 140-2 status output] if the CAPI function CryptImportKey fails.

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

See Also:

CapiKeyFormatter, MSDN library documentation for CryptImportKey

importPrivateKey

public static CapiPrivateKey importPrivateKey(CryptProvider provider,
                                              java.security.PrivateKey privateKey,
                                              KeyUsage keyUsage,
                                              int flags,
                                              boolean forceSecureKeyImport)
                                       throws CapiException

Imports the provided software-based private key into MSCAPI, using the provided key usage to determine the MSCAPI key algorithm for the key.

Refer to importPrivateKey(CryptProvider, PrivateKey, KeySpec, int, boolean) for additional details on the import operation.

FIPS 140-2:

FIPS Service: Key Input/Output (logical port)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

provider - [FIPS 140-2 control input] the CSP to which the private key will be imported

privateKey - [FIPS 140-2 data input] [FIPS 140-2 CSP] a software-based private key

keyUsage - [FIPS 140-2 control input] the key usage associated with the private key; used to determine the algorithm that is associated with the private key in MSCAPI

flags - [FIPS 140-2 control input] the MSCAPI flags; all 32-bits are used

forceSecureKeyImport - [FIPS 140-2 control input] Used to determine whether secure key import is used

Returns:

[FIPS 140-2 data output] an MSCAPI-based representation of the private key

Throws:

CapiException - [FIPS 140-2 status output] if the private key import operation fails

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

Since:

8.0

importPrivateKey

public static CapiPrivateKey importPrivateKey(CryptProvider provider,
                                              java.security.PrivateKey privateKey,
                                              KeySpec keySpec,
                                              int flags,
                                              boolean forceSecureKeyImport)
                                       throws CapiException

Imports the provided software-based private key into MSCAPI, using the provided key specifier to determine the MSCAPI key algorithm for the key.

An attempt is first made to import the private key securely, that is, protected under a symmetric key. If the secure key import attempt fails and the Toolkit is not operating in FIPS mode, then an attempt is made to import the private key into MSCAPI in the clear (unprotected); otherwise an error is returned indicating import in the clear is not permitted when operating in FIPS mode.

The following are the set of steps that occur when performing a secure key import operation.

1. A symmetric secure key import key is generated in Java.
2. The private key being imported is encrypted under the symmetric secure key import key in Java.
3. A public/private secure key import key pair is generated in MSCAPI, the public component of which is exported to Java.
4. The symmetric secure key import key is encrypted under the public secure key import key in Java.
5. The encrypted symmetric secure key import key is imported to MSCAPI and decrypted there using the private secure key import key.
6. The encrypted private key is then imported to MSCAPI and decrypted there using the symmetric secure key import key.

Secure key import is currently only supported for RSA keys. For secure key import of RSA private keys, the public/private secure key import key pair used is an RSA key pair of the same strength. The symmetric key that is used depends on the capabilities of the CSP to which the key is being imported. The following algorithms are supported in Java and listed in order of preference. The first algorithm in this list that is also supported by the CSP is used in the secure key import operation.

• EntrustSymmEncConfig.AES_CBC_256
• EntrustSymmEncConfig.AES_CBC_192
• EntrustSymmEncConfig.AES_CBC_128
• EntrustSymmEncConfig.TRIPLEDES_CBC_192

FIPS 140-2:

FIPS Service: Key Input/Output (logical port)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

provider - [FIPS 140-2 control input] the CSP to which the private key will be imported

privateKey - [FIPS 140-2 data input] [FIPS 140-2 CSP] a software-based private key

keySpec - [FIPS 140-2 control input] the key specifier associated with the private key; used to determine the algorithm that is associated with the private key in MSCAPI

flags - [FIPS 140-2 control input] the MSCAPI flags; all 32-bits are used

forceSecureKeyImport - [FIPS 140-2 control input] Used to determine whether secure key import is used

Returns:

[FIPS 140-2 data output] an MSCAPI-based representation of the private key

Throws:

CapiException - [FIPS 140-2 status output] if the private key import operation fails

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

Since:

8.0

generateKeyPair

public static java.security.KeyPair generateKeyPair(CryptProvider provider,
                                                    EntrustAsymKeyType keyType,
                                                    KeySpec keySpec,
                                                    int flags)
                                             throws CapiException

Generates a key pair in MSCAPI.

FIPS 140-2:

FIPS Service: Key Generation

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 crypto officer role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

provider - [FIPS 140-2 control input] the CSP in which the key pair will be generated

keyType - [FIPS 140-2 data input] the key type; identifies the type of key pair (e.g. RSA-1024) being generated

keySpec - [FIPS 140-2 control input] the key specifier; used to determine the algorithm that is associated with the key pair in MSCAPI

flags - [FIPS 140-2 control input] the MSCAPI flags; only the lower 16-bits are used

Returns:

[FIPS 140-2 data output] [FIPS 140-2 CSP] the key pair; contains an MSCAPI-based representation of the private key and a software-based representation of the public key

Throws:

CapiException - [FIPS 140-2 status output] if the key pair generation operation fails

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

Since:

8.0

encodePrivateKey

public static byte[] encodePrivateKey(java.security.PrivateKey privateKey,
                                      KeySpec keySpec)
                               throws CapiException

Encodes a software-based private key to MSCAPI key blob representation.

FIPS 140-2:

FIPS Service: Key Transport (primitive)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

privateKey - [FIPS 140-2 data input] [FIPS 140-2 CSP] a software-based private key

keySpec - [FIPS 140-2 control input] the key specifier; used to determine the key algorithm that is used in the key blob representation

Returns:

[FIPS 140-2 data output] the MSCAPI key blob representation of the private key

Throws:

CapiException - if the encode operation fails

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

Since:

8.0 Patch

decodePrivateKey

public static java.security.PrivateKey decodePrivateKey(byte[] keyBlob)
                                                 throws CapiException

Decodes a software-based private key from MSCAPI key blob representation.

FIPS 140-2:

FIPS Service: Key Transport (primitive)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

keyBlob - [FIPS 140-2 data input] [FIPS 140-2 CSP] a private key in MSCAPI key blob representation

Returns:

[FIPS 140-2 data output] the software-based representation of the private key

Throws:

CapiException - if the decode operation fails

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

Since:

8.0 Patch

close

public void close()

Close the handle to the native key object, releasing memory. No further calls can be made to this object after calling this method.

FIPS 140-2:

FIPS Service: Modify Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• status output interface (exceptions)

Specified by:

close in class Handle

encrypt

public byte[] encrypt(boolean isFinal,
                      byte[] data,
                      int offset,
                      int length)
               throws CapiException

Encrypts data.

FIPS 140-2:

FIPS Service: Cryptographic Operation

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

isFinal - [FIPS 140-2 control input] true if this is the last data to encrypt, false if there is more data to be encrypted.

data - [FIPS 140-2 data input] the data to encrypt. This data is not overwritten.

offset - [FIPS 140-2 data input] the starting offset in the data array.

length - [FIPS 140-2 data input] the number of bytes in data to decrypt.

Returns:

[FIPS 140-2 data output] the encrypted data.

Throws:

CapiException - [FIPS 140-2 status output] if an error occurs encrypting the data

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

See Also:

MSDN library documentation for CryptEncrypt

decrypt

public byte[] decrypt(boolean isFinal,
                      byte[] data,
                      int offset,
                      int length)
               throws CapiException

Decrypt data previously encrypted using encrypt.

FIPS 140-2:

FIPS Service: Cryptographic Operation

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

isFinal - [FIPS 140-2 control input] true if this is the last data to decrypt, false if there is more data to be decrypted.

data - [FIPS 140-2 data input] the data to decrypt. This data is not overwritten.

offset - [FIPS 140-2 data input] the starting offset in the data array.

length - [FIPS 140-2 data input] the number of bytes in data to decrypt.

Returns:

[FIPS 140-2 data output] the decrypted data.

Throws:

CapiException - [FIPS 140-2 status output] if an error occurs decrypting the data

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

See Also:

MSDN library documentation for CryptDecrypt

getCryptProvider

public CryptProvider getCryptProvider()

Returns the CryptProvider used when creating this key.

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data output interface (return value)
• status output interface (exceptions)

Returns:

[FIPS 140-2 data output] the CryptProvider used when creating this key.

getAlgorithm

public KeyAlgorithms getAlgorithm()
                           throws CapiException

Returns the algorithm associated with this key, or null if the algorithm is not recognized.

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data output interface (return value)
• status output interface (exceptions)

Returns:

[FIPS 140-2 data output] the algorithm associated with this key.

Throws:

CapiException - [FIPS 140-2 status output] if the call to CryptGetKeyParam to obtain the key algorithm id fails.

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

getKeySpec

public KeySpec getKeySpec()
                   throws CapiException

Gets the key specifier associated with this key.

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data output interface (return value)
• status output interface (exceptions)

The key specifier is determined based on the algorithm that is associated with the key in MSCAPI.

Returns:

[FIPS 140-2 data output] the key specifier

Throws:

CapiException - [FIPS 140-2 status output] if the key is associated with an algorithm in MSCAPI that is not supported by the Toolkit

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

Since:

8.0

getKeyParameter

public byte[] getKeyParameter(KeyParam parameter)
                       throws CapiException

Deprecated. use getKeyParam(KeyParam) instead; since 8.0

Gets a parameter for this key.

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

parameter - [FIPS 140-2 control input] the key parameter to retrieve.

Returns:

[FIPS 140-2 data output] the key parameter.

Note

The returned byte array has the bytes in the reverse order of those returned by CryptGetKeyParam

Throws:

CapiException - [FIPS 140-2 status output] if the call to CryptGetKeyParam fails.

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

See Also:

MSDN library documentation for CryptGetKeyParam

getKeyParam

public byte[] getKeyParam(KeyParam keyParamId)
                   throws CapiException

Gets the value of a parameter associated with this key in MSCAPI.

IMPORTANT The key parameter value returned by this API is passed back directly from MSCAPI without modification. Depending on the parameter type, the endianness of the value may need to be accounted for by the caller. For example, any parameter that is defined as a DWORD is represented as a little endian value in MSCAPI. When converting this type of key parameter value to a Java type (an integer for example), the endianness must be accounted for.

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

keyParamId - [FIPS 140-2 control input] a key parameter identifier; identifies the key parameter being retrieved

Returns:

[FIPS 140-2 data output] the value of the requested key parameter

Throws:

CapiException - [FIPS 140-2 status output] if the key parameter get operation fails

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

Since:

8.0

setKeyParam

public void setKeyParam(KeyParam keyParamId,
                        byte[] keyParamValue)
                 throws CapiException

Sets the value of a parameter associated with this key in MSCAPI.

IMPORTANT The key parameter value provided to this API is passed directly to MSCAPI without modification. Depending on the parameter type, the endianness of the value may need to be accounted for by the caller. For example, any parameter that is defined as a DWORD is represented as a little endian value in MSCAPI. When converting a Java type (an integer for example) to this type of key parameter value, the endianness must be accounted for.

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• status output interface (exceptions)

Parameters:

keyParamId - [FIPS 140-2 control input] a key parameter identifier; identifies the key parameter being set

keyParamValue - [FIPS 140-2 data input] the value of the key parameter being set

Throws:

CapiException - [FIPS 140-2 status output]if the key parameter set operation fails

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

Since:

8.0

exportPublicKey

public java.security.PublicKey exportPublicKey()
                                        throws CapiException

Exports the public key from MSCAPI to software-based representation.

FIPS 140-2:

FIPS Service: Key Input/Output (logical port)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data output interface (return value)
• status output interface (exceptions)

Returns:

[FIPS 140-2 data output] [FIPS 140-2 CSP] a software-based representation of the public key

Throws:

CapiException - [FIPS 140-2 status output] if the public key export operation fails

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

Since:

8.0