net.rim.device.api.crypto.keystore
Class CertificateStatusManager

java.lang.Object
  net.rim.device.api.crypto.keystore.CertificateStatusManager

All Implemented Interfaces:

CollectionEventSource

public final class CertificateStatusManager
extends Object
implements CollectionEventSource

Coordinates all status methods required to use access and modify the CertificateStatus of any Certificate on the device.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

Method Summary
	void	addCollectionListener(Object listener) Registers a listener to receive collection events.
	boolean	checkTicket(CertificateStatusManagerTicket ticket) Checks the validity of the ticket.
	static CertificateStatusManager	getInstance() This method returns an instance of the CertificateStatusManager.
	static long	getStaleTime() Returns the current stale time for the handheld.
	CertificateStatus	getStatus(Certificate certificate) This method will return the status of the certificate that is passed into this method.
	CertificateStatusManagerTicket	getTicket() Returns a ticket for the KeyStoreManager assuming that the password was entered correctly.
	boolean	isTicketRequired(byte[] certificateEncoding, String certificateType, CertificateStatus newStatus) This method will determine whether a setStatus call using the certificate and status passed into this method will require a password prompt on the part of the user.
	boolean	isTicketRequired(Certificate certificate, CertificateStatus newStatus) This method will determine whether a setStatus call using the certificate and status passed into this method will require a password prompt on the part of the user.
	void	removeCollectionListener(Object listener) Removes a listener object from the list of those receiving events.
	void	revoke(CertificateRevocationList crl) Revokes the certificate specified by the CRL.
	void	setStatus(byte[] encoding, String type, CertificateStatus status, CertificateStatusManagerTicket ticket) This method will ensure that the certificate has been added to the keystore and if so, it will update the status.
	void	setStatus(Certificate certificate, int reason, CertificateStatusManagerTicket ticket) This method creates a new Certificate status object that contains the reason given as one of the parameters.
	void	setStatus(Certificate certificate, CertificateStatus status, CertificateStatusManagerTicket ticket) This method will ensure that the certificate has been added to the keystore and if so, it will update the status.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static CertificateStatusManager getInstance()

This method returns an instance of the CertificateStatusManager.

Returns:

The CertificateStatusManager object.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getStaleTime

public static long getStaleTime()

Returns the current stale time for the handheld. That is, this represents the amount of time in milliseconds where a certificate status would be considered stale if the status was older than this amount of time.

Returns:

the time in milliseconds representing the time before a status is considered to be stale on the device.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

revoke

public void revoke(CertificateRevocationList crl)
            throws CertificateStatusException

Revokes the certificate specified by the CRL. It is important to note that the certificate status items are kept in the KeyStoreManager so we do not need to inform any of the KeyStores that this status has changed.

Parameters:

crl - The certificate revocation list.

Throws:

CertificateStatusException - Thrown if the certificate status is incorrect or if the method had trouble building up the lists of certificates for verification.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

setStatus

public void setStatus(Certificate certificate,
                      CertificateStatus status,
                      CertificateStatusManagerTicket ticket)
               throws KeyStoreCancelException,
                      InvalidTimeException,
                      BackwardStatusException

This method will ensure that the certificate has been added to the keystore and if so, it will update the status.

It is important to note that this method will NOT allow you to change the status of a certificate back to a state that it was already in. For example, a revoked certificate cannot be changed to a status of GOOD.

Parameters:

certificate - The certificate whose status has changed.

status - The new status of the certificate.

ticket - The specified key store ticket.

Throws:

KeyStoreCancelException - Thrown if the user does not enter a password or cancels the password dialog.

InvalidTimeException - Thrown if the specified time or date is invalid.

BackwardStatusException - Thrown if the user attempts to set the certificate to an invalid status.

IllegalArgumentException - Thrown if the CertificateStatus object is null.

See Also:

CertificateStatusManager.getStatus(net.rim.device.api.crypto.certificate.Certificate)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

setStatus

public void setStatus(Certificate certificate,
                      int reason,
                      CertificateStatusManagerTicket ticket)
               throws KeyStoreCancelException,
                      InvalidTimeException,
                      BackwardStatusException

This method creates a new Certificate status object that contains the reason given as one of the parameters. It then delegates the call to the other revoke method setting the certificate status as revoked.

Parameters:

certificate - The certificate to be revoked.

reason - An integer describing the reason the certificate was revoked referencing the RevocationReason interface.

ticket - The specified key store ticket.

Throws:

KeyStoreCancelException - Thrown if the user does not enter a password or cancels the password dialog.

InvalidTimeException - Thrown if the specified time or date is invalid.

BackwardStatusException - Thrown if the user attempts to set the certificate to an invalid status.

IllegalArgumentException - Thrown if the CertificateStatus object is null.

See Also:

CertificateStatusManager.getStatus(net.rim.device.api.crypto.certificate.Certificate)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

setStatus

public void setStatus(byte[] encoding,
                      String type,
                      CertificateStatus status,
                      CertificateStatusManagerTicket ticket)
               throws KeyStoreCancelException,
                      InvalidTimeException,
                      BackwardStatusException

This method will ensure that the certificate has been added to the keystore and if so, it will update the status.

It is important to note that this method will NOT allow you to change the status of a certificate back to a state that it was already in. For example, a revoked certificate cannot be changed to a status of GOOD.

Parameters:

encoding - the byte[] containing the encoding of the certificate.

type - a string representing the type of the certificate. For example, "WTLS" or "X509".

status - The new status of the certificate.

ticket - The specified key store ticket.

Throws:

KeyStoreCancelException - Thrown if the user does not enter a password or cancels the password dialog.

InvalidTimeException - Thrown if the specified time or date is invalid.

BackwardStatusException - Thrown if the user attempts to set the certificate to an invalid status.

IllegalArgumentException - Thrown if the CertificateStatus object is null.

See Also:

CertificateStatusManager.getStatus(net.rim.device.api.crypto.certificate.Certificate)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

isTicketRequired

public boolean isTicketRequired(Certificate certificate,
                                CertificateStatus newStatus)
                         throws InvalidTimeException,
                                BackwardStatusException

This method will determine whether a setStatus call using the certificate and status passed into this method will require a password prompt on the part of the user. Note that the user is only prompted for the password in the case where the status is changing by a significant value (from UNKNOWN to GOOD for example) instead of changes to the time.

Parameters:

certificate - the certificate to check the new status against..

status - the certificate status to check for the password prompt.

Returns:

a boolean indicating whether a setStatus call with the certificate and status passed into this method.

Throws:

IllegalArgumentException - if the certificate or status is null.

InvalidTimeException - if the setStatus call will throw this exception because the time is invalid.

BackwardStatusException - if the setStatus call will throw this exception because the status is going backwards compared to what is already stored in the CertificateStatusManager.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

isTicketRequired

public boolean isTicketRequired(byte[] certificateEncoding,
                                String certificateType,
                                CertificateStatus newStatus)
                         throws InvalidTimeException,
                                BackwardStatusException

This method will determine whether a setStatus call using the certificate and status passed into this method will require a password prompt on the part of the user. Note that the user is only prompted for the password in the case where the status is changing by a significant value (from UNKNOWN to GOOD for example) instead of changes to the time.

Parameters:

encoding - the byte[] containing the encoding of the certificate.

type - a string representing the type of the certificate. For example, "WTLS" or "X509".

status - the certificate status to check for the password prompt.

Returns:

a boolean indicating whether a setStatus call with the certificate and status passed into this method.

Throws:

IllegalArgumentException - if the certificate or status is null.

InvalidTimeException - if the setStatus call will throw this exception because the time is invalid.

BackwardStatusException - if the setStatus call will throw this exception because the status is going backwards compared to what is already stored in the CertificateStatusManager.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.2

getStatus

public CertificateStatus getStatus(Certificate certificate)

This method will return the status of the certificate that is passed into this method. There is only one certificate status stored for each certificate in the any of the KeyStores so that means that it will find the only status for that certificate.

Parameters:

certificate - The certificate for which to find the status. The equals method is used to find the matching certificates.

Returns:

The certificate status for that certificate. If a null is returned that means the method could not find the certificate.

See Also:

CertificateStatusManager.setStatus(net.rim.device.api.crypto.certificate.Certificate, net.rim.device.api.crypto.certificate.CertificateStatus, net.rim.device.api.crypto.keystore.CertificateStatusManagerTicket)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

getTicket

public CertificateStatusManagerTicket getTicket()
                                         throws KeyStoreCancelException

Returns a ticket for the KeyStoreManager assuming that the password was entered correctly.

Returns:

The CertificateStatusManagerTicket object.

Throws:

KeyStoreCancelException - Thrown if the user cancels out of the password dialog.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

checkTicket

public boolean checkTicket(CertificateStatusManagerTicket ticket)

Checks the validity of the ticket.

Parameters:

ticket - The specified ticket.

Returns:

A boolean that represents validity of the ticket. Returns true if the ticket is valid, false otherwise.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

addCollectionListener

public void addCollectionListener(Object listener)

Registers a listener to receive collection events. Note: object parameters that are passed back to the listener when an event occurs should be down cast to a Certificate object.

Specified by:

addCollectionListener in interface CollectionEventSource

Parameters:

listener - Object to register as a listener which must implement CollectionListener or one of its derived interfaces.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0

removeCollectionListener

public void removeCollectionListener(Object listener)

Removes a listener object from the list of those receiving events. Note: object parameters that are passed back to the listener when an event occurs should be down cast to a Certificate object.

Specified by:

removeCollectionListener in interface CollectionEventSource

Parameters:

listener - Listener to remove.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 3.6.0