| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision |
| docs:guide-user:services:tls:certs [2023/02/04 16:58] – [Self signed certs] openwroot | docs:guide-user:services:tls:certs [2023/06/07 04:58] – split articles stokito |
|---|
| * Many others [[https://letsencrypt.org/docs/client-options/|ACME Client Implementations]] | * Many others [[https://letsencrypt.org/docs/client-options/|ACME Client Implementations]] |
| |
| | If you have already taken care of certificate automation see also [[:docs:guide-user:luci:getting_rid_of_luci_https_certificate_warnings#option_ainstalling_a_publicly_trusted_certificate|Installing a publicly trusted certificate]]. |
| |
| ===== Installing and trusting a root CA certificate in a PKI ===== | |
| |
| As stated above: | |
| |
| >For enabling HTTPS for a website's domain we need a private key and it's TSL certificate that was signed by a Certificate Authority (CA). | |
| |
| But what if you have your private Certificate Authority in your infrastructure? In that case, your CA will sign your certificate but the root certificate (the one from the private CA) won't be trusted by your system. It needs to be installed and added to the system's trust store. | |
| |
| Steps are as follow: | |
| |
| - Get the root CA certificate | |
| - Install the root CA certificate | |
| - Add the root CA certificate to the system's trust store | |
| - A helper script | |
| |
| For this documentation we will assume: | |
| |
| * The CA name is ''ca.private-domain.tld'' | |
| * The CA server is accessible at ''ca.private-domain.tld'', port ''443'' | |
| * The CA cert filename is ''ca.private-domain.tld.cert'' | |
| |
| ==== 1. Get the root CA certificate ==== | |
| |
| Let's get the root CA cert. | |
| |
| <code bash> | |
| openssl s_client -connect ca.private-domain.tld:443 < /dev/null > /tmp/temporary.out | |
| openssl x509 -outform PEM < /tmp/temporary.out > /tmp/ca.private-domain.tld.cert | |
| rm /tmp/temporary.out | |
| </code> | |
| |
| Note: Don't forget to remove the temporary file ''/tmp/temporary.out'' | |
| |
| ==== 2. Install the root CA certificate ==== | |
| |
| Trusted certificates are installed in ''/ect/ssl/certs''. However, it is a good practice to follow the [[https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s09.html|FHS 3]] and use ''/usr/local/share'' for architecture-independant files. | |
| |
| <code bash> | |
| mkdir -p /usr/local/share/ca-certificates | |
| mv /tmp/ca.private-domain.tld.cert /usr/local/share/ca-certificates/ | |
| ln -s /usr/local/share/ca-certificates/ca.private-domain.tld.cert /ect/ssl/certs/ca.private-domain.tld.cert | |
| chmod ugo-x | |
| </code> | |
| |
| ==== 3. Add the root CA certificate to the system's trust store ==== | |
| |
| The certificate is installed but not yet trusted. You need to provide its hash. | |
| |
| <code bash> | |
| # Generate the hash | |
| HASH="$(openssl x509 -hash -noout -in /ect/ssl/certs/ca.private-domain.tld.cert).0" | |
| |
| # Display the hash value | |
| echo "$HASH" | |
| |
| # Link the hash to the certificate | |
| ln -s "/ect/ssl/certs/ca.private-domain.tld.cert" "/ect/ssl/certs/$HASH" | |
| </code> | |
| |
| Note: If another cert has the same hash use suffix ''.1'' or ''.2'' instead of ''.0''. | |
| |
| Congratulations, you've installed and trusted your root CA certificate. | |
| |
| ==== 4. A helper script ==== | |
| |
| <code bash> | |
| CA_NAME="ca.private-domain.tld" | |
| CERT_FILE="$CA_NAME.cert" | |
| CERT_INSTALL_DIR="/usr/local/share/ca-certificates" | |
| CERT_PATH="${CERT_INSTALL_DIR}/${CERT_FILE}" | |
| |
| openssl s_client -connect ${CA_NAME}:443 < /dev/null > /tmp/temporary.out | |
| mkdir -p "$CERT_INSTALL_DIR" | |
| openssl x509 -outform PEM < /tmp/temporary.out > "$CERT_PATH" | |
| HASH="$(openssl x509 -hash -noout -in $CERT_PATH).0" | |
| echo "$HASH" | |
| |
| ln -s "$CERT_PATH" "/etc/ssl/certs/$CERT_FILE" | |
| ln -s "/etc/ssl/certs/$CERT_FILE" "/etc/ssl/certs/$HASH" | |
| ls -al "/etc/ssl/certs/$HASH" | |
| |
| rm /tmp/temporary.out | |
| </code> | |
| |
| ===== ACME.sh ===== | ===== ACME.sh ===== |
| | See [[docs:guide-user:services:tls:acme|acme.sh]] |
| ==== For experienced users ==== | |
| Use a command line and type ''opkg install acme luci-app-acme'' then edit ''/etc/config/acme'' and restart it with ''service acme restart''. | |
| | |
| ==== More easier way by using GUI ==== | |
| | |
| Open LUCI dashboard then in main menu go to ''System'' / ''Software''. Then click on ''Update lists...'' to load list of available packages. | |
| The into the ''Filter'' search type ''luci-app-acme'' and press Enter. Click on install button. It should install acme.sh and its LUCI app to configure. | |
| | |
| To configure in LUCI in the main menu open ''Services'' / ''ACME certs''. | |
| Basic configuration: | |
| * ''Account email'': put your email to receive expiry notices when your certificate is coming up for renewal. | |
| * You'll see a preconfigured EXAMPLE domain. We can change it for ourselves: | |
| * ''Enabled'': Click to enable | |
| * ''Use staging server'': unselect the check | |
| * ''Use for uhttpd'': you probably better to unselect this if not sure. | |
| * ''Key size'': Select ''ECC 256 bits''. The key will be based on an elliptic curve which is more efficient than RSA. | |
| * ''Domain names'': change the example.org to your domain | |
| * Click on ''Save and Apply'' | |
| | |
| Now you'll need to wait for some time while the certificate will be generated. | |
| After that you can find the certificates in ''/etc/acme/YOURDOMAIN_ecc'' folder e.g.: | |
| * ''/etc/acme/YOURDOMAIN_ecc/YOURDOMAIN.key'' the TLS private key. Never share it! | |
| * ''/etc/acme/YOURDOMAIN_ecc/fullchain.cer'' the TLS certificate and chain of CA that signed it. | |
| | |
| You can use them in nginx, uhttpd, lighttpd, [[docs:guide-user:services:email:emailrelay|EmailRelay]] and any other server that you want to configure with TLS. | |
| |
| ===== Self signed certs ===== | ===== Self signed certs ===== |
| See [[:docs:guide-user:services:webserver:uhttpd#https_enable_and_certificate_settings_and_creation|HTTPS Enable and Certificate Settings and Creation]] or [[:docs:guide-user:luci:getting_rid_of_luci_https_certificate_warnings#option_bcreating_installing_trusting_a_self-signed_certificate|Getting rid of LuCI HTTPS warnings]]. | See [[:docs:guide-user:services:webserver:uhttpd#https_enable_and_certificate_settings_and_creation|HTTPS Enable and Certificate Settings and Creation]] or [[:docs:guide-user:luci:getting_rid_of_luci_https_certificate_warnings#option_bcreating_installing_trusting_a_self-signed_certificate|Getting rid of LuCI HTTPS warnings]]. |
| | |
| | ===== Own Certificate Authority with PKI ===== |
| | See [[docs:guide-user:services:tls:pki|Installing and trusting a root CA certificate in a PKI]] |