1
This is krb5-admin.info, produced by makeinfo version 4.5 from
4
Copyright (C) 1985-2010 by the Massachusetts Institute of Technology.
5
INFO-DIR-SECTION Kerberos
7
* krb5-admin: (krb5-admin). Kerberos V5 Administrator's Guide
11
File: krb5-admin.info, Node: dbmodules, Next: plugins, Prev: dbdefaults, Up: krb5.conf
16
Contains database specific parameters used by the database library.
17
Each tag in the [dbmodules] section of the file names a configuration
18
section for database specific parameters that can be referred to by a
19
realm. The value of the tag is a subsection where the relations in that
20
subsection define the database specific parameters.
22
For each section, the following tags may be specified in the subsection:
25
This tag indicates the name of the loadable database library. The
26
value should be `db2' for DB2 database and `kldap' for LDAP
30
This DB2-specific tag indicates the location of the database in the
31
filesystem. The default is
32
`/usr/local/var/krb5kdc/principal'.
35
If set to `true', suppresses KDC updates to the "Last successful
36
authentication" field of principal entries requiring
37
preauthentication. Setting this flag may improve performance.
38
(Principal entries which do not require preauthentication never
39
update the "Last successful authentication" field.)
42
If set to `true', suppresses KDC updates to the "Last failed
43
authentication" and "Failed password attempts" fields of principal
44
entries requiring preauthentication. Setting this flag may improve
45
performance, but also disables account lockout.
47
ldap_kerberos_container_dn
48
This LDAP specific tag indicates the DN of the container object
49
where the realm objects will be located.
52
This LDAP specific tag indicates the default bind DN for the KDC
53
server. The KDC server does a login to the directory as this
54
object. This object should have the rights to read the Kerberos
55
data in the LDAP database.
58
This LDAP specific tag indicates the default bind DN for the
59
Administration server. The administration server does a login to
60
the directory as this object. This object should have the rights
61
to read and write the Kerberos data in the LDAP database.
63
ldap_service_password_file
64
This LDAP specific tag indicates the file containing the stashed
65
passwords (created by `kdb5_ldap_util stashsrvpw') for the objects
66
used by the Kerberos servers to bind to the LDAP server. This file
70
This LDAP specific tag indicates the list of LDAP servers that the
71
Kerberos servers can connect to. The list of LDAP servers is
72
whitespace-separated. The LDAP server is specified by a LDAP URI.
73
It is recommended to use ldapi:// or ldaps:// interface to connect
77
This LDAP specific tags indicates the number of connections to be
78
maintained per LDAP server.
82
File: krb5-admin.info, Node: plugins, Next: pkinit client options, Prev: dbmodules, Up: krb5.conf
90
* kadm5_hook interface::
92
Tags in the [plugins] section can be used to register dynamic plugin
93
modules and to turn modules on and off. Not every krb5 pluggable
94
interface uses the [plugins] section; the ones that do are documented
97
Each pluggable interface corresponds to a subsection of [plugins]. All
98
subsections support the same tags:
101
This tag may have multiple values. Each value is a string of the
102
form "modulename:pathname", which causes the shared object located
103
at pathname to be registered as a dynamic module named modulename
104
for the pluggable interface. If pathname is not an absolute path,
105
it will be treated as relative to the "krb5/plugins" subdirectory
106
of the krb5 library directory.
109
This tag may have multiple values. If there are values for this
110
tag, then only the named modules will be enabled for the pluggable
114
This tag may have multiple values. If there are values for this
115
tag, then the named modules will be disabled for the pluggable
118
The following subsections are currently supported within the [plugins]
122
File: krb5-admin.info, Node: pwqual interface, Next: kadm5_hook interface, Prev: plugins, Up: plugins
127
The pwqual subsection controls modules for the password quality
128
interface, which is used to reject weak passwords when passwords are
129
changed. In addition to any registered dynamic modules, the following
130
built-in modules exist (and may be disabled with the disable tag):
133
Checks against the realm dictionary file
136
Rejects empty passwords
139
Checks against user information stored in Hesiod (only if Kerberos
140
was built with Hesiod support)
143
Checks against components of the principal name
146
File: krb5-admin.info, Node: kadm5_hook interface, Prev: pwqual interface, Up: plugins
151
The kadm5_hook interface provides plugins with information on principal
152
creation, modification, password changes and deletion. This interface
153
can be used to write a plugin to synchronize MIT Kerberos with another
154
database such as Active Directory. No plugins are built in for this
158
File: krb5-admin.info, Node: pkinit client options, Next: Sample krb5.conf File, Prev: plugins, Up: krb5.conf
165
* pkinit identity syntax::
166
* pkinit krb5.conf options::
168
The following are pkinit-specific options. Note that these values may
169
be specified in `[libdefaults]' as global defaults, or within a
170
realm-specific subsection of `[libdefaults]', or may be specified as
171
realm-specific values in the `[realms]' section. Also note that a
172
realm-specific value over-rides, does not add to, a generic
173
`[libdefaults]' specification. The search order is:
174
1. realm-specific subsection of `[libdefaults]'
177
pkinit_anchors = FILE:/usr/local/example.com.crt
180
2. realm-specific value in the `[realms]' section,
183
pkinit_anchors = FILE:/usr/local/otherrealm.org.crt
186
3. generic value in the `[libdefaults]' section.
188
pkinit_anchors = DIR:/usr/local/generic_trusted_cas/
191
File: krb5-admin.info, Node: pkinit identity syntax, Next: pkinit krb5.conf options, Prev: pkinit client options, Up: pkinit client options
193
Specifying pkinit identity information
194
......................................
196
The syntax for specifying Public Key identity, trust, and revocation
197
information for pkinit is as follows:
198
FILE:file-name[,key-file-name]
199
This option has context-specific behavior.
202
file-name specifies the name of a PEM-format file containing
203
the user's certificate. If key-file-name is not specified,
204
the user's private key is expected to be in file-name as
205
well. Otherwise, key-file-name is the name of the file
206
containing the private key.
210
file-name is assumed to be the name of an OpenSSL-style
214
This option has context-specific behavior.
217
directory-name specifies a directory with files named `*.crt'
218
and `*.key', where the first part of the file name is the
219
same for matching pairs of certificate and private key files.
220
When a file with a name ending with `.crt' is found, a
221
matching file ending with `.key' is assumed to contain the
222
private key. If no such file is found, then the certificate
223
in the `.crt' is not used.
227
directory-name is assumed to be an OpenSSL-style hashed CA
228
directory where each CA cert is stored in a file named
229
hash-of-ca-cert.#. This infrastructure is encouraged, but
230
all files in the directory will be examined and if they
231
contain certificates (in PEM format), they will be used.
234
directory-name is assumed to be an OpenSSL-style hashed CA
235
directory where each revocation list is stored in a file
236
named hash-of-ca-cert.r#. This infrastructure is encouraged,
237
but all files in the directory will be examined and if they
238
contain a revocation list (in PEM format), they will be used.
240
PKCS12:pkcs12-file-name
241
pkcs12-file-name is the name of a `PKCS #12' format file,
242
containing the user's certificate and private key.
244
PKCS11:[module_name=]module-name[:slotid=slot-id][:token=token-label][:certid=cert-id][:certlabel=cert-label]
245
All keyword/values are optional. module-name specifies the
246
location of a library implementing `PKCS #11'. If a value is
247
encountered with no keyword, it is assumed to be the module-name.
248
If no module-name is specified, the default is `opensc-pkcs11.so'.
249
slotid= and/or token= may be specified to force the use of a
250
particular smard card reader or token if there is more than one
251
available. certid= and/or certlabel= may be specified to force
252
the selection of a particular certificate on the device. See the
253
`pkinit_cert_match' configuration option for more ways to select a
254
particular certificate to use for pkinit.
256
ENV:environment-variable-name
257
environment-variable-name specifies the name of an environment
258
variable which has been set to a value conforming to one of the
259
previous values. For example, `ENV:X509_PROXY', where environment
260
variable `X509_PROXY' has been set to `FILE:/tmp/my_proxy.pem'.
263
File: krb5-admin.info, Node: pkinit krb5.conf options, Prev: pkinit identity syntax, Up: pkinit client options
265
pkinit krb5.conf options
266
........................
269
Specifies the location(s) to be used to find the user's X.509
270
identity information. This option may be specified multiple times.
271
Each value is attempted in order until identity information is
272
found and authentication is attempted. Note that these values are
273
not used if the user specifies X509_user_identity on the command
277
Specifies the location of trusted anchor (root) certificates which
278
the client trusts to sign KDC certificates. This option may be
279
specified multiple times. These values from the config file are
280
not used if the user specifies X509_anchors on the command line.
283
Specifies the location of intermediate certificates which may be
284
used by the client to complete the trust chain between a KDC
285
certificate and a trusted anchor. This option may be specified
289
Specifies the location of Certificate Revocation List (CRL)
290
information to be used by the client when verifying the validity
291
of the KDC certificate presented. This option may be specified
294
pkinit_require_crl_checking
295
The default certificate verification process will always check the
296
available revocation information to see if a certificate has been
297
revoked. If a match is found for the certificate in a CRL,
298
verification fails. If the certificate being verified is not
299
listed in a CRL, or there is no CRL present for its issuing CA,
300
and `pkinit_require_crl_checking' is `false', then verification
303
However, if `pkinit_require_crl_checking' is `true' and there is
304
no CRL information available for the issuing CA, then verification
307
`pkinit_require_crl_checking' should be set to `true' if the
308
policy is such that up-to-date CRLs must be present for every CA.
311
Specifies the size of the Diffie-Hellman key the client will
312
attempt to use. The acceptable values are currently 1024, 2048,
313
and 4096. The default is 2048.
316
This flag specifies whether the target realm is assumed to support
317
only the old, pre-RFC version of the protocol. The default is
320
pkinit_win2k_require_binding
321
If this flag is set to true, it expects that the target KDC is
322
patched to return a reply with a checksum rather than a nonce.
323
The default is false.
326
This option specifies what Extended Key Usage value the KDC
327
certificate presented to the client must contain. (Note that if
328
the KDC certificate has the pkinit SubjectAlternativeName encoded
329
as the Kerberos TGS name, EKU checking is not necessary since the
330
issuing CA has certified this as a KDC certificate.) The values
331
recognized in the `krb5.conf' file are:
333
This is the default value and specifies that the KDC must
334
have the id-pkinit-KPKdc EKU as defined in RFC4556.
337
If `kpServerAuth' is specified, a KDC certificate with the
338
id-kp-serverAuth EKU as used by Microsoft will be accepted.
341
If `none' is specified, then the KDC certificate will not be
342
checked to verify it has an acceptable EKU. The use of this
343
option is not recommended.
346
The presense of this option indicates that the client is willing to
347
accept a KDC certificate with a dNSName SAN (Subject Alternative
348
Name) rather than requiring the id-pkinit-san as defined in
349
RFC4556. This option may be specified multiple times. Its value
350
should contain the acceptable hostname for the KDC (as contained
354
Specifies matching rules that the client certificate must match
355
before it is used to attempt pkinit authentication. If a user has
356
multiple certificates available (on a smart card, or via other
357
media), there must be exactly one certificate chosen before
358
attempting pkinit authentication. This option may be specified
359
multiple times. All the available certificates are checked
360
against each rule in order until there is a match of exactly one
363
The Subject and Issuer comparison strings are the RFC2253 string
364
representations from the certificate Subject DN and Issuer DN
367
The syntax of the matching rules is:
368
[relation-operator]component-rule `...'
371
can be either `&&', meaning all component rules must match,
372
or `||', meaning only one component rule must match. The
373
default is `&&' if not specified.
376
can be one of the following. Note that there is no
377
punctuation or whitespace between component rules.
378
`<SUBJECT>'regular-expression
380
`<ISSUER>'regular-expression
382
`<SAN>'regular-expression
384
`<EKU>'extended-key-usage-list
385
where extended-key-usage-list is a comma-separated list
386
of required Extended Key Usage values. All values in
387
the list must be present in the certificate.
394
where key-usage-list is a comma-separated list of
395
required Key Usage values. All values in the list must
396
be present in the certificate.
400
pkinit_cert_match = ||<SUBJECT>.*DoE.*<SAN>.*@EXAMPLE.COM
401
pkinit_cert_match = &&<EKU>msScLogin,clientAuth<ISSUER>.*DoE.*
402
pkinit_cert_match = <EKU>msScLogin,clientAuth<KU>digitalSignature
405
File: krb5-admin.info, Node: Sample krb5.conf File, Prev: pkinit client options, Up: krb5.conf
407
Sample krb5.conf File
408
---------------------
410
Here is an example of a generic `krb5.conf' file:
413
default_realm = ATHENA.MIT.EDU
414
default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc
415
default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc
416
dns_lookup_kdc = true
417
dns_lookup_realm = false
421
kdc = kerberos.mit.edu
422
kdc = kerberos-1.mit.edu
423
kdc = kerberos-2.mit.edu:750
424
admin_server = kerberos.mit.edu
425
master_kdc = kerberos.mit.edu
426
default_domain = mit.edu
429
kdc = kerberos.example.com
430
kdc = kerberos-1.example.com
431
admin_server = kerberos.example.com
434
kdc = kerberos.mit.edu
435
admin_server = kerberos.mit.edu
436
database_module = openldap_ldapconf
440
.mit.edu = ATHENA.MIT.EDU
441
mit.edu = ATHENA.MIT.EDU
453
admin_server = FILE=/var/kadm5.log
455
ldap_kerberos_container_dn = cn=krbcontainer,dc=example,dc=com
457
openldap_ldapconf = {
459
ldap_kerberos_container_dn = cn=krbcontainer,dc=example,dc=com
460
ldap_kdc_dn = "cn=krbadmin,dc=example,dc=com"
461
# this object needs to have read rights on
462
# the realm container and principal subtrees
463
ldap_kadmind_dn = "cn=krbadmin,dc=example,dc=com"
464
# this object needs to have read and write rights on
465
# the realm container and principal subtrees
466
ldap_service_password_file = /etc/kerberos/service.keyfile
467
ldap_servers = ldaps://kerberos.mit.edu
468
ldap_conns_per_server = 5
472
File: krb5-admin.info, Node: kdc.conf, Prev: krb5.conf, Up: Configuration Files
477
The `kdc.conf' file contains KDC configuration information, including
478
defaults used when issuing Kerberos tickets. Normally, you should
479
install your `kdc.conf' file in the directory `/usr/local/var/krb5kdc'.
480
You can override the default location by setting the environment
481
variable `KRB5_KDC_PROFILE'.
483
The `kdc.conf' file is set up in the same format as the `krb5.conf'
484
file. (*Note krb5.conf::.) The `kdc.conf' file may contain any or all
485
of the following three sections:
488
Contains default values for overall behavior of the KDC.
491
Contains subsections keyed by Kerberos realm names. Each
492
subsection describes realm-specific information, including where
493
to find the Kerberos servers for that realm.
496
Contains relations which determine how Kerberos programs are to
502
* realms (kdc.conf)::
503
* pkinit kdc options::
504
* Sample kdc.conf File::
507
File: krb5-admin.info, Node: kdcdefaults, Next: realms (kdc.conf), Prev: kdc.conf, Up: kdc.conf
512
The following relation is defined in the [kdcdefaults] section:
515
This relation lists the ports on which the Kerberos server should
516
listen for UDP requests by default. This list is a comma separated
517
list of integers. If this relation is not specified, the
518
compiled-in default is 88,750, the first being the assigned
519
Kerberos port and the second which was used by Kerberos V4.
522
This relation lists the ports on which the Kerberos server should
523
listen for TCP connections by default. This list is a comma
524
separated list of integers. If this relation is not specified,
525
the compiled-in default is not to listen for TCP connections at
528
If you wish to change this (which we do not recommend, because the
529
current implementation has little protection against
530
denial-of-service attacks), the standard port number assigned for
531
Kerberos TCP traffic is port 88.
533
restrict_anonymous_to_tgt
534
This flag determines the default value of
535
restrict_anonymous_to_tgt for realms. The default value is
539
File: krb5-admin.info, Node: realms (kdc.conf), Next: pkinit kdc options, Prev: kdcdefaults, Up: kdc.conf
544
Each tag in the [realms] section of the file names a Kerberos realm.
545
The value of the tag is a subsection where the relations in that
546
subsection define KDC parameters for that particular realm.
548
For each realm, the following tags may be specified in the [realms]
552
(String.) Location of the access control list (acl) file that
553
kadmin uses to determine which principals are allowed which
554
permissions on the database. The default is
555
`/usr/local/var/krb5kdc/kadm5.acl'.
558
(String.) Location of the keytab file that the legacy
559
administration daemons `kadmind4' and `v5passwdd' use to
560
authenticate to the database. The default is
561
`/usr/local/var/krb5kdc/kadm5.keytab'.
563
default_principal_expiration
564
(Absolute time string.) Specifies the default expiration date of
565
principals created in this realm. The default value for this tag
568
default_principal_flags
569
(Flag string.) Specifies the default attributes of principals
570
created in this realm. The format for this string is a
571
comma-separated list of flags, with '+' before each flag that
572
should be enabled and '-' before each flag that should be
573
disabled. The default is postdateable, forwardable, tgt-based,
574
renewable, proxiable, dup-skey, allow-tickets, and service
577
There are a number of possible flags:
580
Enabling this flag allows the principal to obtain
581
postdateable tickets.
584
Enabling this flag allows the principal to obtain forwardable
588
Enabling this flag allows a principal to obtain tickets based
589
on a ticket-granting-ticket, rather than repeating the
590
authentication process that was used to obtain the TGT.
593
Enabling this flag allows the principal to obtain renewable
597
Enabling this flag allows the principal to obtain proxy
601
Enabling this flag allows the principal to obtain a session
602
key for another user, permitting user-to-user authentication
606
Enabling this flag means that the KDC will issue tickets for
607
this principal. Disabling this flag essentially deactivates
608
the principal within this realm.
611
If this flag is enabled on a client principal, then that
612
principal is required to preauthenticate to the KDC before
613
receiving any tickets. On a service principal, enabling this
614
flag means that service tickets for this principal will only
615
be issued to clients with a TGT that has the preauthenticated
619
If this flag is enabled, then the principal is required to
620
preauthenticate using a hardware device before receiving any
624
Enabling this flag forces a password change for this
628
Enabling this flag allows the the KDC to issue service
629
tickets for this principal.
632
If this flag is enabled, it marks this principal as a
633
password change service. This should only be used in special
634
cases, for example, if a user's password has expired, then
635
the user has to get tickets for that principal without going
636
through the normal password authentication in order to be
637
able to change the password.
641
(String.) Location of the dictionary file containing strings that
642
are not allowed as passwords. If none is specified or if there is
643
no policy assigned to the principal, no dictionary checks of
644
passwords will be performed.
647
(Port number.) Specifies the port on which the kadmind daemon is
648
to listen for this realm. The assigned port for kadmind is
652
(Port number.) Specifies the port on which the kpasswd daemon is
653
to listen for this realm. The default is 464.
656
(String.) Specifies the location where the master key has been
657
stored (via `kdb5_util stash'). The default is
658
`/usr/local/var/krb5kdc/.k5.REALM', where REALM is the Kerberos
662
(String.) Specifies the list of ports that the KDC is to listen to
663
for UDP requests for this realm. By default, the value of
664
kdc_ports as specified in the [kdcdefaults] section is used.
667
(String.) Specifies the list of ports that the KDC is to listen to
668
for TCP requests for this realm. By default, the value of
669
kdc_tcp_ports as specified in the [kdcdefaults] section is used.
672
(String.) Specifies the name of the principal associated with the
673
master key. The default is K/M.
676
(Key type string.) Specifies the master key's key type. The
677
default value for this is des3-cbc-sha1. For a list of all
678
possible values, see *Note Supported Encryption Types::.
681
(Delta time string.) Specifes the maximum time period for which a
682
ticket may be valid in this realm. The default value is
686
(Delta time string.) Specifies the maximum time period during
687
which a valid ticket may be renewed in this realm. The default
691
List of key:salt strings. Specifies the default key/salt
692
combinations of principals for this realm. Any principals created
693
through `kadmin' will have keys of these types. The default value
694
for this tag is aes256-cts-hmac-sha1-96:normal
695
aes128-cts-hmac-sha1-96:normal des3-cbc-sha1:normal
696
arcfour-hmac-md5:normal. For lists of possible values, see *Note
697
Supported Encryption Types:: and *Note Salts::.
700
A boolean value (`true', `false'). If set to `true', the KDC will
701
check the list of transited realms for cross-realm tickets against
702
the transit path computed from the realm names and the `capaths'
703
section of its `krb5.conf' file; if the path in the ticket to be
704
issued contains any realms not in the computed path, the ticket
705
will not be issued, and an error will be returned to the client
706
instead. If this value is set to `false', such tickets will be
707
issued anyways, and it will be left up to the application server to
708
validate the realm transit path.
710
If the `disable-transited-check' flag is set in the incoming
711
request, this check is not performed at all. Having the
712
`reject_bad_transit' option will cause such ticket requests to be
715
This transit path checking and config file option currently apply
716
only to TGS requests.
718
Earlier versions of the MIT release (before 1.2.3) had bugs in the
719
application server support such that the server-side checks may
720
not be performed correctly. We recommend turning this option on,
721
unless you know that all application servers in this realm have
722
been updated to fixed versions of the software, and for whatever
723
reason, you don't want the KDC to do the validation.
725
This is a per-realm option so that multiple-realm KDCs may control
726
it separately for each realm, in case (for example) one realm has
727
had the software on its application servers updated but another
730
This option defaults to `true'.
732
restrict_anonymous_to_tgt
733
A boolean value (`true', `false'). If set to `true', the KDC will
734
reject ticket requests from anonymous principals to service
735
principals other than the realm's ticket-granting service. This
736
option allows anonymous PKINIT to be enabled for use as FAST armor
737
tickets without allowing anonymous authentication to services. By
738
default, the value of restrict_anonymous_to_tgt as specified in
739
the [kdcdefaults] section is used.
743
File: krb5-admin.info, Node: pkinit kdc options, Next: Sample kdc.conf File, Prev: realms (kdc.conf), Up: kdc.conf
750
* pkinit kdc.conf options::
752
The following are pkinit-specific options. Note that these values may
753
be specified in `[kdcdefaults]' as global defaults, or within a
754
realm-specific subsection of `[realms]'. Also note that a
755
realm-specific value over-rides, does not add to, a generic
756
`[kdcdefaults]' specification. The search order is:
757
1. realm-specific subsection of `[realms]'
760
pkinit_anchors = FILE:/usr/local/example.com.crt
763
2. generic value in the `[kdcdefaults]' section.
765
pkinit_anchors = DIR:/usr/local/generic_trusted_cas/
768
File: krb5-admin.info, Node: pkinit kdc.conf options, Prev: pkinit kdc options, Up: pkinit kdc options
770
pkinit kdc.conf options
771
.......................
773
For information about the syntax of some of these options, see *Note
774
pkinit identity syntax::.
777
Specifies the location of the KDC's X.509 identity information.
778
This option is required if pkinit is to be supported by the KDC.
781
Specifies the location of trusted anchor (root) certificates which
782
the KDC trusts to sign client certificates. This option is
783
required if pkinit is to be supported by the KDC. This option may
784
be specified multiple times.
787
Specifies the location of intermediate certificates which may be
788
used by the KDC to complete the trust chain between a client's
789
certificate and a trusted anchor. This option may be specified
793
Specifies the location of Certificate Revocation List (CRL)
794
information to be used by the KDC when verifying the validity of
795
client certificates. This option may be specified multiple times.
797
pkinit_require_crl_checking
798
The default certificate verification process will always check the
799
available revocation information to see if a certificate has been
800
revoked. If a match is found for the certificate in a CRL,
801
verification fails. If the certificate being verified is not
802
listed in a CRL, or there is no CRL present for its issuing CA,
803
and `pkinit_require_crl_checking' is `false', then verification
806
However, if `pkinit_require_crl_checking' is `true' and there is
807
no CRL information available for the issuing CA, then verification
810
`pkinit_require_crl_checking' should be set to `true' if the
811
policy is such that up-to-date CRLs must be present for every CA.
814
Specifies the minimum number of bits the KDC is willing to accept
815
for a client's Diffie-Hellman key. The default is 2048.
818
Specifies that the KDC is willing to accept client certificates
819
with the Microsoft UserPrincipalName (UPN) Subject Alternative Name
820
(SAN). This means the KDC accepts the binding of the UPN in the
821
certificate to the Kerberos principal name.
823
The default is false.
825
Without this option, the KDC will only accept certificates with
826
the id-pkinit-san as defined in RFC4556. There is currently no
827
option to disable SAN checking in the KDC.
830
This option specifies what Extended Key Usage (EKU) values the KDC
831
is willing to accept in client certificates. The values
832
recognized in the `kdc.conf' file are:
834
This is the default value and specifies that client
835
certificates must have the id-pkinit-KPClientAuth EKU as
839
If `scLogin' is specified, client certificates with the
840
Microsoft Smart Card Login EKU (id-ms-kp-sc-logon) will be
844
If `none' is specified, then client certificates will not be
845
checked to verify they have an acceptable EKU. The use of
846
this option is not recommended.
849
File: krb5-admin.info, Node: Sample kdc.conf File, Prev: pkinit kdc options, Up: kdc.conf
854
Here's an example of a `kdc.conf' file:
863
max_renewable_life = 7d 0h 0m 0s
864
master_key_type = des3-hmac-sha1
865
supported_enctypes = des3-hmac-sha1:normal des-cbc-crc:normal des-cbc-crc:v4
869
kdc = FILE:/usr/local/var/krb5kdc/kdc.log
870
admin_server = FILE:/usr/local/var/krb5kdc/kadmin.log
873
File: krb5-admin.info, Node: Using DNS, Next: Administrating the Kerberos Database, Prev: Configuration Files, Up: Top
880
* Mapping Hostnames onto Kerberos Realms::
881
* Hostnames for KDCs::
884
File: krb5-admin.info, Node: Mapping Hostnames onto Kerberos Realms, Next: Hostnames for KDCs, Prev: Using DNS, Up: Using DNS
886
Mapping Hostnames onto Kerberos Realms
887
======================================
889
Mapping hostnames onto Kerberos realms is done in one of two ways.
891
The first mechanism, which has been in use for years in MIT-based
892
Kerberos distributions, works through a set of rules in the `krb5.conf'
893
configuration file. (*Note krb5.conf::.) You can specify mappings for
894
an entire domain or subdomain, and/or on a hostname-by-hostname basis.
895
Since greater specificity takes precedence, you would do this by
896
specifying the mappings for a given domain or subdomain and listing the
899
The second mechanism works by looking up the information in special
900
`TXT' records in the Domain Name Service. This is currently not used
901
by default because security holes could result if the DNS TXT records
902
were spoofed. If this mechanism is enabled on the client, it will try
903
to look up a `TXT' record for the DNS name formed by putting the prefix
904
`_kerberos' in front of the hostname in question. If that record is
905
not found, it will try using `_kerberos' and the host's domain name,
906
then its parent domain, and so forth. So for the hostname
907
BOSTON.ENGINEERING.FOOBAR.COM, the names looked up would be:
909
_kerberos.boston.engineering.foobar.com
910
_kerberos.engineering.foobar.com
914
The value of the first TXT record found is taken as the realm name.
915
(Obviously, this doesn't work all that well if a host and a subdomain
916
have the same name, and different realms. For example, if all the hosts
917
in the ENGINEERING.FOOBAR.COM domain are in the ENGINEERING.FOOBAR.COM
918
realm, but a host named ENGINEERING.FOOBAR.COM is for some reason in
919
another realm. In that case, you would set up TXT records for all
920
hosts, rather than relying on the fallback to the domain name.)
922
Even if you do not choose to use this mechanism within your site, you
923
may wish to set it up anyway, for use when interacting with other sites.
926
File: krb5-admin.info, Node: Hostnames for KDCs, Prev: Mapping Hostnames onto Kerberos Realms, Up: Using DNS
931
MIT recommends that your KDCs have a predefined set of CNAME records
932
(DNS hostname aliases), such as `kerberos' for the master KDC and
933
`kerberos-1', `kerberos-2', ... for the slave KDCs. This way, if you
934
need to swap a machine, you only need to change a DNS entry, rather
935
than having to change hostnames.
937
A new mechanism for locating KDCs of a realm through DNS has been added
938
to the MIT Kerberos V5 distribution. A relatively new record type
939
called `SRV' has been added to DNS. Looked up by a service name and a
940
domain name, these records indicate the hostname and port number to
941
contact for that service, optionally with weighting and prioritization.
942
(See RFC 2782 if you want more information. You can follow the
943
example below for straightforward cases.)
945
The use with Kerberos is fairly straightforward. The domain name used
946
in the SRV record name is the domain-style Kerberos realm name. (It is
947
possible to have Kerberos realm names that are not DNS-style names, but
948
we don't recommend it for Internet use, and our code does not support it
949
well.) Several different Kerberos-related service names are used:
952
This is for contacting any KDC by UDP. This entry will be used
953
the most often. Normally you should list port 88 on each of your
957
This is for contacting any KDC by TCP. The MIT KDC by default
958
will not listen on any TCP ports, so unless you've changed the
959
configuration or you're running another KDC implementation, you
960
should leave this unspecified. If you do enable TCP support,
961
normally you should use port 88.
963
`_kerberos-master._udp'
964
This entry should refer to those KDCs, if any, that will
965
immediately see password changes to the Kerberos database. This
966
entry is used only in one case, when the user is logging in and
967
the password appears to be incorrect; the master KDC is then
968
contacted, and the same password used to try to decrypt the
969
response, in case the user's password had recently been changed
970
and the first KDC contacted hadn't been updated. Only if that
971
fails is an "incorrect password" error given.
973
If you have only one KDC, or for whatever reason there is no
974
accessible KDC that would get database changes faster than the
975
others, you do not need to define this entry.
978
This should list port 749 on your master KDC. Support for it is
979
not complete at this time, but it will eventually be used by the
980
`kadmin' program and related utilities. For now, you will also
981
need the `admin_server' entry in `krb5.conf'. (*Note krb5.conf::.)
984
This should list port 464 on your master KDC. It is used when a
985
user changes her password.
988
Be aware, however, that the DNS SRV specification requires that the
989
hostnames listed be the canonical names, not aliases. So, for example,
990
you might include the following records in your (BIND-style) zone file:
993
_kerberos TXT "FOOBAR.COM"
995
kerberos-1 CNAME use-the-force-luke
996
kerberos-2 CNAME bunny-rabbit
997
_kerberos._udp SRV 0 0 88 daisy
998
SRV 0 0 88 use-the-force-luke
999
SRV 0 0 88 bunny-rabbit
1000
_kerberos-master._udp SRV 0 0 88 daisy
1001
_kerberos-adm._tcp SRV 0 0 749 daisy
1002
_kpasswd._udp SRV 0 0 464 daisy
1004
As with the DNS-based mechanism for determining the Kerberos realm of a
1005
host, we recommend distributing the information this way for use by
1006
other sites that may want to interact with yours using Kerberos, even if
1007
you don't immediately make use of it within your own site. If you
1008
anticipate installing a very large number of machines on which it will
1009
be hard to update the Kerberos configuration files, you may wish to do
1010
all of your Kerberos service lookups via DNS and not put the information
1011
(except for `admin_server' as noted above) in future versions of your
1012
`krb5.conf' files at all. Eventually, we hope to phase out the listing
1013
of server hostnames in the client-side configuration files; making
1014
preparations now will make the transition easier in the future.
1017
File: krb5-admin.info, Node: Administrating the Kerberos Database, Next: Configuring Kerberos with OpenLDAP back-end, Prev: Using DNS, Up: Top
1019
Administrating the Kerberos Database
1020
************************************
1022
Your Kerberos database contains all of your realm's Kerberos principals,
1023
their passwords, and other administrative information about each
1024
principal. For the most part, you will use the `kdb5_util' program to
1025
manipulate the Kerberos database as a whole, and the `kadmin' program
1026
to make changes to the entries in the database. (One notable exception
1027
is that users will use the `kpasswd' program to change their own
1028
passwords.) The `kadmin' program has its own command-line interface,
1029
to which you type the database administrating commands.
1031
`Kdb5_util' provides a means to create, delete, load, or dump a
1032
Kerberos database. It also includes a command to stash a copy of the
1033
master database key in a file on a KDC, so that the KDC can authenticate
1034
itself to the `kadmind' and `krb5kdc' daemons at boot time.
1036
`Kadmin' provides for the maintenance of Kerberos principals, KADM5
1037
policies, and service key tables (keytabs). It exists as both a
1038
Kerberos client, `kadmin', using Kerberos authentication and an RPC, to
1039
operate securely from anywhere on the network, and as a local client,
1040
`kadmin.local', intended to run directly on the KDC without Kerberos
1041
authentication. `kadmin.local' need not run on the kdc if the database
1042
is LDAP. Other than the fact that the remote client uses Kerberos to
1043
authenticate the person using it, the functionalities of the two
1044
versions are identical. The local version is necessary to enable you to
1045
set up enough of the database to be able to use the remote version. It
1046
replaces the now obsolete `kdb5_edit' (except for database dump and
1047
load, which are provided by `kdb5_util').
1049
The remote version authenticates to the KADM5 server using the service
1050
principal `kadmin/admin'. If the credentials cache contains a ticket
1051
for the `kadmin/admin' principal, and the `-c ccache' option is
1052
specified, that ticket is used to authenticate to KADM5. Otherwise,
1053
the `-p' and `-k' options are used to specify the client Kerberos
1054
principal name used to authenticate. Once kadmin has determined the
1055
principal name, it requests a `kadmin/admin' Kerberos service ticket
1056
from the KDC, and uses that service ticket to authenticate to KADM5.
1064
* Global Operations on the Kerberos Database::
1065
* Global Operations on the Kerberos LDAP Database::
1066
* Cross-realm Authentication::
1067
* Changing the krbtgt Key::
1070
File: krb5-admin.info, Node: Kadmin Options, Next: Date Format, Prev: Administrating the Kerberos Database, Up: Administrating the Kerberos Database
1075
You can invoke `kadmin' or `kadmin.local' with any of the following
1079
Use REALM as the default Kerberos realm for the database.
1082
Use the Kerberos principal principal to authenticate to Kerberos.
1083
If this option is not given, `kadmin' will append `admin' to
1084
either the primary principal name, the environment variable USER,
1085
or to the username obtained from `getpwuid', in order of
1089
Pass query directly to `kadmin'. This is useful for writing
1090
scripts that pass specific queries to `kadmin'.
1092
You can invoke `kadmin' with any of the following options:
1095
Use the keytab keytab to decrypt the KDC response instead of
1096
prompting for a password on the TTY. In this case, the principal
1097
will be `host/hostname'. If -t is not used to specify a keytab,
1098
then the default keytab will be used.
1100
-c credentials cache
1101
Use credentials_cache as the credentials cache. The credentials
1102
cache should contain a service ticket for the `kadmin/admin'
1103
service, which can be acquired with the `kinit' program. If this
1104
option is not specified, `kadmin' requests a new service ticket
1105
from the KDC, and stores it in its own temporary ccache.
1108
Use password as the password instead of prompting for one on the
1109
TTY. Note: placing the password for a Kerberos principal with
1110
administration access into a shell script can be dangerous if
1111
unauthorized users gain read access to the script.
1114
Specifies the database specific arguments.
1117
Specifies the LDAP server to connect to by a LDAP URI. It is
1118
recommend to use ldapi:// or ldaps:// interface to connect to the
1122
Specifies the Distinguished Name (DN) of the object used by the
1123
administration server to bind to the LDAP server. This object
1124
should have the read and write rights on the realm container,
1125
principal container and realm subtree.
1127
-x bindpwd=<bind_password>
1128
Specifies the password for the above mentioned binddn. It is
1129
recommended not to use this option. Instead, the password can be
1130
stashed using the stashsrvpw command of kdb5_ldap_util.
1132
Note: This database specific argument is applicable only to
1133
kadmin.local and the KADM5 server.
1135
-s admin_server[:port]
1136
Specifies the admin server that kadmin should contact.
1138
You can invoke `kadmin.local' with an of the follwing options:
1141
Specifies the name of the Kerberos database.
1144
Sets the list of cryptosystem and salt types to be used for any new
1145
keys created. See *Note Supported Encryption Types:: and *Note
1146
Salts:: for available types.
1149
Do not authenticate using a keytab. This option will cause kadmin
1150
to prompt for the master database password.
1154
File: krb5-admin.info, Node: Date Format, Next: Principals, Prev: Kadmin Options, Up: Administrating the Kerberos Database
1159
Many of the `kadmin' commands take a duration or time as an argument.
1160
The date can appear in a wide variety of formats, such as:
1175
"3/31/1992 10:00:07 PST"
1176
"January 23, 2007 10:05pm"
1179
Note that if the date specification contains spaces, you must enclose it
1180
in double quotes. Note also that you cannot use a number without a
1181
unit. (I.e., ""60 seconds"" is correct, but "60" is incorrect.) All
1182
keywords are case-insensitive. The following is a list of all of the
1186
january, jan, february, feb, march, mar, april, apr, may, june,
1187
jun, july, jul, august, aug, september, sep, sept, october, oct,
1188
november, nov, december, dec
1191
sunday, sun, monday, mon, tuesday, tues, tue, wednesday, wednes,
1192
wed, thursday, thurs, thur, thu, friday, fri, saturday, sat
1195
year, month, fortnight, week, day, hour, minute, min, second, sec
1198
tomorrow, yesterday, today, now, last, this, next, first, second,
1199
third, fourth, fifth, sixth, seventh, eighth, ninth, tenth,
1200
eleventh, twelfth, ago
1203
`kadmin' recognizes abbreviations for most of the world's time
1204
zones. A complete listing appears in *Note kadmin Time Zones::.
1206
12-hour Time Delimiters
1210
File: krb5-admin.info, Node: Principals, Next: Policies, Prev: Date Format, Up: Administrating the Kerberos Database
1215
Each entry in the Kerberos database contains a Kerberos principal
1216
(*note Definitions::) and the attributes and policies associated with
1221
* Retrieving Information About a Principal::
1223
* Adding or Modifying Principals::
1224
* Deleting Principals::
1225
* Changing Passwords::
1228
File: krb5-admin.info, Node: Retrieving Information About a Principal, Next: Privileges, Prev: Principals, Up: Principals
1230
Retrieving Information About a Principal
1231
----------------------------------------
1236
* Retrieving a List of Principals::
1239
File: krb5-admin.info, Node: Attributes, Next: Retrieving a List of Principals, Prev: Retrieving Information About a Principal, Up: Retrieving Information About a Principal
1244
To retrieve a listing of the attributes and/or policies associated with
1245
a principal, use the `kadmin' `get_principal' command, which requires
1246
the "inquire" administrative privilege. The syntax is:
1248
get_principal principal
1250
The `get_principal' command has the alias `getprinc'.
1252
For example, suppose you wanted to view the attributes of the principal
1253
`jennifer/root@ATHENA.MIT.EDU'. You would type:
1256
kadmin: getprinc jennifer/root
1257
Principal: jennifer/root@ATHENA.MIT.EDU
1258
Expiration date: [never]
1259
Last password change: Mon Jan 31 02:06:40 EDT 2002
1260
Password Expiration date: [none]
1261
Maximum ticket life: 0 days 10:00:00
1262
Maximum renewable life: 7 days 00:00:00
1263
Last modified: Wed Jul 24 14:46:25 EDT 2002 (joeadmin/admin@ATHENA.MIT.EDU)
1264
Last successful authentication: Mon Jul 29 18:20:17 EDT 2002
1265
Last failed authentication: Mon Jul 29 18:18:54 EDT 2002
1266
Failed password attempts: 3
1268
Key: vno 2, Triple DES cbc mode with HMAC/sha1, no salt
1269
Key: vno 2, DES cbc mode with CRC-32, no salt
1270
Attributes: DISALLOW_FORWARDABLE, DISALLOW_PROXIABLE
1274
The `get_principal' command has a `-terse' option, which lists the
1275
fields as a quoted, tab-separated string. For example:
1277
kadmin: getprinc -terse jennifer/root
1278
jennifer/root@ATHENA.MIT.EDU 0 1027458564
1279
0 36000 (joeadmin/admin@ATHENA.MIT.EDU
1280
1027536385 18 2 0 [none] 604800 1027980137
1281
1027980054 3 2 1 2 16 0 1
added
removed
doc/krb5-admin.info-2
