|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectnet.rim.device.api.crypto.certificate.status.CertificateStatusProvider
public abstract class CertificateStatusProvider
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.
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 | ||
|---|---|---|
|
protected |
CertificateStatusProvider(long providerId)
Creates a provider with the given ID. |
| Method Summary | ||
|---|---|---|
|
protected abstract boolean |
checkCompatibility(Certificate[] certChain,
boolean extendedChecking)
Determines if this provider is compatible with the given certificate(s). |
|
protected abstract void |
decodeResponse(Certificate[] certChain,
boolean extendedChecking,
ProviderResponseData response,
KeyStore keyStore,
ProviderUiContext uiContext)
Decodes the response for the given certificate chain. |
|
protected abstract void |
encodeRequest(Certificate[] certChain,
boolean extendedChecking,
ProviderRequestData request,
KeyStore keyStore,
ProviderUiContext uiContext)
Encodes the necessary fields for a given certificate status request. |
|
static int |
fetchCertificateStatus(CertificateStatusRequest request,
CertificateStatusListener listener)
Requests over-the-air status for a certificate without showing UI to the user. |
|
long |
getProviderId()
Returns the ID of this provider. |
|
static boolean |
queryStatusAvailability()
Returns true if there are any status provider plugins registered on the device. |
|
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 boolean |
register(CertificateStatusProvider provider)
Registers the given provider with the framework. |
|
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 |
|---|
public static final int REQUEST_START
public static final int REQUEST_COMPLETE
public static final int REQUEST_DISMISS
public static final int REQUEST_CANCEL
public static final int REQUEST_ERROR
CertificateStatusRequest object that was initially
passed into the request call.
| Constructor Detail |
|---|
protected CertificateStatusProvider(long providerId)
providerId - The ID of the provider.| Method Detail |
|---|
public final long getProviderId()
public static final boolean register(CertificateStatusProvider provider)
provider - The staus provider to be registered.
public static final boolean queryStatusAvailability()
public static final boolean queryStatusAvailability(Certificate[] certChain,
boolean extendedChecking)
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.
public static final int requestCertificateStatus(CertificateStatusRequest request,
CertificateStatusListener listener,
boolean allowDismiss,
boolean allowDetails)
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.
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).
REQUEST_START, REQUEST_COMPLETE, REQUEST_DISMISS,
REQUEST_CANCEL, or REQUEST_ERROR).
public static final int fetchCertificateStatus(CertificateStatusRequest request,
CertificateStatusListener listener)
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.
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.
REQUEST_START, if the request has been started successfully, or
REQUEST_ERROR, if some error condition has occurred.
protected abstract boolean checkCompatibility(Certificate[] certChain,
boolean extendedChecking)
encodeRequest() will not be called for
those certificate. This method is used by queryStatusAvailability()
to determine the status availability of a given certificate chain.
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.
protected abstract void encodeRequest(Certificate[] certChain,
boolean extendedChecking,
ProviderRequestData request,
KeyStore keyStore,
ProviderUiContext uiContext)
throws StatusProviderException
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.
StatusProviderException - Thrown if the status provider encounters an unrecoverable error condition.
protected abstract void decodeResponse(Certificate[] certChain,
boolean extendedChecking,
ProviderResponseData response,
KeyStore keyStore,
ProviderUiContext uiContext)
throws StatusProviderException
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.
StatusProviderException - Thrown if the status provider encounters an unrecoverable error condition.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.