net.rim.device.api.crypto.certificate.status
Class CertificateStatusProvider

java.lang.Object
  extended by net.rim.device.api.crypto.certificate.status.CertificateStatusProvider

public abstract class CertificateStatusProvider
extends Object

Provides access to over-the-air certificate status through various supported protocols. A custom plugin model is used, so developers are free to implement their own certificate status providers that are registered and called by this framework.

For a complete discussion on the behaviour of this API and on implementing custom status providers, please see Creating custom certificate status provider plug-ins.

By default, OCSP (RFC 2560) is supported by this API. Status requests using OCSP can be made by simply calling one of the status request methods in this class.

See Also:
CertificateStatusRequest, CertificateStatusListener, CertificateStatus, 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

Field Summary
Category: Signed static int REQUEST_CANCEL
          Indicates that the user has canceled the request process.
Category: Signed static int REQUEST_COMPLETE
          Indicates that the request process is complete and that the user has dismissed the dialog after receiving the response.
Category: Signed static int REQUEST_DISMISS
          Indicates that the request process has started, but that the user has dismissed the dialog at some point before completion.
Category: Signed static int REQUEST_ERROR
          Indicates that the request process has been terminated with some error condition.
Category: Signed static int REQUEST_START
          Indicates that the request process has begun successfully.
 
Constructor Summary
Category: Signed protected CertificateStatusProvider(long providerId)
          Creates a provider with the given ID.
 
Method Summary
Category: Signed protected abstract  boolean checkCompatibility(Certificate[] certChain, boolean extendedChecking)
          Determines if this provider is compatible with the given certificate(s).
Category: Signed protected abstract  void decodeResponse(Certificate[] certChain, boolean extendedChecking, ProviderResponseData response, KeyStore keyStore, ProviderUiContext uiContext)
          Decodes the response for the given certificate chain.
Category: Signed protected abstract  void encodeRequest(Certificate[] certChain, boolean extendedChecking, ProviderRequestData request, KeyStore keyStore, ProviderUiContext uiContext)
          Encodes the necessary fields for a given certificate status request.
Category: Signed static int fetchCertificateStatus(CertificateStatusRequest request, CertificateStatusListener listener)
          Requests over-the-air status for a certificate without showing UI to the user.
Category: Signed  long getProviderId()
          Returns the ID of this provider.
Category: Signed static boolean queryStatusAvailability()
          Returns true if there are any status provider plugins registered on the device.
Category: Signed static boolean queryStatusAvailability(Certificate[] certChain, boolean extendedChecking)
          Returns true if any registered status provider plugins are compatible with the given certificate or certificate chain and can provide revocation status.
Category: Signed static boolean register(CertificateStatusProvider provider)
          Registers the given provider with the framework.
Category: Signed static int requestCertificateStatus(CertificateStatusRequest request, CertificateStatusListener listener, boolean allowDismiss, boolean allowDetails)
          Requests over-the-air status for a certificate, providing a UI front end to the process.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

REQUEST_START

public static final int REQUEST_START
Indicates that the request process has begun successfully. (Returned from non-UI fetch calls).

See Also:
Constant Field Values
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

REQUEST_COMPLETE

public static final int REQUEST_COMPLETE
Indicates that the request process is complete and that the user has dismissed the dialog after receiving the response.

See Also:
Constant Field Values
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

REQUEST_DISMISS

public static final int REQUEST_DISMISS
Indicates that the request process has started, but that the user has dismissed the dialog at some point before completion.

See Also:
Constant Field Values
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

REQUEST_CANCEL

public static final int REQUEST_CANCEL
Indicates that the user has canceled the request process. No further processing will take place.

See Also:
Constant Field Values
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

REQUEST_ERROR

public static final int REQUEST_ERROR
Indicates that the request process has been terminated with some error condition. A description of the exact error can be found in the CertificateStatusRequest object that was initially passed into the request call.

See Also:
Constant Field Values
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


Constructor Detail

CertificateStatusProvider

protected CertificateStatusProvider(long providerId)
Creates a provider with the given ID. Custom provider implementations must call this method from their constructors. The ID is used to identify the provider within the API, so it must be unique.

Parameters:
providerId - The ID of the provider.
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 Detail

getProviderId

public final long getProviderId()
Returns the ID of this provider.

Returns:
A long representing the provider ID.
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

register

public static final boolean register(CertificateStatusProvider provider)
Registers the given provider with the framework. Until a provider is registered, it will not be available for processing status requests. For any custom provider plugins, this method must be called manually.

Parameters:
provider - The staus provider to be registered.
Returns:
true if successfully registered, false if a provider with the same ID has already been registered.
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

queryStatusAvailability

public static final boolean queryStatusAvailability()
Returns true if there are any status provider plugins registered on the device.

Returns:
A boolean that determines if there are status provider plugins 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

queryStatusAvailability

public static final boolean queryStatusAvailability(Certificate[] certChain,
                                                    boolean extendedChecking)
Returns true if any registered status provider plugins are compatible with the given certificate or certificate chain and can provide revocation status.

Parameters:
certChain - A certificate chain to check against. Note that the end entity certificate must appear at array index [0].
extendedChecking - This boolean indicates that the status provider should perform any extended checking which may depend on the type of certificate or the provider itself. For example, with X509 certificates this boolean indicates that the provider should check the entire certificate chain. Other certificate types may behave differently.
Returns:
True if at least one provider can provide status; 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

requestCertificateStatus

public static final int requestCertificateStatus(CertificateStatusRequest request,
                                                 CertificateStatusListener listener,
                                                 boolean allowDismiss,
                                                 boolean allowDetails)
Requests over-the-air status for a certificate, providing a UI front end to the process.

This method takes a CertificateStatusRequest and begins the request process for it. At this time, a modal popup dialog is shown to the user that displays the ongoing status of the request process. In most cases, this will probably be the desired method of obtaining status, as it takes the burden of displaying status or error messages off of the developer.

Processing of the certificate status request is passed on to all providers registered with the framework. If at least one provider is able to provide status and completes successfully, the operation is considered a success.

This method blocks until the popup dialog is closed by the user, which can happen in one of several ways. If the boolean flag allowDismiss is set to true, a 'Dismiss' button will be shown at the bottom of the dialog. If this is clicked by the user, this method will return with value REQUEST_DISMISS and the dialog will be closed. This is useful if the developer wishes to provide a means for the user to hide the status dialog, but allow the operation to continue in the background asynchronously. If no dismiss button is provided, this method blocks until the process is complete or is cancelled by the user. Upon completion of the status fetch process, the listener method is called with the final status or error condition. A cancel button is available to the user while the dialog is visible. If this button is selected, the request process is stopped entirely, the listener is not called, and the method returns with value REQUEST_CANCEL.

Finally, if the user neither dismisses the dialog nor cancels the request, the dialog will be updated to show the received certificate status upon completion of the request process. Or, alternatively, if an error condition is encountered, the dialog will display an error message. The listener will be called when the dialog is closed but before this method unblocks.

When the received certificate status is shown to the user, it is possible to include a button that allows additional details to be shown using the CertificateInfoDialog when clicked. If this is desired, allowDetails should be set to true.

Parameters:
request - The CertificateStatusRequest to process.
listener - A CertificateStatusListener to be called upon completion of the process, in the case of either error or success. Note that this parameter can be null if the caller is not interested in the return value or the operation status.
allowDismiss - True if the user should be allowed to dismiss the status popup (see detailed description above).
allowDetails - True if the user should be able to view more specific information about the status response when received (see detailed description above).
Returns:
One of the defined return codes indicating the general state of the request process (REQUEST_START, REQUEST_COMPLETE, REQUEST_DISMISS, REQUEST_CANCEL, or REQUEST_ERROR).
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

fetchCertificateStatus

public static final int fetchCertificateStatus(CertificateStatusRequest request,
                                               CertificateStatusListener listener)
Requests over-the-air status for a certificate without showing UI to the user.

This method is essentially a completely asynchronous version of requestCertificateStatus that provides no UI. Once the request process for the given CertificateStatusRequest object has begun, the method exits with value REQUEST_START. If this method returns REQUEST_ERROR, then a fatal error prevented the status process from starting, and the listener is never called. The full error description can be found in the CertificateStatusRequest object.

Processing of the request is handled in much the same way as with requestCertificateStatus except that no UI front end is shown to the user.

When the response is received, the listener is called with the status or error condition.

Parameters:
request - The CertificateStatusRequest to process.
listener - A CertificateStatusListener to be called upon completion of the process, in the case of either error or success. Note that this parameter can be null if the caller is not interested in the return value or operation status.
Returns:
Either REQUEST_START, if the request has been started successfully, or REQUEST_ERROR, if some error condition has occurred.
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

checkCompatibility

protected abstract boolean checkCompatibility(Certificate[] certChain,
                                              boolean extendedChecking)
Determines if this provider is compatible with the given certificate(s). Essentially, a provider should determine if the certificates are of the appropriate type or have the necessary fields for fetching status. Even if the provider claims that the certificates are not compatible with it, there is no guarantee that encodeRequest() will not be called for those certificate. This method is used by queryStatusAvailability() to determine the status availability of a given certificate chain.

Parameters:
certChain - an array of certificates to check for compatibility. Note that the end-entity certificate must appear at array index [0]
extendedChecking - This boolean indicates that the status provider should perform any extended checking which may depend on the type of certificate or the provider itself. For example, with X509 certificates this boolean indicates that the provider should check the entire certificate chain. Other certificate types may behave differently.
Returns:
True if the provider can deal with the given certificate(s); 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

encodeRequest

protected abstract void encodeRequest(Certificate[] certChain,
                                      boolean extendedChecking,
                                      ProviderRequestData request,
                                      KeyStore keyStore,
                                      ProviderUiContext uiContext)
                               throws StatusProviderException
Encodes the necessary fields for a given certificate status request. Custom provider plugins must implement this method to encode the appropriate data fields to be sent to the matching plugin on the proxy. For complete details on implementing this method, see Creating custom certificate status provider plug-ins.

Parameters:
certChain - The array of certificates for this request. Note that the end-entity certificate must appear at array index [0].
extendedChecking - This boolean indicates that the status provider should perform any extended checking which may depend on the type of certificate or the provider itself. For example, with X509 certificates this boolean indicates that the provider should check the entire certificate chain. Other certificate types may behave differently.
request - The request data object that will be sent to the proxy.
keyStore - A KeyStore that may be used to find additional certificates necessary for the request process. This parameter may be null.
uiContext - The UI context this provider can use to show dialogs to the user and log error messages while encoding the request.
Throws:
StatusProviderException - Thrown if the status provider encounters an unrecoverable error condition.
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

decodeResponse

protected abstract void decodeResponse(Certificate[] certChain,
                                       boolean extendedChecking,
                                       ProviderResponseData response,
                                       KeyStore keyStore,
                                       ProviderUiContext uiContext)
                                throws StatusProviderException
Decodes the response for the given certificate chain. Custom provider plugins must implement this method to receive and process that status response received from the proxy. For complete details on implementing this method, see Creating custom certificate status provider plug-ins.

Parameters:
certChain - The array of certificates for this request. Note that the end-entity certificate must appear at array index [0].
extendedChecking - This boolean indicates that the status provider should perform any extended checking which may depend on the type of certificate or the provider itself. For example, with X509 certificates this boolean indicates that the provider should check the entire certificate chain. Other certificate types may behave differently.
response - The response data object received from the proxy.
keyStore - A KeyStore that may be used to find additional certificates necessary for the request process. This parameter may be null.
uiContext - The UI context this provider can use to show dialogs to the user and log error messages while decoding the response.
Throws:
StatusProviderException - Thrown if the status provider encounters an unrecoverable error condition.
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





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal