Museum Help - SSL

Museum SSL Web Browser Interface

Default SSL Configuration

To run an SSL server, you need a private key and a certificate signed by a Certificate Authority. This information can be concatenated in one file, or can each be in a separate file.

Museum ships with a private key file called "localhost.key" and a certificate file called "localhost.pem". These are located in the Museum server installation directory. You are welcome to use these for your SSL setup, however for better security and to eliminate security warnings in client browsers, you may want to use your own private key and certificate.

Customised SSL Configuration

Museum uses OpenSSL to support SSL. For OpenSSL, and therefore Museum, these files will usually end in .pem or .asn.

Keep in mind, some files may not have the correct filename ending, but may actually contain compatible content. The best idea is to give them a try.

You will need to update the Museum configuration file (config.xml, located in the installation directory) to point to your files. config.xml can be edited in any text editor, such as notepad.exe.

<http>
    <enabled>true</enabled>
    <https>true</https>
    <https_certificate_file>replace this with the path to mydomain.pem SSL certificate</https_certificate_file>
    <https_private_key_file>replace this with the path to mydomain.key private key</https_private_key_file>
    <https_passphrase>replace this with your private key passphrase or leave it empty if there is no passphrase</https_passphrase>
    ....
</http>

Using OpenSSL to Generate Keys and Certificates

As mentioned above, OpenSSL is used by Museum, so the easiest way to generate compatible keys and certificates, is to use command line OpenSSL.

The official OpenSSL website http://www.openssl.org/ contains source code, but no binaries.

You can compile your own OpenSSL binaries, or one of the following alternatives would probably be easier:

Shining Light Productions self contained Windows installer for OpenSSL (Easiest)

GnuWin32 native ports of GNU Unix tools

Cygwin Linux emulation environment for Windows

To Generate Private Keys

The following shows the steps to produce the files needed for Museum's default demonstration localhost SSL certificate.

Example command prompt session as actually used to create the localhost.key example provided in the Museum installation directory:

C:\>openssl genrsa -des3 -out localhost.key 1024
Loading 'screen' into random state - done
Generating RSA private key, 1024 bit long modulus
..++++++
.....................++++++
e is 65537 (0x10001)
Enter pass phrase for localhost.key:
Verifying - Enter pass phrase for localhost.key:

Inclusion of the -des3 paramter, will prompt you for a passphrase used to encrypt the contents of the -out file.

This passphrase will have to be entered into the Museum configuration file at the <https_private_key_passphrase> xml node.

passphrase use above was

mylocalhostpassphrase

To Get an SSL Certificate

Option 1 : Generate a Certificate Signing Request (CSR) and Send it to a Certificate Authority (CA)

The first step in obtaining a SLL certificate, is to generate a certificate signing request from your private keys.

Example command prompt session as actually used to create the localhost.csr example provided in the Museum installation directory:

C:\>openssl req -new -key localhost.key -out localhost.csr
Enter pass phrase for localhost.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:Victoria
Locality Name (eg, city) []:Warragul
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Broadgun Software Pty
. Ltd.
Organizational Unit Name (eg, section) []:Secure Delivery
Common Name (eg, YOUR name) []:localhost
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

NOTE : You would use filenames specific to the domain you are working on e.g. mydomain.key and mydomain.csr

The -out .csr file is then sent to a Certificate Authority which will sign it after verifying you.

The Certificate Authority will sign your request and send you back a localhost.pem file to use as your SSL certificate.

Option 2 : Be Your Own Certificate Authority (CA)

If you don't need to use a third party Certificate Authority, you can make your own Certificate Authority and sign the certificate yourself.

First generate the certificate authority private keys:

C:\>openssl genrsa -out ca.key 2048
Loading 'screen' into random state - done
Generating RSA private key, 2048 bit long modulus
........+++
.............+++
e is 65537 (0x10001)

Then make a new Certificate Authority certificate (This is different from the command that generates the certificate sign request, only by the addition of the -x509 parameter)

C:\>openssl req -new -x509 -days 5000 -key ca.key -out ca.pem
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:Victoria
Locality Name (eg, city) []:Warragul
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Broadgun Software Pty
. Ltd.
Organizational Unit Name (eg, section) []:Demonstration Certificate Authority
Common Name (eg, YOUR name) []:broadgun.com
Email Address []:

Now, we configure the current directory to suit the default OpenSSL certificate authority configuration file:

C:\>mkdir demoCA

C:\>mkdir demoCA\newcerts

C:\>type demoCA\index.txt > demoCA\index.txt

C:\>echo 1234 > demoCA\serial

Then call the OpenSSL ca command, overriding default parameters where needed

C:\>openssl ca -policy policy_anything -cert ca.pem -keyfile ca.key -i
n localhost.csr -days 730 -out localhost.pem
Using configuration from C:\Program Files\OpenSSL\bin\openssl.cnf
Loading 'screen' into random state - done
Check that the request matches the signature
Signature ok
Certificate Details:
Serial Number: 4660 (0x1234)
Validity
Not Before: Jul 25 07:13:42 2006 GMT
Not After : Jul 24 07:13:42 2008 GMT
Subject:
countryName = AU
stateOrProvinceName = Victoria
localityName = Warragul
organizationName = Broadgun Software Pty. Ltd.
organizationalUnitName = Secure Delivery
commonName = localhost
X509v3 extensions:
X509v3 Basic Constraints:
CA:FALSE
Netscape Comment:
OpenSSL Generated Certificate
X509v3 Subject Key Identifier:
72:89:6F:41:47:23:A0:EE:C9:A1:AB:17:B3:1A:CF:EA:1F:34:DD:C5
X509v3 Authority Key Identifier:
keyid:6D:C1:6D:23:02:54:9E:26:BF:FF:A2:F2:AC:42:1E:67:C5:C9:F3:4
0

Certificate is to be certified until Jul 24 07:13:42 2008 GMT (730 days)
Sign the certificate? [y/n]:y

1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated

We now have our localhost SSL certificate localhost.pem signed by the certificate authority whose keys where ca.key and certificate that was ca.pem