com.rsa.certj

Class DatabaseService

java.lang.Object
  |
  +--com.rsa.certj.Service
        |
        +--com.rsa.certj.DatabaseService

public final class DatabaseService

extends Service

This class represents a database service. All the database APIs, such as insertCertificate and selectCertificateBySubject are defined as methods for this class. Create an object of this class to perform database operations. The bindService method in the CertJ class creates an object of this class.

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

See Also

CertJ.bindService(int, java.lang.String)

Constructor Summary

DatabaseService(CertJ certJ)

Constructs a DatabaseService object for certJ.

Method Summary

void	deleteCertificate(X500Name issuerName, byte[] serialNumber) Deletes the certificate identified by the issuer name issuerName and serial number serialNumber from any databases bound to this object.
void	deleteCRL(X500Name issuerName, Date lastUpdate) Deletes the CRL identified by the specified issuerName and lastUpdate from any databases bound to this object.
void	deletePrivateKeyByCertificate(Certificate cert) Deletes the private key identified by the specified cert from any database bound to this object.
void	deletePrivateKeyByPublicKey(com.rsa.jsafe.JSAFE_PublicKey publicKey) Deletes the private key identified by the specified matching public key publicKey from any databases bound to this object.
Certificate	firstCertificate() Retrieves the first certificate from any databases bound to this object.
CRL	firstCRL() Retrieves the first CRL from any databases bound to this object.
com.rsa.jsafe.JSAFE_PrivateKey	firstPrivateKey() Retrieves the first private key from any databases bound to this object.
boolean	hasMoreCertificates() Indicates whether any more certificates are available.
boolean	hasMoreCRLs() Indicates whether any more CRLs are available.
boolean	hasMorePrivateKeys() Indicates whether any more private keys are available.
void	insertCertificate(Certificate cert) Inserts cert into any databases bound to this object.
void	insertCertificates(Certificate[] certs) Inserts certs into any databases bound to this object.
void	insertCRL(CRL crl) Inserts crl into any databases bound to this object.
void	insertCRLs(CRL[] crls) Inserts crls into any databases bound to this object.
void	insertPrivateKeyByCertificate(Certificate cert, com.rsa.jsafe.JSAFE_PrivateKey privateKey) Inserts privateKey into any databases bound to this object using cert as a key.
void	insertPrivateKeyByPublicKey(com.rsa.jsafe.JSAFE_PublicKey publicKey, com.rsa.jsafe.JSAFE_PrivateKey privateKey) Inserts privateKey into any databases bound to this object using publicKey as a key.
Certificate	nextCertificate() Retrieves the next certificate from any databases bound to this object.
CRL	nextCRL() Retrieves the next CRL from any databases bound to this object.
com.rsa.jsafe.JSAFE_PrivateKey	nextPrivateKey() Retrieves the next private key from any databases bound to this object.
int	selectCertificateByExtensions(X500Name baseName, X509V3Extensions extensions, Vector certList) Retrieves one or more certificates identified by the specified extensions and baseName from any databases bound to this object and adds a copy of each matching certificate to the certList.
int	selectCertificateByIssuerAndSerialNumber(X500Name issuerName, byte[] serialNumber, Vector certList) Retrieves the certificate identified by the specified issuerName and serialNumber from the database(s) bound to this object and adds a copy of it to the certList.
int	selectCertificateBySubject(X500Name subjectName, Vector certList) Retrieves one or more certificates identified by the specified subjectName from any databases bound to this object and adds a copy of each matching certificate to the certList.
int	selectCRLByIssuerAndTime(X500Name issuerName, Date time, Vector crlList) Retrieves the CRL identified by the specified issuerName and time from any databases bound to this object and adds a copy of the matching CRL to the crlList.
com.rsa.jsafe.JSAFE_PrivateKey	selectPrivateKeyByCertificate(Certificate cert) Retrieves the private key identified by cert from any databases bound to this object.
com.rsa.jsafe.JSAFE_PrivateKey	selectPrivateKeyByPublicKey(com.rsa.jsafe.JSAFE_PublicKey publicKey) Retrieves the private key identified by the matching public key publicKey from any databases bound to this object.

Methods inherited from class com.rsa.certj.Service

getInstance, listProviderNames, toString, unbind

Methods inherited from class java.lang.Object

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

Constructor Detail

DatabaseService

public DatabaseService(CertJ certJ)

Constructs a DatabaseService object for certJ.

Parameters

certJ

The CertJ object that represents the current CertJ object.

Method Detail

insertCertificate

public void insertCertificate(Certificate cert)
                       throws NoServiceException,
                              DatabaseException

Inserts cert into any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to insert the certificate into all of them. If a given certificate is already in the database (as determined by matching issuer names and serial numbers), it is not added again. This is considered equivalent to a successful insertion of the certificate into the database.

Parameters

cert

A Certificate object to insert.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

insertCertificates

public void insertCertificates(Certificate[] certs)
                        throws NoServiceException,
                               DatabaseException

Inserts certs into any databases bound to this object. If more than one service provider instance has been bound to the service, this method attempts to insert the certificates into all of them. If a given certificate is already in the database (as determined by matching issuer names and serial numbers), it is not added again. This is considered equivalent to a successful insertion of the certificate into the database.

Parameters

certs

An array of Certificate objects to insert.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

insertCRL

public void insertCRL(CRL crl)
               throws NoServiceException,
                      DatabaseException

Inserts crl into any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to insert the CRL into all of them. If a given CRL is already in the database (as determined by matching issuer names and last update times), it is not added again. This is considered equivalent to a successful insertion of the CRL into the database.

Parameters

crl

A CRL object to insert.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

insertCRLs

public void insertCRLs(CRL[] crls)
                throws NoServiceException,
                       DatabaseException

Inserts crls into any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to insert the CRLs into all of them. If a given CRL is already in the database (as determined by matching issuer names and serial numbers), it is not added again. This is considered equivalent to a successful insertion of the CRL into the database.

Parameters

crls

An array of CRL objects to insert.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

insertPrivateKeyByCertificate

public void insertPrivateKeyByCertificate(Certificate cert,
                                          com.rsa.jsafe.JSAFE_PrivateKey privateKey)
                                   throws NoServiceException,
                                          DatabaseException

Inserts privateKey into any databases bound to this object using cert as a key. The private key will be associated with its corresponding public key, which can be found in cert. If more than one service provider instance has been bound to the service object, this method attempts to insert the key into all of them. If a given key is already in the database, it is not added again. This is considered equivalent to a successful insertion of the key into the database.

Parameters

	cert		A Certificate object that identifies the corresponding public key.
	key		A JSAFE_PrivateKey object to insert.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

See Also

insertPrivateKeyByPublicKey(com.rsa.jsafe.JSAFE_PublicKey, com.rsa.jsafe.JSAFE_PrivateKey)

insertPrivateKeyByPublicKey

public void insertPrivateKeyByPublicKey(com.rsa.jsafe.JSAFE_PublicKey publicKey,
                                        com.rsa.jsafe.JSAFE_PrivateKey privateKey)
                                 throws NoServiceException,
                                        DatabaseException

Inserts privateKey into any databases bound to this object using publicKey as a key. The private key will be identified by the corresponding public key publicKey. If more than one service provider instance has been bound to the service object, this method attempts to insert the key into all of them. If a given key is already in the database, it is not added again. This is considered equivalent to a successful insertion of the key into the database.

Parameters

	publicKey		A JSAFE_PublicKey object that contains the matching public key for privateKey.
	privateKey		A JSAFE_PrivateKey object to inserted.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

See Also

insertPrivateKeyByCertificate(com.rsa.certj.cert.Certificate, com.rsa.jsafe.JSAFE_PrivateKey)

selectCertificateByIssuerAndSerialNumber

public int selectCertificateByIssuerAndSerialNumber(X500Name issuerName,
                                                    byte[] serialNumber,
                                                    Vector certList)
                                             throws NoServiceException,
                                                    DatabaseException

Retrieves the certificate identified by the specified issuerName and serialNumber from the database(s) bound to this object and adds a copy of it to the certList. If more than one service provider instance has been bound to the service object, it attempts to retrieve the certificate from each service provider, in the order bound, until the certificate is located.

Parameters

	issuerName		An X500Name object that contains the issuer name of the certificate to be selected.
	serialNumber		A byte array that contains the serial number of the certificate to be retrieved.
	certList		A Vector to which this method adds a copy of the matching certificate.

Returns

An int that indicates the number of certificates added to the certList.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

selectCertificateBySubject

public int selectCertificateBySubject(X500Name subjectName,
                                      Vector certList)
                               throws NoServiceException,
                                      DatabaseException

Retrieves one or more certificates identified by the specified subjectName from any databases bound to this object and adds a copy of each matching certificate to the certList. If more than one service provider instance has been bound to the service object, it attempts to retrieve matching certificates from all providers, in the order bound. If a copy of a given certificate is already in the list (as determined by matching issuer names and serial numbers), it is not added again.

Parameters

	subjectName		An X500Name that contains the subject name of the certificates to be selected.
	certList		A Vector to which this method adds a copy of the matching certificates.

Returns

An int that indicates the number of certificates added to the certList.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

selectCertificateByExtensions

public int selectCertificateByExtensions(X500Name baseName,
                                         X509V3Extensions extensions,
                                         Vector certList)
                                  throws NoServiceException,
                                         DatabaseException

Retrieves one or more certificates identified by the specified extensions and baseName from any databases bound to this object and adds a copy of each matching certificate to the certList. If more than one service provider instance has been bound to the service object, this method attempts to retrieve matching certificates from all providers, in the order bound. If a copy of a given certificate is already in the list (as determined by matching issuer names and serial numbers), it is not added to certList again.

Parameters

	baseName		An X500Name that is compared against the subject name of a candidate certificate. All of the components of baseName must match the corresponding components of the candidate certificate subject name. However, the certificate subject name may contain more AVAs than are present in the baseName and still match. If baseName has a value of null, it is considered to match a candidate certificate. However, some database service providers (for example, the LDAP service provider) may refuse to perform this operation unless baseName is specified.
	extensions		An X509V3Extensions object that contains a set of extensions that a candidate certificate should have. If this parameter's value is null, all certificates in the bound database(s) that match the base name will be returned. This object is compared with the extensions contained in a candidate certificate in a way that is functionally equivalent to the compareExtensions method. The extensions parameter of this method would be the first parameter, rule, of compareExtensions, and the extensions object from the candidate certificate would be the second parameter, extensions, of compareExtensions.
	certList		A Vector to which this method adds a copy of the matching certificates.

Returns

An int that indicates the number of certificates added to the certList.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

See Also

(com.rsa.certj.cert.X509V3Extensions, com.rsa.certj.cert.X509V3Extensions)

firstCertificate

public Certificate firstCertificate()
                             throws NoServiceException,
                                    DatabaseException

Retrieves the first certificate from any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to retrieve the first certificate from all providers, in the order bound, until retrieval is successful. Inserting or deleting a certificate after calling this method might affect the behavior of subsequent nextCertificate calls, depending on the underlying provider(s).

Returns

A Certificate object that is the first certificate found.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

nextCertificate

public Certificate nextCertificate()
                            throws NoServiceException,
                                   DatabaseException

Retrieves the next certificate from any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to retrieve the next certificate from all providers in the order bound until retrieval is successful. If no certificate iterator is set up, it throws an exception.

Note: Call firstCertificate before calling this method.

Returns

A Certificate object that is the next certificate found.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

See Also

firstCertificate()

hasMoreCertificates

public boolean hasMoreCertificates()
                            throws NoServiceException,
                                   DatabaseException

Indicates whether any more certificates are available. If no certificate iterator is set up, it sets one up first.

Returns

true if more certificates are available, false otherwise.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

selectCRLByIssuerAndTime

public int selectCRLByIssuerAndTime(X500Name issuerName,
                                    Date time,
                                    Vector crlList)
                             throws NoServiceException,
                                    DatabaseException

Retrieves the CRL identified by the specified issuerName and time from any databases bound to this object and adds a copy of the matching CRL to the crlList. If more than one service provider instance has been bound to the service object, it attempts to retrieve the matching CRL from all providers, in the order bound. If a copy of the CRL is already in the list (as determined by matching issuer names and last-update times), it is not added again. A candidate CRL matches if the issuer names match and if time is greater than or equal to the last-update time of the candidate CRL, and if the candidate CRL has the greatest last-update time of all candidate CRLs with matching issuer names.

Parameters

	issuerName		An X500Name object that contains the CRL issuer name to be selected.
	time		A Date that is compared against the last-update times of candidate CRLs.
	crlList		A Vector to which this method adds a copy of the matching CRLs.

Returns

An int that indicates the number of CRLs added to crlList.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

firstCRL

public CRL firstCRL()
             throws NoServiceException,
                    DatabaseException

Retrieves the first CRL from any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to retrieve the first CRL from all providers, in the order bound, until retrieval is successful. Inserting or deleting a CRL after calling this method might affect the behavior of subsequent nextCRL, depending on the underlying provider(s).

Returns

A CRL that is the first CRL found.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

nextCRL

public CRL nextCRL()
            throws NoServiceException,
                   DatabaseException

Retrieves the next CRL from any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to retrieve the next CRL from all providers, in the order bound, until retrieval is successful. If no CRL iterator is set up, it throws an exception.

Note: Call firstCRL before calling this method.

Returns

A CRL that is the next CRL found.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

hasMoreCRLs

public boolean hasMoreCRLs()
                    throws NoServiceException,
                           DatabaseException

Indicates whether any more CRLs are available. If no CRL iterator is set up, it sets one up first.

Returns

true if more CRLs are available, false otherwise.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

selectPrivateKeyByCertificate

public com.rsa.jsafe.JSAFE_PrivateKey selectPrivateKeyByCertificate(Certificate cert)
                                                             throws NoServiceException,
                                                                    DatabaseException

Retrieves the private key identified by cert from any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to retrieve the key from each provider, in the order bound, until a match is found.

Parameters

cert

A Certificate that identifies the private key to be selected.

Returns

A JSAFE_PrivateKey matching cert.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

selectPrivateKeyByPublicKey

public com.rsa.jsafe.JSAFE_PrivateKey selectPrivateKeyByPublicKey(com.rsa.jsafe.JSAFE_PublicKey publicKey)
                                                           throws NoServiceException,
                                                                  DatabaseException

Retrieves the private key identified by the matching public key publicKey from any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to retrieve the key from each provider, in the order bound, until a match is found.

Parameters

publicKey

A JSAFE_PublicKey that contains the matching public key for the private key being selected.

Returns

A JSAFE_PrivateKey matching publicKey.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

firstPrivateKey

public com.rsa.jsafe.JSAFE_PrivateKey firstPrivateKey()
                                               throws NoServiceException,
                                                      DatabaseException

Retrieves the first private key from any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to retrieve the first private key from all providers, in the order bound, until retrieval is successful.

Returns

A JSAFE_PrivateKey that is the first private key found.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

nextPrivateKey

public com.rsa.jsafe.JSAFE_PrivateKey nextPrivateKey()
                                              throws NoServiceException,
                                                     DatabaseException

Retrieves the next private key from any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to retrieve the next private key from all providers, in the order bound, until retrieval is successful. If no private key iterator is set up, it throws an exception.

Note: Call firstPrivateKey before calling this method.

Returns

A JSAFE_PrivateKey that is the next private key found.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

hasMorePrivateKeys

public boolean hasMorePrivateKeys()
                           throws NoServiceException,
                                  DatabaseException

Indicates whether any more private keys are available. If no private key iterator is set up, it sets one up first.

Returns

true if more private keys are available, false otherwise.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

deleteCertificate

public void deleteCertificate(X500Name issuerName,
                              byte[] serialNumber)
                       throws NoServiceException,
                              DatabaseException

Deletes the certificate identified by the issuer name issuerName and serial number serialNumber from any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to delete the certificate from each provider, in the order bound.

Parameters

	issuerName		An X500Name object that contains the name of the entity that issued the certificate to be deleted.
	serialNumber		A byte array that contains the serial number of the certificate to be deleted.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

deleteCRL

public void deleteCRL(X500Name issuerName,
                      Date lastUpdate)
               throws NoServiceException,
                      DatabaseException

Deletes the CRL identified by the specified issuerName and lastUpdate from any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to delete the CRL from each provider, in the order bound.

Parameters

	issuerName		An X500Name of the issuer of the CRL to be deleted.
	lastUpdate		A Date that indicates the last update field of the CRL.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

deletePrivateKeyByCertificate

public void deletePrivateKeyByCertificate(Certificate cert)
                                   throws NoServiceException,
                                          DatabaseException

Deletes the private key identified by the specified cert from any database bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to delete the private key from each provider, in the order bound.

Parameters

cert

A Certificate that identifies the private key to be deleted.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.

deletePrivateKeyByPublicKey

public void deletePrivateKeyByPublicKey(com.rsa.jsafe.JSAFE_PublicKey publicKey)
                                 throws NoServiceException,
                                        DatabaseException

Deletes the private key identified by the specified matching public key publicKey from any databases bound to this object. If more than one service provider instance has been bound to the service object, this method attempts to delete the key from each provider in the order bound.

Parameters

publicKey

A JSAFE_PublicKey that contains the matching public key for the private key to be deleted.

Throws

NoServiceException - If no database service provider is found that supports this method.

DatabaseException - If a database service provider throws an exception.