SHOW Signed
 

net.rim.device.api.crypto.certificate
Class CertificateUtilities

java.lang.Object
  |
  +--net.rim.device.api.crypto.certificate.CertificateUtilities

public final class CertificateUtilities
extends Object

Provides numerous utilities for creating, manipulating and verifying certificates and certificate chains.

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
See Also:
Certificate, CertificateFactory, CertificateStatus

Method Summary
 Category: Signed static Certificate[] buildCertificateChain(Certificate certificate, Certificate[] pool, KeyStore keyStore)
          Builds the certificate chains for a certificate from a pool of certificates and a keystore, and returns the best one, as determined by the methods in CertificateChainProperties.
 Category: Signed static Certificate[] buildCertificateChain(Certificate certificate, KeyStore keyStore)
          Builds the certificate chains for a certificate from a keystore, and returns the best one, as determined by the methods in CertificateChainProperties.
 Category: Signed static Certificate[][] buildCertificateChains(Certificate certificate, Certificate[] pool, KeyStore keyStore)
          Builds all of the certificate chains for a certificate from a pool of certificates and a keystore.
 Category: Signed static Certificate[][] buildCertificateChains(Certificate certificate, KeyStore keyStore)
          Builds all of the certificate chains for a certificate from a keystore.
 Category: Signed static Certificate[] buildTrustedCertificateChain(Certificate certificate, Certificate[] pool, KeyStore keyStore, KeyStore trustedKeyStore)
          Deprecated. This method chooses one of potentially many certificate chains that may exist for this certificate, based only on whether the chain is trusted. Since there are many other criteria by which chains may be evaluated (e.g. revocation status, time validity, etc) and since these other criteria may affect the choice of the "best" chain, it is recommended that all of the chains be built first, and the best chain be selected using the methods in CertificateChainProperties.
 Category: Signed static Certificate[][] buildTrustedCertificateChains(Certificate certificate, Certificate[] pool, KeyStore keyStore, KeyStore trustedKeyStore)
          Deprecated. This method chooses certificate chains based only on whether they are trusted. Since there are many other criteria by which chains may be evaluated (e.g. revocation status, time validity, etc) and since these other criteria may affect the choice of the "best" chain, it is recommended that all of the chains be built first, and the best chain be selected using the methods in CertificateChainProperties.
 Category: Signed static String calculateThumbprint(Certificate certificate, Digest digest)
          Calculates the thumbprint of the certificate using the given digest.
 Category: Signed static boolean compareDistinguishedNames(DistinguishedName dn1, DistinguishedName dn2)
          Compares two DistinguishedNames component by component.
 Category: Signed static Certificate convertCertificate(Certificate certificate)
          Converts a RIM certificate into a Java ME certificate.
 Category: Signed static void displayCertificateChainDetails(String title, Certificate[] certificateChain)
          Blocks and displays a dialog box containing information about the specified certificate chain.
 Category: Signed static void displayCertificateChainDetails(String title, Certificate[][] certificateChains, KeyStore keyStore)
           
 Category: Signed static void displayCertificateChainDetails(String title, Certificate certificate, KeyStore keyStore)
          Blocks and displays a dialog box containing information about the certificate chains that can be built from the specified certificate.
 Category: Signed static void displayCertificateDetails(Certificate certificate)
          Blocks and displays a dialog box containing information about the specified certificate.
 Category: Signed static void displayCertificateDetails(Certificate certificate, Certificate[] certificatePool, KeyStore keyStore, boolean allowFetchStatus, CertificateStatusManagerTicket ticket)
          Blocks and displays a dialog box containing information about the specified certificate.
 Category: Signed static void displayCertificateDetails(Certificate certificate, Certificate[] certificatePool, KeyStore keyStore, CryptoSystemProperties cryptoSystemProperties, boolean allowFetchStatus, CertificateStatusManagerTicket ticket)
          Blocks and displays a dialog box containing information about the specified certificate.
 Category: Signed static void displayCertificateDetails(Certificate certificate, KeyStore keyStore)
          Blocks and displays a dialog box containing information about the specified certificate.
 Category: Signed static void displayCertificateDetails(Certificate certificate, KeyStore keyStore, boolean allowFetchStatus, CertificateStatusManagerTicket ticket)
          Blocks and displays a dialog box containing information about the specified certificate.
 Category: Signed static String formatDistinguishedName(DistinguishedName dn, char separator)
          Replaces all spaces in provided name with provided separator characters.
 Category: Signed static String getFriendlyName(DistinguishedName distinguishedName)
          Returns a string that contains a "friendly" name for the distinguished name of a certificate.
 Category: Signed static String getHexAsciiString(byte[] data)
          Returns a String containing the hexadecimal ASCII encoding of the given data.
 Category: Signed static String getHexAsciiString(byte[] data, int offset, int length)
          Returns a String containing the hexadecimal ASCII encoding of the given data.
 Category: Signed static String getKeyUsageString(long keyUsage)
          Returns a String that determines how the key is used.
 Category: Signed static String getSubjectFriendlyName(Certificate certificate)
          Returns a string that contains a "friendly" name for the subject of this certificate.
 Category: Signed static boolean isCertificateChainTrusted(Certificate[] chain, KeyStore trustedKeyStore)
          Deprecated. This method evaluates the certificate chain based only on whether it is trusted. Since there are many other criteria by which chains may be evaluated (e.g. revocation status, time validity, etc) and since these other criteria may affect the choice of the "best" chain, it is recommended that all of the chains be built first, and the best chain be selected using the methods in CertificateChainProperties.
 Category: Signed static boolean isCertificateTrusted(Certificate certificate, Certificate[] pool, KeyStore keyStore, KeyStore trustedKeyStore)
          Deprecated. This method evaluates the certificate based only on whether it is trusted. Since there are many other criteria by which chains may be evaluated (e.g. revocation status, time validity, etc) and since these other criteria may affect the choice of the "best" chain, it is recommended that all of the chains be built first, and the best chain be selected using the methods in CertificateChainProperties.
 Category: Signed static boolean isCertificateTrusted(Certificate certificate, KeyStore trustedKeyStore)
          Deprecated. This method evaluates the certificate based only on whether it is trusted. Since there are many other criteria by which chains may be evaluated (e.g. revocation status, time validity, etc) and since these other criteria may affect the choice of the "best" chain, it is recommended that all of the chains be built first, and the best chain be selected using the methods in CertificateChainProperties.
 Category: Signed static Certificate readCertificateFile(String type, byte[] data)
          Parses out a .cer, .crt and other certificate types file and returns the certificate that was found in the file.
 Category: Signed static int selectCertificate(RichTextField descriptionField, String[] names, Certificate[] certificates, KeyStore keyStore)
          Displays a dialog prompting the user to select a certificate from the list of certificates provided.
 Category: Signed static int selectCertificate(RichTextField descriptionField, String[] names, Certificate[] certificates, KeyStore keyStore, KeyStore trustedKeyStore)
          Displays a dialog prompting the user to select a certificate from the list of certificates provided.
 Category: Signed static int selectCertificate(RichTextField descriptionField, String[] names, Certificate[] certificates, KeyStore keyStore, KeyStore trustedKeyStore, CryptoSystemProperties cryptoSystemProperties)
          Displays a dialog prompting the user to select a certificate from the list of certificates provided.
 Category: Signed static int[] selectCertificates(RichTextField descriptionField, String[] names, Certificate[] certificates, int[] selectedCertificates, KeyStore keyStore)
          This method displays a dialog prompting the user to select a group of certificates from the list of certificates provided.
 Category: Signed static int[] selectCertificates(RichTextField descriptionField, String[] names, Certificate[] certificates, int[] selectedCertificates, KeyStore keyStore, KeyStore trustedKeyStore)
          This method displays a dialog prompting the user to select a group of certificates from the list of certificates provided.
 Category: Signed static int[] selectCertificates(RichTextField descriptionField, String[] names, Certificate[] certificates, int[] selectedCertificates, KeyStore keyStore, KeyStore trustedKeyStore, CryptoSystemProperties cryptoSystemProperties)
          This method displays a dialog prompting the user to select a group of certificates from the list of certificates provided.
 Category: Signed static int[] selectCertificates(RichTextField descriptionField, String[] names, Certificate[] certificates, KeyStore keyStore)
          This method displays a dialog prompting the user to select a group of certificates from the list of certificates provided.
 Category: Signed static boolean verifyCertificateChain(Certificate[] chain, KeyStore trustedKeyStore, long date)
          Verifies the signatures of the certificates in a chain.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

buildCertificateChain

public static Certificate[] buildCertificateChain(Certificate certificate,
                                                  Certificate[] pool,
                                                  KeyStore keyStore)
Builds the certificate chains for a certificate from a pool of certificates and a keystore, and returns the best one, as determined by the methods in CertificateChainProperties.

The chain will be built up until a root certificate is encountered, or until the issuer of a certificate cannot be found in the pool or in the keystore. The pool will be searched first for each issuer certificate, and if the certificate is not found there, the keystore will be searched.

Parameters:
certificate - The certificate for which the chain will be built.
pool - The pool of certificates that should be searched for certificates in the chain. Note this can be null.
keyStore - The keystore that should be searched for certificates in the chain. Note this can be null.
Returns:
The certificate chain, with certificate in position 0, its issuer in position 1, etc.
Since:
JDE 3.6.0
See Also:
CertificateChainProperties
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.

buildCertificateChain

public static Certificate[] buildCertificateChain(Certificate certificate,
                                                  KeyStore keyStore)
Builds the certificate chains for a certificate from a keystore, and returns the best one, as determined by the methods in CertificateChainProperties.

The chain will be built up until a root certificate is encountered, or until the issuer of a certificate cannot be found in the keystore.

Parameters:
certificate - The certificate for which the chain should be built.
keyStore - The keystore that should be searched when looking for certificates in the chain. Note this can be null.
Returns:
The certificate chain, with certificate in position 0, its issuer in position 1, etc.
Since:
JDE 3.6.0
See Also:
CertificateChainProperties
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.

buildCertificateChains

public static Certificate[][] buildCertificateChains(Certificate certificate,
                                                     Certificate[] pool,
                                                     KeyStore keyStore)
Builds all of the certificate chains for a certificate from a pool of certificates and a keystore.

The chains will be built up until a root certificate is encountered, or until the issuer of a certificate cannot be found in the pool or in the keystore. The pool will be searched first for each issuer certificate, and if the certificate is not found there, the keystore will be searched.

Parameters:
certificate - The certificate for which the chains will be built.
pool - The pool of certificates that should be searched for certificates in the chains. Note this can be null.
keyStore - The keystore that should be searched for certificates in the chains. Note this can be null.
Returns:
The certificate chains as an array of Certificate[], with certificate in position 0, its issuer in position 1, etc.
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.

buildCertificateChains

public static Certificate[][] buildCertificateChains(Certificate certificate,
                                                     KeyStore keyStore)
Builds all of the certificate chains for a certificate from a keystore.

The chains will be built up until a root certificate is encountered, or until the issuer of a certificate cannot be found in the keystore.

Parameters:
certificate - The certificate for which the chains should be built.
keyStore - The keystore that should be searched for certificates in the chains. Note this can be null.
Returns:
The certificate chains as an array of Certificate[], with certificate in position 0, its issuer in position 1, etc.
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.

buildTrustedCertificateChain

public static Certificate[] buildTrustedCertificateChain(Certificate certificate,
                                                         Certificate[] pool,
                                                         KeyStore keyStore,
                                                         KeyStore trustedKeyStore)
Deprecated. This method chooses one of potentially many certificate chains that may exist for this certificate, based only on whether the chain is trusted. Since there are many other criteria by which chains may be evaluated (e.g. revocation status, time validity, etc) and since these other criteria may affect the choice of the "best" chain, it is recommended that all of the chains be built first, and the best chain be selected using the methods in CertificateChainProperties.

Builds a trusted certificate chain for a certificate from a pool of certificates and a keystore. If no trusted chain is found, null is returned.

The chain will be built up until a root certificate is encountered, or until the issuer of a certificate cannot be found in the pool or in the keystore. The pool will be searched first for each issuer certificate, and if the certificate is not found there, the keystore will be searched.

Parameters:
certificate - The certificate for which the chain will be built.
pool - The pool of certificates that should be searched for certificates in the chain. Note this can be null.
keyStore - The keystore that should be searched for certificates in the chain. Note this can be null.
trustedKeyStore - The keystore that should be searched for the trusted certificates.
Returns:
The certificate chain, with certificate in position 0, its issuer in position 1, etc. or null if no trusted chain could be created.
Since:
JDE 3.6.0
See Also:
CertificateChainProperties
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.

buildTrustedCertificateChains

public static Certificate[][] buildTrustedCertificateChains(Certificate certificate,
                                                            Certificate[] pool,
                                                            KeyStore keyStore,
                                                            KeyStore trustedKeyStore)
Deprecated. This method chooses certificate chains based only on whether they are trusted. Since there are many other criteria by which chains may be evaluated (e.g. revocation status, time validity, etc) and since these other criteria may affect the choice of the "best" chain, it is recommended that all of the chains be built first, and the best chain be selected using the methods in CertificateChainProperties.

Builds all of the trusted certificate chains for a certificate from a pool of certificates and a keystore. If no trusted chains are found, null is returned.

The chains will be built up until a root certificate is encountered, or until the issuer of a certificate cannot be found in the pool or in the keystore. The pool will be searched first for each issuer certificate, and if the certificate is not found there, the keystore will be searched.

Parameters:
certificate - The certificate for which the chains will be built.
pool - The pool of certificates that should be searched for certificates in the chains. Note this can be null.
keyStore - The keystore that should be searched for certificates in the chains. Note this can be null.
trustedKeyStore - The keystore that should be searched for the trusted certificates.
Returns:
The certificate chains as an array of Certificate[], with certificate in position 0, its issuer in position 1, etc. or null if no trusted chain could be created.
Since:
JDE 3.6.0
See Also:
CertificateChainProperties
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.

calculateThumbprint

public static String calculateThumbprint(Certificate certificate,
                                         Digest digest)
Calculates the thumbprint of the certificate using the given digest.
Parameters:
certificate - The certificate to calculate the thumbprint on.
digest - The digest used in the calculation of the thumbprint.
Returns:
A String containing the thumbprint formatted using a hexadecimal ASCII encoding with spaces every 4 characters.
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.

compareDistinguishedNames

public static boolean compareDistinguishedNames(DistinguishedName dn1,
                                                DistinguishedName dn2)
Compares two DistinguishedNames component by component.

This method checks only valid components, and returns true if they both have the same number of components and same values for each component. The comparison between component values is case sensitive.

Parameters:
dn1 - The first distinguished name to compare. Must be non null.
dn2 - The second distinguished name to compare. Must be non null.
Returns:
True if the distinguished names are equal and 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.

convertCertificate

public static Certificate convertCertificate(Certificate certificate)
Converts a RIM certificate into a Java ME certificate.

Use this method to convert a net.rim.device.api.crypto into a Java ME Certificate for display purposes or to conform to the MIDP 2.0 standard where applicable.

Parameters:
certificate - RIM certificate to convert (it will not be affected or modified in any way).
Returns:
A Java ME Certificate version of the certificate that was passed into this method.
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.

displayCertificateChainDetails

public static void displayCertificateChainDetails(String title,
                                                  Certificate[] certificateChain)
Blocks and displays a dialog box containing information about the specified certificate chain.
Parameters:
title - The string that should be used as a title in the dialog box.
certificateChain - The certificate chain that should be displayed, with the end entity certificate at index 0.
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.

displayCertificateChainDetails

public static void displayCertificateChainDetails(String title,
                                                  Certificate[][] certificateChains,
                                                  KeyStore keyStore)
Since:
JDE 4.1.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.

displayCertificateChainDetails

public static void displayCertificateChainDetails(String title,
                                                  Certificate certificate,
                                                  KeyStore keyStore)
Blocks and displays a dialog box containing information about the certificate chains that can be built from the specified certificate.
Parameters:
title - The string that should be used as a title in the dialog box.
certificate - The certificate used to start building the chain
keyStore - The key store used to build the certificate chains.
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.

displayCertificateDetails

public static void displayCertificateDetails(Certificate certificate)
Blocks and displays a dialog box containing information about the specified certificate.
Parameters:
certificate - The certificate about which information to display.
Throws:
IllegalArgumentException - if certificate is null.
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.

displayCertificateDetails

public static void displayCertificateDetails(Certificate certificate,
                                             Certificate[] certificatePool,
                                             KeyStore keyStore,
                                             boolean allowFetchStatus,
                                             CertificateStatusManagerTicket ticket)
Blocks and displays a dialog box containing information about the specified certificate.

If a key store is specified, the dialog will also allow the user to display information about the certificate belonging to the issuer of this certificate.

Parameters:
certificate - The certificate about which information to display.
certificatePool - The pool of certificates that should be searched for certificates in the chain.
keyStore - The key store that will be searched for certificates in the chain.
allowFetchStatus - If set to true, the dialog will contain a button for fetching the certificate's status over the air.
ticket - A CertificateStatusManagerTicket to be used to update the certificate status if requested. If this is null, the user will be prompted for their password.

NOTE: This method was added in BlackBerry version 4.0.

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.

displayCertificateDetails

public static void displayCertificateDetails(Certificate certificate,
                                             Certificate[] certificatePool,
                                             KeyStore keyStore,
                                             CryptoSystemProperties cryptoSystemProperties,
                                             boolean allowFetchStatus,
                                             CertificateStatusManagerTicket ticket)
Blocks and displays a dialog box containing information about the specified certificate.

If a key store is specified, the dialog will also allow the user to display information about the certificate belonging to the issuer of this certificate.

Parameters:
certificate - The certificate about which information to display.
certificatePool - The pool of certificates that should be searched for certificates in the chain.
keyStore - The key store that will be searched for certificates in the chain.
cryptoSystemProperties - An object that can provide information about cryptosystems, like whether it is strong, etc.
allowFetchStatus - If set to true, the dialog will contain a button for fetching the certificate's status over the air.
ticket - A CertificateStatusManagerTicket to be used to update the certificate status if requested. If this is null, the user will be prompted for their password.
Since:
JDE 4.1.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.

displayCertificateDetails

public static void displayCertificateDetails(Certificate certificate,
                                             KeyStore keyStore)
Blocks and displays a dialog box containing information about the specified certificate.

If a key store is specified, the dialog will also allow the user to display information about the certificate belonging to the issuer of this certificate. By default, the user will also be able to fetch the certificate's status over the air.

Parameters:
certificate - The certificate about which information to display.
keyStore - The key store that will be searched for the issuer's certificate.
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.

displayCertificateDetails

public static void displayCertificateDetails(Certificate certificate,
                                             KeyStore keyStore,
                                             boolean allowFetchStatus,
                                             CertificateStatusManagerTicket ticket)
Blocks and displays a dialog box containing information about the specified certificate.

If a key store is specified, the dialog will also allow the user to display information about the certificate belonging to the issuer of this certificate.

Parameters:
certificate - The certificate about which information to display.
keyStore - The key store that will be searched for the issuer's certificate.
allowFetchStatus - If set to true, the dialog will contain a button for fetching the certificate's status over the air.
ticket - A CertificateStatusManagerTicket to be used to update the certificate status if requested. If this is null, the user will be prompted for their password.
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.

formatDistinguishedName

public static String formatDistinguishedName(DistinguishedName dn,
                                             char separator)
Replaces all spaces in provided name with provided separator characters.

Using the string representing the output of a DistinguishedName this method replaces all of the space characters with a different separator character that is passed into this method. This is useful for replacing with newline characters for example.

Parameters:
dn - Distinguished name to use for replacing the separator. This must be non-null.
separator - Separator character to use instead of spaces.
Returns:
String containing the separator in each place that a space is found after the comma.
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.

getFriendlyName

public static String getFriendlyName(DistinguishedName distinguishedName)
Returns a string that contains a "friendly" name for the distinguished name of a certificate.

The friendly name created using the first present attribute in the following list, taken from the distinguished name provided as the parameter to this method:

  • The common name ( OIDs.idAtCommonName )
  • The name ( OIDs.idAtName )
  • The given name + initials + surname ( OIDs.idAtGivenName + OIDs.idAtInitials + OIDs.idAtSurname )
  • The organizational unit ( OIDs.idAtOrganizationalUnitName )
  • The organizational name ( OIDs.idAtOrganizationName )
Parameters:
distinguishedName - The specified DistinguishedName.
Returns:
A String containing the friendly name or null if no friendly name could be created.
Since:
JDE 3.7.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.

getHexAsciiString

public static String getHexAsciiString(byte[] data)
Returns a String containing the hexadecimal ASCII encoding of the given data. Spaces are inserted every 4 characters.
Parameters:
data - The specified byte buffer.
Returns:
The hexadecimal Ascii encoded string. Returns an empty string if the length of the data is 0.
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.

getHexAsciiString

public static String getHexAsciiString(byte[] data,
                                       int offset,
                                       int length)
Returns a String containing the hexadecimal ASCII encoding of the given data. Spaces are inserted every 4 characters.
Parameters:
data - The specified byte buffer.
offset - The starting position of the data in the array.
length - The length of the data in the array.
Returns:
The hexadecimal Ascii string. Returns an empty string if the length of the data or the length parameter is 0.
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.

getKeyUsageString

public static String getKeyUsageString(long keyUsage)
Returns a String that determines how the key is used.
Parameters:
keyUsage - A long that represents how the key is used.
Returns:
A String representing the key usage type or null if the keyUsage is not supported.
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.

getSubjectFriendlyName

public static String getSubjectFriendlyName(Certificate certificate)
Returns a string that contains a "friendly" name for the subject of this certificate.

The friendly name created using the first present attribute in the following list, taken from the subject distinguished name:

  • Common name ( OIDs.idAtCommonName )
  • Name ( OIDs.idAtName )
  • Given name + initials + surname ( OIDs.idAtGivenName + OIDs.idAtInitials + OIDs.idAtSurname )
  • Organizational unit ( OIDs.idAtOrganizationalUnitName )
  • Organizational name ( OIDs.idAtOrganizationName )
Parameters:
certificate - The specified certificate.
Returns:
A String containing the friendly name or null if no friendly name could be created.
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.

isCertificateChainTrusted

public static boolean isCertificateChainTrusted(Certificate[] chain,
                                                KeyStore trustedKeyStore)
Deprecated. This method evaluates the certificate chain based only on whether it is trusted. Since there are many other criteria by which chains may be evaluated (e.g. revocation status, time validity, etc) and since these other criteria may affect the choice of the "best" chain, it is recommended that all of the chains be built first, and the best chain be selected using the methods in CertificateChainProperties.

Determines if the chain is trusted.

Returns true if the certificate chain contains some certificate in the trusted key store, and false otherwise. Note that this function does not verify signatures, check revocation statuses, or check the validity of any of the certificates in the chain.

Parameters:
chain - The specified certificate chain. Must be non null, with at least one certificate in the chain. Note that the end entity certificate must appear at array index [0].
trustedKeyStore - The trusted key store.
Returns:
True if the certificate chain is trusted and false otherwise.
Since:
JDE 3.6.0
See Also:
CertificateChainProperties
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.

isCertificateTrusted

public static boolean isCertificateTrusted(Certificate certificate,
                                           Certificate[] pool,
                                           KeyStore keyStore,
                                           KeyStore trustedKeyStore)
Deprecated. This method evaluates the certificate based only on whether it is trusted. Since there are many other criteria by which chains may be evaluated (e.g. revocation status, time validity, etc) and since these other criteria may affect the choice of the "best" chain, it is recommended that all of the chains be built first, and the best chain be selected using the methods in CertificateChainProperties.

Determines if this certificate is trusted by trying to build a chain into the trustedKeyStore.

The pool and keyStore, if provided, help to find intermediate certificates in the chain to the trusted key store.

Note: This function does not verify signatures, revocation status, or validity of any of the certificates in the chain.

Parameters:
certificate - The certificate to check.
pool - A certificate array of potential members in the certificate chain. Can be null.
keyStore - A key store to try and find potential members of the certificate chain. Can be null.
trustedKeyStore - The trusted key store.
Returns:
True if the certificate is trusted and false otherwise.
Since:
JDE 3.6.0
See Also:
CertificateChainProperties
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.

isCertificateTrusted

public static boolean isCertificateTrusted(Certificate certificate,
                                           KeyStore trustedKeyStore)
Deprecated. This method evaluates the certificate based only on whether it is trusted. Since there are many other criteria by which chains may be evaluated (e.g. revocation status, time validity, etc) and since these other criteria may affect the choice of the "best" chain, it is recommended that all of the chains be built first, and the best chain be selected using the methods in CertificateChainProperties.

Determines if this certificate is trusted by trying to build a chain into the trustedKeyStore.

Note that this function does not verify signatures, check revocation statuses, or check the validity of any of the certificates in the chain.

Parameters:
certificate - The certificate to check.
trustedKeyStore - The trusted key store.
Returns:
True if the certificate is trusted and false otherwise.
Since:
JDE 3.6.0
See Also:
CertificateChainProperties
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.

readCertificateFile

public static Certificate readCertificateFile(String type,
                                              byte[] data)
Parses out a .cer, .crt and other certificate types file and returns the certificate that was found in the file.

If anything goes wrong this method will catch the exceptions and simply return null indicating that there was either no data or a corrupted certificate file.

Parameters:
type - String representing the type of the certificate. This allows us give the code a little bit of a hint as to what type of certificate to expect. Expected values are null, "X509", or "WTLS". If the value of type is null then it will attempt to parse out the certificate as both X509 and WTLS to see if one of them works.
data - the byte[] containing the file contents.
Returns:
Certificate found in the data stream. Note that this may return null.
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.

selectCertificate

public static int selectCertificate(RichTextField descriptionField,
                                    String[] names,
                                    Certificate[] certificates,
                                    KeyStore keyStore)
Displays a dialog prompting the user to select a certificate from the list of certificates provided.

The user is given the option to press v to view any of the certificates. The user is also given the choice to cancel out of the dialog. The certificate at index 0 gets selected by default when the dialog first gets displayed.

Parameters:
descriptionField - A field that will be inserted at the top of the dialog. This field should describe the reason the user is selecting a certificate.
names - An array of strings containing the names of the certificates that you want to show the user. These could be the DNs of the certificates, the labels of the key store data or something else.
certificates - An array of Certificate objects that contain the certificates that you are considering using.
keyStore - A keystore that will be used to display the certificate details for any of the certificates provided. Providing the keystore, allows the certificate display dialog to show information about the issuer of the certificate. This parameter may be null.
Returns:
An integer representing the index into the data array of the certificate that was selected by the user. If the user selects cancel, -1 is returned.
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.

selectCertificate

public static int selectCertificate(RichTextField descriptionField,
                                    String[] names,
                                    Certificate[] certificates,
                                    KeyStore keyStore,
                                    KeyStore trustedKeyStore)
Displays a dialog prompting the user to select a certificate from the list of certificates provided.

The user is given the option to press v to view any of the certificates. The user is also given the choice to cancel out of the dialog. The certificate at index 0 gets selected by default when the dialog first gets displayed.

Parameters:
descriptionField - A field that will be inserted at the top of the dialog. This field should describe the reason the user is selecting a certificate.
names - An array of strings containing the names of the certificates that you want to show the user. These could be the DNs of the certificates, the labels of the key store data or something else.
certificates - An array of Certificate objects that contain the certificates that you are considering using.
keyStore - A keystore that will be used to display the certificate details for any of the certificates provided. Providing the keystore, allows the certificate display dialog to show information about the issuer of the certificate. This parameter may be null.
trustedKeyStore - A keystore that will be used to include trust information when determining which icon to display for each certificate in the dialog. This parameter may be null.
Returns:
An integer representing the index into the data array of the certificate that was selected by the user. If the user selects cancel, -1 is returned.
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.

selectCertificate

public static int selectCertificate(RichTextField descriptionField,
                                    String[] names,
                                    Certificate[] certificates,
                                    KeyStore keyStore,
                                    KeyStore trustedKeyStore,
                                    CryptoSystemProperties cryptoSystemProperties)
Displays a dialog prompting the user to select a certificate from the list of certificates provided.

The user is given the option to press v to view any of the certificates. The user is also given the choice to cancel out of the dialog. The certificate at index 0 gets selected by default when the dialog first gets displayed.

Parameters:
descriptionField - A field that will be inserted at the top of the dialog. This field should describe the reason the user is selecting a certificate.
names - An array of strings containing the names of the certificates that you want to show the user. These could be the DNs of the certificates, the labels of the key store data or something else.
certificates - An array of Certificate objects that contain the certificates that you are considering using.
keyStore - A keystore that will be used to display the certificate details for any of the certificates provided. Providing the keystore, allows the certificate display dialog to show information about the issuer of the certificate. This parameter may be null.
trustedKeyStore - A keystore that will be used to include trust information when determining which icon to display for each certificate in the dialog. This parameter may be null.
cryptoSystemProperties - An object that can provide information about cryptosystems, like whether it is strong, etc.
Returns:
An integer representing the index into the data array of the certificate that was selected by the user. If the user selects cancel, -1 is returned.
Since:
JDE 4.1.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.

selectCertificates

public static int[] selectCertificates(RichTextField descriptionField,
                                       String[] names,
                                       Certificate[] certificates,
                                       int[] selectedCertificates,
                                       KeyStore keyStore)
This method displays a dialog prompting the user to select a group of certificates from the list of certificates provided.

The user is given the option to press v to view any of the certificates. The user is also given the choice to cancel out of the dialog.

Parameters:
descriptionField - A field that will be inserted at the top of the dialog. This field should describe the reason the user is selecting certificates.
names - An array of strings containing the names of the certificates that you want to show the user. These could be the DNs of the certificates, the labels of the key store data or something else.
certificates - An array of Certificate objects that contain the certificates that you are considering using.
keyStore - A keystore that will be used to display the certificate details for any of the certificates provided. Providing the keystore, allows the certificate display dialog to show information about the issuer of the certificate. This parameter may be null.
selectedCertificates - An array of indicies ( within the data array ) which indicate which certificates are to be selected by default when the dialog first gets displayed. If this parameter is null, no certificates are selected when the dialog first gets displayed.
Returns:
An integer array representing the indicies ( within the data array ) that was selected by the user. Returns null if the user selected cancel. Returns an empty array if no certificates were selected.
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.

selectCertificates

public static int[] selectCertificates(RichTextField descriptionField,
                                       String[] names,
                                       Certificate[] certificates,
                                       int[] selectedCertificates,
                                       KeyStore keyStore,
                                       KeyStore trustedKeyStore)
This method displays a dialog prompting the user to select a group of certificates from the list of certificates provided.

The user is given the option to press v to view any of the certificates. The user is also given the choice to cancel out of the dialog.

Parameters:
descriptionField - A field that will be inserted at the top of the dialog. This field should describe the reason the user is selecting certificates.
names - An array of strings containing the names of the certificates that you want to show the user. These could be the DNs of the certificates, the labels of the key store data or something else.
certificates - An array of Certificate objects that contain the certificates that you are considering using.
selectedCertificates - An array of indicies ( within the data array ) which indicate which certificates are to be selected by default when the dialog first gets displayed. If this parameter is null, no certificates are selected when the dialog first gets displayed.
keyStore - A keystore that will be used to display the certificate details for any of the certificates provided. Providing the keystore, allows the certificate display dialog to show information about the issuer of the certificate. This parameter may be null.
trustedKeyStore - A keystore that will be used to include trust information when determining which icon to display for each certificate in the dialog. This parameter may be null.
Returns:
An integer array representing the indicies ( within the data array ) that was selected by the user. Returns null if the user selected cancel. Returns an empty array if no certificates were selected.
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.

selectCertificates

public static int[] selectCertificates(RichTextField descriptionField,
                                       String[] names,
                                       Certificate[] certificates,
                                       int[] selectedCertificates,
                                       KeyStore keyStore,
                                       KeyStore trustedKeyStore,
                                       CryptoSystemProperties cryptoSystemProperties)
This method displays a dialog prompting the user to select a group of certificates from the list of certificates provided.

The user is given the option to press v to view any of the certificates. The user is also given the choice to cancel out of the dialog.

Parameters:
descriptionField - A field that will be inserted at the top of the dialog. This field should describe the reason the user is selecting certificates.
names - An array of strings containing the names of the certificates that you want to show the user. These could be the DNs of the certificates, the labels of the key store data or something else.
certificates - An array of Certificate objects that contain the certificates that you are considering using.
selectedCertificates - An array of indicies ( within the data array ) which indicate which certificates are to be selected by default when the dialog first gets displayed. If this parameter is null, no certificates are selected when the dialog first gets displayed.
keyStore - A keystore that will be used to display the certificate details for any of the certificates provided. Providing the keystore, allows the certificate display dialog to show information about the issuer of the certificate. This parameter may be null.
trustedKeyStore - A keystore that will be used to include trust information when determining which icon to display for each certificate in the dialog. This parameter may be null.
cryptoSystemProperties - An object that can provide information about cryptosystems, like whether it is strong, etc.
Returns:
An integer array representing the indicies ( within the data array ) that was selected by the user. Returns null if the user selected cancel. Returns an empty array if no certificates were selected.
Since:
JDE 4.1.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.

selectCertificates

public static int[] selectCertificates(RichTextField descriptionField,
                                       String[] names,
                                       Certificate[] certificates,
                                       KeyStore keyStore)
This method displays a dialog prompting the user to select a group of certificates from the list of certificates provided.

The user is given the option to press v to view any of the certificates. The user is also given the choice to cancel out of the dialog. No certificates are selected when the dialog first gets displayed.

Parameters:
descriptionField - A field that will be inserted at the top of the dialog. This field should describe the reason the user is selecting certificates.
names - An array of strings containing the names of the certificates that you want to show the user. These could be the DNs of the certificates, the labels of the key store data or something else.
certificates - An array of Certificate objects that contain the certificates that you are considering using.
keyStore - A keystore that will be used to display the certificate details for any of the certificates provided. Providing the keystore, allows the certificate display dialog to show information about the issuer of the certificate. This parameter may be null.
Returns:
An integer array representing the indicies ( within the data array ) that was selected by the user. Returns null if the user selected cancel. Returns an empty array is no certificates were selected.
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.

verifyCertificateChain

public static boolean verifyCertificateChain(Certificate[] chain,
                                             KeyStore trustedKeyStore,
                                             long date)
                                      throws CertificateVerificationException,
                                             CertificateChainTooLongException,
                                             CertificateRevokedException,
                                             CertificateInvalidException,
                                             DecodeException,
                                             InvalidSignatureEncodingException,
                                             NoSuchAlgorithmException,
                                             CryptoTokenException,
                                             CryptoUnsupportedOperationException,
                                             InvalidCryptoSystemException
Verifies the signatures of the certificates in a chain.

The last known on-device status of each certificate is checked as the signatures are verified. The function returns normally if every signature verifies properly, and no certificate in the chain is known to be revoked.

Parameters:
chain - The chain of certificates to be verified. Must be non null and contain at least one certificate. Note that the end entity certificate must appear at array index [0].
trustedKeyStore - A keyStore that contains keys that the user trusts.
date - The date of the signature.
Returns:
True if a certificate in the chain was contained in trustedKeyStore, and false if no certificate in the chain was contained in trustedKeyStore.
Throws:
CertificateVerificationException - Thrown if a signature on a certificate in the chain did not verify properly
CertificateChainTooLongException - Thrown if the chain is longer than allowed by the CA's path length constraint, as defined in the Basic Constraints Extension
CertificateRevokedException - Thrown if a certificate in the chain is known to be revoked
CertificateInvalidException - Thrown if a certificate in the chain is not valid (ie. it has expired or it has not yet become valid).
DecodeException - Thrown if an error occurs while decoding the certificate.
InvalidSignatureEncodingException - Thrown if a signature is encoded incorrectly.
NoSuchAlgorithmException - Thrown if the specified algorithm is invalid.
CryptoTokenException - Thrown if an error occurs with the crypto token or the crypto token is invalid.
CryptoUnsupportedOperationException - Thrown if a call is made to an unsupported operation.
InvalidCryptoSystemException - Thrown if the specified crypto system is invalid.
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.



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.