How to replace the self-signed certificate for Universal Device Service console

Article ID: KB31084

Type: Support Content

Last Modified: 03-12-2015

 

Product(s) Affected:

  • Universal Device Service
Jump to: Environment | Overview
CollapseEnvironment
  • Universal Device Service 6.0 to 6.2
  • BlackBerry Enterprise Service 10 version 10.1 to 10.2
CollapseOverview

During the installation of the Universal Device Service, the installation process creates a self-signed certificate to support SSL communications with a web browser and the administrative console. This certificate is created following the SHA-2 security standards using Java 7. This certificate is not the same as the certificates used for the Communication or Core modules, and is also not the same as the Apple Push Notification Service certificate. This SSL certificate is stored in the Java keystore similar to other BlackBerry Administration Service console products. Administrators accessing the Universal Device Service administrative console can either import the self-signed certificate into their workstations via the browser, or administrators can choose to replace the self-signed certificate with one issued by a trusted Certificate Authority.

Some key factors to know ahead of time:

For Universal Device Service 6.0 to 6.2:

  • The Java Keytool installed with Universal Device Service 6.0 to 6.2 is located at C:\Program Files (x86)\Research In Motion\Universal Device Service\RIM.BUDS.Gui\jre\bin
  • The certificate keystore is located at : C:\Program Files (x86)\Research In Motion\Universal Device Service\RIM.BUDS.Gui\ssl
  • The keystore used to store the certificate is keystore with no extension.

For BlackBerry Enterprise Service 10 version 10.1 to 10.2:

  • The Java Keytool for BES10 version 10.1 to 10.2 is located at C:\Program Files (x86)\Java\jre1.7.0_##\bin , where ## represents the Java JRE7 update version that is installed. For this article, we will assume the Java path is C:\Program Files (x86)\Java\jre1.7.0_55\bin
  • The certificate keystore for BES10 version 10.1 to 10.2 is located (by default) at: C:\Program Files (x86)\Research In Motion\BlackBerry Enterprise Service 10\RIM.BUDS.Gui\ssl
  • The keystore used to store the certificate is keystore with no extension.

Will a completed certificate .pfx file be provided by the Certificate Authority for this console service certificate, or will a new certificate request be required from this server? This is needed for a decision in Task 2.

Additional information required:

  • These steps assume that the keystore password is password, and that the new keypair password will be password.
    • In Universal Device Service 6.0 to 6.2, the keystore password was entered during the installation of the product.
    • In BlackBerry Enterprise Service 10 version 10.1 to 10.2 environment, the keystore password is the same as the keystore password used for the BlackBerry Administration Service for the BlackBerry Device Service.
      To verify the current password for the web.keystore file:
      1. Log in to the BlackBerry Administration Service using an administrator account with the Security Administrator role
      2. On the Servers and components menu, expand BlackBerry Solution topology > BlackBerry Domain > Component view.
      3. Click BlackBerry Administration Service
      4. Check the Security settings section.
    • For this article, the keystore password ( -storepass) will be assumed to be password.
  • Requirements for a Webserver SSL certificate from the Trusted Certificate Authority will be needed (see Task 3), like Private Key Size, Key Algorithm (RSA), and Distinguished Name.

Task 1 Delete the existing Self-Signed Certificate from the keystore
Taks 2 Determine if to create a new certificate request here or receive a completed .pfx from...
Task 3 Generate a new certificate with a private key
Task 4 Generate a certificate request to be submitted to the Trusted Certificate Authority
Task 5 Submit the request to the Trusted Certificate Authority
Task 6 Import the certificates into the keystore
Task 7 Import a previously completed certificate .pfx file issued by a certificate authority
Task 8 Restart the BlackBerry services

Task 1 - Delete the existing Self-Signed Certificate from the keystore

  1. Open a Command Window as Administrator.
  2. Navigate to the folder where the certificate keystore is located.
    • For Universal Device Service 6.0 to 6.2:
      cd "C:\Program Files (x86)\Research In Motion\Universal Device Service\RIM.BUDS.Gui\ssl" 
       
    • For BlackBerry Enterprise Service 10 version 10.1 to 10.2:
      cd "C:\Program Files (x86)\Research In Motion\BlackBerry Enterprise Service 10\RIM.BUDS.Gui\ssl"
  3. Backup the keystore file. (ie: copy the file, and it is safe to keep the backup file in the same folder location)
  4. List the contents of the keystore file:
    • For Universal Device Service 6.0 to 6.2:
      ..\jre\bin\keytool.exe -list -keystore keystore -v -storepass password
       
    • For BlackBerry Enterprise Service 10 version 10.1 to 10.2: (Java path should have been confirmed in the "key factors to know ahead of time" section above)
      "c:\Program Files (x86)\Java\jre1.7.0_55\bin\keytool.exe" -list -keystore keystore -v -storepass password
  5. An example output is displayed here (obtained without the -v switch, -v is for verbose. Note the buds.gui.ks.tomcat entry is PrivateKeyEntry) :
     
    Keystore type: JKS
    Keystore provider: SUN
    Your keystore contains 2 entries
    buds.gui.sslcert, Aug 11, 2012, trustedCertEntry,
    Certificate fingerprint (SHA1): 7B:45:8F:2C:F2:FF:AF:3A:8F:8B:1E:D0:2C:12:83:3F:1D:F3:77:E0
    buds.gui.ks.tomcat, Aug 11, 2012, PrivateKeyEntry,
    Certificate fingerprint (SHA1): F4:24:8E:B7:3C:91:18:87:53:5A:8F:05:ED:F0:47:28:98:BB:BB:51
     
  6. Delete the self-signed certificate with the alias of buds.gui.ks.tomcat:
    • For Universal Device Service 6.0 to 6.2:
      ..\jre\bin\keytool.exe -delete -alias buds.gui.ks.tomcat -keystore keystore -storepass password -v
       
    •  For BlackBerry Enterprise Service 10 version 10.1 to 10.2:
      "c:\Program Files (x86)\Java\jre1.7.0_55\bin\keytool.exe" -delete -alias buds.gui.ks.tomcat -keystore keystore -storepass password -v
  7. List the keystore file to ensure it is only has one reference (for buds.gui.sslcert):
    • For Universal Device Service 6.0 to 6.2:
      ..\jre\bin\keytool.exe -list -keystore keystore -v -storepass password 
       
    •  For BlackBerry Enterprise Service 10 version 10.1 to 10.2:
      "c:\Program Files (x86)\Java\jre1.7.0_55\bin\keytool.exe" -list -keystore keystore -v -storepass password

Task 2 - Determine if to create a new certificate request here or receive a completed .pfx from the certificate authority

Proceed to Task 3 if the intention is to create a new private key locally within the Java keystore and submitting the Certificate Signing Request to the Certificate Authority.

Otherwise, obtain a .pfx file (Personal Information Exchange file, in a PKCS 12 format. Please refer to the Certificate Authority for additional information.

If a .pfx file has been obtained from the Certificate Authority, skip to Task 7.

Task 3 - Generate a new certificate with a private key

  1. Reference the Trusted Certificate Authority for settings to use here.
  2. While still in the same command window as in Task 1:
    • For Universal Device Service 6.0 to 6.2:
      ..\jre\bin\keytool.exe -genkeypair -alias buds.gui.ks.tomcat -dname "cn=fqdn_of_server.example.com, ou=OU_Info, o=UDS, l=City, s=State, c=US" -keyalg RSA -keysize 2048 -keystore keystore -storepass password -validity 180
      Enter key password for buds.gui.ks.tomcat
      (Return if same as keystore password):
       
       
    • For BlackBerry Enterprise Service 10 version 10.1 to 10.2:
      "c:\Program Files (x86)\Java\jre1.7.0_55\bin\keytool.exe" -genkeypair -alias buds.gui.ks.tomcat -dname "cn=fqdn_of_server.example.com, ou=OU_Info, o=UDS, l=City, s=State, c=US" -keyalg RSA -keysize 2048 -keystore keystore -storepass password -validity 180
      Enter key password for buds.gui.ks.tomcat
      (Return if same as keystore password):
  3. This command will prompt to enter a password for this specific key. By pressing Enter or Return, the command will use the same password for this entry as the keystore password.

Task 4 - Generate a certificate request to be submitted to the Trusted Certificate Authority

  1. Create a folder to store the certificate request and subsequent certificates for easy access (these steps assume C:\Downloads\ ).
  2. Reference the Certificate Authority for settings to use here like Key Algorithm ( -keyalg) and Key Size ( -keysize).
  3. Create the certificate request:
    • For Universal Device Service 6.0 to 6.2 :
      ..\jre\bin\keytool.exe -certreq -alias buds.gui.ks.tomcat -keystore keystore -storepass password -keyalg RSA -keysize 2048 -file "c:\Downloads\UDSGUICert.req"
       
    • For BlackBerry Enterprise Service 10 version 10.1 to 10.2:
      "c:\Program Files (x86)\Java\jre1.7.0_55\bin\keytool.exe" -certreq -alias buds.gui.ks.tomcat -keystore keystore -storepass password -keyalg RSA -keysize 2048 -file "c:\Downloads\UDSGUICert.req"

Task 5 - Submit the request to the Trusted Certificate Authority.

This process will assume an internal Microsoft Certificate Authority is being used, but the steps would be similar for other on-premise or public Certificate Authorities.

  1. Connect to the certificate authority web service via a supported web browser.
    http://domaincontroller.example.com/certsrv
  2. Click on Request a certificate
  3. Click on Advanced certificate request
  4. Click on 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
  5. Open the certificate file generated from Task 4 with Notepad.
  6. Copy the entire contents of the file except the last carriage return. Select the -- Begin -- to the -- End -- segments.
  7. Paste the contents into the available box in the browser.
  8. Select a Web Server Template from the template drop-down list.
  9. In the Additional Attributes section, add any valid Subject Alternative Names with this format (should include the name used in the CN= section of Task 3) :
    dns=udsserver.example.com&dns=fqdn_of_uds_server.example.com
    This is useful if the primary URL for the BlackBerry Mobile Fusion Studio or BlackBerry Management Studio is a DNS alias for a physical server name. It is best practices to load the first Subject Alternative Name to be the same name as the primary URL, and then load any physical server names as Fully Qualified Domain Names. Do not prefix with http.
  10. Click Submit.
  11. Save the certificate.
    1. Select DER encoded.
    2. Click Download certificate.
    3. Save the certificate as udsguicert.cer, and save to a folder easily accessible by the command window session (like C:\Downloads\).
  12. Save any root and intermediate certificate authority certificates.
    1. Click Home
    2. Click on Download a CA certificate, certificate chain, or CRL
    3. Click on Download a CA certificate
    4. Save the certificate as udsguirootcacert.cer
    5. Repeat for the entire chain.

Task 6 - Import the certificates into the keystore

  1. Locate the downloaded certificates from Task 5 and place them in an easy folder for command line access below. These steps assume that the folder is C:\Downloads\
  2. Import the Root Certificate Authority certificate into the keystore:
    • For Universal Device Service 6.0 to 6.2:
      ..\jre\bin\keytool.exe -import -alias cacert -keystore keystore -storepass password -file "c:\Downloads\udsguirootcacert.cer" 
       
    • For BlackBerry Enterprise Service 10 version 10.1 to 10.2:
      "c:\Program Files (x86)\Java\jre1.7.0_55\bin\keytool.exe" -import -alias cacert -keystore keystore -storepass password -file "c:\Downloads\udsguirootcacert.cer"
  3. When prompted to Trust this certificate, enter Yes.
  4. The response will be Certificate has been added to keystore
  5. Import any Intermediate Certificate Authority certificates into the keystore with the same command as in step 2. However, use a different alias. Sample commands would look like these:
    • For Universal Device Service 6.0 to 6.2:
      ..\jre\bin\keytool.exe -import -alias cacert2 -keystore keystore -storepass password -file "C:\Downloads\rootcacert2.cer" 
       
    • For BlackBerry Enterprise Service 10 version 10.1 to 10.2:
      "c:\Program Files (x86)\Java\jre1.7.0_55\bin\keytool.exe" -import -alias cacert2 -keystore keystore -storepass password -file "C:\Downloads\rootcacert2.cer"
  6. Import the signed certificate response to match the certificate request generated in Task 4:
    • For Universal Device Service 6.0 to 6.2:
      ..\jre\bin\keytool.exe -import -alias buds.gui.ks.tomcat -keystore keystore -storepass password -file "C:\Downloads\udsguicert.cer" 
       
    • For BlackBerry Enterprise Service 10 version 10.1 to 10.2:
      "c:\Program Files (x86)\Java\jre1.7.0_55\bin\keytool.exe" -import -alias buds.gui.ks.tomcat -keystore keystore -storepass password -file "C:\Downloads\udsguicert.cer"
  7. The response will be Certificate Reply was installed in keystore.

Note: The last response is not the same as the previous responses. When importing a regular certificate, the response is Certificate has been added to keystore. However, when importing a certificate to complete the pending certificate request, the response is Certificate Reply was installed into keystore. This ensures that the certificate is binding to the pending private key generated from Task 3.

At this point, skip to Task 8.

Task 7 - Import a previously completed certificate .pfx file issued by a certificate authority

These steps are only used if a certificate .pfx file has been provided. The .pfx needs to include a Private Key for the certificate, the alias of the certificate needs to be buds.gui.ks.tomcat, and preferably should also include the certificate chain. The .pfx file password is assumed to be password for these examples.

To make this process easier, a third party produce called Portecle can be used to open the .pfx file and make some adjustments. Otherwise, Java keytool commands can be used to rename the alias and validate the contents of the .pfx file.

  1. Copy the .pfx file to an easily accessible folder (for this example, C:\Downloads\)
  2. List the contents of the .pfx file to see the current alias value:
    keytool.exe -list -v -keystore "c:\Downloads\udsgui.pfx" -storetype pkcs12 -storepass password
    Sample response is here:
     
    Keystore type: PKCS12
    Keystore provider: SunJSSE
     
    Your keystore contains 1 entry
     
    Alias name: le-f539545c-2b4f-44a3-937e-8835968f0655
    Creation date: 12-Mar-2015
    Entry type: PrivateKeyEntry
    Certificate chain length: 3
    Certificate[1]:
    Owner: CN=UDSGUI.example.com, OU=PKI, O=Waterloo, C=CA
    Issuer: CN=Internal CA, OU=PKI, O=Waterloo, C=CA
    Serial number: 2bc52
     
    Note : the alias here is le-f539545c-2b4f-44a3-937e-8835968f0655, that this is a PrivateKeyEntry, and that there are additional certificates in the chain included in the .pfx file.
     
  3. Rename the alias to buds.gui.ks.tomcat.
    keytool.exe -changealias -alias "le-f539545c-2b4f-44a3-937e-8835968f0655" -destalias buds.gui.ks.tomcat -keystore "c:\Downloads\udsgui.pfx" -storetype pkcs12 -storepass password 
     
  4. To verify the alias change:
     
    keytool.exe -list -keystore "c:\Downloads\udsgui.pfx" -storetype pkcs12 -storepass password
    Keystore type: PKCS12
    Keystore provider: SunJSSE
     
    Your keystore contains 1 entry
     
    buds.gui.ks.tomcat, 12-Mar-2015, PrivateKeyEntry,
    Certificate fingerprint (SHA1): FF:91:28:A5:F5:4D:40:E2:8E:AD:96:21:F8:59:63:FB:BA:EA:AE:14
     
  5. Import the .pfx file contents into keystore. Assumptions here are that the .pfx file's password is password and the keystore password is also password.
     
    "C:\Program Files (x86)\Java\jre1.7.0_55\bin\keytool.exe" -destkeystore keystore -deststoretype JKS -storepass password -v -importkeystore -srckeystore "C:\Downloads\udsgui.pfx" -srcstoretype PKCS12 -srcstorepass password
    Entry for alias buds.gui.ks.tomcat successfully imported.
    Import command completed: 1 entries successfully imported, 0 entries failed or cancelled
    [Storing keystore]
  6. Verify the contents of the keystore:
     
    "C:\Program Files (x86)\Java\jre1.7.0_55\bin\keytool.exe" -list -v -keystore keystore -storepass password
     
    Keystore type: JKS
    Keystore provider: SUN
     
    Your keystore contains 2 entries
     
    Alias name: buds.gui.sslcert
    Creation date: 3-Oct-2014
    Entry type: trustedCertEntry
     
    *******************************************
    *******************************************
     
    Alias name: buds.gui.ks.tomcat
    Creation date: 27-Feb-2015
    Entry type: PrivateKeyEntry
    Certificate chain length: 3
    Certificate[1]:
    Owner: CN=UDSGUI.example.com, OU=PKI, O=Waterloo, C=CA
    Issuer: CN=Internal CA, OU=PKI, O=Waterloo, C=CA
    Serial number: 2bc52
     
  7. Continue to Task 8.

Task 8 - Restart the BlackBerry services

For Universal Device Service 6.0 to 6.2:
  1. Open the Services applet.
  2. Locate the service BlackBerry Administration Console.
  3. Right-click on BlackBerry Administration Console service and select Stop.
  4. Right-click on BlackBerry Scheduler service and select Stop.
  5. Right-click on BlackBerry Web Services service and select Stop.
  6. Start these same services in order.
For BlackBerry Enterprise Service 10 version 10.1 to 10.2:
  1. Open the Services applet.
  2. Locate the service BES10 - Administration Console.
  3. Right-click on BES10 - Administration Console service and select Stop.
  4. Right-click on BES10 - Scheduler service and select Stop.
  5. Right-click on BES10 - BlackBerry Web Services service and select Stop.
  6. Right-click on BES10 - BlackBerry Secure Connect Service service and select Stop.
  7. Right-click on BES10 - BlackBerry Work Connect Notification Service service and select Stop.
  8. Start these same services in order. 

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.