Setting up HTTPS using Let's Encrypt

By default EPrints does not come setup to use HTTPS. This is because you need to generate a SSL certificate and if this is not signed by a known Certificate Authority a user's web browser is likely to complain vigorously. In the past it has typically costed a fair amount of money to obtain a SSL certificate from your hosting provider. However, now there is Let's Encrypt it is possible to get a certificate for free. This is not to say you should use Let's Encrypt in all cases. UK academic institutions should continue to obtain their SSL certificates through Jisc and other institutions/organisations may already have similar arrangements for obtaining SSL certificates.

As well as being free, Let's Encrypt has an automated way for renewing certificates. However, it should be noted that the length of its certificates is a lot shorter at just 3 months. As the renewal process is automatic, this time period is more appropriate to maximise security. Let's Encrypt's certificate generation requires your EPrints repository to be publicly accessible. Beneath are instructions on how to set up EPrints to enable HTTPS with a Let's Encrypt certificate.

1. Go to the https://certbot.eff.org/ and follow the instructions for your web server and operating system (the former will almost always be Apache) and follow the instructions provided.

2. When you get to the point of running the certbot command you want the certificate only so should type as the root user:

certbot --apache certonly

3. Take a note of the path to were your certificate, key and CA chain have been saved. This will probably be something like

/etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/

4. If you have not already done so, create an directory called ssl inside your archive's directory, i.e.

mkdir EPRINTS_PATH/archives/REPOID/ssl/

5. Create a file inside the new ssl directory called securevhost.conf and include the following contents, amending the ServerName, SSLCertificateFile, SSLCertificateKeyFile SSLCertificateChainFile and Include as appropriate at least. You will note that this configuration also enables HTTP Strict Transport Security (HSTS) for additional security. This ensures that after the first time you visit HTTPS for a particular site in your web browser, all future HTTP requests for this hostname will automatically be converted by your browser to HTTPS.

<VirtualHost *:443>

    ServerName YOUR-REPOSITORY-DOMAIN:443

    # Enable HSTS
    Header always set Strict-Transport-Security "max-age=63072000;"

    SSLEngine on
    SSLProtocol all -SSLv2 -SSLv3
    SSLHonorCipherOrder on
    SSLCipherSuite HIGH:!aNULL:!eNULL:!kECDH:!aDH:!RC4:!3DES:!CAMELLIA:!MD5:!PSK:!SRP:!KRB5:@STRENGTH

    SSLCertificateFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/cert.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/privkey.pem
    SSLCertificateChainFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/chain.pem

    SetEnvIf User-Agent ".*MSIE.*" \
        nokeepalive ssl-unclean-shutdown \
        downgrade-1.0 force-response-1.0

    LogLevel warn
    ErrorLog logs/ssl_error_log    
    TransferLog logs/ssl_access_log
    CustomLog logs/ssl_request_log \
        "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

    Include EPRINTS_PATHH/cfg/apache_ssl/REPOID.conf

    PerlTransHandler +EPrints::Apache::Rewrite

</VirtualHost>

6. If you have not already done so, add a configuration file at /opt/eprints3/archives/REPOID/cfg/cfg.d/https.pl with the following configuration:

$c->{securehost} = $c->{host};
$c->{secureport} = 443;
$c->{http_root} = undef;

7. Now you will need to regenerate the rest of your Apache configuration for EPrints with the following command run as the EPrints user. (Substitute the path as appropriate):

/opt/eprints3/bin/generate_apacheconf --system --replace

8. Apache will not yet have been setup to include the Apache configuration file you created in step 5. To include this, you will need to edit the file in your Apache configuration directory (/etc/httpd/ on RHEL/CentOS/Fedora and /etc/apache2/ on Debian/Ubuntu) and find the file that contains the line cfg/apache.conf, e.g.

cd /etc/httpd/
grep -r "cfg/apache.conf" *

9. Once you have found it you will need to edit it and add the following line, changing the path as appropriate:

Include EPRINTS_PATH/archives/REPOID/ssl/securevhost.conf

10. Now, (as root or using sudo) test that the Apache configuration is correct and fix any issues if necessary:

apachectl configtest

11. Restart Apache and check whether you can access your EPrints repository using HTTPS in a web browser:

apachectl restart

12. If the guide on cerbot.eff.org you used in step 1 tells you to to setup a cron job then follow those instructions. The easiest way to do this is probably to run crontab -e as root and add the following cron job, substituting the minute (43) and hours (6,18) for you own choice maintaining a 12 hour gap between the hours:

43 6,18 * * * certbot renew

Additional Notes

The default EPrints Apache Rewrite handler declines any requests to a URL containing /..

This means that the challenge/response for a LetsEncrypt certificate renewal that uses the /.well-known/acme-challenge/ path will fail.

To make this work you could add a location block to your Apache config, to ensure the /.well-known/ are not handled by EPrints, or use an EPrints URL rewrite trigger to handle the request:

#this could be saved into e.g. [EPRINTS_ROOT]/lib/cfg.d/z_rewrite_url_LetsEncrypt.pl

# import Apache constant e.g. 'OK'
use EPrints::Apache::AnApache;

$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub {
        my( %o ) = @_;

        # if the incoming request matches the LetsEncrypt challenge URL...
        if( $o{uri} =~ m!^${o{urlpath}}/\.well-known/acme-challenge/! )
        {
                # and the LetsEncrypt renewal process has put the file in EPRINTS_ROOT/archives/ARCHIVEID/html/.well-known/acme-challenge/
                if( -f $o{repository}->get_conf( "htdocs_path" ).$o{uri} )
                {
                        # reply with an HTTP '200' 
                        ${$o{return_code}} = OK;
                        # and return the file reqested
                        $o{request}->filename( $o{repository}->get_conf( "htdocs_path" ).$o{uri} );
                }
                # and say that we've handled the request - so no more triggers should be run.
                return EP_TRIGGER_DONE;
        }
} );