From b52acabf478e8d1aa19f7823aade81eed1553143 Mon Sep 17 00:00:00 2001 From: Nalin Dahyabhai Date: Tue, 22 Apr 2014 16:31:14 -0400 Subject: Add some longer-form docs for HTTPS Add some longer-form documentation for the new HTTPS support, walking a prospective administrator through generating a bare minimal signing setup, deploying a WSGI-based proxy server onto an Apache httpd server using mod_ssl and mod_wsgi, and configuring clients to use it. ticket: 7929 --- doc/admin/https.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/admin/index.rst | 1 + 2 files changed, 49 insertions(+) create mode 100644 doc/admin/https.rst diff --git a/doc/admin/https.rst b/doc/admin/https.rst new file mode 100644 index 000000000..b4e68b2b2 --- /dev/null +++ b/doc/admin/https.rst @@ -0,0 +1,48 @@ +.. _https: + +HTTPS proxy configuration +========================= + +In addition to being able to use UDP or TCP to communicate directly +with a KDC as is outlined in RFC4120, and with kpasswd services in a +similar fashion, the client libraries can attempt to use an HTTPS +proxy server to communicate with a KDC or kpasswd service, using the +protocol outlined in [MS-KKDCP]. + +Communicating with a KDC through an HTTPS proxy allows clients to +contact servers when network firewalls might otherwise prevent them +from doing so. The use of TLS also encrypts all traffic between the +clients and the KDC, preventing observers from conducting password +dictionary attacks or from observing the client and server principals +being authenticated, at additional computational cost to both clients +and servers. + +An HTTPS proxy server is provided as a feature in some versions of +Microsoft Windows Server, and a WSGI implementation named `kdcproxy` +is available in the python package index. + + +Configuring the clients +----------------------- + +To use an HTTPS proxy, a client host must trust the CA which issued +that proxy's SSL certificate. If that CA's certificate is not in the +system-wide default set of trusted certificates, configure the +following relation in the client host's :ref:`krb5.conf(5)` file in +the appropriate :ref:`realms` subsection:: + + http_anchors = FILE:/etc/krb5/cacert.pem + +Adjust the pathname to match the path of the file which contains a +copy of the CA's certificate. The `http_anchors` option is documented +more fully in :ref:`krb5.conf(5)`. + +Configure the client to access the KDC and kpasswd service by +specifying their locations in its :ref:`krb5.conf(5)` file in the form +of HTTPS URLs for the proxy server:: + + kdc = https://server.fqdn/KdcProxy + kpasswd_server = https://server.fqdn/KdcProxy + +If the proxy and client are properly configured, client commands such +as ``kinit``, ``kvno``, and ``kpasswd`` should all function normally. diff --git a/doc/admin/index.rst b/doc/admin/index.rst index 3406843b1..3cd57f524 100644 --- a/doc/admin/index.rst +++ b/doc/admin/index.rst @@ -17,6 +17,7 @@ For administrators otp.rst princ_dns.rst enctypes.rst + https.rst .. toctree:: :maxdepth: 1 -- cgit