SHOW Signed

net.rim.device.api.crypto.certificate
Interface Certificate

All Superinterfaces:

Persistable, net.rim.vm.Persistable

All Known Implementing Classes:

X509Certificate, WTLSCertificate

public interface Certificate

extends Persistable

Defines the properties of all certificates. A certificate is a collection of data used to associate a public key with an identity.

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.

See Also:

CertificateStatus, CertificateField, CertificateFactory

Field Summary

static long

EMAIL_ADDRESSES The identifier to indicate the extraction of email addresses from the certificate.

Method Summary

	void	checkCertificateChain(int position, Certificate[] chain) Checks to make sure that the certificate at position is valid within the chain.
	CertificateDisplayField[]	getCustomDisplayFields() Returns custom information about the certificate for display in a dialog.
	byte[]	getEncoding() Returns the encoding of the certificate.
	byte[]	getEncoding(int field) Returns the encoding of the field within the certificate (see CertificateField).
	CertificateExtension	getExtension(OID oid) Returns the extension for the given oid if it exists in the certificate, otherwise null.
	CertificateExtension[]	getExtensions() Returns all the extensions associated with this certificate, or null.
	CertificateExtension[]	getExtensions(boolean criticalBit) Returns all the extensions associated with this certificate that have their critical bit set to the value of criticalBit, or null if none are found.
	Object	getInformation(long id, Object param, Object defaultValue) Retrieves generic information about the certificate
	DistinguishedName	getIssuer() Returns a DistinguishedName object, representing the issuer of this certificate.
	long	getNotAfter() Returns the date on which this certificate will expire.
	long	getNotBefore() Returns the date on which this certificate will become valid.
	PublicKey	getPublicKey() Extracts the subject's public key.
	String	getPublicKeyAlgorithm() Returns a string representing the intended use of the public key.
	byte[]	getSerialNumber() Returns the certificates serial number as a byte array representing an an integer in big-endian (network) order.
	String	getSignatureAlgorithm() Returns a string representing the signature algorithm used to sign this certificate.
	CertificateStatus	getStatus() Retrieves the CertificateStatus for this certificate object
	DistinguishedName	getSubject() Returns a DistinguishedName object, representing the subject name of this certificate.
	String	getSubjectFriendlyName() Returns a human-readable string version of the name of the subject of this certificate.
	String	getType() Returns the type of this certificate, such as "X509", "WTLS" etc.
	int	getVersion() Returns the version of the certificate.
	boolean	isCA() Returns true if the certificate is of a certificate authority.
	boolean	isRoot() Returns true if the certificate is self signed.
	boolean	isValid() Checks that this certificate is valid, using the current date and time as the time reference.
	boolean	isValid(long date) Check that this certificate is valid, using date as the time reference.
	int	queryKeyUsage(long purpose) Indicates whether the key contained in this certificate may be used for the specified purpose.
	void	setStatus(CertificateStatus status) Sets the current CertificateStatus for this certificate object.
	void	verify() Verifies the certificate if the certificate is self signed.
	void	verify(KeyStore keyStore) Verifies the certificate.
	void	verify(PublicKey issuerPublicKey) Verifies the certificate.

Field Detail

EMAIL_ADDRESSES

public static final long EMAIL_ADDRESSES

The identifier to indicate the extraction of email addresses from the certificate. This identifier can be passed into getInformation, which should return an array of email addresses. The result from getInformation should be casted to a String []. If no email addresses are found, getInformation should return null.

See Also:

getInformation(long, java.lang.Object, java.lang.Object)

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.

Method Detail

verify

public void verify(PublicKey issuerPublicKey)
            throws CertificateVerificationException,
                   DecodeException,
                   InvalidSignatureEncodingException,
                   NoSuchAlgorithmException,
                   CryptoTokenException,
                   CryptoUnsupportedOperationException

Verifies the certificate.

The function checks that the certificate was signed by issuerPublicKey.

Parameters:

issuerPublicKey - The public key of the certificate issuer.

Throws:

CertificateVerificationException - Thrown if the certificate cannot be verified.

DecodeException - Thrown if the data is improperly formatted.

InvalidSignatureEncodingException - Thrown if the specified signature is invalid.

NoSuchAlgorithmException - Thrown if the specified algorithm is not known.

CryptoTokenException - Thrown if an error occurs with the crypto token or crypto token is invalid.

CryptoUnsupportedOperationException - Thrown if a call is made to an unsupported operation.

Since:

JDE 3.6

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.

verify

public void verify(KeyStore keyStore)
            throws CertificateVerificationException,
                   DecodeException,
                   InvalidSignatureEncodingException,
                   NoSuchAlgorithmException,
                   NoIssuerFoundException,
                   CryptoTokenException,
                   CryptoUnsupportedOperationException

Verifies the certificate.

The function checks that the certificate was signed by at least one of the publicKeys from the given keyStore.

Parameters:

keyStore - The keyStore that contains the keys.

Throws:

CertificateVerificationException - Thrown if the certificate cannot be verified.

DecodeException - Thrown if the data is improperly formatted.

InvalidSignatureEncodingException - Thrown if the specified signature is invalid.

NoSuchAlgorithmException - Thrown if the specified algorithm is not known.

NoIssuerFoundException - Thrown when the issuer of the certificate cannot be found.

CryptoTokenException - Thrown if an error occurs with the crypto token or crypto token is invalid.

CryptoUnsupportedOperationException - Thrown if a call is made to an unsupported operation.

Since:

JDE 3.6

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.

isRoot

public boolean isRoot()

Returns true if the certificate is self signed.

Returns:

A boolean. True if the certificate is self signed, false otherwise.

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.

isCA

public boolean isCA()

Returns true if the certificate is of a certificate authority.

Returns:

A boolean. True if the certificate is of a certificate authority. Returns false otherwise.

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.

verify

public void verify()
            throws CertificateVerificationException,
                   DecodeException,
                   InvalidSignatureEncodingException,
                   NoSuchAlgorithmException,
                   CryptoTokenException,
                   CryptoUnsupportedOperationException

Verifies the certificate if the certificate is self signed.

Throws:

CertificateVerificationException - Thrown if the certificate cannot be verified.

DecodeException - Thrown if the data is improperly formatted.

InvalidSignatureEncodingException - Thrown if the specified signature is invalid.

NoSuchAlgorithmException - Thrown if the specified algorithm is not known.

CryptoTokenException - Thrown if an error occurs with the crypto token or crypto token is invalid.

CryptoUnsupportedOperationException - Thrown if a call is made to an unsupported operation.

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.

checkCertificateChain

public void checkCertificateChain(int position,
                                  Certificate[] chain)
                           throws CertificateChainTooLongException,
                                  CertificateVerificationException

Checks to make sure that the certificate at position is valid within the chain.

Parameters:

position - The position of this ceritificate within the chain.

chain - The array of certificates representing the certificate chain. The end-entity cert must be at array index [0].

Throws:

CertificateChainTooLongException - Thrown if the number of certificates, before this one, in the chain is longer than the certificates policy allows.

CertificateVerificationException - Thrown if there is another problem with the chain

Since:

JDE 3.6

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.

getPublicKey

public PublicKey getPublicKey()
                       throws InvalidCryptoSystemException

Extracts the subject's public key.

Returns:

The user's PublicKey.

Throws:

InvalidCryptoSystemException - Thrown if the crypto system used to create the key was invalid.

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.

getPublicKeyAlgorithm

public String getPublicKeyAlgorithm()

Returns a string representing the intended use of the public key. If no specific algorithm is intended for this public key, then the generic string for the public key will be returned.

Returns:

A string representing the intended use of the public key or null if an error occurred.

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.

getSignatureAlgorithm

public String getSignatureAlgorithm()

Returns a string representing the signature algorithm used to sign this certificate.

Returns:

A string representing the signature algorithm used to sign this certificate.

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.

getIssuer

public DistinguishedName getIssuer()

Returns a DistinguishedName object, representing the issuer of this certificate.

Returns:

The distinguished name of the certificate issuer.

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.

getSubject

public DistinguishedName getSubject()

Returns a DistinguishedName object, representing the subject name of this certificate.

Returns:

The distinguished name of the subject of the certifcate.

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.

getStatus

public CertificateStatus getStatus()

Retrieves the CertificateStatus for this certificate object

Returns:

the current CertificateStatus stored for this certificate on the device. May be null.

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.

setStatus

public void setStatus(CertificateStatus status)
               throws KeyStoreCancelException,
                      InvalidTimeException,
                      BackwardStatusException

Sets the current CertificateStatus for this certificate object.

Parameters:

status - the new CertificateStatus that will be set for this certificate. It is important to note that this status should not attempt to set the status backwards (i.e. from REVOKED to GOOD) and it should not allow the date of a status to be in the future.

Throws:

KeyStoreCancelException - if the user decides not to enter their KeyStore password.

InvalidTimeException - if the time of the status is set in the future.

BackwardStatusException - if the status of the certificate is being backwards (i.e. from REVOKED to GOOD ).

Since:

JDE 3.6

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.

isValid

public boolean isValid()

Checks that this certificate is valid, using the current date and time as the time reference.

It checks that the current date is between the values returned by getNotValidBefore() and getNotValidAfter().

Note that this method only checks that the current date is within the validity period specified in the certificate.

Returns:

A boolean that determines if the certificate is valid. Returns true if the certificate is valid, false otherwise.

See Also:

verify()

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.

isValid

public boolean isValid(long date)

Check that this certificate is valid, using date as the time reference.

It checks that date is between the values returned by getNotBefore() and getNotValidAfter().

Note that this method only checks that date is within the validity period specified in the certificate.

Parameters:

date - The Date used to verify the certificate.

Returns:

A boolean that determines if the certificate is valid. Returns true if the certificate is valid, false otherwise.

Since:

JDE 3.6

See Also:

verify()

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.

getNotBefore

public long getNotBefore()

Returns the date on which this certificate will become valid.

Returns:

A long that specifies when the certificate will become valid.

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.

getNotAfter

public long getNotAfter()

Returns the date on which this certificate will expire.

Returns:

A long that specifies when the certificate will expire.

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.

getExtension

public CertificateExtension getExtension(OID oid)

Returns the extension for the given oid if it exists in the certificate, otherwise null.

Parameters:

oid - The oid with the extension.

Returns:

The CertificateExtension or null.

Since:

JDE 3.6

See Also:

OIDs

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.

getExtensions

public CertificateExtension[] getExtensions()

Returns all the extensions associated with this certificate, or null.

Returns:

An array of CertificateExtensions or null.

See Also:

OIDs

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.

getExtensions

public CertificateExtension[] getExtensions(boolean criticalBit)

Returns all the extensions associated with this certificate that have their critical bit set to the value of criticalBit, or null if none are found.

Parameters:

criticalBit - a boolean that is true, if all critical extensions are to be returned and set to false if all non-critical extensions are to be returned

Returns:

An array of CertificateExtensions or null.

Since:

JDE 3.6

See Also:

OIDs

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.

getType

public String getType()

Returns the type of this certificate, such as "X509", "WTLS" etc.

Returns:

A String representing the certificate type.

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.

getVersion

public int getVersion()

Returns the version of the certificate.

The version is specific to the type of certificate.

Returns:

An integer representing the version number.

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.

getSerialNumber

public byte[] getSerialNumber()

Returns the certificates serial number as a byte array representing an an integer in big-endian (network) order.

Returns:

A byte array containing the serial number.

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.

getEncoding

public byte[] getEncoding()

Returns the encoding of the certificate.

Returns:

A byte array containing the encoding. May be null.

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.

getEncoding

public byte[] getEncoding(int field)

Returns the encoding of the field within the certificate (see CertificateField).

Parameters:

field - An integer that represents the field.

Returns:

A byte array that represents the encoding of the field. May be null.

Since:

JDE 3.6

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.

getSubjectFriendlyName

public String getSubjectFriendlyName()

Returns a human-readable string version of the name of the subject of this certificate.

This string could be used for display purposes, for example. For the default behaviour, which attempts to build a friendly name using parts of the subject distinguished name, invoke CertificateUtilities.getSubjectFriendlyName(Certificate certificate).

Returns:

A String representing the subject name. May be null.

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.

queryKeyUsage

public int queryKeyUsage(long purpose)

Indicates whether the key contained in this certificate may be used for the specified purpose.

Parameters:

purpose - A constant chosen from the KeyUsage constants indicating the purpose for which the key will be checked.

Returns:

KeyUsageResult.ALLOWED	Thrown if the subject public key may be used for the specified purpose.
KeyUsageResult.NOT_ALLOWED	Thrown if the subject public key may not be used for the specified purpose.
KeyUsageResult.UNSPECIFIED	Thrown if it is unspecified whether the subject public key may be used for this purpose.

Since:

JDE 3.6

See Also:

KeyUsageResult

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.

getCustomDisplayFields

public CertificateDisplayField[] getCustomDisplayFields()

Returns custom information about the certificate for display in a dialog.

The displayCertificateDetails method in CertificateUtilities uses this custom information to format a dialog box containing details about the certificate. Details common to all types of certificates, like the subject name, issuer name, etc., are always displayed in the dialog; this function allows specific certificate types to add specific information to the dialog.

Returns:

An array of CertificateDisplayField objects containing label/value pairs for the information that is to be shown in the dialog, or null if no custom information should be displayed

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.

getInformation

public Object getInformation(long id,
                             Object param,
                             Object defaultValue)

Retrieves generic information about the certificate

Parameters:

id - the id of the data to retrieve

param - a parameter that may be used to determine what information to return

defaultValue - a default value that should be returned if the certificate does not recognize the id.

Returns:

information about the certificate matching the id and param

Since:

JDE 3.6

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.