1@c $Id: setup.texi,v 1.27.2.2 2003/10/21 21:37:56 lha Exp $ 2 3@node Setting up a realm, Things in search for a better place, Building and Installing, Top 4 5@chapter Setting up a realm 6 7@menu 8* Configuration file:: 9* Creating the database:: 10* keytabs:: 11* Serving Kerberos 4/524/kaserver:: 12* Remote administration:: 13* Password changing:: 14* Testing clients and servers:: 15* Slave Servers:: 16* Incremental propagation:: 17* Salting:: 18* Cross realm:: 19* Transit policy:: 20* Setting up DNS:: 21@end menu 22 23A 24@cindex realm 25realm is an administrative domain. The name of a Kerberos realm is 26usually the Internet domain name in uppercase. Call your realm the same 27as your Internet domain name if you do not have strong reasons for not 28doing so. It will make life easier for you and everyone else. 29 30@node Configuration file, Creating the database, Setting up a realm, Setting up a realm 31@section Configuration file 32 33To setup a realm you will first have to create a configuration file: 34@file{/etc/krb5.conf}. The @file{krb5.conf} file can contain many 35configuration options, some of which are described here. 36 37There is a sample @file{krb5.conf} supplied with the distribution. 38 39The configuration file is a hierarchical structure consisting of 40sections, each containing a list of bindings (either variable 41assignments or subsections). A section starts with 42@samp{[section-name]}. A binding consists of a left hand side, an equal 43(@samp{=}) and a right hand side (the left hand side tag must be 44separated from the equal with some whitespace.) Subsections has a 45@samp{@{} as the first non-whitespace character after the equal. All 46other bindings are treated as variable assignments. The value of a 47variable extends to the end of the line. 48 49@example 50[section1] 51 a-subsection = @{ 52 var = value1 53 other-var = value with @{@} 54 sub-sub-section = @{ 55 var = 123 56 @} 57 @} 58 var = some other value 59[section2] 60 var = yet another value 61@end example 62 63In this manual, names of sections and bindings will be given as strings 64separated by slashes (@samp{/}). The @samp{other-var} variable will thus 65be @samp{section1/a-subsection/other-var}. 66 67For in-depth information about the contents of the configuration file, refer to 68the @file{krb5.conf} manual page. Some of the more important sections 69are briefly described here. 70 71The @samp{libdefaults} section contains a list of library configuration 72parameters, such as the default realm and the timeout for KDC 73responses. The @samp{realms} section contains information about specific 74realms, such as where they hide their KDC. This section serves the same 75purpose as the Kerberos 4 @file{krb.conf} file, but can contain more 76information. Finally the @samp{domain_realm} section contains a list of 77mappings from domains to realms, equivalent to the Kerberos 4 78@file{krb.realms} file. 79 80To continue with the realm setup, you will have to create a configuration file, 81with contents similar to the following. 82 83@example 84[libdefaults] 85 default_realm = MY.REALM 86[realms] 87 MY.REALM = @{ 88 kdc = my.kdc my.slave.kdc 89 kdc = my.third.kdc 90 @} 91[domain_realm] 92 .my.domain = MY.REALM 93 94@end example 95 96If you use a realm name equal to your domain name, you can omit the 97@samp{libdefaults}, and @samp{domain_realm}, sections. If you have a 98SRV-record for your realm, or your Kerberos server has CNAME called 99@samp{kerberos.my.realm}, you can omit the @samp{realms} section too. 100 101@node Creating the database, keytabs, Configuration file, Setting up a realm 102@section Creating the database 103 104The database library will look for the database in the directory 105@file{/var/heimdal}, so you should probably create that directory. 106Make sure the directory have restrictive permissions. 107 108@example 109# mkdir /var/heimdal 110@end example 111 112The keys of all the principals are stored in the database. If you 113choose to, these can be encrypted with a master key. You do not have to 114remember this key (or password), but just to enter it once and it will 115be stored in a file (@file{/var/heimdal/m-key}). If you want to have a 116master key, run @samp{kstash} to create this master key: 117 118@example 119# kstash 120Master key: 121Verifying password - Master key: 122@end example 123 124To initialise the database use the @code{kadmin} program, with the 125@samp{-l} option (to enable local database mode). First issue a 126@kbd{init MY.REALM} command. This will create the database and insert 127default principals for that realm. You can have more than one realm in 128one database, so @samp{init} does not destroy any old database. 129 130Before creating the database, @samp{init} will ask you some questions 131about max ticket lifetimes. 132 133After creating the database you should probably add yourself to it. You 134do this with the @samp{add} command. It takes as argument the name of a 135principal. The principal should contain a realm, so if you haven't setup 136a default realm, you will need to explicitly include the realm. 137 138@example 139# kadmin -l 140kadmin> init MY.REALM 141Realm max ticket life [unlimited]: 142Realm max renewable ticket life [unlimited]: 143kadmin> add me 144Max ticket life [unlimited]: 145Max renewable life [unlimited]: 146Attributes []: 147Password: 148Verifying password - Password: 149@end example 150 151Now start the KDC and try getting a ticket. 152 153@example 154# kdc & 155# kinit me 156me@@MY.REALMS's Password: 157# klist 158Credentials cache: /tmp/krb5cc_0 159 Principal: me@@MY.REALM 160 161 Issued Expires Principal 162Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@@MY.REALM 163@end example 164 165If you are curious you can use the @samp{dump} command to list all the 166entries in the database. It should look something similar to the 167following example (note that the entries here are truncated for 168typographical reasons): 169 170@smallexample 171kadmin> dump 172me@@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ... 173kadmin/admin@@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ... 174krbtgt/MY.REALM@@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ... 175kadmin/changepw@@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ... 176@end smallexample 177 178@node keytabs, Serving Kerberos 4/524/kaserver, Creating the database, Setting up a realm 179@section keytabs 180 181To extract a service ticket from the database and put it in a keytab you 182need to first create the principal in the database with @samp{ank} 183(using the @kbd{--random-key} flag to get a random key) and then 184extract it with @samp{ext_keytab}. 185 186@example 187kadmin> add --random-key host/my.host.name 188Max ticket life [unlimited]: 189Max renewable life [unlimited]: 190Attributes []: 191kadmin> ext host/my.host.name 192# ktutil list 193Version Type Principal 194 1 des-cbc-md5 host/my.host.name@@MY.REALM 195 1 des-cbc-md4 host/my.host.name@@MY.REALM 196 1 des-cbc-crc host/my.host.name@@MY.REALM 197 1 des3-cbc-sha1 host/my.host.name@@MY.REALM 198@end example 199 200@node Serving Kerberos 4/524/kaserver, Remote administration, keytabs, Setting up a realm 201@section Serving Kerberos 4/524/kaserver 202 203Heimdal can be configured to support 524, Kerberos 4 or kaserver. All 204theses services are default turned off. Kerberos 4 support also 205depends on if Kerberos 4 support is compiled in with Heimdal. 206 207@subsection 524 208 209524 is a service that allows the KDC to convert Kerberos 5 tickets to 210Kerberos 4 tickets for backward compatibility. See also Using 2b 211tokens with AFS in @xref{Things in search for a better place}. 212 213524 can be turned on by adding this to the configuration file 214 215@example 216[kdc] 217 enable-524 = yes 218@end example 219 220@subsection Kerberos 4 221 222Kerberos 4 is the predecessor to to Kerberos 5. It only support single 223DES. You should only enable Kerberos 4 support if you have a need for 224for compatibility with an installed base of Kerberos 4 clients/servers. 225 226Kerberos 4 can be turned on by adding this to the configuration file 227 228@example 229[kdc] 230 enable-kerberos4 = yes 231@end example 232 233@subsection kaserver 234 235Kaserver is a Kerberos 4 that is used in AFS, the protocol have some 236features over plain Kerberos 4, but like Kerberos 4 only use single 237DES too. 238 239You should only enable Kerberos 4 support if you have a need for for 240compatibility with an installed base of AFS machines. 241 242Kaserver can be turned on by adding this to the configuration file 243 244@example 245[kdc] 246 enable-kaserver = yes 247@end example 248 249@node Remote administration, Password changing, Serving Kerberos 4/524/kaserver, Setting up a realm 250@section Remote administration 251 252The administration server, @samp{kadmind}, can be started by 253@samp{inetd} (which isn't recommended) or run as a normal daemon. If you 254want to start it from @samp{inetd} you should add a line similar to the 255one below to your @file{/etc/inetd.conf}. 256 257@example 258kerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind 259@end example 260 261You might need to add @samp{kerberos-adm} to your @file{/etc/services} 262as 749/tcp. 263 264Access to the administration server is controlled by an acl-file, (default 265@file{/var/heimdal/kadmind.acl}.) The lines in the access file, has the 266following syntax: 267@smallexample 268principal [priv1,priv2,...] [glob-pattern] 269@end smallexample 270 271The matching is from top to bottom for matching principal (and if given, 272glob-pattern). When there is a match, the rights of that lines are 273used. 274 275The privileges you can assign to a principal are: @samp{add}, 276@samp{change-password} (or @samp{cpw} for short), @samp{delete}, 277@samp{get}, @samp{list}, and @samp{modify}, or the special privilege 278@samp{all}. All of these roughly corresponds to the different commands 279in @samp{kadmin}. 280 281If a @var{glob-pattern} is given on a line, it restricts the right for 282the principal to only apply for the subjects that match the pattern. 283The patters are of the same type as those used in shell globbing, see 284@url{none,,fnmatch(3)}. 285 286In the example below @samp{lha/admin} can change every principal in the 287database. @samp{jimmy/admin} can only modify principals that belong to 288the realm @samp{E.KTH.SE}. @samp{mille/admin} is working at the 289help desk, so he should only be able to change the passwords for single 290component principals (ordinary users). He will not be able to change any 291@samp{/admin} principal. 292 293@example 294lha/admin@@E.KTH.SE all 295jimmy/admin@@E.KTH.SE all *@@E.KTH.SE 296jimmy/admin@@E.KTH.SE all */*@@E.KTH.SE 297mille/admin@@E.KTH.SE change-password *@@E.KTH.SE 298@end example 299 300@node Password changing, Testing clients and servers, Remote administration, Setting up a realm 301@section Password changing 302 303To allow users to change their passwords, you should run @samp{kpasswdd}. 304It is not run from @samp{inetd}. 305 306You might need to add @samp{kpasswd} to your @file{/etc/services} as 307464/udp. 308 309@subsection Password quality assurance 310 311It is important that users have good passwords, both to make it harder 312to guess them and to avoid off-line attacks (pre-authentication provides 313some defense against off-line attacks). To ensure that the users choose 314good passwords, you can enable password quality controls in 315@samp{kpasswdd}. The controls themselves are done in a shared library 316that is used by @samp{kpasswdd}. To configure in these controls, add 317lines similar to the following to your @file{/etc/krb5.conf}: 318 319@example 320[password_quality] 321 check_library = @var{library} 322 check_function = @var{function} 323@end example 324 325The function @var{function} in the shared library @var{library} will be 326called for proposed new passwords. The function should be declared as: 327 328@example 329const char * 330function(krb5_context context, krb5_principal principal, krb5_data *pwd); 331@end example 332 333The function should verify that @var{pwd} is a good password for 334@var{principal} and if so return @code{NULL}. If it is deemed to be of 335low quality, it should return a string explaining why that password 336should not be used. 337 338Code for a password quality checking function that uses the cracklib 339library can be found in @file{lib/kadm5/sample_password_check.c} in the 340source code distribution. It requires the cracklib library built with 341the patch available at 342@url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}. 343 344If no password quality checking function is configured, it is only 345verified that it is at least six characters of length. 346 347@node Testing clients and servers, Slave Servers, Password changing, Setting up a realm 348@section Testing clients and servers 349 350Now you should be able to run all the clients and servers. Refer to the 351appropriate man pages for information on how to use them. 352 353@node Slave Servers, Incremental propagation, Testing clients and servers, Setting up a realm 354@section Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm 355 356It is desirable to have at least one backup (slave) server in case the 357master server fails. It is possible to have any number of such slave 358servers but more than three usually doesn't buy much more redundancy. 359 360All Kerberos servers for a realm shall have the same database so that 361they present the same service to all the users. The 362@pindex hprop 363@code{hprop} program, running on the master, will propagate the database 364to the slaves, running 365@pindex hpropd 366@code{hpropd} processes. 367 368Every slave needs a database directory, the master key (if it was used 369for the database) and a keytab with the principal 370@samp{hprop/@var{hostname}}. Add the principal with the 371@pindex ktutil 372@code{ktutil} command and start 373@pindex hpropd 374@code{propd}, as follows: 375 376@example 377slave# ktutil get -p foo/admin hprop/`hostname` 378slave# mkdir /var/heimdal 379slave# hpropd 380@end example 381 382The master will use the principal @samp{kadmin/hprop} to authenticate to 383the slaves. This principal should be added when running @kbd{kadmin -l 384init} but if you do not have it in your database for whatever reason, 385please add it with @kbd{kadmin -l add}. 386 387Then run 388@pindex hprop 389@code{hprop} on the master: 390 391@example 392master# hprop slave 393@end example 394 395This was just an on-hands example to make sure that everything was 396working properly. Doing it manually is of course the wrong way and to 397automate this you will want to start 398@pindex hpropd 399@code{hpropd} from @code{inetd} on the slave(s) and regularly run 400@pindex hprop 401@code{hprop} on the master to regularly propagate the database. 402Starting the propagation once an hour from @code{cron} is probably a 403good idea. 404 405@node Incremental propagation, Salting , Slave Servers, Setting up a realm 406@section Incremental propagation 407 408There is also a newer and still somewhat experimental mechanism for 409doing incremental propagation in Heimdal. Instead of sending the whole 410database regularly, it sends the changes as they happen on the master to 411the slaves. The master keeps track of all the changes by assigned a 412version number to every change to the database. The slaves know which 413was the latest version they saw and in this way it can be determined if 414they are in sync or not. A log of all the changes is kept on the master 415and when a slave is at an older versioner than the oldest one in the 416log, the whole database has to be sent. 417 418Protocol-wise, all the slaves connects to the master and as a greeting 419tell it the latest version that they have (@samp{IHAVE} message). The 420master then responds by sending all the changes between that version and 421the current version at the master (a series of @samp{FORYOU} messages) 422or the whole database in a @samp{TELLYOUEVERYTHING} message. 423 424@subsection Configuring incremental propagation 425 426The program that runs on the master is @code{ipropd-master} and all 427clients run @code{ipropd-slave}. 428 429Create the file @file{/var/heimdal/slaves} on the master containing all 430the slaves that the database should be propagated to. Each line contains 431the full name of the principal (for example 432@samp{iprop/hemligare.foo.se@@FOO.SE}). 433 434You should already have @samp{iprop/tcp} defined as 2121, in your 435@file{/etc/services}. Otherwise, or if you need to use a different port 436for some peculiar reason, you can use the @kbd{--port} option. This is 437useful when you have multiple realms to distribute from one server. 438 439Then you need to create these principals that you added in the 440configuration file. Create one @samp{iprop/hostname} for the master and 441for every slave. 442 443 444@example 445master# /usr/heimdal/sbin/ktutil get iprop/`hostname` 446@end example 447 448The next step is to start the @code{ipropd-master} process on the master 449server. The @code{ipropd-master} listens on the UNIX-socket 450@file{/var/heimdal/signal} to know when changes have been made to the 451database so they can be propagated to the slaves. There is also a 452safety feature of testing the version number regularly (every 30 453seconds) to see if it has been modified by some means that do not raise 454this signal. Then, start @code{ipropd-slave} on all the slaves: 455 456@example 457master# /usr/heimdal/libexec/ipropd-master & 458slave# /usr/heimdal/libexec/ipropd-slave master & 459@end example 460 461@node Salting, Cross realm, Incremental propagation, Setting up a realm 462@section Salting 463@cindex Salting 464 465Salting is used to make it harder to precalculate all possible 466keys. Using a salt increases the search space to make it almost 467impossible to precalculate all keys. Salting is the process of mixing a 468public string (the salt) with the password, then sending it through an 469encryption-type specific string-to-key function that will output the 470fixed size encryption key. 471 472In Kerberos 5 the salt is determined by the encryption-type, except 473in some special cases. 474 475In @code{des} there is the Kerberos 4 salt 476(none at all) or the afs-salt (using the cell (realm in 477afs-lingo)). 478 479In @code{arcfour} (the encryption type that Microsoft Windows 2000 uses) 480there is no salt. This is to be compatible with NTLM keys in Windows 481NT 4. 482 483@code{[kadmin]default_keys} in @file{krb5.conf} controls 484what salting to use, 485 486The syntax of @code{[kadmin]default_keys} is 487@samp{[etype:]salt-type[:salt-string]}. @samp{etype} is the encryption 488type (des, des3, arcfour), @code{salt-type} is the type of salt (pw-salt 489or afs3-salt), and the salt-string is the string that will be used as 490salt (remember that if the salt is appended/prepended, the empty salt "" 491is the same thing as no salt at all). 492 493Common types of salting includes 494 495@itemize @bullet 496@item @code{v4} (or @code{des:pw-salt:}) 497 498The Kerberos 4 salting is using no salt att all. Reason there is colon 499that the end or the salt string is that it makes the salt the empty 500string (same as no salt). 501 502@item @code{v5} (or @code{pw-salt}) 503 504@code{pw-salt} means all regular encryption-types that is regular 505 506@item @code{afs3-salt} 507 508@code{afs3-salt} is the salting that is used with Transarc kaserver. Its 509the cell appended to the password. 510 511@end itemize 512 513@node Cross realm, Transit policy , Salting, Setting up a realm 514@section Cross realm 515@cindex Cross realm 516 517Suppose you are residing in the realm @samp{MY.REALM}, how do you 518authenticate to a server in @samp{OTHER.REALM}? Having valid tickets in 519@samp{MY.REALM} allows you to communicate with kerberised services in that 520realm. However, the computer in the other realm does not have a secret 521key shared with the Kerberos server in your realm. 522 523It is possible to add a share keys between two realms that trust each 524other. When a client program, such as @code{telnet} or @code{ssh}, 525finds that the other computer is in a different realm, it will try to 526get a ticket granting ticket for that other realm, but from the local 527Kerberos server. With that ticket granting ticket, it will then obtain 528service tickets from the Kerberos server in the other realm. 529 530For a two way trust between @samp{MY.REALM} and @samp{OTHER.REALM} 531add the following principals to each realm. The principals should be 532@samp{krbtgt/OTHER.REALM@@MY.REALM} and 533@samp{krbtgt/MY.REALM@@OTHER.REALM} in @samp{MY.REALM}, and 534@samp{krbtgt/MY.REALM@@OTHER.REALM} and 535@samp{krbtgt/OTHER.REALM@@MY.REALM}in @samp{OTHER.REALM}. 536 537In Kerberos 5 the trust can be one configured to be one way. So that 538users from @samp{MY.REALM} can authenticate to services in 539@samp{OTHER.REALM}, but not the opposite. In the example above, the 540@samp{krbtgt/MY.REALM@@OTHER.REALM} then should be removed. 541 542The two principals must have the same key, key version number, and the 543same set of encryption types. Remember to transfer the two keys in a 544safe manner. 545 546@example 547@cartouche 548vr$ klist 549Credentials cache: FILE:/tmp/krb5cc_913.console 550 Principal: lha@@E.KTH.SE 551 552 Issued Expires Principal 553May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE 554 555vr$ telnet -l lha hummel.it.su.se 556Trying 2001:6b0:5:1095:250:fcff:fe24:dbf... 557Connected to hummel.it.su.se. 558Escape character is '^]'. 559Waiting for encryption to be negotiated... 560[ Trying mutual KERBEROS5 (host/hummel.it.su.se@@SU.SE)... ] 561[ Kerberos V5 accepts you as ``lha@@E.KTH.SE'' ] 562Encryption negotiated. 563Last login: Sat May 3 14:11:47 from vr.l.nxs.se 564hummel$ exit 565 566vr$ klist 567Credentials cache: FILE:/tmp/krb5cc_913.console 568 Principal: lha@@E.KTH.SE 569 570 Issued Expires Principal 571May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE 572May 3 13:55:56 May 3 23:55:54 krbtgt/SU.SE@@E.KTH.SE 573May 3 14:10:54 May 3 23:55:54 host/hummel.it.su.se@@SU.SE 574 575@end cartouche 576@end example 577 578@node Transit policy, Setting up DNS , Cross realm, Setting up a realm 579@section Transit policy 580@cindex Transit policy 581 582If you want to use cross realm authentication through an intermediate 583realm it must be explicitly allowed by either the KDCs or the server 584receiving the request. This is done in @file{krb5.conf} in the 585@code{[capaths]} section. 586 587When the ticket transits through a realm to another realm, the 588destination realm adds its peer to the "transited-realms" field in the 589ticket. The field is unordered, this is since there is no way to know if 590know if one of the transited-realms changed the order of the list. 591 592The syntax for @code{[capaths]} section: 593 594@example 595@cartouche 596[capaths] 597 CLIENT-REALM = @{ 598 SERVER-REALM = PERMITTED-CROSS-REALMS ... 599 @} 600@end cartouche 601@end example 602 603The realm @code{STACKEN.KTH.SE} allows clients from @code{SU.SE} and 604@code{DSV.SU.SE} to cross in. Since @code{STACKEN.KTH.SE} only have 605direct cross realm with @code{KTH.SE}, and @code{DSV.SU.SE} only have direct cross 606realm with @code{SU.SE} they need to use both @code{SU.SE} and 607@code{KTH.SE} as transit realms. 608 609@example 610@cartouche 611[capaths] 612 SU.SE = @{ 613 STACKEN.KTH.SE = KTH.SE 614 @} 615 DSV.SU.SE = @{ 616 STACKEN.KTH.SE = SU.SE KTH.SE 617 @} 618 619@end cartouche 620@end example 621 622@c To test the cross realm configuration, use: 623@c kmumble transit-check client server transit-realms ... 624 625@node Setting up DNS, , Transit policy, Setting up a realm 626@section Setting up DNS 627@cindex Setting up DNS 628 629If there is information about where to find the KDC or kadmind for a 630realm in the @file{krb5.conf} for a realm, that information will be 631preferred and DNS will not be queried. 632 633Heimdal will try to use DNS to find the KDCs for a realm. First it 634will try to find @code{SRV} resource record (RR) for the realm. If no 635SRV RRs are found, it will fall back to looking for a @code{A} RR for 636a machine named kerberos.REALM, and then kerberos-1.REALM, etc 637 638Adding this information to DNS makes the client have less 639configuration (in the common case, no configuration) and allows the 640system administrator to change the number of KDCs and on what machines 641they are running without caring about clients. 642 643The backside of using DNS that the client might be fooled to use the 644wrong server if someone fakes DNS replies/data, but storing the IP 645addresses of the KDC on all the clients makes it very hard to change 646the infrastructure. 647 648Example of the configuration for the realm @code{EXAMPLE.COM}, 649 650@example 651 652$ORIGIN example.com. 653_kerberos._tcp SRV 10 1 88 kerberos.example.com. 654_kerberos._udp SRV 10 1 88 kerberos.example.com. 655_kerberos._tcp SRV 10 1 88 kerberos-1.example.com. 656_kerberos._udp SRV 10 1 88 kerberos-1.example.com. 657_kpasswd._udp SRV 10 1 464 kerberos.example.com. 658_kerberos-adm._tcp SRV 10 1 749 kerberos.example.com. 659 660@end example 661 662More information about DNS SRV resource records can be found in 663RFC-2782 (A DNS RR for specifying the location of services (DNS SRV)). 664 665