Update the tls documentation (#1061)

* Update the tls documentation

* cant test corefile because we dont have pem data

* Add note on client support

1 files changed, 26 insertions, 5 deletions

diff --git a/middleware/tls/README.md b/middleware/tls/README.md
index bb7494eb8..a5c02c4c7 100644
--- a/middleware/tls/README.md
+++ b/middleware/tls/README.md
@@ -3,6 +3,19 @@
 *tls* allows you to configure the server certificates for the TLS and gRPC servers.
 For other types of servers it is ignored.
 
+CoreDNS supports queries that are encrypted using TLS (DNS over Transport Layer Security, RFC 7858)
+or are using gRPC (https://grpc.io/, not an IETF standard). Normally DNS traffic isn't encrypted at
+all (DNSSEC only signs resource records).
+
+The *proxy* middleware also support gRPC (`protocol gRPC`), meaning you can chain CoreDNS servers
+using this protocol.
+
+The *tls* "middleware" allows you to configure the cryptographic keys that are needed for both
+DNS-over-TLS and DNS-over-gRPC. If the `tls` directive is omitted, then no encryption takes place.
+
+The gRPC protobuffer is defined in `pb/dns.proto`. It defines the proto as a simple wrapper for the
+wire data of a DNS message.
+
 ## Syntax
 
 ~~~ txt
@@ -11,21 +24,29 @@ tls CERT KEY CA
 
 ## Examples
 
-Start a DNS-over-TLS server.
+Start a DNS-over-TLS server that picks up incoming DNS-over-TLS queries on port 5553 and uses the
+nameservers defined in `/etc/resolv.conf` to resolve the query. This proxy path uses plain old DNS.
 
 ~~~
-tls://.:4453 {
+tls://.:5553 {
 	tls cert.pem key.pem ca.pem
 	proxy . /etc/resolv.conf
 }
 ~~~
 
-Start a DNS-over-gRPC server. If the `tls` directive were omitted, then
-it would use plain HTTP not HTTPS.
+Start a DNS-over-gRPC server that is similar to the previous example, but using DNS-over-gRPC for
+incoming queries.
 
 ~~~
-grpc://.:443 {
+grpc://. {
 	tls cert.pem key.pem ca.pem
 	proxy . /etc/resolv.conf
 }
 ~~~
+
+Only Knot DNS' `kdig` supports DNS-over-TLS queries, no command line client supports gRPC making
+debugging these transports harder than it should be.
+
+## Also See
+
+RFC 7858 and https://grpc.io.