SHOW Signed
 

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

java.lang.Object
  |
  +--net.rim.device.api.crypto.keystore.CertificateStatusManager
All Implemented Interfaces:
Collection, CollectionEventSource

public final class CertificateStatusManager
extends Object
implements Collection, 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:
JDE 3.6.0

Method Summary
 Category: Signed  void addCollectionListener(Object listener)
          Registers a listener to receive collection events.
 Category: Signed  boolean checkTicket(CertificateStatusManagerTicket ticket)
          Checks the validity of the ticket.
 Category: Signed static CertificateStatusManager getInstance()
          This method returns an instance of the CertificateStatusManager.
 Category: Signed static long getStaleTime()
          Returns the current stale time for the handheld.
 Category: Signed  CertificateStatus getStatus(Certificate certificate)
          This method will return the status of the certificate that is passed into this method.
 Category: Signed  CertificateStatusManagerTicket getTicket()
          Returns a ticket for the KeyStoreManager assuming that the password was entered correctly.
 Category: Signed  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.
 Category: Signed  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.
 Category: Signed  void removeCollectionListener(Object listener)
          Removes a listener object from the list of those receiving events.
 Category: Signed  void revoke(CertificateRevocationList crl)
          Revokes the certificate specified by the CRL.
 Category: Signed  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.
 Category: Signed  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.
 Category: Signed  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.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

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.

Parameters:
listener - Object to register as a listener which must implement CollectionListener or one of its derived interfaces.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 3.6.0
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.

getInstance

public static CertificateStatusManager getInstance()
This method returns an instance of the CertificateStatusManager.

Returns:
The CertificateStatusManager object.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 4.0.0
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.

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.
Since:
JDE 3.6.0
See Also:
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.

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.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 4.0.2
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.

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.
Since:
JDE 4.0.0
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.

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.

Parameters:
listener - Listener to remove.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 3.6.0
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.

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.
Since:
JDE 3.6.0
See Also:
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.

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.
Since:
JDE 3.6.0
See Also:
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.

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.
Since:
JDE 3.6.0
See Also:
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.



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.