com.entrust.toolkit.capi

Class CryptProvider

java.lang.Object

com.entrust.toolkit.capi.CapiHandle

com.entrust.toolkit.capi.CryptProvider

public class CryptProvider
extends CapiHandle

This class encapsulates information about a handle to a CAPI Cryptographic Service Provider (CSP). It is analogous the CAPI HCRYPTPROV type, and is used for all situations where an HCRYPTPROV is required for a native call. It also stores the name of the CAPI container associated with this CSP, if any, and the CSP name and type.

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

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canUseHardwareRng() Return whether or not this provider can use a hardware random number generator.
void	close() Closes the handle to the CSP, releasing memory allocated by native code.
void	forceUseHardwareRng() Force random number generation to be done using a hardware RNG.
void	genRandom(byte[] randomBytes) Fills the given array with random bytes.
void	genRandom(byte[] randomBytes, int offset, int length) Fills the given array with length random bytes, starting at offset.
byte[]	genRandom(int numBytes) Generates numBytes random bytes and returns an array containing those bytes.
java.lang.String	getContainerName() Returns the name of the container associated with this object.
java.util.List<java.lang.String>	getContainers() Returns a List of Strings that are the names of the containers belonging to this provider.
byte[]	getCSPParam(ProviderParam providerParam) Gets the value of a CSP parametet associated with this CryptProvider in MSCAPI
static ProviderInfo	getDefaultProviderInfo(ProviderType providerType, int flags) Returns information about the default provider for the given provider type.
static ProviderInfo	getFirstAvailableProvider(java.lang.String[] providerNames) Given a String list of provider names, return the first provider that is available.
CryptImplType	getImplementationType() Returns the implementation type of this provider.
static CryptProvider	getInstance(java.lang.String container, java.lang.String provider, ProviderType providerType, int flags) Creates an returns an initialized CryptProvider.
ProviderInfo	getProviderInfo() Returns information about the CSP associated with this object.
static ProviderInfo	getProviderInfo(java.lang.String providerName) Returns information about the MSCAPI cryptographic service provider (CSP) with the given name.
static java.util.List<ProviderInfo>	getProviders() Returns a List of ProviderInfo objects, one for each provider installed on the system.
static java.util.List<ProviderInfo>	getProviderTypes() Returns a List of ProviderInfo objects, one for each provider type installed on the system.
static byte[]	getRandomDataFromDefaultProvider(int size) Generates the requested number of random bytes using the default CAPI cryptographic service provider.
java.util.List<ProviderAlgorithmInfo>	getSupportedAlgorithms() Returns a List of ProviderAlgorithmInfo objects that denote the algorithms supported by this provider.
void	setCSPParam(ProviderParam providerParam, byte[] cspValue) Sets the value of a CSP parameter associated with this CryptProvider in MSCAPI.
boolean	supportsAlgorithm(Algorithms algorithm) Returns true if this provider supports the given algorithm, false if not.

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

clearHandle, debugInfo, debugInfo, equals, finalize, getHandle, hashCode, setExtendedDebugging

Methods inherited from class java.lang.Object

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

Method Detail

getProviderTypes

public static java.util.List<ProviderInfo> getProviderTypes()
                                                     throws CapiException

Returns a List of ProviderInfo objects, one for each provider type installed on the system.

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] a List of ProviderInfo objects, one for each provider type installed on the system.

Throws:

CapiException - [FIPS 140-2 status output] if there is a problem obtaining the provider type information from CAPI.

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

getProviders

public static java.util.List<ProviderInfo> getProviders()
                                                 throws CapiException

Returns a List of ProviderInfo objects, one for each provider installed on the system.

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] a List of ProviderInfo objects, one for each provider installed on the system.

Throws:

CapiException - [FIPS 140-2 status output] if there is a problem obtaining the provider information from CAPI.

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

getProviderInfo

public static ProviderInfo getProviderInfo(java.lang.String providerName)
                                    throws CapiException

Returns information about the MSCAPI cryptographic service provider (CSP) with the given name.

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 input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

providerName - [FIPS 140-2 data input] name of an MSCAPI CSP

Returns:

[FIPS 140-2 data output] information about the MSCAPI CSP

Throws:

CapiException - [FIPS 140-2 status output] if the operation fails (e.g. there are no CSPs on the system with the indicated name)

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

Since:

8.0

getFirstAvailableProvider

public static ProviderInfo getFirstAvailableProvider(java.lang.String[] providerNames)
                                              throws CapiException

Given a String list of provider names, return the first provider that is available. For example, this method will return the first available provider if the following list is passed in.

 String provList[] = new String[]{"Microsoft Enhanced RSA and AES Cryptographic Provider",
                                  "Microsoft Enhanced RSA and AES Cryptographic Provider (Prototype)",
                                  "Microsoft Enhanced Cryptographic Provider v1.0"};
 

Parameters:

providerNames - An array of Provider Names

Returns:

The ProviderInfo of the firstAvailableProvider

Throws:

CapiException

getDefaultProviderInfo

public static ProviderInfo getDefaultProviderInfo(ProviderType providerType,
                                  int flags)
                                           throws CapiException

Returns information about the default provider for the given provider type.

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:

providerType - [FIPS 140-2 control input] The provider type to get information about.

flags - [FIPS 140-2 control input]

• CapiConstants.CRYPT_MACHINE_DEFAULT - Causes the computer default CSP of the specified type to be returned.
• CapiConstants.CRYPT_USER_DEFAULT Causes the user default CSP of the specified type to be returned.

Returns:

[FIPS 140-2 data output] A ProviderInfo object with information about the requested provider type.

Throws:

CapiException - [FIPS 140-2 status output] if an error occurs retrieving information about the provider. Some provider types may not have a default provider registered.

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

See Also:

MSDN library documentation for CryptGetDefaultProvider

getInstance

public static CryptProvider getInstance(java.lang.String container,
                        java.lang.String provider,
                        ProviderType providerType,
                        int flags)
                                 throws CapiException

Creates an returns an initialized CryptProvider.

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)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

container - [FIPS 140-2 data input] name of the container, or null for the default container for the named provider. Note that not all CSPs support default containers.

provider - [FIPS 140-2 data input] name of the CSP, or null for the default CSP for the given provider type.

providerType - [FIPS 140-2 control input] the type of the provider.

flags - [FIPS 140-2 control input] flags that control how the instance is obtained. A combination of the flags CRYPT_VERIFYCONTEXT, CRYPT_NEWKEYSET, CRYPT_DELETEKEYSET, CRYPT_MACHINE_KEYSET, and CRYPT_SILENT from CapiConstants, or 0.

Returns:

[FIPS 140-2 data output] a CryptProvider object that is initialized with a handle to the named provider. When the CRYPT_DELETEKEYSET flag is used, the returned value is undefined and should be ignored.

Throws:

CapiException - [FIPS 140-2 status output] if a handle to the CSP cannot be acquired for any reason.

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

See Also:

MSDN library documentation of the function CryptAcquireContext

getRandomDataFromDefaultProvider

public static byte[] getRandomDataFromDefaultProvider(int size)
                                               throws CapiException

Generates the requested number of random bytes using the default CAPI cryptographic service provider.

This call will load the default CAPI native library if the CAPI native library has not yet been loaded.

FIPS 140-2:

FIPS Service: Random Number 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 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:

size - [FIPS 140-2 control input] the number of random bytes to be generated

Returns:

[FIPS 140-2 data output] the random data that was generated

Throws:

CapiException - [FIPS 140-2 status output] thrown if an error occurs while generating the random data

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

close

public void close()

Closes the handle to the CSP, releasing memory allocated by native code. This call renders this object useless, although the "get" calls will still return valid information.

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 CapiHandle

getProviderInfo

public ProviderInfo getProviderInfo()

Returns information about the CSP associated with this object.

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] information about the CSP associated with this object.

Throws:

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

getContainerName

public java.lang.String getContainerName()

Returns the name of the container associated with this object.

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 name of the container associated with this object. Returns null if this provider is not associated with a container, which may be the case if the CRYPT_VERIFY_CONTEXT flag was used.

Throws:

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

getSupportedAlgorithms

public java.util.List<ProviderAlgorithmInfo> getSupportedAlgorithms()
                                                             throws CapiException

Returns a List of ProviderAlgorithmInfo objects that denote the algorithms supported by this provider.

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] a List of ProviderAlgorithmInfo objects that denote the algorithms supported by this provider.

Throws:

CapiException - if there is a problem obtaining the list of algorithms from CAPI.

supportsAlgorithm

public boolean supportsAlgorithm(Algorithms algorithm)

Returns true if this provider supports the given algorithm, false if not.

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:

algorithm - [FIPS 140-2 control input] the algorithm to check for support.

Returns:

[FIPS 140-2 data output] true if this provider supports the given algorithm, false if not.

Throws:

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

getContainers

public java.util.List<java.lang.String> getContainers()
                                               throws CapiException

Returns a List of Strings that are the names of the containers belonging to this provider.

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] a List of Strings that are the names of the containers belonging to this provider.

Throws:

CapiException - [FIPS 140-2 status output] if there is a problem obtaining the list of containers from CAPI.

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

genRandom

public void genRandom(byte[] randomBytes)
               throws CapiException

Fills the given array with random bytes. The CAPI cryptographic service provider is used to generate the random bytes.

FIPS 140-2:

FIPS Service: Random Number 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 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)

Parameters:

randomBytes - [FIPS 140-2 data output] the byte array to fill will random bytes.

Throws:

CapiException - [FIPS 140-2 status output] if an error occurs generating the random data.

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

See Also:

MSDN library documentation for CryptGenRandom

genRandom

public void genRandom(byte[] randomBytes,
             int offset,
             int length)
               throws CapiException

Fills the given array with length random bytes, starting at offset. The CAPI cryptographic service provider is used to generate the random bytes.

FIPS 140-2:

FIPS Service: Random Number 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 user role and accesses the following FIPS 140-2 logical interfaces:

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

Parameters:

randomBytes - [FIPS 140-2 data output] the byte array to fill will random bytes.

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

length - [FIPS 140-2 data input] the number of random bytes to generate.

Throws:

CapiException - [FIPS 140-2 status output] if an error occurs generating the random data.

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

See Also:

MSDN library documentation for CryptGenRandom

genRandom

public byte[] genRandom(int numBytes)
                 throws CapiException

Generates numBytes random bytes and returns an array containing those bytes. The CAPI cryptographic service provider is used to generate the random bytes.

FIPS 140-2:

FIPS Service: Random Number 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 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:

numBytes - [FIPS 140-2 control input] the number of random bytes to generate.

Returns:

[FIPS 140-2 data output] the byte array containing numBytes random bytes.

Throws:

CapiException - [FIPS 140-2 status output] if an error occurs generating the random data.

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

See Also:

MSDN library documentation for CryptGenRandom

canUseHardwareRng

public boolean canUseHardwareRng()

Return whether or not this provider can use a hardware random number generator.

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] whether or not this provider can use a hardware RNG.

Throws:

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

forceUseHardwareRng

public void forceUseHardwareRng()
                         throws CapiException

Force random number generation to be done using a hardware RNG. There is no way to undo this call after it has been made.

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)
• status output interface (exceptions)

Throws:

CapiException - if this provider does not support a hardware RNG, or a problem occurs setting hardware RNG usage.

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

getImplementationType

public CryptImplType getImplementationType()

Returns the implementation type of this provider.

• CRYPT_IMPL_HARDWARE - the implementation is in hardware.
• CRYPT_IMPL_SOFTWARE - the implementation is in software.
• CRYPT_IMPL_MIXED - the implementation involves both hardware and software.
• CRYPT_IMPL_UNKNOWN - the implementation type is unknown.

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 implementation type of this provider.

Throws:

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

See Also:

MSDN library documentation for CryptGetProvParam

setCSPParam

public void setCSPParam(ProviderParam providerParam,
               byte[] cspValue)
                 throws CapiException

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

IMPORTANT The csp 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: 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)
• data input interface (parameters)
• status output interface (exceptions)

Parameters:

providerParam - [FIPS 140-2 control input] A provider parameter; identifies the CSP parameter being set

cspValue - [FIPS 140-2 data input] the value of the csp parameter being set

Throws:

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

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

Since:

8.0

getCSPParam

public byte[] getCSPParam(ProviderParam providerParam)
                   throws CapiException

Gets the value of a CSP parametet associated with this CryptProvider 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:

providerParam - [FIPS 140-2 control input] A provider parameter; identifies the CSP parameter being retrieved

Returns:

[FIPS 140-2 data output] the value of the requested CSP 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