Add documentation for new kadmin features

Add docs for the new 'extract' acl and for the new 'lockdown_keys'
principal attribute.

ticket: 8365

diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst
index be874b1a5363754acce75bea460415f4fed85d30..7ae2a3f63bb9f06f2a00e5470495fa229c1ff453 100644 (file)
--- a/doc/admin/admin_commands/kadmin_local.rst
+++ b/doc/admin/admin_commands/kadmin_local.rst
@@ -353,6 +353,17 @@ Options:
     **+no_auth_data_required** prevents PAC or AD-SIGNEDPATH data from
     being added to service tickets for the principal.
 
+{-\|+}\ **lockdown_keys**
+    **+lockdown_keys** prevents keys for this principal from leaving
+    the KDC via kadmind.  The chpass and extract operations are denied
+    for a principal with this attribute.  The chrand operation is
+    allowed, but will not return the new keys.  The delete and rename
+    operations are also denied if this attribute is set, in order to
+    prevent a malicious administrator from replacing principals like
+    krbtgt/* or kadmin/* with new principals without the attribute.
+    This attribute can be set via the network protocol, but can only
+    be removed using kadmin.local.
+
 **-randkey**
     Sets the key of the principal to a random value.
 
@@ -891,8 +902,8 @@ The options are:
 
 **-norandkey**
     Do not randomize the keys. The keys and their version numbers stay
-    unchanged.  This option is only available in kadmin.local, and
-    cannot be specified in combination with the **-e** option.
+    unchanged.  This option cannot be specified in combination with the
+    **-e** option.
 
 An entry for each of the principal's unique encryption types is added,
 ignoring multiple keys with the same encryption type but different

diff --git a/doc/admin/conf_files/kadm5_acl.rst b/doc/admin/conf_files/kadm5_acl.rst
index f5cfd2f1e995d14d76453774c42860708f8adc46..d23fb8a5789e120351f282d49285ee3e9e5d868e 100644 (file)
--- a/doc/admin/conf_files/kadm5_acl.rst
+++ b/doc/admin/conf_files/kadm5_acl.rst
@@ -57,6 +57,16 @@ ignored.  Lines containing ACL entries have the format::
     \* Same as x.
     == ======================================================
 
+.. note::
+
+        The ``extract`` privilege is not included in the wildcard
+        privilege; it must be explicitly assigned.  This privilege
+        allows the user to extract keys from the database, and must be
+        handled with great care to avoid disclosure of important keys
+        like those of the kadmin/* or krbtgt/* principals.  The
+        **lockdown_keys** principal attribute can be used to prevent
+        key extraction from specific principals regardless of the
+        granted privilege.
 
 *target_principal*
     (Optional. Partially or fully qualified Kerberos principal name.)

diff --git a/src/man/kadm5.acl.man b/src/man/kadm5.acl.man
index c53b9d169a278578ee04869fc5ffae94fb8adc61..f5daf525ab4cb49ab57f41913f8a8bce9ae8d5fb 100644 (file)
--- a/src/man/kadm5.acl.man
+++ b/src/man/kadm5.acl.man
@@ -101,6 +101,12 @@ T} T{
 T}
 _
 T{
+e
+T}     T{
+[Dis]allows the extraction of principal keys
+T}
+_
+T{
 i
 T}     T{
 [Dis]allows inquiries about principals or policies
@@ -133,7 +139,7 @@ _
 T{
 x
 T}     T{
-Short for admcilsp. All privileges
+Short for admcilsp. All privileges (except \fBe\fP)
 T}
 _
 T{
@@ -143,6 +149,22 @@ Same as x.
 T}
 _
 .TE
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The \fBextract\fP privilege is not included in the wildcard
+privilege; it must be explicitly assigned.  This privilege
+allows the user to extract keys from the database, and must be
+handled with great care to avoid disclosure of important keys
+like those of the kadmin/* or krbtgt/* principals.  The
+\fBlockdown_keys\fP principal attribute can be used to prevent
+key extraction from specific principals regardless of the
+granted privilege.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
 .TP
 .B \fItarget_principal\fP
 (Optional. Partially or fully qualified Kerberos principal name.)
@@ -240,6 +262,6 @@ tickets with a life of longer than 9 hours.
 .SH AUTHOR
 MIT
 .SH COPYRIGHT
-1985-2015, MIT
+1985-2016, MIT
 .\" Generated by docutils manpage writer.
 .

diff --git a/src/man/kadmin.man b/src/man/kadmin.man
index 631282a72b304540e67fa55a5d72ddc04f0f7d53..2730f355914d664d4921946c7965f5be372e310a 100644 (file)
--- a/src/man/kadmin.man
+++ b/src/man/kadmin.man
@@ -377,6 +377,17 @@ constrained delegation.
 \fB+no_auth_data_required\fP prevents PAC or AD\-SIGNEDPATH data from
 being added to service tickets for the principal.
 .TP
+.B {\-|+}\fBlockdown_keys\fP
+\fB+lockdown_keys\fP prevents keys for this principal from leaving
+the KDC via kadmind.  The chpass and extract operations are denied
+for a principal with this attribute.  The chrand operation is
+allowed, but will not return the new keys.  The delete and rename
+operations are also denied if this attribute is set, in order to
+prevent a malicious administrator from replacing principals like
+krbtgt/* or kadmin/* with new principals without the attribute.
+This attribute can be set via the network protocol, but can only
+be removed using kadmin.local.
+.TP
 .B \fB\-randkey\fP
 Sets the key of the principal to a random value.
 .TP
@@ -962,8 +973,8 @@ Display less verbose information.
 .TP
 .B \fB\-norandkey\fP
 Do not randomize the keys. The keys and their version numbers stay
-unchanged.  This option is only available in kadmin.local, and
-cannot be specified in combination with the \fB\-e\fP option.
+unchanged.  This option cannot be specified in combination with the
+\fB\-e\fP option.
 .UNINDENT
 .sp
 An entry for each of the principal\(aqs unique encryption types is added,
@@ -1053,6 +1064,6 @@ interface to the OpenVision Kerberos administration program.
 .SH AUTHOR
 MIT
 .SH COPYRIGHT
-1985-2015, MIT
+1985-2016, MIT
 .\" Generated by docutils manpage writer.
 .