diff options
Diffstat (limited to 'doc/pdf/admin.tex')
| -rw-r--r-- | doc/pdf/admin.tex | 163 |
1 files changed, 133 insertions, 30 deletions
diff --git a/doc/pdf/admin.tex b/doc/pdf/admin.tex index 1cf190826169..62ce0e0358b8 100644 --- a/doc/pdf/admin.tex +++ b/doc/pdf/admin.tex @@ -15,7 +15,7 @@ \title{Kerberos Administration Guide} \date{ } -\release{1.15.1} +\release{1.16} \author{MIT} \newcommand{\sphinxlogo}{} \renewcommand{\releasename}{Release} @@ -939,9 +939,10 @@ includedir DIRNAME directory must exist and be readable. Including a directory includes all files within the directory whose names consist solely of alphanumeric characters, dashes, or underscores. Starting in release -1.15, files with names ending in ''.conf'' are also included. Included -profile files are syntactically independent of their parents, so each -included file must begin with a section header. +1.15, files with names ending in ''.conf'' are also included, unless the +name begins with ''.''. Included profile files are syntactically +independent of their parents, so each included file must begin with a +section header. The krb5.conf file can specify that configuration should be obtained from a loadable module, rather than the file itself, using the @@ -1075,7 +1076,7 @@ the client should request when making a TGS-REQ, in order of preference from highest to lowest. The list may be delimited with commas or whitespace. See {\hyperref[admin/conf_files/kdc_conf:encryption-types]{\emph{Encryption types}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} for a list of the accepted values for this tag. -The default value is \code{aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4}, but single-DES encryption types +The default value is \code{aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4}, but single-DES encryption types will be implicitly removed from this list if the value of \textbf{allow\_weak\_crypto} is false. @@ -1089,7 +1090,7 @@ Identifies the supported list of session key encryption types that the client should request when making an AS-REQ, in order of preference from highest to lowest. The format is the same as for default\_tgs\_enctypes. The default value for this tag is -\code{aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4}, but single-DES encryption types will be implicitly +\code{aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4}, but single-DES encryption types will be implicitly removed from this list if the value of \textbf{allow\_weak\_crypto} is false. @@ -1171,7 +1172,7 @@ For security reasons, .k5login files must be owned by the local user or by root. \item[{\textbf{kcm\_mach\_service}}] \leavevmode -On OS X only, determines the name of the bootstrap service used to +On macOS only, determines the name of the bootstrap service used to contact the KCM daemon for the KCM credential cache type. If the value is \code{-}, Mach RPC will not be used to contact the KCM daemon. The default value is \code{org.h5l.kcm}. @@ -1263,7 +1264,7 @@ used across NATs. The default value is true. \item[{\textbf{permitted\_enctypes}}] \leavevmode Identifies all encryption types that are permitted for use in session key encryption. The default value for this tag is -\code{aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4}, but single-DES encryption types will be implicitly +\code{aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4}, but single-DES encryption types will be implicitly removed from this list if the value of \textbf{allow\_weak\_crypto} is false. @@ -1699,6 +1700,10 @@ client principal Uses the service realm to guess an appropriate cache from the collection +\item[{\textbf{hostname}}] \leavevmode +If the service principal is host-based, uses the service hostname +to guess an appropriate cache from the collection + \end{description} @@ -1731,6 +1736,26 @@ principal creation, modification, password changes and deletion. This interface can be used to write a plugin to synchronize MIT Kerberos with another database such as Active Directory. No plugins are built in for this interface. + + +\subparagraph{kadm5\_auth interface} +\label{admin/conf_files/krb5_conf:kadm5-auth-interface}\label{admin/conf_files/krb5_conf:kadm5-auth} +The kadm5\_auth section (introduced in release 1.16) controls modules +for the kadmin authorization interface, which determines whether a +client principal is allowed to perform a kadmin operation. The +following built-in modules exist for this interface: +\begin{description} +\item[{\textbf{acl}}] \leavevmode +This module reads the {\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}} file, and authorizes +operations which are allowed according to the rules in the file. + +\item[{\textbf{self}}] \leavevmode +This module authorizes self-service operations including password +changes, creation of new random keys, fetching the client's +principal record or string attributes, and fetching the policy +record associated with the client principal. + +\end{description} \phantomsection\label{admin/conf_files/krb5_conf:clpreauth} \subparagraph{clpreauth and kdcpreauth interfaces} @@ -1812,6 +1837,32 @@ principal name maps to the local account name. \end{description} +\subparagraph{certauth interface} +\label{admin/conf_files/krb5_conf:certauth}\label{admin/conf_files/krb5_conf:certauth-interface} +The certauth section (introduced in release 1.16) controls modules for +the certificate authorization interface, which determines whether a +certificate is allowed to preauthenticate a user via PKINIT. The +following built-in modules exist for this interface: +\begin{description} +\item[{\textbf{pkinit\_san}}] \leavevmode +This module authorizes the certificate if it contains a PKINIT +Subject Alternative Name for the requested client principal, or a +Microsoft UPN SAN matching the principal if \textbf{pkinit\_allow\_upn} +is set to true for the realm. + +\item[{\textbf{pkinit\_eku}}] \leavevmode +This module rejects the certificate if it does not contain an +Extended Key Usage attribute consistent with the +\textbf{pkinit\_eku\_checking} value for the realm. + +\item[{\textbf{dbmatch}}] \leavevmode +This module authorizes or rejects the certificate according to +whether it matches the \textbf{pkinit\_cert\_match} string attribute on +the client principal, if that attribute is present. + +\end{description} + + \subsubsection{PKINIT options} \label{admin/conf_files/krb5_conf:pkinit-options} \begin{notice}{note}{Note:} @@ -2345,9 +2396,10 @@ The following tags may be specified in a {[}realms{]} subsection: \item[{\textbf{acl\_file}}] \leavevmode (String.) Location of the access control list file that {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} uses to determine which principals are allowed -which permissions on the Kerberos database. The default value is -{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/kadm5.acl}. For more information on Kerberos ACL -file see {\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}}. +which permissions on the Kerberos database. To operate without an +ACL file, set this relation to the empty string with \code{acl\_file = +""}. The default value is {\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/kadm5.acl}. For more +information on Kerberos ACL file see {\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}}. \item[{\textbf{database\_module}}] \leavevmode (String.) This relation indicates the name of the configuration @@ -2459,6 +2511,11 @@ 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. +\item[{\textbf{encrypted\_challenge\_indicator}}] \leavevmode +(String.) Specifies the authentication indicator value that the KDC +asserts into tickets obtained using FAST encrypted challenge +pre-authentication. New in 1.16. + \item[{\textbf{host\_based\_services}}] \leavevmode (Whitespace- or comma-separated list.) Lists services which will get host-based referral processing even if the server principal is @@ -3073,9 +3130,6 @@ Specifies an authentication indicator to include in the ticket if pkinit is used to authenticate. This option may be specified multiple times. (New in release 1.14.) -\item[{\textbf{pkinit\_kdc\_ocsp}}] \leavevmode -Specifies the location of the KDC's OCSP. - \item[{\textbf{pkinit\_pool}}] \leavevmode Specifies the location of intermediate certificates which may be used by the KDC to complete the trust chain between a client's @@ -3203,7 +3257,7 @@ The triple DES family: des3-cbc-sha1 \hline aes & -The AES family: aes256-cts-hmac-sha1-96 and aes128-cts-hmac-sha1-96 +The AES family: aes256-cts-hmac-sha1-96, aes128-cts-hmac-sha1-96, aes256-cts-hmac-sha384-192, and aes128-cts-hmac-sha256-128 \\ \hline rc4 @@ -3523,16 +3577,17 @@ joeadmin/*@ATHENA.MIT.EDU i */root@ATHENA.MIT.EDU \PYGZsh{} line 3 sms@ATHENA.MIT.EDU x * \PYGZhy{}maxlife 9h \PYGZhy{}postdateable \PYGZsh{} line 6 \end{Verbatim} -(line 1) Any principal in the \code{ATHENA.MIT.EDU} realm with -an \code{admin} instance has all administrative privileges. +(line 1) Any principal in the \code{ATHENA.MIT.EDU} realm with an +\code{admin} instance has all administrative privileges except extracting +keys. -(lines 1-3) The user \code{joeadmin} has all permissions with his -\code{admin} instance, \code{joeadmin/admin@ATHENA.MIT.EDU} (matches line -1). He has no permissions at all with his null instance, -\code{joeadmin@ATHENA.MIT.EDU} (matches line 2). His \code{root} and other -non-\code{admin}, non-null instances (e.g., \code{extra} or \code{dbadmin}) have -inquire permissions with any principal that has the instance \code{root} -(matches line 3). +(lines 1-3) The user \code{joeadmin} has all permissions except +extracting keys with his \code{admin} instance, +\code{joeadmin/admin@ATHENA.MIT.EDU} (matches line 1). He has no +permissions at all with his null instance, \code{joeadmin@ATHENA.MIT.EDU} +(matches line 2). His \code{root} and other non-\code{admin}, non-null +instances (e.g., \code{extra} or \code{dbadmin}) have inquire permissions +with any principal that has the instance \code{root} (matches line 3). (line 4) Any \code{root} principal in \code{ATHENA.MIT.EDU} can inquire or change the password of their null instance, but not any other @@ -3546,9 +3601,22 @@ permission can only be granted globally, not to specific target principals. (line 6) Finally, the Service Management System principal -\code{sms@ATHENA.MIT.EDU} has all permissions, but any principal that it -creates or modifies will not be able to get postdateable tickets or -tickets with a life of longer than 9 hours. +\code{sms@ATHENA.MIT.EDU} has all permissions except extracting keys, but +any principal that it creates or modifies will not be able to get +postdateable tickets or tickets with a life of longer than 9 hours. + + +\subsubsection{MODULE BEHAVIOR} +\label{admin/conf_files/kadm5_acl:module-behavior} +The ACL file can coexist with other authorization modules in release +1.16 and later, as configured in the {\hyperref[admin/conf_files/krb5_conf:kadm5-auth]{\emph{kadm5\_auth interface}}} section of +{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}. The ACL file will positively authorize +operations according to the rules above, but will never +authoritatively deny an operation, so other modules can authorize +operations in addition to those authorized by the ACL file. + +To operate without an ACL file, set the \emph{acl\_file} variable in +{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} to the empty string with \code{acl\_file = ""}. \subsubsection{SEE ALSO} @@ -3787,7 +3855,7 @@ convey more information about a realm's KDCs with a single query. The client performs a query for the following URI records: \begin{itemize} \item {} -\code{\_kerberos.REALM} for fiding KDCs. +\code{\_kerberos.REALM} for finding KDCs. \item {} \code{\_kerberos-adm.REALM} for finding kadmin services. @@ -7002,6 +7070,29 @@ time as follows: kadmin \PYGZhy{}q \PYGZsq{}add\PYGZus{}principal +requires\PYGZus{}preauth \PYGZhy{}nokey YOUR\PYGZus{}PRINCNAME\PYGZsq{} \end{Verbatim} +By default, the KDC requires PKINIT client certificates to have the +standard Extended Key Usage and Subject Alternative Name attributes +for PKINIT. Starting in release 1.16, it is possible to authorize +client certificates based on the subject or other criteria instead of +the standard PKINIT Subject Alternative Name, by setting the +\textbf{pkinit\_cert\_match} string attribute on each client principal entry. +For example: + +\begin{Verbatim}[commandchars=\\\{\}] +kadmin set\PYGZus{}string user@REALM pkinit\PYGZus{}cert\PYGZus{}match \PYGZdq{}\PYGZlt{}SUBJECT\PYGZgt{}CN=user@REALM\PYGZdl{}\PYGZdq{} +\end{Verbatim} + +The \textbf{pkinit\_cert\_match} string attribute follows the syntax used by +the {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} \textbf{pkinit\_cert\_match} relation. To allow the +use of non-PKINIT client certificates, it will also be necessary to +disable key usage checking using the \textbf{pkinit\_eku\_checking} relation; +for example: + +\begin{Verbatim}[commandchars=\\\{\}] +[kdcdefaults] + pkinit\PYGZus{}eku\PYGZus{}checking = none +\end{Verbatim} + \section{Configuring the clients} \label{admin/pkinit:configuring-the-clients} @@ -8328,6 +8419,13 @@ Enables One Time Passwords (OTP) preauthentication for a client \emph{principal}. The \emph{value} is a JSON string representing an array of objects, each having optional \code{type} and \code{username} fields. +\item[{\textbf{pkinit\_cert\_match}}] \leavevmode +Specifies a matching expression that defines the certificate +attributes required for the client certificate used by the +principal during PKINIT authentication. The matching expression +is in the same format as those used by the \textbf{pkinit\_cert\_match} +option in {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}. (New in release 1.16.) + \end{description} This command requires the \textbf{modify} privilege. @@ -9992,6 +10090,7 @@ Specifies the location of the keytab file. {[}\textbf{-F} \emph{principal\_database}{]} {[}\textbf{-p} \emph{kdb5\_util\_prog}{]} {[}\textbf{-P} \emph{port}{]} +{[}\textbf{--pid-file}=\emph{pid\_file}{]} {[}\textbf{-d}{]} {[}\textbf{-t}{]} @@ -10081,6 +10180,10 @@ is only useful in combination with the \textbf{-S} option. Allows the user to specify the path to the kpropd.acl file; by default the path used is {\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/kpropd.acl}. +\item[{\textbf{--pid-file}=\emph{pid\_file}}] \leavevmode +In standalone mode, write the process ID of the daemon into +\emph{pid\_file}. + \end{description} @@ -10299,7 +10402,7 @@ Alias: \textbf{delent} \label{admin/admin_commands/ktutil:add-entry}\begin{quote} \textbf{add\_entry} \{\textbf{-key}\textbar{}\textbf{-password}\} \textbf{-p} \emph{principal} -\textbf{-k} \emph{kvno} \textbf{-e} \emph{enctype} +\textbf{-k} \emph{kvno} \textbf{-e} \emph{enctype} {[}\textbf{-s} \emph{salt}{]} \end{quote} Add \emph{principal} to keylist using key or password. @@ -10623,7 +10726,7 @@ Default {\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{keysalt list}} \hline Permitted enctypes & -\code{aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4} +\code{aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4} & \\ \hline KDC default port |