From 3bf731534adccd109908178b61f5989a63eb5d94 Mon Sep 17 00:00:00 2001 From: Fermulator Date: Mon, 16 Dec 2019 07:11:55 -0500 Subject: [PATCH] More on CA and reference domain ownership (#10764) * DOCS: more on CA and reference domain ownership I've been using the self-signed certificate option for some time, and was hunting for alternative options to transition to a trusted cert. Going back to documentation, updating it with some context for those possibly unfamiliar (CA), and adding a reference to the domain ownership method. * add site root * revert site root * :pencil2: Tweaks Co-authored-by: Franck Nijhof --- .../tls_self_signed_certificate.markdown | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/source/_docs/ecosystem/certificates/tls_self_signed_certificate.markdown b/source/_docs/ecosystem/certificates/tls_self_signed_certificate.markdown index d2b1d2c7d29..22fde562eba 100644 --- a/source/_docs/ecosystem/certificates/tls_self_signed_certificate.markdown +++ b/source/_docs/ecosystem/certificates/tls_self_signed_certificate.markdown @@ -4,16 +4,21 @@ description: "Configure a Certificate Authority and self-signed certificate to u redirect_from: /cookbook/tls_self_signed_certificate/ --- -If your Home Assistant instance is only accessible from your local network you can still protect the communication between your browsers and the frontend with SSL/TLS. -[Let's encrypt]({{site_root}}/blog/2017/09/27/effortless-encryption-with-lets-encrypt-and-duckdns/) will only work if you have a DNS entry and remote access is allowed. +If your Home Assistant instance is only accessible from your local network, you can still protect the communication between your browsers and the frontend with SSL/TLS. +[Let's Encrypt](/blog/2017/09/27/effortless-encryption-with-lets-encrypt-and-duckdns/) will only work if you have a DNS entry and remote access is allowed. -The solution is to use a self-signed certificate. As you most likely don't have a certification authority (CA) your browser will complain about the security. If you have a CA then this will not be an issue. +The solution is to use a self-signed certificate. Please note, however, that after you have completed these steps, your browser will complain about the security of the certificate as it was not issued by a trusted authority. + +* This is due to self-signed certificates having not been issued by a certification authority ([`CA`](https://cheapsslsecurity.com/blog/what-is-a-certificate-authority-ca/)). If you have your own CA, then this will not be an issue. +* A fantastic workaround for this, while keeping your instance isolated securely off the Internet, is to use a [`Certificate for SSL/TLS via domain ownership`](/docs/ecosystem/certificates/tls_domain_certificate/). + +If you don't mind the browser warnings and simply want SSL/TLS encryption and therefore have decided to use a self-signed certificate permanently or temporarily, read on! If you use Chrome browser version 58 or above and/or **don't want to have issues regarding a non-trusted CA or CN (Common Name)**, follow this full tutorial: [Create Root Certificate Authority and self-signed certificate for your Home Assistant. Compatible with Chrome browser > version 58](https://gist.github.com/tiagofreire-pt/4920be8d03a3dfa8201c6afedd00305e). Otherwise, follow this: To create a certificate locally, you need the [OpenSSL](https://www.openssl.org/) command-line tool. -Change to your Home Assistant [configuration directory](/getting-started/configuration/) like `~/.homeassistant`. This will make it easier to backup your certificate and the key. Run the command shown below. +Change to your Home Assistant [configuration directory](/getting-started/configuration/) like `~/.homeassistant`. This will make it easier to backup your certificate and the key. Run the command shown below. The certificate **must** be `.pem` extension. @@ -63,16 +68,17 @@ sudo chmod 600 fullchain.pem privkey.pem A tutorial "[Working with SSL Certificates, Private Keys and CSRs](https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs)" could give you some insight about special cases. -### iOS and macOS Specific Requirements +## iOS and macOS Specific Requirements + +### iOS -#### iOS If you are going to use this certificate with the iOS app, you need to ensure you complete **all** fields during the certificate creation process, then: * Send **only** the `fullchain.pem` file to the iOS device, using airdrop or other transfer method. * Open the `.pem` file on the iOS device, follow the prompts to trust and install it. * If you are using iOS 10.3 or newer then [additional steps](https://support.apple.com/en-us/HT204477) are needed. -#### iOS 13 and macOS 10.15 +### iOS 13 and macOS 10.15 There are [new security requirements](https://support.apple.com/en-us/HT210176) for TLS server certificates in iOS 13 and macOS 10.15. To summarize: