SHOW Signed

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

java.lang.Object
  |
  +--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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Since:

JDE 3.6.0

See Also:

CertificateStatusRequest, CertificateStatusListener, CertificateStatus, Certificate

Field Summary

	static int	REQUEST_CANCEL Indicates that the user has canceled the request process.
	static int	REQUEST_COMPLETE Indicates that the request process is complete and that the user has dismissed the dialog after receiving the response.
	static int	REQUEST_DISMISS Indicates that the request process has started, but that the user has dismissed the dialog at some point before completion.
	static int	REQUEST_ERROR Indicates that the request process has been terminated with some error condition.
	static int	REQUEST_START Indicates that the request process has begun successfully.

Constructor Summary

Method Summary

	static int	fetchCertificateStatus(CertificateStatusRequest request, CertificateStatusListener listener) Requests over-the-air status for a certificate without showing UI to the user.
	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.
	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).

Since:

JDE 3.6.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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.

Since:

JDE 3.6.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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.

Since:

JDE 3.6.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

REQUEST_CANCEL

public static final int REQUEST_CANCEL

Indicates that the user has canceled the request process. No further processing will take place.

Since:

JDE 3.6.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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.

Since:

JDE 3.6.0

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Constructor Detail

Method Detail

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.

Since:

JDE 4.0.2

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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).

Since:

JDE 4.0.2

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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.

Since:

JDE 4.0.2

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.