From 66995f9ce0ff28bd01bd22dd9d17d83847e7de34 Mon Sep 17 00:00:00 2001 From: Remi Gacogne Date: Wed, 28 Aug 2019 11:17:18 +0200 Subject: [PATCH] dnsdist: Fix some syntax errors in the OCSP stapling guide --- pdns/dnsdistdist/docs/guides/ocsp-stapling.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/pdns/dnsdistdist/docs/guides/ocsp-stapling.rst b/pdns/dnsdistdist/docs/guides/ocsp-stapling.rst index 5fc815199..761525715 100644 --- a/pdns/dnsdistdist/docs/guides/ocsp-stapling.rst +++ b/pdns/dnsdistdist/docs/guides/ocsp-stapling.rst @@ -1,8 +1,8 @@ OCSP Stapling ============= -dnsdist supports OCSP stapling for DNS over HTTPS and DNS over TLS since 1.4.0-rc1. OCSP, Online Certificate Status Protocol (:rfc:`RFC 6960`) is a protocol allowing a client to check the expiration status of a certificate from the certification authority (CA) that delivered it. -Since the requirement for the client to first retrieve the certificate then do additional steps to gather an OCSP response is not very efficient, and also discloses to the CA which certificate is validated, a mechanism has been designed to allow the server to retrieve the OCSP response from the CA and provide it to the client during the TLS exchange. This mechanism is named the TLS Certificate Status Request extension (:rfc:`RFC 6066`), also known as OCSP stapling. +dnsdist supports OCSP stapling for DNS over HTTPS and DNS over TLS since 1.4.0-rc1. OCSP, Online Certificate Status Protocol (:rfc:`6960`) is a protocol allowing a client to check the expiration status of a certificate from the certification authority (CA) that delivered it. +Since the requirement for the client to first retrieve the certificate then do additional steps to gather an OCSP response is not very efficient, and also discloses to the CA which certificate is validated, a mechanism has been designed to allow the server to retrieve the OCSP response from the CA and provide it to the client during the TLS exchange. This mechanism is named the TLS Certificate Status Request extension (:rfc:`6066`), also known as OCSP stapling. While OCSP stapling is a net win for the client, it means that the server needs to retrieve the OCSP response itself and update it at regular interval, since the OCSP response tends to be short-lived by design. @@ -14,11 +14,13 @@ Local PKI When a local PKI is used to issue the certificate, or for testing purposes, dnsdist provides the :func:`generateOCSPResponse` function to generate an OCSP response file for a certificate, using the certificate and private key of the certification authority that signed that certificate: .. code-block:: lua + generateOCSPResponse(pathToServerCertificate, pathToCACertificate, pathToCAPrivateKey, outputFile, numberOfDaysOfValidity, numberOfMinutesOfValidity) The resulting file can be directly used with the :func:`addDOHLocal` or the :func:`addTLSLocal` functions: .. code-block:: lua + addDOHLocal("127.0.0.1:443", "/path/to/the/server/certificate", "/path/to/the/server/private/key", { "/" }, { ocspResponses={"/path/to/generated/ocsp/response"}}) addTLSLocal("127.0.0.1:853", "/path/to/the/server/certificate", "/path/to/the/server/private/key", { ocspResponses={"/path/to/generated/ocsp/response"}}) @@ -34,6 +36,7 @@ One of those options is to the use the OpenSSL ocsp command-line tool, although The first step is to retrieve the URL at which the CA provides an OCSP responder. This can be done via the OpenSSL x509 command: .. code-block:: sh + openssl x509 -noout -ocsp_uri -in /path/to/the/server/certificate It will output something like "http://ocsp.int-x3.letsencrypt.org". @@ -41,16 +44,19 @@ It will output something like "http://ocsp.int-x3.letsencrypt.org". Now we can use the OCSP tool to request an OCSP response for this certificate from the CA, provided that we have the certificate of the CA at hand, but it's usually needed to get a correct chain of certificates anyway: .. code-block:: sh + openssl ocsp -issuer /path/to/the/ca/certificate -cert /path/to/the/server/certificate -text -url url/we/retrieved/earlier -respout /path/to/write/the/OCSP/response If everything goes well, this results in an OCSP response for the server certificate being written to /path/to/write/the/OCSP/response. It seems that earlier versions of OpenSSL did not properly handle the URL, and one needed to split the host and path parts of the OCSP URL, and use the ``-header`` option of the ocsp command: .. code-block:: sh + openssl ocsp -issuer /path/to/the/ca/certificate -cert /path/to/the/server/certificate -text -url -header 'Host' -respout /path/to/write/the/OCSP/response We can now use it directly with the :func:`addDOHLocal` or the :func:`addTLSLocal` functions: .. code-block:: lua + addDOHLocal("127.0.0.1:443", "/path/to/the/server/certificate", "/path/to/the/server/private/key", { "/" }, { ocspResponses={"/path/to/write/the/OCSP/response"}}) addTLSLocal("127.0.0.1:853", "/path/to/the/server/certificate", "/path/to/the/server/private/key", { ocspResponses={"/path/to/write/the/OCSP/response"}}) @@ -62,6 +68,7 @@ Testing Once a valid OCSP response has retrieved and loaded into dnsdist, it is possible to test that everything is working fine using the OpenSSL s_client command: .. code-block:: sh + openssl s_client -connect -status -servername | grep -F 'OCSP Response Status' should return something like ``OCSP Response Status: successful (0x0)``, indicating that the client received a valid OCSP stapling response from the server. -- 2.40.0