Enable SSL on Blackboard Academic Suite

Secure Sockets Layer (SSL) is a protocol for protecting Internet communications. SSL ensures that a communication is not read or changed by another entity. The Blackboard Academic Suite uses SSL to secure all or some communications between the Web server and the client machine.

How does SSL work?

SSL works through public key encryption. Transmissions are decrypted and encrypted using certificates. The steps below outline the process for establishing a connection over SSL:

1. Client contacts the server with a list of encryption methods.
2. The Server returns its certificate and a public key. These initial communications are scrambled with random data.
3. Client validates the certificate.
4. Client creates a secret string using an encryption method recognised by both the client and the server. The string is combined with the server’s public key and sent back to the server.
5. Both the client and server create session keys based on the secret string.
6. The client sends a message to the server that it will now use the session key to encrypt and decrypt communications.
7. The server responds that it will also use the session key.
8. After each side confirms, the session keys are used to encrypt and decrypt communications during the session.

How to obtain a certificate?

The simplest way to obtain a certificate for use with a Web site is through a vendor known as a Certifying Authority (CA). The process is relatively simple.

1. Generate a certificate request.
2. Send the request to a CA.
3. The CA creates and registers a certificate.
4. Make this certificate available to the Web Server (IIS or Apache).

Configuring SSL for Apache

1. Login to the Web/Application server as root.
2. Set the PATH to include the OpenSSL provided by Blackboard with the following commands:
PATH=/usr/local/blackboard/apps/openssl/bin:$PATH
export PATH
3. Generate your own Certifying Authority (CA) using the following commands.
openssl genrsa -des3 -out ca.key 4096

Generating RSA private key, 4096 bit long modulus
When prompted for a pass phrase for ca.key, enter the pass phrase.

openssl req -new -x509 -days 365 -key ca.key -out ca.crt

When prompted for the pass phrase for ca.key, enter the one you just input.
Input the following information when prompted:
Country Name
State or Province Name (full name)
Locality Name
Organization Name
Organizational Unit Name
Common Name (set this one different from the server’s CN)
Email Address

4. Generate a server key and request for signing (csr).
This step creates an unsigned server key, and a request that you want it signed (the .csr file) by a Certifying Authority.

openssl genrsa -des3 -out server.key 4096

When prompted for a pass phrase for server.key, enter the pass phrase.
openssl req -new -key server.key -out server.csr

When prompted for the pass phrase for server.key, enter the one you just input.
Input the following information when prompted:
Country Name
State or Province Name (full name)
Locality Name
Organization Name
Organizational Unit Name
Common Name (set this one different from the CA’s CN)
Email Address
A challenge password (It will prompt you to enter a challenge password to be sent with your certificate request)
An optional company name

5. Sign the certificate signing request (csr) with the self-created certifying authority (CA) that you made earlier.
openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt

If the signature of certificate signing request (csr) is OK, you will be prompted to enter pass phrase for ca.key.

6. Examine the components using the following commands.
openssl rsa -noout -text -in server.key
openssl req -noout -text -in server.csr
openssl rsa -noout -text -in ca.key
openssl x509 -noout -text -in ca.crt

7. Edit the /usr/local/blackboard/apps/httpd/conf/httpd.conf file to include the following directive.
Include conf/ssl.conf

8. Edit the /blackboard/config/bb-config.properties file by adding the following attributes.
bbconfig.unix.ssl.certificatefile=/path/to/your/server.crt
bbconfig.unix.ssl.certificatekeyfile=/path/to/your/server.key

The default place to store your server.crt is /usr/local/blackboard/apps/httpd/conf/ssl.crt/.
The default place to store your server.key is /usr/local/blackboard/apps/httpd/conf/ssl.key/.

Configuring SSL for the Collaboration Tool with a Signed Certificate

Setting up SSL to encrypt connections to the Blackboard Academic Suite does not secure the Collaboration Tool because the Collaboration Tool uses Tomcat, not Apache or IIS, to handle user connections and serve pages. Securing the Collaboration Tool requires using a separate SSL certificate with Tomcat.

1. Convert the server.key and server.crt into a PKCS12 keystore using OpenSSL.
openssl pkcs12 -export -out keystore.pkcs12 -in /path/to/your/server.crt -inkey /path/to/your/server.key

This will prompt for a keystore password. The default password is ‘changeit’. The keystore will be created as keystore.pkcs12 in the current directory. Move this to an appropriate location.

2. Adjust Tomcat to use the keystore.
Uncomment the following section in /usr/local/blackboard/apps/collab-server/http/tomcat/conf/server.xml.bb:
<Connector port=”@@bbconfig.collabserver.portnumber.ssl.default@@”
               maxThreads=”150″ minSpareThreads=”25″ maxSpareThreads=”75″
               keystoreFile=”@@bbconfig.collabserver.keystore.filename@@”
               keystorePass=”@@bbconfig.collabserver.keystore.password@@”
               enableLookups=”false” clientAuth=”false” sslProtocol=”TLS” abovekeystoreType=”PKCS12″
               acceptCount=”100″ disableUploadTimeout=”true” debug=”0″ scheme=”https” secure=”true”/>

3. Edit bb-config.properties in /usr/local/blackboard/config to add the following settings.
bbconfig.collabserver.portnumber.ssl.default=8443
bbconfig.collabserver.keystore.filename=/path/to/your/keystore.pkcs12
bbconfig.collabserver.keystore.password=changeit (please CHANGE IT!)

Push out changes

/usr/local/blackboard/tools/admin/PushConfigUpdates.sh