com.rsa.certj

Class CertJ

java.lang.Object
  |
  +--com.rsa.certj.CertJ

public final class CertJ

extends Object

This class collects a number of common parameters and state variables. It tracks are the lists of currently registered service providers and a random number object for use in Crypto-J API calls.

Copyright © RSA Security Inc., 1999-2001. All rights reserved.

Field Summary

static String	CERT_J_VERSION Indicates the current version of Cert-J.
static int	SERVICE_ORDER_FIRST Indicates that the service provider should be inserted before others of the same type.
static int	SERVICE_ORDER_LAST Indicates that the service provider should be inserted after others of the same type.
static int	SPT_CERT_PATH Denotes a certification path processing service provider.
static int	SPT_CERT_STATUS Denotes a certificate revocation status service provider.
static int	SPT_DATABASE Denotes a database service provider.
static int	SPT_PKI Denotes a PKI service provider.
static int	SPT_RANDOM Denotes a random service provider.

Constructor Summary

CertJ()

Constructs an instance of CertJ and initializes it with only one service provider, a DefaultRandom provider, which is created by new DefaultRandom ("Default Random").

CertJ(Provider[] providers)

Constructs an instance of CertJ and initializes it with a list of service handlers given in providers.

Method Summary

void	addProvider(Provider provider) Adds a provider.
void	addProvider(Provider provider, int order) Adds a provider using a particular ordering.
Service	bindService(int type, String name) Creates a Service of type and name that can be used as a parameter to CertJ API methods that target a specific service provider or set of service providers.
Service	bindServices(int type) Binds all the providers of a given type to a Service.
Service	bindServices(int type, String[] names) Creates a Service consisting of one or more currently-registered service providers.
boolean	buildCertPath(CertPathCtx pathCtx, Object startObject, Vector certPath, Vector crlList, Vector crlCerts, Vector policyInfoList) Constructs a path in certPath from startObject to one of the trusted certificates provided in pathCtx, the certification path context.
CertRevocationInfo	checkCertRevocation(CertPathCtx pathCtx, Certificate cert) Determines whether a particular certificate is revoked or not based on the information provided in pathCtx.
static String	getDefaultDevice() Returns the device string that will be used when an object of this class is instantiated.
String	getDevice() Returns a String that represents a device associated with this object.
void	getNextCertInPath(CertPathCtx pathCtx, Object baseObject, Vector certList) Collects a set of candidate certificates that have public keys that can verify the signature of baseObject, using the path-processing options and conditions in pathCtx.
com.rsa.jsafe.JSAFE_Session[]	getPKCS11Sessions() Returns the PKCS11 sessions collected before
com.rsa.jsafe.JSAFE_SecureRandom	getRandomObject() Returns the random object associated with this object.
void	importPKCS12(File pkcs12File, char[] password, DatabaseService database) Reads the contents of the PKCS #12 file, pkcs12File, using password as the password and stores it in the specified database service, database.
void	importPKCS12(String pkcs12File, char[] password, DatabaseService database) Reads the contents of the PKCS #12 file, pkcs12File, using password as the password and stores it in the specified database service, database.
String[]	listAllProviders() Returns a String array that contains a descriptive string for each provider registered in this object.
String[]	listProviderNames(int providerType) Returns a String array that contains the names of all the providers registered for a given type.
void	registerService(Provider provider) Registers an additional service provider given in Provider, after a CertJ object is constructed.
void	registerService(Provider provider, int order) Registers an additional service provider given in Provider, after a CertJ object is constructed, using a particular ordering.
void	removeProvider(int type, String name) Removes a provider.
static String	serviceTypeToString(int type) Returns a String describing the specified service type.
static void	setDefaultDevice(String device) Sets the value of the default device string associated with this class.
void	setDevice(String device) Keeps the device string to be used for crypto operations.
void	setPKCS11Sessions(com.rsa.jsafe.JSAFE_Session[] SessionArray) Sets the value of the opened PKCS11 sessions
void	unbindService(Service service) Unbinds service providers in the specified service.
void	unregisterAll() Unregisters all currently registered service providers.
void	unregisterService(int type, String name) Unregisters a previously registered service provider.
boolean	validateCertificate(CertPathCtx pathCtx, Certificate cert, com.rsa.jsafe.JSAFE_PublicKey validationKey) Verifies those aspects of the certification path processing policy that can be determined from the information available in the specified cert, using any parameters specified in pathCtx.
boolean	verifyCertPath(CertPathCtx pathCtx, Object startObject) Verifies a certification path from startObject to one of the trusted certificates provided in pathCtx, the certification path context, without returning the path verified.

Methods inherited from class java.lang.Object

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

Field Detail

SPT_RANDOM

public static final int SPT_RANDOM

Denotes a random service provider.

SPT_DATABASE

public static final int SPT_DATABASE

Denotes a database service provider.

SPT_CERT_STATUS

public static final int SPT_CERT_STATUS

Denotes a certificate revocation status service provider.

SPT_CERT_PATH

public static final int SPT_CERT_PATH

Denotes a certification path processing service provider.

SPT_PKI

public static final int SPT_PKI

Denotes a PKI service provider.

SERVICE_ORDER_FIRST

public static final int SERVICE_ORDER_FIRST

Indicates that the service provider should be inserted before others of the same type.

SERVICE_ORDER_LAST

public static final int SERVICE_ORDER_LAST

Indicates that the service provider should be inserted after others of the same type. CertJ.registerService uses this value as the default when the order is not specified.

CERT_J_VERSION

public static final String CERT_J_VERSION

Indicates the current version of Cert-J.

Constructor Detail

CertJ

public CertJ()
      throws ProviderManagementException

Constructs an instance of CertJ and initializes it with only one service provider, a DefaultRandom provider, which is created by new DefaultRandom ("Default Random").

Throws

ProviderManagementException - If any service provider management API fails.

CertJ

public CertJ(Provider[] providers)
      throws ProviderManagementException

Constructs an instance of CertJ and initializes it with a list of service handlers given in providers.

Parameters

providers

A Provider array that contains definitions of service handlers to register. If it does not contain a random number provider, it will register a DefaultRandom provider, which is created by new DefaultRandom ("Default Random").

Throws

ProviderManagementException - If registering any service provider fails.

Method Detail

setPKCS11Sessions

public void setPKCS11Sessions(com.rsa.jsafe.JSAFE_Session[] SessionArray)

Sets the value of the opened PKCS11 sessions

Parameters

SessionArray

an array of JSAFE_Session to be used for Asymmetric encryption/decryption and sigature/verification.

See Also

getPKCS11Sessions()

getPKCS11Sessions

public com.rsa.jsafe.JSAFE_Session[] getPKCS11Sessions()

Returns the PKCS11 sessions collected before

Returns

An array of JSAFE_Session indicating the PKCS11 sessions used for sign/verify or encrypt/decrypt. null can be returned.

See Also

setPKCS11Sessions(JSAFE_Session[])

getDefaultDevice

public static String getDefaultDevice()

Returns the device string that will be used when an object of this class is instantiated.

Returns

A String indicating the default device string.

setDefaultDevice

public static void setDefaultDevice(String device)

Sets the value of the default device string associated with this class. A future object of this class will use this string as the device string.

Parameters

device

A String indicating the new value to be used for the default device string.

unregisterAll

public void unregisterAll()

Unregisters all currently registered service providers.

registerService

public void registerService(Provider provider)
                     throws InvalidParameterException,
                            ProviderManagementException

Registers an additional service provider given in Provider, after a CertJ object is constructed. It adds an entry for the service provider at the end of the list of service providers. If the provider is a random number provider and if there is already a random number provider being registered, it will throw a ProviderManagementException. Use unregisterSerive first to remove the existing random number provider.

Parameters

provider

A Provider that defines a provider object to be registered.

Throws

InvalidParameterException - If some of the parameters are invalid.

ProviderManagementException - If any service provider management API fails.

registerService

public void registerService(Provider provider,
                            int order)
                     throws InvalidParameterException,
                            ProviderManagementException

Registers an additional service provider given in Provider, after a CertJ object is constructed, using a particular ordering. It adds an entry for the service provider in the list of service providers in the order specified in order, either, SERVICE_ORDER_FIRST or SERVICE_ORDER_LAST. If the provider is a random number provider and if there is already a random number provider being registered, it will throw a ProviderManagementException. Use unregisterSerive first to remove the existing random number provider.

Parameters

	provider		A Provider that defines a provider object to be registered.
	order		An int that specifies whether the service provider should be placed before or after other service providers of the same type in the provider list. Possible values are SERVICE_ORDER_FIRST and SERVICE_ORDER_LAST.

Throws

InvalidParameterException - If some of the parameters are invalid.

ProviderManagementException - If any service provider management operation fails.

unregisterService

public void unregisterService(int type,
                              String name)
                       throws InvalidParameterException

Unregisters a previously registered service provider. The service handler with the specified type and name is removed and the provider's unregister method is called. Since CertJ automatically unregisters all currently registered service providers when the CertJ is shut down by unregisterAll, the application does not need to call this method if the next CertJ call will be unregisterAll. The application must be careful to ensure that the service provider being unregistered is not bound to any service handles.

Parameters

	type		An int that denotes the service provider type. It should contain one of the SPT_* constants.
	name		A String that contains the service provider instance name. The method uses this string to identify the specific service provider instance to be unregistered.

Throws

InvalidParameterException - If some of the parameters are invalid.

addProvider

public void addProvider(Provider provider)
                 throws InvalidParameterException,
                        ProviderManagementException

Adds a provider. It performs the same task as registerService(Provider).

Parameters

provider

A Provider that defines the service provider to be added.

Throws

InvalidParameterException - If some of the parameters are invalid.

ProviderManagementException - If any service provider management API fails.

See Also

registerService(com.rsa.certj.Provider)

addProvider

public void addProvider(Provider provider,
                        int order)
                 throws InvalidParameterException,
                        ProviderManagementException

Adds a provider using a particular ordering. It performs the same task as registerService(Provider, int).

Parameters

	provider		A Provider that defines the service provider to be added.
	order		An int that specifies whether the service provider should be placed before or after other service providers of the same type in the provider list.

Throws

InvalidParameterException - If some of the parameters are invalid.

ProviderManagementException - If any service provider management API fails.

See Also

registerService(com.rsa.certj.Provider, int)

removeProvider

public void removeProvider(int type,
                           String name)
                    throws InvalidParameterException

Removes a provider. It performs the same task as unregisterService(int, Sting).

Parameters

	type		An int that denotes the service provider type. It should contain one of the SPT_* constants.
	name		A String that contains the service provider instance name. The method uses this string to identify the specific service provider instance to be removed.

Throws

InvalidParameterException - If some of the parameters are invalid.

See Also

unregisterService(int, java.lang.String)

bindService

public Service bindService(int type,
                           String name)
                    throws InvalidParameterException,
                           ProviderManagementException

Creates a Service of type and name that can be used as a parameter to CertJ API methods that target a specific service provider or set of service providers. Certain Cert-J API methods, such as database operations, are defined for an object of a Service class. To use those API methods, call this method to create an appropriate service.

Parameters

	type		An int that denotes the service provider type. It should contain one of the SPT_* constants.
	name		A String that contains the service provider instance name. The method uses this string to identify the specific service provider instance to be bound to a Service. The application may pass null in place of the service name. This will cause bindService to bind to the first service provider of the given type.

Returns

A Service consisting of a provider of given type and name.

Throws

InvalidParameterException - If some of the parameters are invalid.

ProviderManagementException - If any service provider management API fails.

See Also

bindServices(int, java.lang.String[])

bindServices

public Service bindServices(int type,
                            String[] names)
                     throws InvalidParameterException,
                            ProviderManagementException

Creates a Service consisting of one or more currently-registered service providers. The type of service is type and names contains a list of provider names to be bound to the service. Certain Cert-J API methods, such as database operations, are definedfor an object of a Service class. To use those API methods, call this method to create an appropriate service. Some service types (for example, SPT_DATABASE) allow an ordered list of instances to be specified in the service provider name array. If null is specified for names, all of the provider instances of the given type are bound in registration order.

Parameters

	type		An int that denotes the service provider type. It should contain one of the SPT_* constants.
	names		A String array giving the service provider instance names. The method uses this array to identify the specific service provider instances to be bound to the Service, and the order in which they should be called by methods referencing this Service. The application may pass null in place of the service name array. This will induce this method to bind to all service providers of the given type, in the order in which the service providers are registered.

Returns

A Service consisting of providers of the giventype and names.

Throws

InvalidParameterException - If some of the parameters are invalid.

ProviderManagementException - If any service provider management API fails.

See Also

bindServices(int)

bindServices

public Service bindServices(int type)
                     throws InvalidParameterException,
                            ProviderManagementException

Binds all the providers of a given type to a Service.

Parameters

type

An int that denotes the service provider type. It should be one of the SPT_* constants.

Returns

A Service consisting of all the registered providers of given type.

Throws

InvalidParameterException - If some of the parameters are invalid.

ProviderManagementException - If any service provider management API fails.

See Also

bindServices(int, java.lang.String[])

unbindService

public void unbindService(Service service)

Unbinds service providers in the specified service.

Parameters

service

A Service returned by a previous call to bindService or bindServices.

listAllProviders

public String[] listAllProviders()

Returns a String array that contains a descriptive string for each provider registered in this object.

Returns

A String array that contains a descriptive string for each provider.

listProviderNames

public String[] listProviderNames(int providerType)

Returns a String array that contains the names of all the providers registered for a given type.

Parameters

providerType

An int indicating the type of provider. It is one of SPT_* constant.

Returns

A String array that contains the names of the providers registered for a given type.

getRandomObject

public com.rsa.jsafe.JSAFE_SecureRandom getRandomObject()
                                                 throws NoServiceException,
                                                        RandomException

Returns the random object associated with this object.

Returns

the JSAFE_SecureRandom object associated with this object.

Throws

NoServiceException - If unable to get random object.

getDevice

public String getDevice()

Returns a String that represents a device associated with this object.

Returns

A String that represents a device.

setDevice

public void setDevice(String device)

Keeps the device string to be used for crypto operations.

Parameters

device

A String that represents a device.

verifyCertPath

public boolean verifyCertPath(CertPathCtx pathCtx,
                              Object startObject)
                       throws InvalidParameterException,
                              NoServiceException,
                              CertPathException

Verifies a certification path from startObject to one of the trusted certificates provided in pathCtx, the certification path context, without returning the path verified.

Parameters

	pathCtx		A CertPathCtx that is used to ensure that the constructed certification path is valid. Less strict checking during path construction can be requested by the appropriate use of pathOptions of this object.
	startObject		Either a Certificate or a CRL.

Returns

true if valid path is verified, or false otherwise.

Throws

InvalidParameterException - If some of the parameters are invalid.

NoServiceException - If no provider is found for Certification Path Processing Service.

CertPathException - If a certification path processing provider fails.

See Also

buildCertPath(com.rsa.certj.spi.path.CertPathCtx, java.lang.Object, java.util.Vector, java.util.Vector, java.util.Vector, java.util.Vector)

buildCertPath

public boolean buildCertPath(CertPathCtx pathCtx,
                             Object startObject,
                             Vector certPath,
                             Vector crlList,
                             Vector crlCerts,
                             Vector policyInfoList)
                      throws InvalidParameterException,
                             NoServiceException,
                             CertPathException

Constructs a path in certPath from startObject to one of the trusted certificates provided in pathCtx, the certification path context. The CRLs that need to verify the path are stored in crlList. The certificates needed to verify the CRLs are stored in crlCerts. The policy information found in the path is stored in policyInfoList.

This method can be used for path validation by passing null values for the certPath, crlList, crlCerts, and policyInfoList parameters, because this method will throw an exception if the path is not valid. Doing this is equivalent to calling the verifyCertPath method.

Parameters

	pathCtx		A CertPathCtx that is used to ensure that the constructed certification path is valid. Less strict checking during path construction can be requested by the appropriate use of pathOptions associated with this object.
	startObject		Either a Certificate or a CRL. If startObject is a certificate, the resulting path will include the startObject as the first certificate in the path. If startObject is a CRL, the first certificate in the path will be the CRL issuer.
	certPath		A Vector that holds a valid certification path. This parameter is optional, and may be set to null if not used. On output, a set of certificates that consist of the certification path for startObject will be added to this list unless they are already on the list.
	crlList		A Vector that will hold a list of CRLs that need to verify certPath. This parameter is optional, and may be set to null if not used. On output, the list will contain any CRLs needed to verify the resulting certification path. Note that some certificate revocation status services may not use or return CRLs.
	crlCerts		A Vector that will hold a list of Certificates that are needed to verify crlList. This parameter is optional, and may be set to null if not used. On output, the list will contain any additional certificates not included in certPath that may be required to validate CRLs returned in crlList. If the crlList parameter is set to null, this parameter will be ignored. The certificates returned in this parameter are essentially the union of certificate paths extending from the returned CRLs to the trusted certificates in pathCtx except that the certificates returned in certPath may or may not be included in this list.
	policyInfoList		A Vector that will hold a list of PolicyInformation that are found in certPath. This parameter is optional and may be set to null if not used. On output, the policy information list will contain an entry for each policy under which the certificate was issued. Each entry in the list is a PolicyInformation object.

Returns

true if valid path is built, false otherwise.

Throws

InvalidParameterException - If some of the parameters are invalid.

NoServiceException - If no provider is found for Certification Path Processing Service.

CertPathException - If a certification path processing provider fails.

See Also

verifyCertPath(com.rsa.certj.spi.path.CertPathCtx, java.lang.Object)

getNextCertInPath

public void getNextCertInPath(CertPathCtx pathCtx,
                              Object baseObject,
                              Vector certList)
                       throws InvalidParameterException,
                              NoServiceException,
                              CertPathException

Collects a set of candidate certificates that have public keys that can verify the signature of baseObject, using the path-processing options and conditions in pathCtx. The returned candidate certificates are stored in certList.

Parameters

	pathCtx		A CertPathCtx object that is used to determine the validation time and other path building options.
	baseObject		An Object object that is used to locate one or more certificates that may contain the public key needed to verify the base certificate's signature. Information contained in the base object (typically the issuer name or the authority key identifier) is used to select a set of certificates. Currently the object is either a Certificate or a CRL.
	certList		A Vector that will contain certificates that might be able to verify baseObject's signature. This method may (but need not) apply additional criteria from the path processing algorithm and options to reduce the set of candidate certificates. The caller is responsible for the actual validation of baseObject, the candidate certificates, and any relationship between baseObject and candidate certificates required by the certification path processing algorithm.

Returns

A set of candidate certificates that have public keys that can verify the signature of baseObject, using the path-processing options and conditions in pathCtx.

Throws

InvalidParameterException - If some of the parameters are invalid.

NoServiceException - If no provider is found for Certification Path Processing Service.

CertPathException - If a certification path processing provider fails.

validateCertificate

public boolean validateCertificate(CertPathCtx pathCtx,
                                   Certificate cert,
                                   com.rsa.jsafe.JSAFE_PublicKey validationKey)
                            throws InvalidParameterException,
                                   NoServiceException,
                                   CertPathException

Verifies those aspects of the certification path processing policy that can be determined from the information available in the specified cert, using any parameters specified in pathCtx. This method will not look at any information that is contained in other certificates in the certification path. That is, unlike buildCertPath, this method does not take the entire certificate chain into account. It only looks at the provider information contained in the cert and verifies the certificate based it. Examples of certificate fields that may be validated by this routine include:

Validity Period – The certificate was signed using the private key corresponding to the public key specified in the validationKey.

Validation Key – The certificate validity period includes the validation time specified in the pathCtx.

The pathOptions field of the pathCtx can selectively disable the above checks or any others that are implemented by the service provider.

Parameters

	pathCtx		A CertPathCtx that is used to determine the validation time and path validation options. Some fields may not be applicable to single-certificate validation.
	cert		A Certificate to be validated.
	validationKey		A JSAFE_PublicKey used to validate the certificate signature.

Returns

true if validation of the certificate succeeds, false otherwise.

Throws

InvalidParameterException - If any of the parameters are invalid or null.

NoServiceException - If no provider is found for certification path processing service.

CertPathException - If a certification path processing provider fails.

checkCertRevocation

public CertRevocationInfo checkCertRevocation(CertPathCtx pathCtx,
                                              Certificate cert)
                                       throws InvalidParameterException,
                                              NoServiceException,
                                              CertStatusException

Determines whether a particular certificate is revoked or not based on the information provided in pathCtx. The method returns the the revocation status and related information.

Parameters

	pathCtx		A CertPathCtx object that is used to ensure that the constructed certification path is valid. This method uses the certification path-processing context to determine the status checking mechanism.
	cert		A Certificate to be checked.

Returns

A CertRevocationInfo object that holds information about the status of cert.

Throws

InvalidParameterException - If any of the parameters are invalid or null.

NoServiceException - If no provider is found for Certificate Revocation Status Service.

CertStatusException - If a certificate revocation status provider fails.

importPKCS12

public void importPKCS12(String pkcs12File,
                         char[] password,
                         DatabaseService database)
                  throws PKCS12Exception

Reads the contents of the PKCS #12 file, pkcs12File, using password as the password and stores it in the specified database service, database.

Parameters

	pkcs12File		A String indicating the name of the PKCS #12 file to read.
	password		A char array that contains the password for the PKCS #12 file.
	database		A DatabaseService representing the database or databases where the contents of the PKCS #12 file will be stored.

Throws

PKCS12Exception - If any PKCS #12 operation fails.

importPKCS12

public void importPKCS12(File pkcs12File,
                         char[] password,
                         DatabaseService database)
                  throws PKCS12Exception

Reads the contents of the PKCS #12 file, pkcs12File, using password as the password and stores it in the specified database service, database.

Parameters

	pkcs12File		A File identifying the PKCS #12 file to read.
	password		A char array that contains the password for the PKCS #12 file.
	database		A DatabaseService representing the database or databases where the contents of the PKCS #12 file will be stored.

Throws

PKCS12Exception - If any PKCS #12 operation fails.

serviceTypeToString

public static String serviceTypeToString(int type)

Returns a String describing the specified service type.

Parameters

type

An int indicating the type of service.

Returns

A String describing the specified service type.