SSL

EasyEngine uses AcmePHP library to manage SSL certificates. You pass --ssl flag to create a site with SSL.

Currently there are three options you can pass to --ssl flag

  • --ssl=le. It should be used if you want to issue a new certificate from Let’s Encrypt.
  • --ssl=inherit. It should be used if there’s an existing site example.com with wildcard certificate and you want to create abc.example.com which will inherit (reuse) the certificate of example.com instead of issuing a new one.
  • --ssl=self if you want to create a self signed certificate. Useful for https site on local machine.

Getting Certificate from Let’s Encrypt

ADVERTISEMENT

In order to get certificate from Let’s Encrypt, you’ll have to use --ssl=le flag during site create.

ee site create example.com --type=wp --ssl=le

Optionally, If you want a wildcard certificate, you also need to pass --wildcard flag.

ee site create example.com --type=wp --ssl=le --wildcard
ADVERTISEMENT

⚠️ Note: If you’ve used --wildcard flag, you need to run following command after adding your DNS entries: 

ee site ssl example.com

In order to get a SSL certificate from a certificate authority, you have to prove to the certificate authority that you own the domain. The certificate authority gives you a “challenge” to prove that you own the domain. You then need to “solve” the given challenge. The certificate authority gives you two primary methods which can be used to solve challenge – 

  • HTTP Challenge
  • DNS Challenge 

HTTP Challenge

ADVERTISEMENT

When you use --ssl=le, by default this method is selected unless you’ve used --wildcard flag. EasyEngine automatically “solves” the challenge for you if this method is selected. Its only requirement is that the domain of site should point to the server where you’re creating site.

First of all, the certificate authority (Let’s Encrypt) tells us to put a specific string in a file at example.com/.well-known/acme-challenge/xxxxxxxxxxxxxxxx. Once you do it, the certificate authority checks if you have added the given string there. If it finds that specific string there, it marks the given challenge as solved and gives you certificate for the domain. However, you don’t need to worry about doing any of this as EasyEngine already handles it for you.

DNS Challenge

When you use --ssl=le with --wildcard flag, DNS challenge is used by default as it is the only method which supports wildcard certificates. In this method, you have to manually add a TXT record in your DNS. In future, we will attempt to automate it with a CloudFlare integration 

In this method, the certificate authority gives you DNS entries that you need to add to verify ownership of the domain.

ADVERTISEMENT
$ ee site create example.com --ssl=le --wildcard
Configuring project.
Creating site example.com.
Copying configuration files.
Starting site's services.
Success: Configuration files copied.
Checking and verifying site-up status. This may take some time.
Add the following TXT record to your DNS zone
Domain: _acme-challenge.example.com.
TXT value: xxxxxxxxx
Wait for the propagation before moving to the next step
Tips: Use the following command to check the propagation
host -t TXT _acme-challenge.example.com.
Add the following TXT record to your DNS zone
Domain: _acme-challenge.example.com.
TXT value: yyyyyyyyy
Wait for the propagation before moving to the next step
Tips: Use the following command to check the propagation
host -t TXT _acme-challenge.example.com.
IMPORTANT: Run `ee site ssl example.com` once the DNS changes have propagated to complete the certification generation and installation.
Starting site's services.

After running the above command, in this case, you need to add the following entries in your DNS

KeyValue
_acme-challenge.example.comxxxxxxxxx
_acme-challenge.example.comyyyyyyyyy

 After adding the entries, run the following command to verify that the changes have been propagated in the DNS – 

$ host -t TXT _acme-challenge.easyengine.io
_acme-challenge.example.com descriptive text "jfKbXNIhMB5agYNfYQqwZdFJmaHv1j-c_-wBk3cI7qg"
_acme-challenge.example.com descriptive text "bIcFm-nUWaOGjtqDiTFMvDz2aFInLyro5bN9E2VvWpI"
ADVERTISEMENT

Finally run following to verify the challenge and get the certificate from Let’s Encrypt – 

ee site ssl example.com

DNS Challenge on Non-wildcard Site

If there’s a site which isn’t wildcard but you still need DNS challenge on it, then you can do so by setting preferred_dns_challenge option in config file to dns:

ee config set preferred_ssl_challenge dns

It will ensure all sites created will use DNS challenge instead of HTTP. 

To restore the default behaviour, use:

ee config set preferred_ssl_challenge http

Inheriting Certs

Let’s say  there’s an existing site example.com with wildcard certificate and you want to create abc.example.com which will reuse the certificate of example.com instead of issuing a new one. Then you can do it with --ssl=inherit flag:

ee site create abc.example.com --ssl=inherit

Self Signed Certificates

You can generate a self signed certificate while creating a site by using --ssl=self flag. It is quite useful for creating https sites on local machine. 

ee site create example.com --ssl=self 

EasyEngine adds the self signed certificate’s Certificate Authority(CA) to your OS trust store so the sites created with self signed certificate do not display warnings in browser on that machine.

TLS Ciphers

We use ciphers from Mozilla’s Intermediate profile  by default. You can use different set of ciphers by choosing a different ssl policy. You can use other ssl policies by updating ssl-policy in EasyEngine’s config:

ee config set ssl-policy Mozilla-Intermediate

 Policies that you can use are – Mozilla-Old, Mozilla-Intermediate, Mozilla-Modern, AWS-TLS-1-2-2017-01, AWS-TLS-1-1-2017-01, AWS-2016-08, AWS-2015-05, AWS-2015-03 and AWS-2015-02. You can have a look at our code to see which ciphers and protocols will be used for which policy.

You can read more about how SSL is handled in nginx-proxy here.

Subpages