com.pheox.jcapi
Class JCAPIUtil

java.lang.Object
  com.pheox.jcapi.JCAPIUtil

public final class JCAPIUtil
extends java.lang.Object

Utility functions not directly related to the functionality of the JCE framework are available through this class.

To learn more about how this class can be used, please look at the following example programs that can be found in JCAPI's examples directory, by default located in C:\<application data directory>\JCAPI\examples:

• util\CertStores.java
• util\EnvironmentInfo.java
• util\ListSupportedAlgorithms.java
• util\StringUtils.java

Since:

1.0

Field Summary

static int	ALG_CLASS_ALL MS CAPI algorithm class known by JCAPI.
static int	ALG_CLASS_ANY MS CAPI algorithm class known by JCAPI.
static int	ALG_CLASS_DATA_ENCRYPT MS CAPI algorithm class known by JCAPI.
static int	ALG_CLASS_HASH MS CAPI algorithm class known by JCAPI.
static int	ALG_CLASS_KEY_EXCHANGE MS CAPI algorithm class known by JCAPI.
static int	ALG_CLASS_MSG_ENCRYPT MS CAPI algorithm class known by JCAPI.
static int	ALG_CLASS_SIGNATURE MS CAPI algorithm class known by JCAPI.
static int	KEY_USAGE_ENCRYPTION Equals the MS CAPI key usage identity AT_KEYEXCHANGE.
static int	KEY_USAGE_SIGNATURE Equals the MS CAPI key usage identity AT_SIGNATURE.

Method Summary

static java.lang.String	asHex(byte[] buf) Returns a hex decimal (base 16) string representation of the given byte array.
static void	createCertStore(java.lang.String name) Creates a MS CAPI certificate/system store.
static byte[]	decodeBase64(java.lang.String buf) Will decode the Base64 encoded string.
static void	deleteCertStore(java.lang.String name) Will delete the MS CAPI certificate/system store given by parameter name.
static java.lang.String	encodeBase64(byte[] buf) Will Base64 encode the given string.
static int	getAlgorithmClass(int algId) Returns the algorithm class of the given algorithm identifier.
static JCAPICSPAlgorithmKeyLengths	getAlgorithmKeyLengths(JCAPICSPAlgorithm alg) Returns the supported key lengths (minimum, maximum, and default lengths) for the given algorithm.
static JCAPICSPAlgorithm[]	getAlgorithmsByCSP(java.lang.String cspName) Returns all algorithms that are supported by the Cryptographic Service Provider (CSP) given in cspName.
static java.lang.String	getCertificateFriendlyName(java.lang.String alias) Returns the MS CAPI friendly name of the certificate referred by the given parameter alias.
static java.lang.String	getCertStoreFriendlyName(java.lang.String certStoreName) Returns the friendly name of the MS CAPI certificate/system store given by parameter certStoreName.
static java.lang.String[]	getCertStoreNames() Returns a list of all MS CAPI certificate stores (a.k.a system stores) available.
static java.lang.String	getCSP(java.lang.String alias) Returns the name of the Cryptographic Service Provider (CSP) used for managing the certificate/key entry given by parameter alias.
static java.lang.String[]	getCSPs() Returns a list of all available MS CAPI Cryptographic Service Providers (CSP) in your system.
static java.lang.String	getEnvironmentInfo() Returns information about the environment in which JCAPI is executed.
static java.lang.String	getJCAPIDLLVersion() Returns the version of the JCAPI DLL that is used by this particular version of JCAPI.
static java.lang.String	getJCAPILicense() Returns the license agreement for this particular copy of JCAPI.
static java.lang.String	getJCAPIVersion() Returns the version of JCAPI.
static int	getPrivateKeyUsage(java.lang.String alias) Returns the key usage of the key entry given by parameter alias.
static int	getProviderTypeByAlias(java.lang.String alias) Returns the provider type of the JCAPI certificate alias given in parameter alias.
static int	getProviderTypeByCSP(java.lang.String csp) Returns the provider type of the Cryptographic Service Provider (CSP) name given in parameter csp.
static boolean	isCertStoreAvailable(java.lang.String store) Returns true if the given MS CAPI certificate/system store exists, else false.
static boolean	isCSPAvailable(java.lang.String csp) Returns true if the Cryptographic Service Provider (CSP) given in parameter csp can be found and used in MS CAPI, else false.
static void	setCertificateFriendlyName(java.lang.String alias, java.lang.String friendlyName) Set friendly name friendlyName for the certificate referred by the given parameter alias.

Methods inherited from class java.lang.Object

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

Field Detail

ALG_CLASS_ANY

public static final int ALG_CLASS_ANY

MS CAPI algorithm class known by JCAPI.

Since:

2.0

See Also:

Constant Field Values

ALG_CLASS_SIGNATURE

public static final int ALG_CLASS_SIGNATURE

MS CAPI algorithm class known by JCAPI.

Since:

2.0

See Also:

Constant Field Values

ALG_CLASS_MSG_ENCRYPT

public static final int ALG_CLASS_MSG_ENCRYPT

MS CAPI algorithm class known by JCAPI.

Since:

2.0

See Also:

Constant Field Values

ALG_CLASS_DATA_ENCRYPT

public static final int ALG_CLASS_DATA_ENCRYPT

MS CAPI algorithm class known by JCAPI.

Since:

2.0

See Also:

Constant Field Values

ALG_CLASS_HASH

public static final int ALG_CLASS_HASH

MS CAPI algorithm class known by JCAPI.

Since:

2.0

See Also:

Constant Field Values

ALG_CLASS_KEY_EXCHANGE

public static final int ALG_CLASS_KEY_EXCHANGE

MS CAPI algorithm class known by JCAPI.

Since:

2.0

See Also:

Constant Field Values

ALG_CLASS_ALL

public static final int ALG_CLASS_ALL

MS CAPI algorithm class known by JCAPI.

Since:

2.0

See Also:

Constant Field Values

KEY_USAGE_ENCRYPTION

public static final int KEY_USAGE_ENCRYPTION

Equals the MS CAPI key usage identity AT_KEYEXCHANGE.

Since:

2.0

See Also:

Constant Field Values

KEY_USAGE_SIGNATURE

public static final int KEY_USAGE_SIGNATURE

Equals the MS CAPI key usage identity AT_SIGNATURE.

Since:

2.0

See Also:

Constant Field Values

Method Detail

getJCAPIVersion

public static java.lang.String getJCAPIVersion()

Returns the version of JCAPI.

Returns:

the version of JCAPI.

Since:

1.0

getJCAPIDLLVersion

public static java.lang.String getJCAPIDLLVersion()

Returns the version of the JCAPI DLL that is used by this particular version of JCAPI.

Returns:

the version of the JCAPI DLL.

Throws:

JCAPIJNIRuntimeException - if an unexpected error occur inside MS CAPI.

Since:

1.0

getEnvironmentInfo

public static java.lang.String getEnvironmentInfo()

Returns information about the environment in which JCAPI is executed.
Use this method to get the environmental information to be included in an eventual error report. This will help us to understand and locate the error much faster.

Returns:

the environment information.

Throws:

JCAPIJNIRuntimeException - if an unexpected error occur inside MS CAPI.

Since:

1.0

getJCAPILicense

public static java.lang.String getJCAPILicense()

Returns the license agreement for this particular copy of JCAPI.

Returns:

the license agreement.

Since:

1.0

getCSPs

public static java.lang.String[] getCSPs()

Returns a list of all available MS CAPI Cryptographic Service Providers (CSP) in your system.

Returns:

a list of available MS CAPI CSPs.

Throws:

JCAPIJNIRuntimeException - if an unexpected error occur in MS CAPI.

Since:

2.0

getCSP

public static java.lang.String getCSP(java.lang.String alias)
                               throws JCAPIUnknownAliasException,
                                      java.lang.IllegalArgumentException

Returns the name of the Cryptographic Service Provider (CSP) used for managing the certificate/key entry given by parameter alias.

Parameters:

alias - the JCAPI alias of the certificate/key entry.

Returns:

the name of the CSP.

Throws:

JCAPIUnknownAliasException - if given alias does not exist.

java.lang.IllegalArgumentException - if parameter alias is null or empty.

JCAPIJNIRuntimeException - if an unexpected error occur inside MS CAPI.

Since:

1.1

isCSPAvailable

public static boolean isCSPAvailable(java.lang.String csp)
                              throws java.lang.IllegalArgumentException

Returns true if the Cryptographic Service Provider (CSP) given in parameter csp can be found and used in MS CAPI, else false.

For example, the following CSP is present on all Windows systems, and this method will thus always return true in this case:
JCAPIUtil.isCSPAvailable("Microsoft Base Cryptographic Provider v1.0");

Hint: you can get a list of all available CSPs through the following method getCSPs().

Parameters:

csp - the csp to check for.

Returns:

true if the CSP can be found, else false.

Throws:

java.lang.IllegalArgumentException - if parameter csp is null or empty.

Since:

2.0

getCertStoreNames

public static java.lang.String[] getCertStoreNames()

Returns a list of all MS CAPI certificate stores (a.k.a system stores) available.
On a MS Windows operating system, the following stores shall at least be available:

• My
• CA
• Root
• Trust
• UserDS

For more information about the meaning of these stores, see class description for JCAPIKeyStore.

JCAPI uses the ADDRESSBOOK store as its default certificate entry store. If this store does not exist (which is usually the case if Outlook has not been installed and configured yet) then JCAPI will automatically create the ADDRESSBOOK store during start up.

JCAPI will by default access all certificate stores available e.g. when method aliases() in class java.security.KeyStore is called, then an enumeration of certificates found in all these stores are returned.

If you want JCAPI to access a different set of certificate stores, then use the JCAPI dynamic key store feature, see method JCAPICryptoFactory.createKeyStoreInstance(String,String,String[],String,String,String,String,String,boolean).

Returns:

a list of MS CAPI certificate stores accessed by JCAPI.

Throws:

JCAPIJNIRuntimeException - if an unexpected error occur in MS CAPI.

Since:

2.0

isCertStoreAvailable

public static boolean isCertStoreAvailable(java.lang.String store)
                                    throws java.lang.IllegalArgumentException

Returns true if the given MS CAPI certificate/system store exists, else false.

Parameters:

store - the MS CAPI certificate/system store to check for.

Returns:

true if the store can be found, else false.

Throws:

java.lang.IllegalArgumentException - if parameter store is null or empty.

Since:

2.0

getCertificateFriendlyName

public static java.lang.String getCertificateFriendlyName(java.lang.String alias)
                                                   throws JCAPIUnknownAliasException,
                                                          java.lang.IllegalArgumentException

Returns the MS CAPI friendly name of the certificate referred by the given parameter alias.

Parameters:

alias - the certificate alias.

Returns:

the certificate's friendly name, or null if no friendly name is defined for alias.

Throws:

JCAPIUnknownAliasException - if given alias does not exist.

java.lang.IllegalArgumentException - if parameter alias is null or empty.

JCAPIJNIRuntimeException - if an unexpected error occur in JCAPI DLL.

Since:

1.1

setCertificateFriendlyName

public static void setCertificateFriendlyName(java.lang.String alias,
                                              java.lang.String friendlyName)
                                       throws java.lang.IllegalArgumentException,
                                              JCAPIUnknownAliasException

Set friendly name friendlyName for the certificate referred by the given parameter alias.
Note: maximum length is 127 characters. A friendly name longer than 127 characters will be truncated.

Parameters:

alias - The certificate alias.

friendlyName - The certificate friendly name.

Throws:

java.lang.IllegalArgumentException - if parameter alias is null or empty, or if parameter friendlyName is null.

JCAPIUnknownAliasException - if the given alias does not exist.

JCAPIJNIRuntimeException - if an unexpected error occur in JCAPI DLL.

Since:

1.1

getCertStoreFriendlyName

public static java.lang.String getCertStoreFriendlyName(java.lang.String certStoreName)
                                                 throws java.lang.IllegalArgumentException,
                                                        JCAPIJNIRuntimeException

Returns the friendly name of the MS CAPI certificate/system store given by parameter certStoreName.
For example, if you pass the string My in the certStoreName parameter, then the string Personal is returned when you are using an English version of your Windows operating system.

Hint: use method getCertStoreNames() to get a list of all existing MS CAPI certificate/system stores.

Parameters:

certStoreName - The name of a MS CAPI certificate/system store.

Returns:

the friendly name of the MS CAPI certificate/system store, or null if certStoreName does not exist or if no friendly name is defined for certStoreName.

Throws:

java.lang.IllegalArgumentException - if parameter certStoreName is null or empty,

JCAPIJNIRuntimeException - if an unexpected error occur in JCAPI DLL.

Since:

1.1

getPrivateKeyUsage

public static int getPrivateKeyUsage(java.lang.String alias)
                              throws java.lang.IllegalArgumentException,
                                     java.security.InvalidKeyException,
                                     JCAPIUnknownAliasException,
                                     JCAPIJNIRuntimeException

Returns the key usage of the key entry given by parameter alias.

Possible return values are:

• KEY_USAGE_ENCRYPTION
• KEY_USAGE_SIGNATURE

The key usage will tell you the primary purpose of using that particular private key. It is common to use one private key for signing, and another private key for encryption/wrapping. In MS CAPI this is also known as AT_SIGNATURE and AT_KEYEXCHANGE.
Some CSPs don't allow a signing key to be used for encryption, and vice versa.

Parameters:

alias - the JCAPI alias of the key entry to check.

Returns:

the private key usage identifier.

Throws:

java.lang.IllegalArgumentException - if alias is null or empty.

java.security.InvalidKeyException - if alias doesn't refer to a key entry i.e. it has no private key.

JCAPIUnknownAliasException - if the alias doesn't exist.

JCAPIJNIRuntimeException - if an unexpected error occur in JCAPI DLL.

Since:

2.0

createCertStore

public static void createCertStore(java.lang.String name)
                            throws java.lang.IllegalArgumentException

Creates a MS CAPI certificate/system store.
This method will not throw an exception if the store does already exist.

Parameters:

name - the name of a MS CAPI certificate/system store to be created. Cannot be null or empty.

Throws:

java.lang.IllegalArgumentException - if parameter name is null or empty.

JCAPIJNIRuntimeException - if the store cannot be created.

Since:

2.0

deleteCertStore

public static void deleteCertStore(java.lang.String name)
                            throws java.lang.IllegalArgumentException

Will delete the MS CAPI certificate/system store given by parameter name.
Please note that this method will delete the store even if it's not empty, meaning that all certificates and keys stored in the store will be deleted as well.

Hint: use method getCertStoreNames() to get a list of all existing MS CAPI certificate/system stores.

Parameters:

name - the name of a MS CAPI certificate/system store to be deleted. Cannot be null or empty.

Throws:

java.lang.IllegalArgumentException - if parameter name is null or empty.

JCAPIJNIRuntimeException - if the store cannot be deleted e.g. if it does not exist.

Since:

2.0

getAlgorithmsByCSP

public static JCAPICSPAlgorithm[] getAlgorithmsByCSP(java.lang.String cspName)
                                              throws java.security.NoSuchProviderException,
                                                     java.lang.IllegalArgumentException

Returns all algorithms that are supported by the Cryptographic Service Provider (CSP) given in cspName.

Parameters:

cspName - the name of the Cryptographic Service Provider (CSP).

Returns:

an array of JCAPICSPAlgorithm instances, or an empty array if no supported algorithms are found.

Throws:

java.security.NoSuchProviderException - if cspName is not a known/registered MS CAPI Cryptographic Service Provider.

java.lang.IllegalArgumentException - if parameter cspName is null or empty.

JCAPIJNIRuntimeException - if MS CAPI fails to enumerate the supported algorithms.

Since:

2.0

getAlgorithmKeyLengths

public static JCAPICSPAlgorithmKeyLengths getAlgorithmKeyLengths(JCAPICSPAlgorithm alg)
                                                          throws java.security.NoSuchProviderException,
                                                                 java.lang.IllegalArgumentException

Returns the supported key lengths (minimum, maximum, and default lengths) for the given algorithm.

Parameters:

alg - the MS CAPI CSP supported algorithm.

Returns:

a JCAPICSPAlgorithmKeyLengths instance containing key length info, or null if no info could be found.

Throws:

java.security.NoSuchProviderException - if the alg instance holds a non-existing provider.

java.lang.IllegalArgumentException - if parameter alg is null.

JCAPIJNIRuntimeException - if MS CAPI fails to get the key lengths for the given algorithm.

Since:

2.0

getAlgorithmClass

public static int getAlgorithmClass(int algId)

Returns the algorithm class of the given algorithm identifier.

The algorithm classes known by JCAPI are:

• ALG_CLASS_ANY
• ALG_CLASS_SIGNATURE
• ALG_CLASS_MSG_ENCRYPT
• ALG_CLASS_DATA_ENCRYPT
• ALG_CLASS_HASH
• ALG_CLASS_KEY_EXCHANGE
• ALG_CLASS_ALL

Parameters:

algId - the algorithm identifier.

Returns:

the algorithm class.

Since:

2.0

getProviderTypeByAlias

public static int getProviderTypeByAlias(java.lang.String alias)
                                  throws java.lang.IllegalArgumentException

Returns the provider type of the JCAPI certificate alias given in parameter alias.

Parameters:

alias - The JCAPI certificate alias to get the provider type for.

Returns:

the provider type, or 0 if the alias doesn't exist.

Throws:

java.lang.IllegalArgumentException - if alias is null or empty.

JCAPIJNIRuntimeException - if an unexpected error occur in MS CAPI.

Since:

2.0

getProviderTypeByCSP

public static int getProviderTypeByCSP(java.lang.String csp)
                                throws java.lang.IllegalArgumentException,
                                       java.security.NoSuchProviderException

Returns the provider type of the Cryptographic Service Provider (CSP) name given in parameter csp.

Parameters:

csp - The MS CAPI CSP name to get the provider type for.

Returns:

the provider type.

Throws:

java.lang.IllegalArgumentException - if csp is null or empty.

java.security.NoSuchProviderException - if the given CSP doesn't exist.

JCAPIJNIRuntimeException - if an unexpected error occur in MS CAPI.

Since:

2.0

encodeBase64

public static java.lang.String encodeBase64(byte[] buf)

Will Base64 encode the given string.

Parameters:

buf - the string to Base64 encode.

Returns:

the Base64 encoded string.

Since:

2.0

decodeBase64

public static byte[] decodeBase64(java.lang.String buf)

Will decode the Base64 encoded string.

Parameters:

buf - the Base64 encoded string to decode.

Returns:

the decode string.

Since:

2.0

asHex

public static java.lang.String asHex(byte[] buf)

Returns a hex decimal (base 16) string representation of the given byte array. Each byte is separated by a comma character.

Parameters:

buf - an array of bytes to convert to a hex decimal string.

Returns:

the converted hex decimal string.

Since:

2.0