Difference between revisions of "Setting up HTTPS using Let's Encrypt"

From EPrints Documentation
Jump to: navigation, search
m
m (reformatting including some typo correction)
Line 5: Line 5:
  
 
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.
 
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:
 
2. When you get to the point of running the certbot command you want the certificate only so should type as the root user:
Line 13: Line 12:
 
3. Take a note of the path to were your certificate, key and CA chain have been saved.  This will probably be something like
 
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/example.eprints.org/
+
  /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/
  
4. If you have not already done so create an directory called '''ssl''' inside your archive's directory. E.g.
+
4. If you have not already done so, create an directory called <tt>ssl</tt> inside your archive's directory, i.e.
  
  mkdir /opt/eprints3/archives/example/ssl/
+
  mkdir /opt/eprints3/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.  You will note that this configuration also enables [https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security 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.
+
5. Create a file inside the new ssl directory called <tt>securevhost.conf</tt> and include the following contents, amending the <tt>ServerName</tt>, <tt>SSLCertificateFile</tt>, <tt>SSLCertificateKeyFile</tt> <tt>SSLCertificateChainFile</tt> and <tt>Include</tt> as appropriate at least.  You will note that this configuration also enables [https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security 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>
 
  <VirtualHost *:443>
 
   
 
   
     ServerName example.eprints.org:443
+
     ServerName YOUR-REPOSITORY-DOMAIN:443
 
   
 
   
 
     # Enable HSTS
 
     # Enable HSTS
Line 33: Line 32:
 
     SSLCipherSuite HIGH:!aNULL:!eNULL:!kECDH:!aDH:!RC4:!3DES:!CAMELLIA:!MD5:!PSK:!SRP:!KRB5:@STRENGTH
 
     SSLCipherSuite HIGH:!aNULL:!eNULL:!kECDH:!aDH:!RC4:!3DES:!CAMELLIA:!MD5:!PSK:!SRP:!KRB5:@STRENGTH
 
   
 
   
     SSLCertificateFile /etc/letsencrypt/live/example.eprints.org/cert.pem
+
     SSLCertificateFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/cert.pem
     SSLCertificateKeyFile /etc/letsencrypt/live/example.eprints.org/privkey.pem
+
     SSLCertificateKeyFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/privkey.pem
     SSLCertificateChainFile /etc/letsencrypt/live/example.eprints.org/chain.pem
+
     SSLCertificateChainFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/chain.pem
 
   
 
   
 
     SetEnvIf User-Agent ".*MSIE.*" \
 
     SetEnvIf User-Agent ".*MSIE.*" \
Line 47: Line 46:
 
         "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
 
         "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
 
   
 
   
     Include /opt/eprints3/cfg/apache_ssl/test.conf
+
     Include /opt/eprints3/cfg/apache_ssl/REPOID.conf
 
   
 
   
 
     PerlTransHandler +EPrints::Apache::Rewrite
 
     PerlTransHandler +EPrints::Apache::Rewrite
Line 53: Line 52:
 
  </VirtualHost>
 
  </VirtualHost>
  
6. Now you will need to regenerate the rest of your Apache configuration for EPrints will the following command run as the EPrints user. (Substitute the path as appropriate):
+
6. 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
 
  /opt/eprints3/bin/generate_apacheconf --system --replace
  
7. Apache will not yet have been setup to include the Apache configuration file you create 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.
+
7. 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 (<tt>/etc/httpd/</tt> on RHEL/CentOS/Fedora and <tt>/etc/apache2/</tt> on Debian/Ubuntu) and find the file that contains the line <tt>cfg/apache.conf</tt>, e.g.
  
 
  cd /etc/httpd/
 
  cd /etc/httpd/
Line 64: Line 63:
 
8. Once you have found it you will need to edit it and add the following line, changing the path as appropriate:
 
8. Once you have found it you will need to edit it and add the following line, changing the path as appropriate:
  
  Include /opt/eprints3/archives/example/ssl/securevhost.conf
+
  Include /opt/eprints3/archives/REPOID/ssl/securevhost.conf
  
 
9. Now test that the Apache configuration is correct and fix any issues if necessary:
 
9. Now test that the Apache configuration is correct and fix any issues if necessary:
Line 74: Line 73:
 
  apachectl restart
 
  apachectl restart
  
11. 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:
+
11. 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 <tt>crontab -e</tt> 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
 
  43 6,18 * * * certbot renew

Revision as of 13:29, 26 October 2017

Manual Sections

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 /opt/eprints3/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 /opt/eprints3/cfg/apache_ssl/REPOID.conf

    PerlTransHandler +EPrints::Apache::Rewrite

</VirtualHost>

6. 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

7. 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 "cfg/apache.conf" *

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

Include /opt/eprints3/archives/REPOID/ssl/securevhost.conf

9. Now test that the Apache configuration is correct and fix any issues if necessary:

apachectl configtest

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

apachectl restart

11. 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