HTTPS/SSL

By default, Paradise is configured to run on unsecured HTTP (for easier first-time setup). Support for HTTPS can be enabled by setting EnableSSL to true in <path to Paradise.WebServices>\Paradise.Settings.WebServices.xml (see Server Configuration for more info).

Getting a SSL certificate

When requesting a SSL certificate, you basically have three options:

• Self-signed (aka. untrusted) certificates
• Paying for SSL certificates
• Let's Encrypt (renewal every ~90 days)

For this guide, we're focussing on self-signed certificates and Let's Encrypt.

Self-signed certificates

OpenSSL

On UNIX-based systems, you can create a self-signed certificate using OpenSSL (which also works on Windows but needs to be installed first). Simply run the following command:

openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout example.key -out example.crt -subj "/CN=example.com"

Replace example.com with your desired domain or IP address. To change the output file names, change the -keyout and -out parameters.
If you want a different expiry date (the default in this example is 10 years), set the -days parameter to your desired value.
To protect your private key with a password, remove the -nodes parameter.

This command may ask you for simple personal information. If you want, you can skip these questions and accept the default values.

To import this certificate into the Windows certificate store, you'll need to convert it to .pfx first. This can be done with this command:

openssl pkcs12 -export -out example.pfx -inkey example.key -in example.crt

If you added a password to your private key, you need to enter it before the certificate can be converted.
You may want to password-protect the converted certificate too. Otherwise, just hit Return when it asks you to enter an export password.

The exported .pfx file can now be imported into the Windows certificate store. When importing, select Local Machine and confirm the certificate location. If you've set a password, you may enter it in the next step. Make sure to mark the private key as exportable. The certificate should be automatically import into Personal → Certifcates.

Windows

On Windows, you can create a self-signed SSL certificate using a single command, which also automatically stores it in the correct certificate store:

New-SelfSignedCertificate –Subject example.com -NotAfter (Get-Date).AddDays(3650) -CertStoreLocation "cert:\LocalMachine\My" 

Again, replace example.com with your desired domain or IP address, or change the expiry date by adjusting the -NotAfter parameter.

:information_source: If you have set Hostname in Paradise.Settings.WebServices.xml, please note that the hostname in your SSL certificate (CN=...) MUST match the value of this key!

Let's Encrypt

Let's Encrypt provides SSL certificates for free. The only "downside" is that it needs to be renewed every ~90 days, and you need a web server on port 80 that can be reached via a domain.

For instructions on how to get a certificate from Let's Encrypt, please refer to the official certbot documentation. The certificate then must be converted to .pfx the same way as a self-signed certificate generated using OpenSSL.

Setting up Paradise for SSL

:information_source: If you're dealing with more than one certificate, please try to avoid duplicate friendly names. If there is more than certificate with the same friendly name, the Paradise Web Services will fail to launch.

After importing your certificate into the Windows Certificate Store, it needs to be bound to the ports you're using for the Paradise Web Services. If you're familiar with the command line, this can be done by using netsh. If not, there is a little tool called HttpConfig which makes binding certificates super easy, barely an inconvenience.

After opening HttpConfig, switch to the SSL tab and click Add to add a new configuration. For IP Address, enter 0.0.0.0 to make this configuration available for any interface. Enter the port for the Web Services (default 8080). Next to the GUID field, click New to generate a new GUID. Now, under Certificate, click Browse. If Windows does not show your SSL certificate right away, click More choices and select your certificate. Repeat the process for the File Server as well (default port 8081). Finally, click Apply.

Now, for the last step, set the SSLCertificateName key in Paradise.Settings.WebServices.xml to either the Issued To or Friendly Name fields as shown in the Certificate Store. Congratulations, you now have set up SSL within Paradise!