859
edits
Changes
From SME Server
Jump to navigationJump to search→Certificate Errors
{{Languages|Letsencrypt}}
{{Level|Medium}}
{{Level|Medium}}
==Introduction==
==Introduction==
{{warning box| The original protocol used by Let’s Encrypt for certificate issuance and management is called ACMEv1. In March of 2018 Letsencrypt introduced support for ACMEv2, a newer version of the protocol that matches what was finalized today as RFC 8555 328. They have been encouraging subscribers to move to the ACMEv2 protocol.
In March 2019 they announced an end of life plan for ACMEv1.
In November of 2019 they will stop allowing new account registrations through their ACMEv1 API endpoint. '''IMPORTANTLY''' Existing accounts will continue to function normally.
In June of 2020 they will stop allowing new domains to validate via ACMEv1.
Starting at the beginning of 2021 they will occasionally disable ACMEv1 issuance and renewal for periods of 24 hours, no more than once per month (OCSP service will not be affected). The intention is to induce client errors that might encourage subscribers to update to clients or configurations that use ACMEv2.
Renewal failures should be limited since new domain validations will already be disabled and we recommend renewing certificates 30 days before they expire.
In June of 2021 they will entirely disable ACMEv1 as a viable way to get a Let’s Encrypt certificate.}}
[https://letsencrypt.org/ Let’s Encrypt] is a new Certificate Authority:
[https://letsencrypt.org/ Let’s Encrypt] is a new Certificate Authority:
It’s free, automated, and open. Its main purpose is to allow people to encrypt their internet traffic at no cost, easily, and automatically. The certs delivered must be renewed every 3 months.
It’s free, automated, and open. Its main purpose is to allow people to encrypt their internet traffic at no cost, easily, and automatically. The certs delivered must be renewed every 3 months.
=== Version ===
=== Version ===
{{ #smeversion:smeserver-letsencrypt }}
{{#smeversion:smeserver-letsencrypt }}
<br>
<br>
{{ #smeversion:dehydrated }}
{{#smeversion:dehydrated }}
<br>
<br>
* www.example.com is a valid domain name--the domain has been registered, and DNS records are published for it.
* www.example.com is a valid domain name--the domain has been registered, and DNS records are published for it.
* www.example.com resolves to your SME Server--published DNS records give the external IP address of your SME Server when queried for www.example.com.
* www.example.com resolves to your SME Server--published DNS records give the external IP address of your SME Server when queried for www.example.com.
* Your SME Server is connected to the Internet.
* Your SME Server is connected to the Internet, and is able to make outbound connections on ports 80 and 443.
* Port 80 on your SME Server is open to the Internet--you aren't behind a firewall, or some ISP filtering, that would block it.
* Port 80 on your SME Server is open to the Internet (i.e., the Internet can reach your server on port 80)--you aren't behind a firewall, or some ISP filtering, that would block it. If you've made SSL mandatory for the Primary ibay, port 443 must also be open.
Letsencrypt will issue certificates that include multiple hostnames (for example, www.example.com, example.com, and mail.example.com), all of which would be part of the request. All of the conditions above must be true for all of the hostnames you want to include in the certificate.
Letsencrypt will issue certificates that include multiple hostnames (for example, www.example.com, example.com, and mail.example.com), all of which would be part of the request. All of the conditions above must be true for all of the hostnames you want to include in the certificate.
db hosts setprop www.domain1.com letsencryptSSLcert enabled
db hosts setprop www.domain1.com letsencryptSSLcert enabled
You can also set this contrib to obtain a certificate for all domains, all hostnames, or all domains AND hostnames.
You can obtain a certificate for either of the following: all domains, all hostnames, or all domains AND hostnames. Only set one of the following.
With the system configuration described above, setting this to "domains" will obtain a certificate covering domain1.com and domain2.com, but not www.domain1.com, etc. Setting it to "hosts" will obtain a certificate covering www.domain1.com, mail.domain1.com, ftp.domain1.com, etc., but not domain1.com or domain2.com. Setting this property to "all" will include all domain names and hostnames in the certificate.
config setprop letsencrypt configure domains
config setprop letsencrypt configure hosts
config setprop letsencrypt configure all
To use individually enabled hosts or domains leave the default none.
config setprop letsencrypt configure none
With the system configuration described above, setting this to "domains" will obtain a certificate covering domain1.com and domain2.com, but not www.domain1.com, etc. Setting it to "hosts" will obtain a certificate covering www.domain1.com, mail.domain1.com, ftp.domain1.com, etc., but not domain1.com or domain2.com. Setting this property to "all" will include all domain names and hostnames in the certificate. '''see [[Letsencrypt#Some_challenges_complete_successfully_but_some_hostnames_fail|NOTE]] before setting this to "all"'''
====Other configuration properties====
====Other configuration properties====
Please first read the condition terms for using Let's Encrypt [[https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf]]
Please first read the condition terms for using Let's Encrypt [[https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf]]
config setprop letsencrypt ACCEPT_TERMS yes
config setprop letsencrypt ACCEPT_TERMS yes
{{Note box|Creation of a new certificate requires the API being set to V2, see warning box above}}
===V2 API===
With the latest version of letsencrypt/dehydrated the V2 API is needed to create new certificates, V1 is depreciated for creation of new certificates however is still valid for existing certificates created with it.
The key is called API. It will default to '1' if left unset. Options are '1', '2', 'auto'
For updating current V1 certificates leave as default or set to 1, auto
# config show letsencrypt
letsencrypt=service
ACCEPT_TERMS=yes
configure=none
email=####@#####.###
hookScript=disabled
status=enabled
# config setprop letsencrypt API 1
# signal-event console-save
# config show letsencrypt
letsencrypt=service
ACCEPT_TERMS=yes
API=1
configure=none
email=####@#####.###
hookScript=disabled
status=enabled
For creating a new certificate or updating a V2 set to 2
# config setprop letsencrypt API 2
# signal-event console-save
# config show letsencrypt
letsencrypt=service
ACCEPT_TERMS=yes
API=2
configure=none
email=####@#####.###
hookScript=disabled
status=enabled
===Enable Test Mode===
===Enable Test Mode===
You can now run dehydrated for the first time, and make sure it's able to connect to the Let's Encrypt servers, validate the hostnames you're requesting, and issue certificates. To do this, run
You can now run dehydrated for the first time, and make sure it's able to connect to the Let's Encrypt servers, validate the hostnames you're requesting, and issue certificates. To do this, run
dehydrated -c
dehydrated -c
If it prints only "# INFO: Using main config file /etc/dehydrated/config" and returns you to the shell prompt, see [[Bugzilla:10300]].
{{Note box|Solution for error "Malformed account ID in KeyID header URL" using API 2, for contrib versions 0.6.13 or older See [[Bugzilla:10828]] or update to latest contrib}}
If this runs without errors, try to connect to your server-manager page. You should see an error that the security certificate wasn't issued by a trusted certification authority; this is perfectly normal. However, there should be a certificate, it should include all the hostnames you wanted included, and it should be valid for the next ninety days. If this was successful, proceed to production.
If this runs without errors, try to connect to your server-manager page. You should see an error that the security certificate wasn't issued by a trusted certification authority; this is perfectly normal. However, there should be a certificate, it should include all the hostnames you wanted included, and it should be valid for the next ninety days. If this was successful, proceed to production.
Once you've obtained your certificate and configured your server, test your server with a tool like [https://www.ssllabs.com/ssltest/ SSLLabs.com] to make sure it's working properly.
Once you've obtained your certificate and configured your server, test your server with a tool like [https://www.ssllabs.com/ssltest/ SSLLabs.com] to make sure it's working properly.
===Archive old certificates===
A new function lets you cleanup old and archive old certificates.
dehydrated --cleanup (-gc)
===Rush jobs===
===Rush jobs===
for the test ('''adjust the domains and hosts'''):
for the test ('''adjust the domains and hosts'''):
config setprop letsencrypt ACCEPT_TERMS yes status test
config setprop letsencrypt ACCEPT_TERMS yes status test API 2
#foreach of your domains you want SSL do the following
#foreach of your domains you want SSL do the following
db domains setprop '''domain1.com''' letsencryptSSLcert enabled
db domains setprop '''domain1.com''' letsencryptSSLcert enabled
==Manual Installation of Dehydrated==
==Manual Installation of Dehydrated==
{{warning box| the following is not to be executed if you have installed the smeserver-letsencrypt contrib rpm as it is already handled by the contrib}}
As discussed above, dehydrated is a lightweight ACME client that's implemented as a BASH script. It has very few dependencies, and is a better fit for the "SME way" of doing things than the official certbot client. If you'd prefer to configure it manually, rather than installing the contrib described above, you may do so manually or by pulling a copy of the latest version using git.
As discussed above, dehydrated is a lightweight ACME client that's implemented as a BASH script. It has very few dependencies, and is a better fit for the "SME way" of doing things than the official certbot client. If you'd prefer to configure it manually, rather than installing the contrib described above, you may do so manually or by pulling a copy of the latest version using git.
===Contrib install of Dehydrated===
===Install of Dehydrated rpm from smecontrib repository===
The dehydrated script has been imported into the contribs repository and can be installed as follows:
The dehydrated script has been imported into the contribs repository and can be installed as follows:
Enter the following in this file:
Enter the following in this file:
#!/bin/bash
#!/bin/bash
/usr/local/bin/dehydrated -c
/usr/bin/dehydrated -c
Ctrl-X to exit, Y to save. Then make it executable:
Ctrl-X to exit, Y to save. Then make it executable:
chmod +x /etc/cron.daily/call-dehydrated
chmod +x /etc/cron.daily/call-dehydrated
{{warning box| end of the manual installation and configuration of dehydrated without smeserver-letsencrypt contrib}}
==Requiring SSL==
==Requiring SSL==
==Backup==
==Backup==
Your certificate, private key, and other important information are stored in /etc/dehydrated, which is not included in the standard SME Server backup routines. Make sure to add this directory to your backups. See, e.g., [[Backup with dar#Adding files and directories|Backup with dar]] if you're using the workstation backup feature. If using Affa for backup, add
Your certificate, private key, and other important information are stored in /etc/dehydrated, which is not included in the standard SME Server backup routines. Make sure to add this directory to your backups. See, e.g., [[Backup with dar#Adding_Files_and_Directories|Backup with dar]] if you're using the workstation backup feature. If using Affa for backup, add
Include=/etc/dehydrated
Include=/etc/dehydrated
Once you've made these changes, do:
Once you've made these changes, do:
signal-event post-upgrade
signal-event reboot
Also see
https://wiki.contribs.org/Useful_Commands#How_to_simply_recreate_the_certificate_for_SME_Server
rm /home/e-smith/ssl.{crt,key,pem}/*
config delprop modSSL CommonName
config delprop modSSL crt
config delprop modSSL key
signal-event post-upgrade
signal-event post-upgrade
signal-event reboot
signal-event reboot
===Errors===
===Errors===
====No registration exists matching provided key====
If you see the following:
If you see the following:
See above for removing private keys and regenerating
See above for removing private keys and regenerating
====rateLimited, Too many currently pending Authorizations====
If you see something like this you may have hit the rate limit:
If you see something like this you may have hit the rate limit:
https://letsencrypt.org/docs/rate-limits/
https://letsencrypt.org/docs/rate-limits/
====Some challenges complete successfully but some hostnames fail====
If you see some of your challenges returned without error but some fail, you possibly do not have Public DNS A or MX records for all the host names that you are adding to your certificate.
Using the command:
config setprop letsencrypt configure all
Is likely to cause this error. When a domain is added to an SME server, several host names are created automatically. these include ftp.your-domain.com, wpad.your-domain.com, proxy.your-domain.com, mail.your-domain.com, www.your-domain.com. Most of us do not create public DNS records for all these host names. When letsencrypt issues a challenge for a list of host names and '''ONE''' does not resolve, the challenge will fail and the certificate will not generate at all.
To resolve this, issue the following command:
config setprop letsencrypt configure none
Then follow up with the commands to enable letsencrypt for each PUBLIC resolvable domain and hostname:
db domains setprop domain1.com letsencryptSSLcert enabled
and for each hostname:
db hosts setprop www.domain1.com letsencryptSSLcert enabled
db hosts setprop mail.domain1.com letsencryptSSLcert enabled
until all the public facing hostnames are enabled
followed by:
signal-event console-save
Thanks to MSmith for the following forum thread.
https://forums.contribs.org/index.php/topic,53052.0.html
====Challenge fails with unauthorized 403 error====
If your challenge returns something like the following:
ERROR: Challenge is invalid! (returned: invalid) (result: {
"type": "http-01",
"status": "invalid",
"error": {
"type": "urn:acme:error:unauthorized",
"detail": "Invalid response from http://www.your-domain.com/.well-known/acme-challenge/<redacted text>
"status": 403
and your ''httpd error_log'' on your server shows something like this:
(13)Permission denied: access to /.well-known/acme-challenge/<redacted> denied
(13)Permission denied: access to /.well-known/acme-challenge/<redacted> denied
(13)Permission denied: access to /.well-known/acme-challenge/<redacted> denied
You need to check the ownership and rights on ''/home/e-smith/files/ibays/Primary'' and on ''/home/e-smith/files/ibays/Primary/html''. The contrib creates a hidden working directory at ''/home/e-smith/files/ibays/Primary/html/.well-known'' and inside that directory a second directory with the following path ''/home/e-smith/files/ibays/Primary/html/.well-known/acme-challenge''. The script creates the two new directories with the correct ownerships and rights, however, if the ownership and rights on the ibay and the html directory do not allow the script to access the new location, the challenge will fail with ''access denied''
use the following to check the rights:
cd /home/e-smith/files/ibays
then
ls -l
on my test server with only the Primary ibay I get the following (you will probably show a bunch more ibays on your server but we are only concerned with Primary):
total 4
drwxr-xr-x 5 root root 4096 Jul 25 2016 Primary
If this is not what you see, you need to correct it.
'''THIS MAY BREAK NON STANDARD CUSTOMIZATION OF YOUR SERVER, YOU NEED TO UNDERSTAND WHY THIS HAS BEEN CHANGED BEFORE YOU REVERSE IT'''
From within ''/home/e-smith/files/ibays/'' issue the following:
chown root:root Primary
If the rights are not correct, issue:
chmod 0755 Primary
Next check the html directory.
cd /home/e-smith/files/ibays/Primary
then
ls -l
on my test server I have the following
[root@backupserver Primary]# ls -l
total 12
drwxr-s--- 2 admin shared 4096 Jul 25 2016 cgi-bin
drwxr-s--- 2 admin shared 4096 Jul 25 2016 files
'''drwxr-s--- 3 admin shared 4096 Jun 11 08:06 html'''
If this is not what you see,
'''FIRST READ ABOVE WARNING'''
then adjust as follows
chown admin:shared html
If the rights are not correct, issue:
chmod 2750 html
rerun
dehydrated -c
and your challenges should complete.
https://forums.contribs.org/index.php/topic,53147.0.html
==Advanced Topics==
==Advanced Topics==
===Obtaining certificates for other servers===
===Obtaining certificates for other servers===
The dehydrated client can be used to obtain certificates for other servers on your network, if the hostnames resolve (from outside your network) to your SME Server. Here's how to do this using John Crisp's contrib.
The dehydrated client can be used to obtain certificates for other servers on your network, if the hostnames resolve (from outside your network) to your SME Server. Here's how to do this using the smeserver-letsencrypt contrib.
====Hosts and Domains====
{{Note box| This section is not necessary as far as I am aware. You should just be able to set a host with "HostType local" and an InternalIP address as letsencryptSSLcert enabled and then regenerate domains.txt}}
You'll need to create two template fragments: one to add your hostname to /etc/dehydrated/domains.txt, and the second to handle the certificate once it's generated. To create the first, do
You'll need to create two template fragments: one to add your hostname to /etc/dehydrated/domains.txt, and the second to handle the certificate once it's generated. To create the first, do
Then Ctrl-X to exit, Y to save.
Then Ctrl-X to exit, Y to save.
====Hook Script deployment====
The second template fragment will be a portion of the hook script, so the dehydrated client knows what to do with this certificate. This must be present, otherwise dehydrated will configure your SME server to use this certificate rather than the certificate for the SME Server.
The second template fragment will be a portion of the hook script, so the dehydrated client knows what to do with this certificate. This must be present, otherwise dehydrated will configure your SME server to use this certificate rather than the certificate for the SME Server.
mkdir -p /etc/e-smith/templates-custom/usr/local/bin/hook-script.sh/
mkdir -p /etc/e-smith/templates-custom/usr/bin/hook-script.sh/
nano -w 05deploy_cert_hostname
nano -w 05deploy_cert_hostname
These certificates will be automatically renewed, just like the main server certificate.
These certificates will be automatically renewed, just like the main server certificate.
===Obtaining certificates for a private SME Server===
As noted above in the prerequisites section, your SME Server must ordinarily be accessible from the Internet so that the Let's Encrypt servers can validate that you control it. However, if your SME Server is not accessible from the Internet, the smeserver-letsencrypt contrib provides a method that can be used to validate domain control. In order to use this method, the following conditions must be true:
* The hostname of your internal SME Server (example: internal.mydomain.tld) resolves, on the public Internet, to a valid IP address
* The host to which internal.mydomain.tld resolves (example: external.mydomain.tld) has a running web server on port 80
* The root user from internal.mydomain.tld can connect to external.mydomain.tld via SSH without entering a password (i.e., you've set up SSH public key authentication)
This method uses a simple script that's included in the smeserver-letsencrypt contrib, which requires that four database entries be set:
config setprop letsencrypt hookScript enabled
config setprop letsencrypt host '''external.mydomain.tld'''
config setprop letsencrypt user '''root'''
config setprop letsencrypt path '''/home/e-smith/files/ibays/Primary/html/.well-known/acme-challenge'''
signal-event console-save
The parts in bold above should be changed to match your situation; the path variable should be the filesystem location that external.mydomain.tld serves as /.well-known/acme-challenge/ . When dehydrated creates the challenge file, it will transfer it via scp to user@host:path/, and then allow the Let's Encrypt server to validate. Once validation is accomplished, the script will remove the challenge file from user@host:path/
= Bugs =
= Bugs =
{{#smechangelog:smeserver-letsencrypt}}
{{#smechangelog:smeserver-letsencrypt}}
[[Category:Howto]] [[Category:Security]] [[Category:Howto]]
[[Category:Contrib]]
[[Category:Howto]]
[[Category:Security]]
[[Category: Administration:Certificates]]
[[Category: Administration:Certificates]]
