How to replace a self-signed SSL certificate with a custom certificate after the installation of BlackBerry Administration Service

Article ID: KB12887

Type: Support Content

Last Modified: 04-02-2014

 

Product(s) Affected:

  • BlackBerry Web Desktop Manager
  • BlackBerry Enterprise Server for Microsoft Exchange
  • BlackBerry Enterprise Server for IBM Domino
  • BlackBerry Enterprise Server for Novell GroupWise
CollapseEnvironment
  • BlackBerry Enterprise Server 5.0 to 5.0 SP4
  • BlackBerry Administration Service
  • BlackBerry Web Desktop Manager
  • Windows
CollapseOverview

Log into the server as the BlackBerry Enterprise Server service account and complete the following tasks to replace the self-signed Secure Socket Layer (SSL) certificate used by the BlackBerry Administration Service and the BlackBerry Web Desktop Manager with a custom certificate (such as one from VeriSign or from a Windows certificate authority):

Note:

  • If the environment has multiple BlackBerry Administration Service nodes in a BAS Pool, do not follow this document and instead refer to KB20759.
  • There are two types of certificates referenced, the CACert.cer and the BASCert.cer. The CACert.cer refers to the Root and any Intermediate certificates that are provided by the Certificate Authority. The BASCert.cer is the certificate that is requested from the certificate authority for the BlackBerry Administration Service.

Task 1 - Back up the web.keystore file

Note: Do not remove or rename the existing web.keystore file.

  1. Browse to the appropriate path:

    • For 32-bit operating systems:
      C:\Program Files\Research In Motion\BlackBerry Enterprise Server\bas\bin\web.keystore
       
       
    • For 64-bit operating systems:
      C:\Program Files (x86)\Research In Motion\BlackBerry Enterprise Server\bas\bin\web.keystore
  2. Right-click on web.keystore  and select Copy.
  3. Right-click on a blank space in this folder and select Paste.
  4. Rename the copy of web.keystore to web.keystore.OLD.

Task 2 - Delete the self-signed SSL certificate

  1. On the task bar, click Start > All Programs > Accessories > Command Prompt.  
  2. Change the directory to the bin folder for the appropriate version of the Java Runtime Environment (JRE).

    For example:
     
    • For 32-bit operating systems:
      C:\Program Files\Java\jrex.x.x_xx\bin
       
       
    • For 64-bit operating systems:
      C:\Program Files (x86)\Java\jrex.x.x_xx\bin
       

  3. Type the appropriate command line:
     
    • For 32-bit operating systems:
      keytool
      -delete -alias httpssl -keystore "C:\Program Files\Research In Motion\BlackBerry Enterprise Server\bas\bin\web.keystore"
       
    • For 64-bit operating systems:
      keytool -delete -alias httpssl -keystore "C:\Program Files (x86)\Research In Motion\BlackBerry Enterprise Server\bas\bin\web.keystore"

Task 3 - Generate the BlackBerry Administration Service certificate key pair

Type the appropriate command line:

    • For 32-bit operating systems:
      keytool -genkey -alias httpssl -keystore "C:\Program Files\Research In Motion\BlackBerry Enterprise Server\bas\bin\web.keystore" -storepass "<password>" -dname "CN=<BAS Server or BAS Pool full name>, OU=BAS, O=Company, L=City, ST=ST, C=US"
       
    • For 64-bit operating systems:
      keytool -genkey -alias httpssl -keystore "C:\Program Files (x86)\Research In Motion\BlackBerry Enterprise Server\bas\bin\web.keystore" -storepass "<password>" -dname "CN=<BAS Server or BAS Pool full name>, OU=BAS, O=Company, L=City, ST=ST, C=US"

Note: Some Certificate Authority (CA) servers require RSA encryption of the certificate request. If this is the case, add -keyalg RSA to this keytool command. Also, the keyalg RSA switch defaults to 1024 as a keysize. For environments that require 2048 as a keysize, use the -keysize 2048 command switch. e.g. -keyalg RSA -keysize 2048

Note: Replace <password> with the web.keystore password. The double quotes (") are required.

IMPORTANT: After following this step, the web.keystore file now contains a private key entry. This exact private key must be matched with the reply generated from the Certificate Authority below in order for this process to succeed. It is highly recommended that the web.keystore file be backed up after this step has been performed, so that this private key is retained. If this is not done, and any of the following steps are not successful, then it will be necessary to clear out the keystore and start again from Task 1. This is especially important to note for environments with manual certificate request processes.

Task 4 - Generate a certificate request to the certification authority

  1. Type the appropriate command line:
     
    • For 32-bit operating systems:
      keytool -certreq -alias httpssl -keystore "C:\Program Files\Research in Motion\BlackBerry Enterprise Server\BAS\bin\web.keystore" -file "C:\certreq.csr"
       
    • For 64-bit operating systems:
      keytool -certreq -alias httpssl -keystore "C:\Program Files (x86)\Research in Motion\BlackBerry Enterprise Server\BAS\bin\web.keystore" -file "C:\certreq.csr"

      Note: If the -keyalg switch was used in Task 3 for a CA that requires RSA encryption, it is recommended to also use it here. Also, the -keyalg RSA switch defaults to 1024 as a keysize. For environments that require 2048 as a keysize, use the -keysize 2048 command switch. e.g. -keyalg RSA -keysize 2048
  2. When prompted, enter the keystore password.

Task 5 - Request the certificate from the certificate authority (CA)

Note: The steps in this task are based on the steps required to request a certificate from a Windows certificate authority. If requesting a certificate from a third-party certificate authority, see the information in the Additional Information section. Domain administrator permission is required to complete this task.

  1. Log off the server as the BlackBerry Enterprise Server service account.
  2. Log into the server with a domain account with domain administrator permissions.
  3. Browse to the organization's certificate server using Windows Internet Explorer.
  4. Click Request a certificate.
  5. Click Advanced certificate request.
  6. Click Submit a certificate request by using a base-64-encoded CMC or PKCS #10 file, or submit a renewal request by using a base-64-encoded PKCS#7 file.
  7. Paste the full contents of the certreq.csr file into the Saved Request field.
  8. Choose Web Server from the Certificate Template drop-down list.
  9. Click Submit.
  10. Click Download certificate.
  11. Save the file to C:\bascert.cer when prompted.

    Note: If the error The certificate is not valid for the requested usage appears, choose Subordinates Certification Authority from the Certificate Template drop-down list instead of Web Server.

Task 6 - Download the CA certificate from the certificate authority

  1. Browse to the organization's certificate server using Windows Internet Explorer.
  2. Click Download a CA Certificate, certificate chain, or CRL.
  3. Click Download CA Certificate.
  4. Save the file to C:\CAcert.cer when prompted.

Task 7 - Import the CA certificate into the BlackBerry Administration Service key store

  1. Log off the server as the domain account used in Task 5 and Task 6 above to request the certificate from the certificate authority (CA).
  2. Log onto the server as BlackBerry Enterprise Server service account.
  3. In the command prompt window used in Task 2, type:

    • For 32-bit operating systems:
      keytool -import -alias cacert -keystore "C:\Program Files\Research in Motion\BlackBerry Enterprise Server\BAS\bin\web.keystore" -file "C:\CAcert.cer"
       
    • For 64-bit operating systems:
      keytool -import -alias cacert -keystore "C:\Program Files (x86)\Research in Motion\BlackBerry Enterprise Server\BAS\bin\web.keystore" -file "C:\CAcert.cer"
  4. Enter the key store password, and then enter yes when asked to trust this certificate.
  5. If the BlackBerry Administration Service certificate is issued by an Intermediate CA, perform steps 1 and 2 to import certificates of every Intermediate CA in the certificate chain. Use a unique alias name for every imported certificate.

Task 8 - Import the BlackBerry Administration Service certificate to the BlackBerry Administration Service key store

In the command prompt window used in Task 7, type:

  • For 32-Bit operating systems:
    keytool -import -alias httpssl -keystore "C:\Program Files\Research in Motion\BlackBerry Enterprise Server\BAS\bin\web.keystore" -file "C:\bascert.cer"
     
  • For 64-bit operating systems:
    keytool -import -alias httpssl -keystore "C:\Program Files (x86)\Research in Motion\BlackBerry Enterprise Server\BAS\bin\web.keystore" -file "C:\bascert.cer"

Task 9 - Restart the BlackBerry Administration Service

CollapseAdditional Information

Visit http://java.sun.com for more information on the keytool command line tool.

If the certificate authority requires an RSA type of certificate request, use -keyalg RSA in the keytool command. See the following example:

keytool.exe -certreq -alias httpssl -keyalg RSA -keystore "C:\Program Files\Research in Motion\BlackBerry Enterprise Server\BAS\bin\web.keystore" -file "C:\certreq.csr"

For more information on the use of SSL certificates on multiple BlackBerry Administration Services using Subject Alternative Names, see KB20759.

If the BlackBerry Administration Service is installed on a separate partition, it may be necessary to copy the keytool used in the generation of the pair to the same partition of the BlackBerry Administration Service Installation. Running the tool from a separate partition may alter the expiration date of the certificate.

For third-party certificate authorities, such as Verisign, it may be necessary to import Root and Intermediate certificates from the certificate authority, rather than just the Root Certificate that is imported when requesting from a Windows certificate authority. If only the Intermediate certificates are installed then the following error may be displayed when attempting to load the custom certificate reply file (BASCert.cer):

keytool error: java.lang.Exception: Failed to establish chain from reply

KB23492 discusses this error and the steps to acquire and install the Root certificate.

Note: The default password for the web.keystore file is changeit

Disclaimer

By downloading, accessing or otherwise using the Knowledge Base documents you agree:

   (a) that the terms of use for the documents found at www.blackberry.com/legal/knowledgebase apply to your use or reference to these documents; and

   (b) not to copy, distribute, disclose or reproduce, in full or in part any of the documents without the express written consent of RIM.


Visit the BlackBerry Technical Solution Center at www.blackberry.com/btsc.