1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
From b52acabf478e8d1aa19f7823aade81eed1553143 Mon Sep 17 00:00:00 2001
From: Nalin Dahyabhai <nalin@dahyabhai.net>
Date: Tue, 22 Apr 2014 16:31:14 -0400
Subject: [PATCH 10/13] 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 0000000..b4e68b2
--- /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 3406843..3cd57f5 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
--
2.1.0
|
