com.rsa.certj.spi.db

Interface DatabaseInterface

public interface DatabaseInterface

This interface specifies the Database Service Programming Interface (SPI) methods, such as insertCertificate, that can be implemented by a database service provider.

A database provider may implement some or all of the methods in the Database SPI. If an application invokes a database method or uses an argument that is not supported by the database provider, Cert-J will throw an exception.

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

Method Summary

void	deleteCertificate(X500Name issuerName, byte[] serialNumber) Deletes the certificate identified by the specified issuer name, issuerName, and serial number, serialNumber, from the database managed by the database service provider.
void	deleteCRL(X500Name issuerName, Date lastUpdate) Deletes the CRL identified by the specified issuer name, issuerName, and last-update time, lastUpdate, from the database managed by the database service provider.
void	deletePrivateKeyByCertificate(Certificate cert) Deletes the private key identified by the specified certificate, cert, from the database managed by the database service provider.
void	deletePrivateKeyByPublicKey(com.rsa.jsafe.JSAFE_PublicKey publicKey) Deletes the private key identified by the specified public key, publicKey, from the database managed by the database service provider.
Certificate	firstCertificate() Retrieves the first available certificate from the database provider.
CRL	firstCRL() Retrieves the first available CRL from the database provider.
com.rsa.jsafe.JSAFE_PrivateKey	firstPrivateKey() Retrieves the first private key from the database provider.
boolean	hasMoreCertificates() Returns a boolean that indicates whether any more certificates are available in the database.
boolean	hasMoreCRLs() Returns a boolean that indicates whether any more CRLs are available in the database.
boolean	hasMorePrivateKeys() Returns a boolean that ndicates whether any more private keys are available.
void	insertCertificate(Certificate certificate) Inserts a Certificate, certificate, into the database managed by the service provider.
void	insertCRL(CRL crl) Inserts a CRL, crl, into the database managed by the service provider.
void	insertPrivateKeyByCertificate(Certificate cert, com.rsa.jsafe.JSAFE_PrivateKey privateKey) Inserts privateKey into the database managed by the service provider.
void	insertPrivateKeyByPublicKey(com.rsa.jsafe.JSAFE_PublicKey publicKey, com.rsa.jsafe.JSAFE_PrivateKey privateKey) Inserts privateKey into the database managed by the service provider.
boolean	isCertificateIteratorSetup() Returns a boolean value indicating whether a certificate iterator is already set up or not.
boolean	isCRLIteratorSetup() Returns a boolean value indicating whether a CRL iterator is already set up or not.
boolean	isPrivateKeyIteratorSetup() Returns a boolean value indicating whether a private key iterator is already set up or not.
Certificate	nextCertificate() Returns the next available certificate.
CRL	nextCRL() Returns the next available CRL.
com.rsa.jsafe.JSAFE_PrivateKey	nextPrivateKey() Returns the next available private key.
int	selectCertificateByExtensions(X500Name baseName, X509V3Extensions extensions, Vector certList) Retrieves one or more certificates identified by the specified extensions, extensions, and base subject name, baseName, from the database managed by the service provider.
int	selectCertificateByIssuerAndSerialNumber(X500Name issuerName, byte[] serialNumber, Vector certList) Retrieves the certificate identified by the specified issuer name, issuerName, and serial number, serialNumber, from the database managed by the service provider and adds a copy of it to the certificate list, certList, if the certificate is not already in the list.
int	selectCertificateBySubject(X500Name subjectName, Vector certList) Retrieves one or more certificates identified by the specified subject name, subjectName, from the database managed by the service provider and adds a copy of each matching certificate to the certificate list, certList.
int	selectCRLByIssuerAndTime(X500Name issuerName, Date time, Vector crlList) Retrieves the CRL identified by the specified issuer name, issuerName, and time, time, from the database managed by the service provider and adds a copy of the matching CRL to the CRL list, crlList.
com.rsa.jsafe.JSAFE_PrivateKey	selectPrivateKeyByCertificate(Certificate cert) Retrieves the private key identified by the specified certificate, cert, from the database managed by the service provider.
com.rsa.jsafe.JSAFE_PrivateKey	selectPrivateKeyByPublicKey(com.rsa.jsafe.JSAFE_PublicKey publicKey) Retrieves the private key identified by the specified public key, publicKey, from the database managed by the service provider.
void	setupCertificateIterator() Sets up a certificate iterator.
void	setupCRLIterator() Sets up a CRL iterator.
void	setupPrivateKeyIterator() Sets up a private key iterator.

Method Detail

insertCertificate

public void insertCertificate(Certificate certificate)
                       throws NotSupportedException,
                              DatabaseException

Inserts a Certificate, certificate, into the database managed by the service provider.

Note: 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

certificate

A Certificate to add to the database.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

insertCRL

public void insertCRL(CRL crl)
               throws NotSupportedException,
                      DatabaseException

Inserts a CRL, crl, into the database managed by the service provider.

Note: 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 to add the database.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

insertPrivateKeyByCertificate

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

Inserts privateKey into the database managed by the service provider. The private key will be associated with its correspondingpublic key which can be found in a certificate, cert. Note: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 that corresponds with the private key to be added.
	privateKey		A JSAFE_PrivateKey to add to the database.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

insertPrivateKeyByPublicKey

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

Inserts privateKey into the database managed by the service provider. The private key is identified by the corresponding subject public key, publicKey. Note: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 that contains the matching public key corresponding to privateKey.
	key		A JSAFE_PrivateKey to add to the database.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

selectCertificateByIssuerAndSerialNumber

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

Retrieves the certificate identified by the specified issuer name, issuerName, and serial number, serialNumber, from the database managed by the service provider and adds a copy of it to the certificate list, certList, if the certificate is not already in the list.

Parameters

	issuerName		An X500Name that contains the issuer name to search for.
	serialNumber		A byte array that contains the serial number to search for.
	certList		A Vector to which the the certificate is added.

Returns

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

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

selectCertificateBySubject

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

Retrieves one or more certificates identified by the specified subject name, subjectName, from the database managed by the service provider and adds a copy of each matching certificate to the certificate list, certList. 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 to search for.
	certList		A Vector that the certificates found are added to.

Returns

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

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

selectCertificateByExtensions

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

Retrieves one or more certificates identified by the specified extensions, extensions, and base subject name, baseName, from the database managed by the service provider. This method adds a copy of each matching certificate to the certificate list,certList. Note: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

	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 Attribute-Value-Assertions than are present in the baseName and still be considered a match. If baseName has a value of null, it is considered to match a candidate certificate. Note, however, that some database service providers (for example, the LDAP 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 CertJUtils>compareExtensions. This parameter of this method would be the first parameter of CertJUtils.compareExtensions, and the extensions object from the candidate certificate fields would be the second parameter.
	certList		A Vector into which the matching certificate(s) will be added.

Returns

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

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

See Also

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

isCertificateIteratorSetup

public boolean isCertificateIteratorSetup()
                                   throws NotSupportedException,
                                          DatabaseException

Returns a boolean value indicating whether a certificate iterator is already set up or not.

Returns

true if an iterator is set up or false otherwise.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

See Also

firstCertificate()

setupCertificateIterator

public void setupCertificateIterator()
                              throws NotSupportedException,
                                     DatabaseException

Sets up a certificate iterator.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

firstCertificate

public Certificate firstCertificate()
                             throws NotSupportedException,
                                    DatabaseException

Retrieves the first available certificate from the database provider. This method also sets up the certificate enumeration environment for subsequent nextCertificate calls. Inserting or deleting a certificate after calling this method may or may not affect the behavior of subsequent nextCertificate calls depending on the provider implementation.

Returns

A Certificate that is the first certificate found in the database.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

See Also

nextCertificate()

hasMoreCertificates()

nextCertificate

public Certificate nextCertificate()
                            throws NotSupportedException,
                                   DatabaseException

Returns the next available certificate. If no iterator is set up, it will throw a DatabaseException. If previous calls to nextCertificate have exhausted all the certificates, this call returns null and uninstalls the iterator.

Returns

A Certificate that is the next certificate found in the database. If none is available, this method returns null.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

See Also

firstCertificate()

hasMoreCertificates()

hasMoreCertificates

public boolean hasMoreCertificates()
                            throws NotSupportedException,
                                   DatabaseException

Returns a boolean that indicates whether any more certificates are available in the database.

Returns

A boolean with a value of true if there are more certificates, false otherwise.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

selectCRLByIssuerAndTime

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

Retrieves the CRL identified by the specified issuer name, issuerName, and time, time, from the database managed by the service provider and adds a copy of the matching CRL to the CRL list, crlList. 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.

Parameters

	issuerName		An X500Name that contains the name of the entity that issued the CRL.
	time		A Date that should be greater than or equal to the last-update time of a candidate CRL.
	crlList		A Vector into which the CRL(s) found are added.

Returns

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

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

isCRLIteratorSetup

public boolean isCRLIteratorSetup()
                           throws NotSupportedException,
                                  DatabaseException

Returns a boolean value indicating whether a CRL iterator is already set up or not.

Returns

true if an iterator is set up or false otherwise.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

See Also

firstCRL()

setupCRLIterator

public void setupCRLIterator()
                      throws NotSupportedException,
                             DatabaseException

Sets up a CRL iterator.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

firstCRL

public CRL firstCRL()
             throws NotSupportedException,
                    DatabaseException

Retrieves the first available CRL from the database provider. This method also sets up the CRL enumeration environment for subsequent nextCRL calls. Inserting or deleting a CRL after calling this method may or may not affect the behavior of subsequent nextCRL calls depending on the provider implementation.

Returns

A CRL that is the first CRL found in the database.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

See Also

nextCRL()

hasMoreCRLs()

nextCRL

public CRL nextCRL()
            throws NotSupportedException,
                   DatabaseException

Returns the next available CRL.

Returns

A CRL that is the next CRL found in the database.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

See Also

firstCRL()

hasMoreCRLs()

hasMoreCRLs

public boolean hasMoreCRLs()
                    throws NotSupportedException,
                           DatabaseException

Returns a boolean that indicates whether any more CRLs are available in the database.

Returns

A boolean with a value of true if there are more CRLs, false otherwise.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

See Also

firstCRL()

nextCRL()

selectPrivateKeyByCertificate

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

Retrieves the private key identified by the specified certificate, cert, from the database managed by the service provider.

Parameters

cert

A Certificate that contains the public key that corresponds with the private key to be retrieved.

Returns

A JSAFE_PrivateKey that was found in the search. If no private key is found, null is returned.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

selectPrivateKeyByPublicKey

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

Retrieves the private key identified by the specified public key, publicKey, from the database managed by the service provider.

Parameters

publicKey

A JSAFE_PublicKey that contains the public key that corresponds with the private key to be retrieved.

Returns

A JSAFE_PrivateKey that was found in the search. If no private key is found, null is returned.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

isPrivateKeyIteratorSetup

public boolean isPrivateKeyIteratorSetup()
                                  throws NotSupportedException,
                                         DatabaseException

Returns a boolean value indicating whether a private key iterator is already set up or not.

Returns

true if an iterator is set up or false otherwise.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

See Also

firstPrivateKey()

setupPrivateKeyIterator

public void setupPrivateKeyIterator()
                             throws NotSupportedException,
                                    DatabaseException

Sets up a private key iterator.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

firstPrivateKey

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

Retrieves the first private key from the database provider. This method also sets up the private key enumeration environment for subsequent nextPrivateKey calls. Inserting or deleting a private key after calling this method may or may not affect the behavior of subsequent nextPrivateKey calls depending on the provider implementation.

Returns

A JSAFE_PrivateKey that is the first private key found in the database.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

See Also

nextPrivateKey()

hasMorePrivateKeys()

nextPrivateKey

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

Returns the next available private key.

Returns

A JSAFE_PrivateKey that is the next private key found in the database.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

See Also

firstPrivateKey()

hasMorePrivateKeys()

hasMorePrivateKeys

public boolean hasMorePrivateKeys()
                           throws NotSupportedException,
                                  DatabaseException

Returns a boolean that ndicates whether any more private keys are available.

Returns

A boolean with a value of true if there are more private keys, false otherwise.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

See Also

firstPrivateKey()

nextPrivateKey()

deleteCertificate

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

Deletes the certificate identified by the specified issuer name, issuerName, and serial number, serialNumber, from the database managed by the database service provider.

Parameters

	issuerName		An X500Name 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

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

deleteCRL

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

Deletes the CRL identified by the specified issuer name, issuerName, and last-update time, lastUpdate, from the database managed by the database service provider.

Parameters

	issuerName		An X500Name that contains the name of the entity that issued the CRL to be deleted.
	lastUpdate		A Date that contains the value of the last update field of the CRL.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

deletePrivateKeyByCertificate

public void deletePrivateKeyByCertificate(Certificate cert)
                                   throws NotSupportedException,
                                          DatabaseException

Deletes the private key identified by the specified certificate, cert, from the database managed by the database service provider.

Parameters

cert

Certificate that corresponds with the privatekey to be deleted.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.

deletePrivateKeyByPublicKey

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

Deletes the private key identified by the specified public key, publicKey, from the database managed by the database service provider.

Parameters

publicKey

A JSAFE_PublicKey that contains the public key corresponding with the private key to be deleted.

Throws

NotSupportedException - If the provider does not support this SPI method.

DatabaseException - If there is an unrecoverable error in the database.