Update man pages

src/man/kadmin.man

@@ -255,12 +255,18 @@ key for another user.  \fB+allow_dup_skey\fP clears this flag.
 .B {\-|+}\fBrequires_preauth\fP
 \fB+requires_preauth\fP requires this principal to preauthenticate
 before being allowed to kinit.  \fB\-requires_preauth\fP clears this
-flag.
+flag.  When \fB+requires_preauth\fP is set on a service principal,
+the KDC will only issue service tickets for that service principal
+if the client\(aqs initial authentication was performed using
+preauthentication.
 .TP
 .B {\-|+}\fBrequires_hwauth\fP
 \fB+requires_hwauth\fP requires this principal to preauthenticate
 using a hardware device before being allowed to kinit.
-\fB\-requires_hwauth\fP clears this flag.
+\fB\-requires_hwauth\fP clears this flag.  When \fB+requires_hwauth\fP is
+set on a service principal, the KDC will only issue service tickets
+for that service principal if the client\(aqs initial authentication was
+performed using a hardware device to preauthenticate.
 .TP
 .B {\-|+}\fBok_as_delegate\fP
 \fB+ok_as_delegate\fP sets the \fBokay as delegate\fP flag on tickets
@@ -291,9 +297,22 @@ flag.
 \fB+password_changing_service\fP marks this principal as a password
 change service principal.
 .TP
+.B {\-|+}\fBok_to_auth_as_delegate\fP
+\fB+ok_to_auth_as_delegate\fP allows this principal to acquire
+forwardable tickets to itself from arbitrary users, for use with
+constrained delegation.
+.TP
+.B {\-|+}\fBno_auth_data_required\fP
+\fB+no_auth_data_required\fP prevents PAC or AD\-SIGNEDPATH data from
+being added to service tickets for the principal.
+.TP
 .B \fB\-randkey\fP
 Sets the key of the principal to a random value.
 .TP
+.B \fB\-nokey\fP
+Causes the principal to be created with no key.  New in release
+1.12.
+.TP
 .B \fB\-pw\fP \fIpassword\fP
 Sets the password of the principal to the specified string and
 does not prompt for a password.  Note: using this option in a
@@ -463,13 +482,15 @@ kadmin:
 .SS purgekeys
 .INDENT 0.0
 .INDENT 3.5
-\fBpurgekeys\fP [\fB\-keepkvno\fP \fIoldest_kvno_to_keep\fP] \fIprincipal\fP
+\fBpurgekeys\fP [\fB\-all\fP|\fB\-keepkvno\fP \fIoldest_kvno_to_keep\fP] \fIprincipal\fP
 .UNINDENT
 .UNINDENT
 .sp
 Purges previously retained old keys (e.g., from \fBchange_password
 \-keepold\fP) from \fIprincipal\fP.  If \fB\-keepkvno\fP is specified, then
-only purges keys with kvnos lower than \fIoldest_kvno_to_keep\fP.
+only purges keys with kvnos lower than \fIoldest_kvno_to_keep\fP.  If
+\fB\-all\fP is specified, then all keys are purged.  The \fB\-all\fP option
+is new in release 1.12.
 .sp
 This command requires the \fBmodify\fP privilege.
 .SS get_principal

src/man/kdc.conf.man

@@ -34,7 +34,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 The kdc.conf file supplements \fIkrb5.conf(5)\fP for programs which
 are typically only used on a KDC, such as the \fIkrb5kdc(8)\fP and
 \fIkadmind(8)\fP daemons and the \fIkdb5_util(8)\fP program.
-Relations documented here may also be specified in krb5.conf.
+Relations documented here may also be specified in krb5.conf; for the
+KDC programs mentioned, krb5.conf and kdc.conf will be merged into a
+single configuration profile.
 .sp
 Normally, the kdc.conf file is found in the KDC state directory,
 \fB@LOCALSTATEDIR@\fP\fB/krb5kdc\fP.  You can override the default location by setting the
@@ -174,8 +176,8 @@ preauthenticate using a hardware device before receiving any
 tickets.
 .TP
 .B \fBno\-auth\-data\-required\fP
-Enabling this flag prevents PAC data from being added to
-service tickets for the principal.
+Enabling this flag prevents PAC or AD\-SIGNEDPATH data from
+being added to service tickets for the principal.
 .TP
 .B \fBok\-as\-delegate\fP
 If this flag is enabled, it hints the client that credentials
@@ -229,9 +231,10 @@ authentication process that was used to obtain the TGT.
 .TP
 .B \fBdict_file\fP
 (String.)  Location of the dictionary file containing strings that
-are not allowed as passwords.  If none is specified or if there is
-no policy assigned to the principal, no dictionary checks of
-passwords will be performed.
+are not allowed as passwords.  The file should contain one string
+per line, with no additional whitespace.  If none is specified or
+if there is no policy assigned to the principal, no dictionary
+checks of passwords will be performed.
 .TP
 .B \fBhost_based_services\fP
 (Whitespace\- or comma\-separated list.)  Lists services which will
@@ -543,6 +546,82 @@ administrative server will be appended to the file
 .fi
 .UNINDENT
 .UNINDENT
+.SS [otp]
+.sp
+Each subsection of [otp] is the name of an OTP token type.  The tags
+within the subsection define the configuration required to forward a
+One Time Password request to a RADIUS server.
+.sp
+For each token type, the following tags may be specified:
+.INDENT 0.0
+.TP
+.B \fBserver\fP
+This is the server to send the RADIUS request to.  It can be a
+hostname with optional port, an ip address with optional port, or
+a Unix domain socket address.  The default is
+\fB@LOCALSTATEDIR@\fP\fB/krb5kdc\fP\fB/<name>.socket\fP.
+.TP
+.B \fBsecret\fP
+This tag indicates a filename (which may be relative to \fB@LOCALSTATEDIR@\fP\fB/krb5kdc\fP)
+containing the secret used to encrypt the RADIUS packets.  The
+secret should appear in the first line of the file by itself;
+leading and trailing whitespace on the line will be removed.  If
+the value of \fBserver\fP is a Unix domain socket address, this tag
+is optional, and an empty secret will be used if it is not
+specified.  Otherwise, this tag is required.
+.TP
+.B \fBtimeout\fP
+An integer which specifies the time in seconds during which the
+KDC should attempt to contact the RADIUS server.  This tag is the
+total time across all retries and should be less than the time
+which an OTP value remains valid for.  The default is 5 seconds.
+.TP
+.B \fBretries\fP
+This tag specifies the number of retries to make to the RADIUS
+server.  The default is 3 retries (4 tries).
+.TP
+.B \fBstrip_realm\fP
+If this tag is \fBtrue\fP, the principal without the realm will be
+passed to the RADIUS server.  Otherwise, the realm will be
+included.  The default value is \fBtrue\fP.
+.UNINDENT
+.sp
+In the following example, requests are sent to a remote server via UDP.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[otp]
+    MyRemoteTokenType = {
+        server = radius.mydomain.com:1812
+        secret = SEmfiajf42$
+        timeout = 15
+        retries = 5
+        strip_realm = true
+    }
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+An implicit default token type named \fBDEFAULT\fP is defined for when
+the per\-principal configuration does not specify a token type.  Its
+configuration is shown below.  You may override this token type to
+something applicable for your situation.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[otp]
+    DEFAULT = {
+        strip_realm = false
+    }
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .SH PKINIT OPTIONS
 .IP Note
 The following are pkinit\-specific options.  These values may

src/man/krb5.conf.man

@@ -178,12 +178,12 @@ The libdefaults section may contain any of the following relations:
 .INDENT 0.0
 .TP
 .B \fBallow_weak_crypto\fP
-If this flag is set to false, then weak encryption types will be
-filtered out of the previous three lists (as noted in
-\fIEncryption_and_salt_types\fP in \fIkdc.conf(5)\fP).  The
-default value for this tag is false, which may cause
-authentication failures in existing Kerberos infrastructures that
-do not support strong crypto.  Users in affected environments
+If this flag is set to false, then weak encryption types (as noted in
+\fIEncryption_and_salt_types\fP in \fIkdc.conf(5)\fP) will be filtered
+out of the lists \fBdefault_tgs_enctypes\fP, \fBdefault_tkt_enctypes\fP, and
+\fBpermitted_enctypes\fP.  The default value for this tag is false, which
+may cause authentication failures in existing Kerberos infrastructures
+that do not support strong crypto.  Users in affected environments
 should set this tag to true until their infrastructure adopts
 stronger ciphers.
 .TP
@@ -264,6 +264,13 @@ compatibility purposes; stale values of this setting can prevent
 clients from taking advantage of new stronger enctypes when the
 libraries are upgraded.
 .TP
+.B \fBdns_canonicalize_hostname\fP
+Indicate whether name lookups will be used to canonicalize
+hostnames for use in service principal names.  Setting this flag
+to false can improve security by reducing reliance on DNS, but
+means that short hostnames will not be canonicalized to
+fully\-qualified hostnames.  The default value is true.
+.TP
 .B \fBdns_lookup_kdc\fP
 Indicate whether DNS SRV records should be used to locate the KDCs
 and other servers for a realm, if they are not listed in the
@@ -428,7 +435,8 @@ default, if allowed by the KDC.  The default value is false.
 .B \fBrdns\fP
 If this flag is true, reverse name lookup will be used in addition
 to forward name lookup to canonicalizing hostnames for use in
-service principal names.  The default value is true.
+service principal names.  If \fBdns_canonicalize_hostname\fP is set
+to false, this flag has no effect.  The default value is true.
 .TP
 .B \fBrealm_try_domains\fP
 Indicate whether a host\(aqs domain components should be used to
@@ -590,7 +598,9 @@ The [domain_realm] section provides a translation from a domain name
 or hostname to a Kerberos realm name.  The tag name can be a host name
 or domain name, where domain names are indicated by a prefix of a
 period (\fB.\fP).  The value of the relation is the Kerberos realm name
-for that particular host or domain.  The Kerberos realm may be
+for that particular host or domain.  A host name relation implicitly
+provides the corresponding domain name relation, unless an explicit domain
+name relation is provided.  The Kerberos realm may be
 identified either in the \fI\%realms\fP section or using DNS SRV records.
 Host names and domain names should be in lower case.  For example:
 .INDENT 0.0
@@ -600,18 +610,20 @@ Host names and domain names should be in lower case.  For example:
 .ft C
 [domain_realm]
     crash.mit.edu = TEST.ATHENA.MIT.EDU
-    .mit.edu = ATHENA.MIT.EDU
+    .dev.mit.edu = TEST.ATHENA.MIT.EDU
     mit.edu = ATHENA.MIT.EDU
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-maps the host with the exact name \fBcrash.mit.edu\fP into the
-TEST.ATHENA.MIT.EDU realm.  The period prefix in \fB.mit.edu\fP denotes
-that all systems in the \fBmit.edu\fP domain belong to
-\fBATHENA.MIT.EDU\fP realm.  The third entry maps the host \fBmit.edu\fP
-itself to the \fBATHENA.MIT.EDU\fP realm.
+maps the host with the name \fBcrash.mit.edu\fP into the
+\fBTEST.ATHENA.MIT.EDU\fP realm.  The second entry maps all hosts under the
+domain \fBdev.mit.edu\fP into the \fBTEST.ATHENA.MIT.EDU\fP realm, but not
+the host with the name \fBdev.mit.edu\fP.  That host is matched
+by the third entry, which maps the host \fBmit.edu\fP and all hosts
+under the domain \fBmit.edu\fP that do not match a preceding rule
+into the realm \fBATHENA.MIT.EDU\fP.
 .sp
 If no translation entry applies to a hostname used for a service
 principal for a service ticket request, the library will try to get a
@@ -800,6 +812,12 @@ absolute path, it will be treated as relative to the
 \fBplugin_base_dir\fP value from \fI\%[libdefaults]\fP.
 .UNINDENT
 .sp
+For pluggable interfaces where module order matters, modules
+registered with a \fBmodule\fP tag normally come first, in the order
+they are registered, followed by built\-in modules in the order they
+are documented below.  If \fBenable_only\fP tags are used, then the
+order of those tags overrides the normal module order.
+.sp
 The following subsections are currently supported within the [plugins]
 section:
 .SS ccselect interface
@@ -861,6 +879,30 @@ This module implements the encrypted challenge FAST factor.
 .B \fBencrypted_timestamp\fP
 This module implements the encrypted timestamp mechanism.
 .UNINDENT
+.SS hostrealm interface
+.sp
+The hostrealm section (introduced in release 1.12) controls modules
+for the host\-to\-realm interface, which affects the local mapping of
+hostnames to realm names and the choice of default realm.  The following
+built\-in modules exist for this interface:
+.INDENT 0.0
+.TP
+.B \fBprofile\fP
+This module consults the [domain_realm] section of the profile for
+authoritative host\-to\-realm mappings, and the \fBdefault_realm\fP
+variable for the default realm.
+.TP
+.B \fBdns\fP
+This module looks for DNS records for fallback host\-to\-realm
+mappings and the default realm.  It only operates if the
+\fBdns_lookup_realm\fP variable is set to true.
+.TP
+.B \fBdomain\fP
+This module applies heuristics for fallback host\-to\-realm
+mappings.  It implements the \fBrealm_try_domains\fP variable, and
+uses the uppercased parent domain of the hostname if that does not
+produce a result.
+.UNINDENT
 .SS localauth interface
 .sp
 The localauth section (introduced in release 1.12) controls modules
@@ -869,30 +911,30 @@ between Kerberos principals and local system accounts.  The following
 built\-in modules exist for this interface:
 .INDENT 0.0
 .TP
-.B \fBauth_to_local\fP
-This module processes \fBauth_to_local\fP values in the default
-realm\(aqs section, and applies the default method if no
-\fBauth_to_local\fP values exist.
-.TP
-.B \fBan2ln\fP
-This module authorizes a principal to a local account if the
-principal name maps to the local account name.
-.TP
 .B \fBdefault\fP
 This module implements the \fBDEFAULT\fP type for \fBauth_to_local\fP
 values.
 .TP
-.B \fBk5login\fP
-This module authorizes a principal to a local account according to
-the account\(aqs \fI.k5login(5)\fP file.
+.B \fBrule\fP
+This module implements the \fBRULE\fP type for \fBauth_to_local\fP
+values.
 .TP
 .B \fBnames\fP
 This module looks for an \fBauth_to_local_names\fP mapping for the
 principal name.
 .TP
-.B \fBrule\fP
-This module implements the \fBRULE\fP type for \fBauth_to_local\fP
-values.
+.B \fBauth_to_local\fP
+This module processes \fBauth_to_local\fP values in the default
+realm\(aqs section, and applies the default method if no
+\fBauth_to_local\fP values exist.
+.TP
+.B \fBk5login\fP
+This module authorizes a principal to a local account according to
+the account\(aqs \fI.k5login(5)\fP file.
+.TP
+.B \fBan2ln\fP
+This module authorizes a principal to a local account if the
+principal name maps to the local account name.
 .UNINDENT
 .SH PKINIT OPTIONS
 .IP Note