Creating or Obtaining an SSL Key and Certificate

You can get your own private key and SSL certificate in the following ways:

• Your organization may already have a private key and SSL certificate, so first try requesting the private key and SSL certificate from your IT, network, or security team.  When you have your organization's private key and SSL certificate, you can skip ahead to the instructions on replacing HipChat Server's key and self-signed certificate with your organization's private key and SSL certificate.
• If your organization doesn't have a private key and SSL certificate, follow the steps in the next section, Generating a private key and CSR to get an SSL certificate.

Generating a private key and CSR to get an SSL certificate

If your organization doesn't already have a private key and SSL certificate, follow the instructions in this section. It explains how to generate your own private key and a certificate signing request (CSR), which you can then use to get an SSL certificate.

1. Generate a private key.
2. Generate a certificate signing request (CSR).  
3. Send the CSR to a certificate authority (CA), who will then send you an SSL certificate. (You can search online for a CA.)
4. When you have your SSL certificate, replace HipChat Server's default private key and self-signed certificate with your own. 

Generating a private key

If you don't already have a private key, you can generate your own private key using openssl.

1. Access the command line interface (CLI):
   • If you deployed HipChat Server using an open archive (OVA) file, open your virtual machine's console. 
   • If you deployed HipChat Server using an Amazon machine image (AMI), open a command line interface (CLI) and type:
     ssh admin@hipchat.example.com
     where hipchat.example.com is your fully qualified domain name (FQDN) (Or, you can use the HipChat Server's IP address.)
2. To generate the private key, run the following command:
   openssl genrsa -out <fqdn>.key 2048
   where fqdn is your fully qualified domain name, such as hipchat.example.com
   This command outputs your new private key, for example, hipchat.example.com.key.
3. To download the private key from the server to to your local machine's current directory, run the following commands:
   scp admin@fqdn.com/fqdn.key .
where fqdn is your fully qualified domain name, such as hipchat.example.com 
   Note: If you deployed using an Amazon machine image (AMI), use the -i option to provide your private ssh key.
   Note: You can also run the command less fqdn.key  to view, then copy your private key.
4. Enter HipChat Server's ssh password when prompted. 
5. Save your private key in a safe place. We recommend you use a secure password manager, like KeePass.
   
6. Follow the steps in the next section to generate a CSR.

Generating a CSR

1. Access the command line interface (CLI):
   • If you deployed HipChat Server using an open archive (OVA) file, open your virtual machine's console. 
   • If you deployed HipChat Server using an Amazon machine image (AMI), open a command line interface (CLI) and type:
     ssh admin@hipchat.example.com
     where hipchat.example.com is your fully qualified domain name (FQDN) (Or, you can use the HipChat Server's IP address.) 
2. Run the following command:
openssl req -new -key <fqdn>.key -out <fqdn>.csr   
   where <fqdn>.key is the private key you generated in the previous section and fqdn is your fully qualified domain name, such as hipchat.example.com 
3. Answer the questions that appear on the screen.
   Note: Some CA's web parsing tools do not accept a CSR with the email address field or other optional fields included.
4. If you deployed HipChat Server using an open archive (OVA) file:
   1. To download the CSR from the server to to your local machine's current directory, run the following command:
      scp admin@fqdn.com/fqdn.csr .
      where fqdn is your fully qualified domain name, such as hipchat.example.com 
      Note: You can also run the command less fqdn.csr to view, then copy your CSR.
   2. Enter HipChat Server's SSH password when prompted. 
5. If you deployed HipChat Server using an Amazon machine image (AMI), run:
    scp -i path/to/aws.key admin@fqdn.com/fqdn.csr
   where fqdn is your fully qualified domain name, such as hipchat.example.com and aws.key is HipChat Server's SSH password
   Note: You can also run the command less fqdn.csr to view, then copy your CSR.
6. Save your CSR in a safe place. 
7. Send your CSR to a certificate authority (CA), who creates the SSL certificate for you. (You can search online for a CA.)
8. When you have your certificate, replace HipChat Server's default private key and self-signed certificate with your own. 

Replacing HipChat Server's default key and self-signed certificate

Once you have your own private key and signed certificate, you can replace HipChat Server's default private key and self-signed certificate with yours.

1. In a text editor, concatenate your private key and SSL certificate in the following format: 

    -----BEGIN CERTIFICATE-----  
   (Primary SSL certificate: your_domain_name.crt)  
   -----END CERTIFICATE----- 
   -----BEGIN CERTIFICATE-----  
   (All required intermediate certificate files: intermediates.crt)    
   -----END CERTIFICATE-----  
   -----BEGIN PRIVATE KEY-----  
   (The private key you generated: fqdn.key)  
   -----END PRIVATE KEY-----

2. Save the file using the following filename format: your_domain_name.pem 
   Note: A .pem file is just a Base64-encoded .der file.
3. Copy the text of your .pem file.
4. Log into HipChat Server using HipChat Server's fully qualified domain name (for example, https://hipchat.example.com) or HipChat Server's IP address (for example, https://IPv4).
5. Click Server admin > SSL.
6. Paste the text in the field provided.
7. Click Modify.
   Note: Services are restarted with the new private key and SSL certificate. They can take a few minutes to restart. After they restart, you should see a lock symbol next to HipChat Server's url in your browser. (If you don't see the lock symbol, then the SSL certificate is not trusted by the browser. Check your private key and SSL certificates in your .pem file to ensure they're correct.)
8. Click the lock symbol to verify that the new certificate is active. If it's active, you will see it trusted by your browser with the SSL details showing your certificate's Common Name and Organization.

Viewing the current private key and SSL certificate

You can view the key and certificate that is currently configured for HipChat Server from HipChat Server's web UI.

1. Log into HipChat Server using HipChat Server's fully qualified domain name (for example, https://hipchat.example.com) or HipChat Server's IP address (for example, https://IPv4).
2. Click Server admin > SSL.
   Note: This doesn't show the self-signed certificate that is included with HipChat Server.

You can also type the following command in the CLI:

1. Access the command line interface (CLI):
   If you deployed HipChat Server using an open archive (OVA) file, open your virtual machine's console. 
   If you deployed HipChat Server using an Amazon machine image (AMI), open a command line interface (CLI) and type:
   ssh admin@hipchat.example.com
   where hipchat.example.com is your fully qualified domain name (FQDN) (Or, you can use the HipChat Server's IP address.)
2. Type the following command:
   hipchat ssl --show
Note: This command does show the self-signed certificate included with HipChat Server.

Installing SSL certificates for integrations

If you're integrating other applications with HipChat Server, you may need to install SSL certificates from other certificate authorities (CAs) for the integrations.

1. Copy your integration's SSL certificate files to the following directory:
   /usr/local/share/ca-certificates 

2. Run the following commands to update your SSL certificates:
   sudo update-ca-certificates
hipchat service --restart 
   Services are restarted with the new SSL certificates. 

Tips for Ubuntu Desktop users

If you're using Ubuntu Desktop and the HipChat Linux Client, you can use the following commands when you need to update the trusted root CA certificates (and any intermediate certificates) to connect to HipChat Server:

/etc/ssl/certs				# the major default certificates (.crt)

/usr/local/share/ca-certificates	# user imported certificates

copy or create /usr/local/share/ca-certificates/MyNewCA.crt

sudo update-ca-certificates

Troubleshooting

Many certificate issues arise from badly formed pem files. Try the following:

1. Create the pem file, again. Ensure you preserve line returns.
2. Log in to HipChat Server using HipChat Server's fully qualified domain name (for example, https://hipchat.example.com) or HipChat Server's IP address (for example, https://IPv4).
3. Click Server admin > SSL.
4. Paste the key and certificate text in the field provided.
5. Click Modify.

If the web user interface cannot be accessed within ten minutes of installing an SSL certificate or key, revert to the self-signed certificate.

Reverting to a self-signed certificate

If you're having issues with the private key or SSL certificate you installed, you can revert to a self-signed certificate.

To generate and activate a new self-signed certificate, run the following command:

hipchat ssl --selfsign

The self signed certificate has a CommonName equal to the current FQDN of HipChat Server.