SSL CERTIFICATION

The ADT supports two certificate authorities by default, LetsEncrypt and Zerossl
The ADT makes use of two ACME clients, lego and acme.sh
The ADT also allows you to supply certificates manually if you wish to choose a different provider or if you want to bring your own certificate.

The Lego client only supports LetsEncrypt issued certificates because because "Server requires External Account Binding. Use --eab with --kid and --hmac" for usage with zerossl which complicates our workflow so the ADT will fall back to the acme.sh client if it is configured to try and issue a certificate from ZeroSSL through the Lego ACME client.

The acme.sh client supports LetsEncrypt and ZeroSSL.

The valid configuration combinations are as follows in

${BUILD_HOME}/builddecripts/buildstyles.dat

For the acme.sh client

1. SSLCERTCLIENT:acme:github.com (this will install acme.sh from the github repository)

or

1. SSLCERTCLIENT:acme:acme.sh (this will install acme.sh from the website using this script GetAcme.sh

For the lego client

1. SSLCERTCLIENT:lego:binary (this will install lego direct from a precompiled binary)

or

1. SSLCERTCLIENT:lego:snap (this will install lego using a snap package)

Template configurations are:

If you want to use ZeroSSL (which requires that you use the acme.sh ACME client) for the value of SSLCERTCLIENT

 export SSL_GENERATION_METHOD="AUTOMATIC"
 export SSL_GENERATION_SERVICE="ZEROSSL"

If you want to use LetsEncrypt which you can use with lego or acme.sh ACME clients

 export SSL_GENERATION_METHOD="AUTOMATIC"
 export SSL_GENERATION_SERVICE="LETSENCRYPT"

And so those are the configuration settings that you need to set if you want to issue an SSL certificate for your websevers as part of your build process.

The SSL certificates have a lifecycle once they are generated and it the flow of the lifecycle of a certificate is as follows.

1. A new certificate is generated by "InstallNewSSLCertificate" being called as part of the build process
2. The certificate is copied to a subdirectory of the runtimedata directory so that if you run the build again the certificate can be reused rather than reissued
3. The certificate is also copied to a bucket in the datastore with a nomenclature of:

<website_url>-<cloudhost>-<zero|lets>-ssl

When a new build is run before a new SSL certificate is issued, the runtimedata directory and the datastore are checked for existing certificates and if existing (valid) certificates exist for the current domain then the certificates are reused. If there is no valis certificates already existing then a new certificate is issued as per step 1 above.

Certificates have a limited lifespan and will eventually expire if your servers are long running. The build machine checks the certificate stored in the runtimedata directory for the current domain via a cron job and if the certificate which is stored on the build machine is close to expiration a new certificate is generated and written to the datastore. This mechanism presumes that you will have a running build server which is active as long as your webservers are active and the task to check for invalid certificates is action from cron on the build machine. When the new certificate is issued it will be written to the runtimedata directory and also to the datastore. Every webserver will then check for a new certificate having been action and provisioned by the build machine and if a new or fresh certificate is found in the datastore then the webserver will update the certificate it is using to be this new certificate and you are then good with a new certificate with an extended lifespan before it needs to be renewed again.

NOTE: its possible to use your laptop as your build machine if your laptop runs Ubuntu or Debian or you can have a portable SSD drive with Ubuntu or Debian on it and use that as your build machine, but, clearly, its very likely that your laptop or SSD drive won't be online at the time of night when the build machine checks for the expiration of certificates so it means that if you use your laptop as your build machine then you will need to be mindful of SSL certificate expirations and that cron most likely won't be checking for them and that you need to tend to such things as a manual process rather than relying on a build machine that is online 24-7 to action the process of certificate renewal for you.

For LetsEncrypt there's two types of SSL certificates that can be issued. There's full certificates and there's staging certificates. The staging certificates will give you a browser warning when you visit your site, something like, "This is not secure". "Staging certificates" have no issuance limits where as "full certificates" do have issuance limits

To issue a live certificate set:

SSL_LIVE_CERT="1"

rather than

SSL_LIVE_CERT="0"

which will issue a staging certificate.

NOTE: Staging certificates are only possible when using Letsencrypt they are not supported for Zerossl