1@c $Id$ 2 3@node Setting up a realm, Applications, Building and Installing, Top 4 5@chapter Setting up a realm 6 7A 8@cindex realm 9realm is an administrative domain. The name of a Kerberos realm is 10usually the Internet domain name in uppercase. Call your realm the same 11as your Internet domain name if you do not have strong reasons for not 12doing so. It will make life easier for you and everyone else. 13 14@menu 15* Configuration file:: 16* Creating the database:: 17* Modifying the database:: 18* Checking the setup:: 19* keytabs:: 20* Serving Kerberos 4/524/kaserver:: 21* Remote administration:: 22* Password changing:: 23* Testing clients and servers:: 24* Slave Servers:: 25* Incremental propagation:: 26* Encryption types and salting:: 27* Credential cache server - KCM:: 28* Cross realm:: 29* Transit policy:: 30* Setting up DNS:: 31* How clients locate Kerberos KDCs:: 32* Using LDAP to store the database:: 33* Providing Kerberos credentials to servers and programs:: 34* Setting up PK-INIT:: 35* KDC maintainence:: 36* Debugging Kerberos problems:: 37@end menu 38 39@node Configuration file, Creating the database, Setting up a realm, Setting up a realm 40@section Configuration file 41 42To setup a realm you will first have to create a configuration file: 43@file{/etc/krb5.conf}. The @file{krb5.conf} file can contain many 44configuration options, some of which are described here. 45 46There is a sample @file{krb5.conf} supplied with the distribution. 47 48The configuration file is a hierarchical structure consisting of 49sections, each containing a list of bindings (either variable 50assignments or subsections). A section starts with 51@samp{[@samp{section-name}]}. A binding consists of a left hand side, an equal sign 52(@samp{=}) and a right hand side (the left hand side tag must be 53separated from the equal sign with some whitespace). Subsections have a 54@samp{@{} as the first non-whitespace character after the equal sign. All 55other bindings are treated as variable assignments. The value of a 56variable extends to the end of the line. 57 58@example 59[section1] 60 a-subsection = @{ 61 var = value1 62 other-var = value with @{@} 63 sub-sub-section = @{ 64 var = 123 65 @} 66 @} 67 var = some other value 68[section2] 69 var = yet another value 70@end example 71 72In this manual, names of sections and bindings will be given as strings 73separated by slashes (@samp{/}). The @samp{other-var} variable will thus 74be @samp{section1/a-subsection/other-var}. 75 76For in-depth information about the contents of the configuration file, refer to 77the @file{krb5.conf} manual page. Some of the more important sections 78are briefly described here. 79 80The @samp{libdefaults} section contains a list of library configuration 81parameters, such as the default realm and the timeout for KDC 82responses. The @samp{realms} section contains information about specific 83realms, such as where they hide their KDC@. This section serves the same 84purpose as the Kerberos 4 @file{krb.conf} file, but can contain more 85information. Finally the @samp{domain_realm} section contains a list of 86mappings from domains to realms, equivalent to the Kerberos 4 87@file{krb.realms} file. 88 89To continue with the realm setup, you will have to create a configuration file, 90with contents similar to the following. 91 92@example 93[libdefaults] 94 default_realm = MY.REALM 95[realms] 96 MY.REALM = @{ 97 kdc = my.kdc my.slave.kdc 98 kdc = my.third.kdc 99 kdc = 130.237.237.17 100 kdc = [2001:6b0:1:ea::100]:88 101 @} 102[domain_realm] 103 .my.domain = MY.REALM 104 105@end example 106 107If you use a realm name equal to your domain name, you can omit the 108@samp{libdefaults}, and @samp{domain_realm}, sections. If you have a DNS 109SRV-record for your realm, or your Kerberos server has DNS CNAME 110@samp{kerberos.my.realm}, you can omit the @samp{realms} section too. 111 112@cindex KRB5_CONFIG 113If you want to use a different configuration file then the default you 114can point a file with the enviroment variable @samp{KRB5_CONFIG}. 115 116@example 117env KRB5_CONFIG=$HOME/etc/krb5.conf kinit user@@REALM 118@end example 119 120@node Creating the database, Modifying the database, Configuration file, Setting up a realm 121@section Creating the database 122 123The database library will look for the database in the directory 124@file{@value{dbdir}}, so you should probably create that directory. 125Make sure the directory has restrictive permissions. 126 127@example 128# mkdir /var/heimdal 129@end example 130 131The keys of all the principals are stored in the database. If you 132choose to, these can be encrypted with a master key. You do not have to 133remember this key (or password), but just to enter it once and it will 134be stored in a file (@file{/var/heimdal/m-key}). If you want to have a 135master key, run @samp{kstash} to create this master key: 136 137@example 138# kstash 139Master key: 140Verifying password - Master key: 141@end example 142 143If you want to generate a random master key you can use the 144@kbd{--random-key} flag to kstash. This will make sure you have a good key 145on which attackers can't do a dictionary attack. 146 147If you have a master key, make sure you make a backup of your master 148key file; without it backups of the database are of no use. 149 150To initialise the database use the @command{kadmin} program, with the 151@kbd{-l} option (to enable local database mode). First issue a 152@kbd{init MY.REALM} command. This will create the database and insert 153default principals for that realm. You can have more than one realm in 154one database, so @samp{init} does not destroy any old database. 155 156Before creating the database, @samp{init} will ask you some questions 157about maximum ticket lifetimes. 158 159After creating the database you should probably add yourself to it. You 160do this with the @samp{add} command. It takes as argument the name of a 161principal. The principal should contain a realm, so if you haven't set up 162a default realm, you will need to explicitly include the realm. 163 164@example 165# kadmin -l 166kadmin> init MY.REALM 167Realm max ticket life [unlimited]: 168Realm max renewable ticket life [unlimited]: 169kadmin> add me 170Max ticket life [unlimited]: 171Max renewable life [unlimited]: 172Attributes []: 173Password: 174Verifying password - Password: 175@end example 176 177Now start the KDC and try getting a ticket. 178 179@example 180# kdc & 181# kinit me 182me@@MY.REALMS's Password: 183# klist 184Credentials cache: /tmp/krb5cc_0 185 Principal: me@@MY.REALM 186 187 Issued Expires Principal 188Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@@MY.REALM 189@end example 190 191If you are curious you can use the @samp{dump} command to list all the 192entries in the database. It should look something similar to the 193following example (note that the entries here are truncated for 194typographical reasons): 195 196@smallexample 197kadmin> dump 198me@@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ... 199kadmin/admin@@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ... 200krbtgt/MY.REALM@@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ... 201kadmin/changepw@@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ... 202@end smallexample 203 204@node Modifying the database, Checking the setup, Creating the database, Setting up a realm 205@section Modifying the database 206 207All modifications of principals are done with with kadmin. 208 209A principal has several attributes and lifetimes associated with it. 210 211Principals are added, renamed, modified, and deleted with the kadmin 212commands @samp{add}, @samp{rename}, @samp{modify}, @samp{delete}. 213Both interactive editing and command line flags can be used (use --help 214to list the available options). 215 216There are different kinds of types for the fields in the database; 217attributes, absolute time times and relative times. 218 219@subsection Attributes 220 221When doing interactive editing, attributes are listed with @samp{?}. 222 223The attributes are given in a comma (@samp{,}) separated list. 224Attributes are removed from the list by prefixing them with @samp{-}. 225 226@smallexample 227kadmin> modify me 228Max ticket life [1 day]: 229Max renewable life [1 week]: 230Principal expiration time [never]: 231Password expiration time [never]: 232Attributes [disallow-renewable]: requires-pre-auth,-disallow-renewable 233kadmin> get me 234 Principal: me@@MY.REALM 235[...] 236 Attributes: requires-pre-auth 237@end smallexample 238 239@subsection Absolute times 240 241The format for absolute times are any of the following: 242 243@smallexample 244never 245now 246YYYY-mm-dd 247YYYY-mm-dd HH:MM:SS 248@end smallexample 249 250 251@subsection Relative times 252 253The format for relative times are any of the following combined: 254 255@smallexample 256N year 257M month 258O day 259P hour 260Q minute 261R second 262@end smallexample 263 264@c Describe more of kadmin commands here... 265 266@node Checking the setup, keytabs, Modifying the database, Setting up a realm 267@section Checking the setup 268 269There are two tools that can check the consistency of the Kerberos 270configuration file and the Kerberos database. 271 272The Kerberos configuration file is checked using 273@command{verify_krb5_conf}. The tool checks for common errors, but 274commonly there are several uncommon configuration entries that are 275never added to the tool and thus generates ``unknown entry'' warnings. 276This is usually nothing to worry about. 277 278The database check is built into the kadmin tool. It will check for 279common configuration error that will cause problems later. Common 280check are for existence and flags on important principals. The 281database check by run by the following command : 282 283@example 284kadmin -l check REALM.EXAMPLE.ORG 285@end example 286 287@node keytabs, Serving Kerberos 4/524/kaserver, Checking the setup, Setting up a realm 288@section keytabs 289 290To extract a service ticket from the database and put it in a keytab, you 291need to first create the principal in the database with @samp{add} 292(using the @kbd{--random-key} flag to get a random key) and then 293extract it with @samp{ext_keytab}. 294 295@example 296kadmin> add --random-key host/my.host.name 297Max ticket life [unlimited]: 298Max renewable life [unlimited]: 299Attributes []: 300kadmin> ext host/my.host.name 301kadmin> exit 302# ktutil list 303Version Type Principal 304 1 des-cbc-md5 host/my.host.name@@MY.REALM 305 1 des-cbc-md4 host/my.host.name@@MY.REALM 306 1 des-cbc-crc host/my.host.name@@MY.REALM 307 1 des3-cbc-sha1 host/my.host.name@@MY.REALM 308@end example 309 310@node Serving Kerberos 4/524/kaserver, Remote administration, keytabs, Setting up a realm 311@section Serving Kerberos 4/524/kaserver 312 313Heimdal can be configured to support 524, Kerberos 4 or kaserver. All 314these services are turned off by default. Kerberos 4 is always 315supported by the KDC, but the Kerberos 4 client support also depends 316on Kerberos 4 support having been included at compile-time, using 317@kbd{--with-krb4=dir}. 318 319@subsection 524 320 321524 is a service that allows the KDC to convert Kerberos 5 tickets to 322Kerberos 4 tickets for backward compatibility. See also Using 2b 323tokens with AFS in @xref{AFS}. 324 325524 can be turned on by adding this to the configuration file 326 327@example 328[kdc] 329 enable-524 = yes 330@end example 331 332@subsection Kerberos 4 333 334Kerberos 4 is the predecessor to to Kerberos 5. It only supports 335single DES@. You should only enable Kerberos 4 support if you have 336needs for compatibility with an installed base of Kerberos 4 337clients/servers. 338 339Kerberos 4 can be turned on by adding this to the configuration file 340 341@example 342[kdc] 343 enable-kerberos4 = yes 344@end example 345 346@subsection kaserver 347 348Kaserver is a Kerberos 4 that is used in AFS@. The protocol has some 349extra features over plain Kerberos 4, but like Kerberos 4, only uses 350single DES@. 351 352You should only enable Kaserver support if you have needs for 353compatibility with an installed base of AFS machines. 354 355Kaserver can be turned on by adding this to the configuration file 356 357@example 358[kdc] 359 enable-kaserver = yes 360@end example 361 362@node Remote administration, Password changing, Serving Kerberos 4/524/kaserver, Setting up a realm 363@section Remote administration 364 365The administration server, @command{kadmind}, can be started by 366@command{inetd} (which isn't recommended) or run as a normal daemon. If you 367want to start it from @command{inetd} you should add a line similar to the 368one below to your @file{/etc/inetd.conf}. 369 370@example 371kerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind 372@end example 373 374You might need to add @samp{kerberos-adm} to your @file{/etc/services} 375as @samp{749/tcp}. 376 377Access to the administration server is controlled by an ACL file, 378(default @file{/var/heimdal/kadmind.acl}.) The file has the following 379syntax: 380@smallexample 381principal [priv1,priv2,...] [glob-pattern] 382@end smallexample 383 384The matching is from top to bottom for matching principals (and if given, 385glob-pattern). When there is a match, the access rights of that line are 386applied. 387 388The privileges you can assign to a principal are: @samp{add}, 389@samp{change-password} (or @samp{cpw} for short), @samp{delete}, 390@samp{get}, @samp{list}, and @samp{modify}, or the special privilege 391@samp{all}. All of these roughly correspond to the different commands 392in @command{kadmin}. 393 394If a @var{glob-pattern} is given on a line, it restricts the access 395rights for the principal to only apply for subjects that match the 396pattern. The patterns are of the same type as those used in shell 397globbing, see @url{none,,fnmatch(3)}. 398 399In the example below @samp{lha/admin} can change every principal in the 400database. @samp{jimmy/admin} can only modify principals that belong to 401the realm @samp{E.KTH.SE}. @samp{mille/admin} is working at the 402help desk, so he should only be able to change the passwords for single 403component principals (ordinary users). He will not be able to change any 404@samp{/admin} principal. 405 406@example 407lha/admin@@E.KTH.SE all 408jimmy/admin@@E.KTH.SE all *@@E.KTH.SE 409jimmy/admin@@E.KTH.SE all */*@@E.KTH.SE 410mille/admin@@E.KTH.SE change-password *@@E.KTH.SE 411@end example 412 413@node Password changing, Testing clients and servers, Remote administration, Setting up a realm 414@section Password changing 415 416To allow users to change their passwords, you should run @command{kpasswdd}. 417It is not run from @command{inetd}. 418 419You might need to add @samp{kpasswd} to your @file{/etc/services} as 420@samp{464/udp}. If your realm is not setup to use DNS, you might also 421need to add a @samp{kpasswd_server} entry to the realm configuration 422in @file{/etc/krb5.conf} on client machines: 423 424@example 425[realms] 426 MY.REALM = @{ 427 kdc = my.kdc my.slave.kdc 428 kpasswd_server = my.kdc 429 @} 430@end example 431 432@subsection Password quality assurance 433 434It is important that users have good passwords, both to make it harder 435to guess them and to avoid off-line attacks (although 436pre-authentication provides some defence against off-line attacks). 437To ensure that the users choose good passwords, you can enable 438password quality controls in @command{kpasswdd} and @command{kadmind}. 439The controls themselves are done in a shared library or an external 440program that is used by @command{kpasswdd}. To configure in these 441controls, add lines similar to the following to your 442@file{/etc/krb5.conf}: 443 444@example 445[password_quality] 446 policies = external-check builtin:minimum-length modulename:policyname 447 external_program = /bin/false 448 policy_libraries = @var{library1.so} @var{library2.so} 449@end example 450 451In @samp{[password_quality]policies} the module name is optional if 452the policy name is unique in all modules (members of 453@samp{policy_libraries}). All built-in policies can be qualified with 454a module name of @samp{builtin} to unambiguously specify the built-in 455policy and not a policy by the same name from a loaded module. 456 457The built-in policies are 458 459@itemize @bullet 460 461@item external-check 462 463Executes the program specified by @samp{[password_quality]external_program}. 464 465A number of key/value pairs are passed as input to the program, one per 466line, ending with the string @samp{end}. The key/value lines are of 467the form 468@example 469principal: @var{principal} 470new-password: @var{password} 471@end example 472where @var{password} is the password to check for the previous 473@var{principal}. 474 475If the external application approves the password, it should return 476@samp{APPROVED} on standard out and exit with exit code 0. If it 477doesn't approve the password, an one line error message explaining the 478problem should be returned on standard error and the application 479should exit with exit code 0. In case of a fatal error, the 480application should, if possible, print an error message on standard 481error and exit with a non-zero error code. 482 483@item minimum-length 484 485The minimum length password quality check reads the configuration file 486stanza @samp{[password_quality]min_length} and requires the password 487to be at least this length. 488 489@item character-class 490 491The character-class password quality check reads the configuration 492file stanza @samp{[password_quality]min_classes}. The policy requires 493the password to have characters from at least that many character 494classes. Default value if not given is 3. 495 496The four different characters classes are, uppercase, lowercase, 497number, special characters. 498 499@end itemize 500 501If you want to write your own shared object to check password 502policies, see the manual page @manpage{kadm5_pwcheck,3}. 503 504Code for a password quality checking function that uses the cracklib 505library can be found in @file{lib/kadm5/sample_password_check.c} in 506the source code distribution. It requires that the cracklib library 507be built with the patch available at 508@url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}. 509 510A sample policy external program is included in 511@file{lib/kadm5/check-cracklib.pl}. 512 513If no password quality checking function is configured, the only check 514performed is that the password is at least six characters long. 515 516To check the password policy settings, use the command 517@command{verify-password-quality} in @command{kadmin} program. The password 518verification is only performed locally, on the client. It may be 519convenient to set the environment variable @samp{KRB5_CONFIG} to point 520to a test version of @file{krb5.conf} while you're testing the 521@samp{[password_quality]} stanza that way. 522 523@node Testing clients and servers, Slave Servers, Password changing, Setting up a realm 524@section Testing clients and servers 525 526Now you should be able to run all the clients and servers. Refer to the 527appropriate man pages for information on how to use them. 528 529@node Slave Servers, Incremental propagation, Testing clients and servers, Setting up a realm 530@section Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm 531 532It is desirable to have at least one backup (slave) server in case the 533master server fails. It is possible to have any number of such slave 534servers but more than three usually doesn't buy much more redundancy. 535 536All Kerberos servers for a realm must have the same database so that 537they present the same service to the users. The 538@pindex hprop 539@command{hprop} program, running on the master, will propagate the database 540to the slaves, running 541@pindex hpropd 542@command{hpropd} processes. 543 544Every slave needs a database directory, the master key (if it was used 545for the database) and a keytab with the principal 546@samp{hprop/@var{hostname}}. Add the principal with the 547@pindex ktutil 548@command{ktutil} command and start 549@pindex hpropd 550@command{hpropd}, as follows: 551 552@example 553slave# ktutil get -p foo/admin hprop/`hostname` 554slave# mkdir /var/heimdal 555slave# hpropd 556@end example 557 558The master will use the principal @samp{kadmin/hprop} to authenticate to 559the slaves. This principal should be added when running @kbd{kadmin -l 560init} but if you do not have it in your database for whatever reason, 561please add it with @kbd{kadmin -l add}. 562 563Then run 564@pindex hprop 565@code{hprop} on the master: 566 567@example 568master# hprop slave 569@end example 570 571This was just an hands-on example to make sure that everything was 572working properly. Doing it manually is of course the wrong way, and to 573automate this you will want to start 574@pindex hpropd 575@command{hpropd} from @command{inetd} on the slave(s) and regularly run 576@pindex hprop 577@command{hprop} on the master to regularly propagate the database. 578Starting the propagation once an hour from @command{cron} is probably a 579good idea. 580 581@node Incremental propagation, Encryption types and salting, Slave Servers, Setting up a realm 582@section Incremental propagation 583 584There is also a newer mechanism for 585doing incremental propagation in Heimdal. Instead of sending the whole 586database regularly, it sends the changes as they happen on the master to 587the slaves. The master keeps track of all the changes by assigning a 588version number to every change to the database. The slaves know which 589was the latest version they saw and in this way it can be determined if 590they are in sync or not. A log of all the changes is kept on the master, 591and when a slave is at an older version than the oldest one in the 592log, the whole database has to be sent. 593 594Protocol-wise, all the slaves connect to the master and as a greeting 595tell it the latest version that they have (@samp{IHAVE} message). The 596master then responds by sending all the changes between that version and 597the current version at the master (a series of @samp{FORYOU} messages) 598or the whole database in a @samp{TELLYOUEVERYTHING} message. There is 599also a keep-alive protocol that makes sure all slaves are up and running. 600 601In addition on listening on the network to get connection from new 602slaves, the ipropd-master also listens on a status unix 603socket. kadmind and kpasswdd both open that socket when a transation 604is done and written a notification to the socket. That cause 605ipropd-master to check for new version in the log file. As a fallback in 606case a notification is lost by the unix socket, the log file is 607checked after 30 seconds of no event. 608 609@subsection Configuring incremental propagation 610 611The program that runs on the master is @command{ipropd-master} and all 612clients run @command{ipropd-slave}. 613 614Create the file @file{/var/heimdal/slaves} on the master containing all 615the slaves that the database should be propagated to. Each line contains 616the full name of the principal (for example 617@samp{iprop/hemligare.foo.se@@FOO.SE}). 618 619You should already have @samp{iprop/tcp} defined as 2121, in your 620@file{/etc/services}. Otherwise, or if you need to use a different port 621for some peculiar reason, you can use the @kbd{--port} option. This is 622useful when you have multiple realms to distribute from one server. 623 624Then you need to create those principals that you added in the 625configuration file. Create one @samp{iprop/hostname} for the master and 626for every slave. 627 628 629@example 630master# /usr/heimdal/sbin/ktutil get iprop/`hostname` 631@end example 632 633@example 634slave# /usr/heimdal/sbin/ktutil get iprop/`hostname` 635@end example 636 637 638The next step is to start the @command{ipropd-master} process on the master 639server. The @command{ipropd-master} listens on the UNIX domain socket 640@file{/var/heimdal/signal} to know when changes have been made to the 641database so they can be propagated to the slaves. There is also a 642safety feature of testing the version number regularly (every 30 643seconds) to see if it has been modified by some means that do not raise 644this signal. Then, start @command{ipropd-slave} on all the slaves: 645 646@example 647master# /usr/heimdal/libexec/ipropd-master & 648slave# /usr/heimdal/libexec/ipropd-slave master & 649@end example 650 651To manage the iprop log file you should use the @command{iprop-log} 652command. With it you can dump, truncate and replay the logfile. 653 654@node Encryption types and salting, Credential cache server - KCM, Incremental propagation, Setting up a realm 655@section Encryption types and salting 656@cindex Salting 657@cindex Encryption types 658 659The encryption types that the KDC is going to assign by default is 660possible to change. Since the keys used for user authentication is 661salted the encryption types are described together with the salt 662strings. 663 664Salting is used to make it harder to pre-calculate all possible 665keys. Using a salt increases the search space to make it almost 666impossible to pre-calculate all keys. Salting is the process of mixing a 667public string (the salt) with the password, then sending it through an 668encryption type specific string-to-key function that will output the 669fixed size encryption key. 670 671In Kerberos 5 the salt is determined by the encryption type, except in 672some special cases. 673 674In @code{des} there is the Kerberos 4 salt 675(none at all) or the afs-salt (using the cell (realm in 676AFS lingo)). 677 678In @code{arcfour} (the encryption type that Microsoft Windows 2000 uses) 679there is no salt. This is to be compatible with NTLM keys in Windows 680NT 4. 681 682@code{[kadmin]default_keys} in @file{krb5.conf} controls 683what salting to use. 684 685The syntax of @code{[kadmin]default_keys} is 686@samp{[etype:]salt-type[:salt-string]}. @samp{etype} is the encryption 687type (des-cbc-crc, arcfour-hmac-md5, aes256-cts-hmac-sha1-96), 688@code{salt-type} is the type of salt (pw-salt or afs3-salt), and the 689salt-string is the string that will be used as salt (remember that if 690the salt is appended/prepended, the empty salt "" is the same thing as 691no salt at all). 692 693Common types of salting include 694 695@itemize @bullet 696@item @code{v4} (or @code{des:pw-salt:}) 697 698The Kerberos 4 salting is using no salt at all. Reason there is colon 699at the end of the salt string is that it makes the salt the empty 700string (same as no salt). 701 702@item @code{v5} (or @code{pw-salt}) 703 704@code{pw-salt} uses the default salt for each encryption type is 705specified for. If the encryption type @samp{etype} isn't given, all 706default encryption will be used. 707 708@item @code{afs3-salt} 709 710@code{afs3-salt} is the salt that is used with Transarc kaserver. It's 711the cell name appended to the password. 712 713@end itemize 714 715@node Credential cache server - KCM, Cross realm, Encryption types and salting, Setting up a realm 716@section Credential cache server - KCM 717@cindex KCM 718@cindex Credential cache server 719 720When KCM running is easy for users to switch between different 721kerberos principals using @file{kswitch} or built in support in 722application, like OpenSSH's GSSAPIClientIdentity. 723 724Other advantages are that there is the long term credentials are not 725written to disk and on reboot the credential is removed when kcm 726process stopps running. 727 728Configure the system startup script to start the kcm process, 729@file{/usr/heimdal/libexec/kcm} and then configure the system to use kcm in @file{krb5.conf}. 730 731@example 732[libdefaults] 733 default_cc_type = KCM 734@end example 735 736Now when you run @command{kinit} it doesn't overwrite your existing 737credentials but rather just add them to the set of 738credentials. @command{klist -l} lists the credentials and the star 739marks the default credential. 740 741@example 742$ kinit lha@@KTH.SE 743lha@@KTH.SE's Password: 744$ klist -l 745 Name Cache name Expires 746lha@@KTH.SE 0 Nov 22 23:09:40 * 747lha@@SU.SE Initial default ccache Nov 22 14:14:24 748@end example 749 750When switching between credentials you can use @command{kswitch}. 751 752@example 753$ kswitch -i 754 Principal 7551 lha@@KTH.SE 7562 lha@@SU.SE 757Select number: 2 758@end example 759 760After switching, a new set of credentials are used as default. 761 762@example 763$ klist -l 764 Name Cache name Expires 765lha@@SU.SE Initial default ccache Nov 22 14:14:24 * 766lha@@KTH.SE 0 Nov 22 23:09:40 767@end example 768 769Som applications, like openssh with Simon Wilkinsons patch applied, 770support specifiying that credential to use. The example below will 771login to the host computer.kth.se using lha@@KTH.SE (not the current 772default credential). 773 774@example 775$ ssh \ 776 -o GSSAPIAuthentication=yes \ 777 -o GSSAPIKeyExchange=yes \ 778 -o GSSAPIClientIdentity=lha@@KTH.SE \ 779 computer.kth.se 780@end example 781 782 783 784@node Cross realm, Transit policy, Credential cache server - KCM, Setting up a realm 785@section Cross realm 786@cindex Cross realm 787 788Suppose you reside in the realm @samp{MY.REALM}, how do you 789authenticate to a server in @samp{OTHER.REALM}? Having valid tickets in 790@samp{MY.REALM} allows you to communicate with Kerberised services in that 791realm. However, the computer in the other realm does not have a secret 792key shared with the Kerberos server in your realm. 793 794It is possible to share keys between two realms that trust each 795other. When a client program, such as @command{telnet} or @command{ssh}, 796finds that the other computer is in a different realm, it will try to 797get a ticket granting ticket for that other realm, but from the local 798Kerberos server. With that ticket granting ticket, it will then obtain 799service tickets from the Kerberos server in the other realm. 800 801For a two way trust between @samp{MY.REALM} and @samp{OTHER.REALM} 802add the following principals to each realm. The principals should be 803@samp{krbtgt/OTHER.REALM@@MY.REALM} and 804@samp{krbtgt/MY.REALM@@OTHER.REALM} in @samp{MY.REALM}, and 805@samp{krbtgt/MY.REALM@@OTHER.REALM} and 806@samp{krbtgt/OTHER.REALM@@MY.REALM}in @samp{OTHER.REALM}. 807 808In Kerberos 5 the trust can be configured to be one way. So that 809users from @samp{MY.REALM} can authenticate to services in 810@samp{OTHER.REALM}, but not the opposite. In the example above, the 811@samp{krbtgt/MY.REALM@@OTHER.REALM} then should be removed. 812 813The two principals must have the same key, key version number, and the 814same set of encryption types. Remember to transfer the two keys in a 815safe manner. 816 817@example 818vr$ klist 819Credentials cache: FILE:/tmp/krb5cc_913.console 820 Principal: lha@@E.KTH.SE 821 822 Issued Expires Principal 823May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE 824 825vr$ telnet -l lha hummel.it.su.se 826Trying 2001:6b0:5:1095:250:fcff:fe24:dbf... 827Connected to hummel.it.su.se. 828Escape character is '^]'. 829Waiting for encryption to be negotiated... 830[ Trying mutual KERBEROS5 (host/hummel.it.su.se@@SU.SE)... ] 831[ Kerberos V5 accepts you as ``lha@@E.KTH.SE'' ] 832Encryption negotiated. 833Last login: Sat May 3 14:11:47 from vr.l.nxs.se 834hummel$ exit 835 836vr$ klist 837Credentials cache: FILE:/tmp/krb5cc_913.console 838 Principal: lha@@E.KTH.SE 839 840 Issued Expires Principal 841May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE 842May 3 13:55:56 May 3 23:55:54 krbtgt/SU.SE@@E.KTH.SE 843May 3 14:10:54 May 3 23:55:54 host/hummel.it.su.se@@SU.SE 844 845@end example 846 847@node Transit policy, Setting up DNS, Cross realm, Setting up a realm 848@section Transit policy 849@cindex Transit policy 850 851Under some circumstances, you may not wish to set up direct 852cross-realm trust with every realm to which you wish to authenticate 853or from which you wish to accept authentications. Kerberos supports 854multi-hop cross-realm trust where a client principal in realm A 855authenticates to a service in realm C through a realm B with which 856both A and C have cross-realm trust relationships. In this situation, 857A and C need not set up cross-realm principals between each other. 858 859If you want to use cross-realm authentication through an intermediate 860realm, it must be explicitly allowed by either the KDCs for the realm 861to which the client is authenticating (in this case, realm C), or the 862server receiving the request. This is done in @file{krb5.conf} in the 863@code{[capaths]} section. 864 865In addition, the client in realm A need to be configured to know how 866to reach realm C via realm B. This can be done either on the client or 867via KDC configuration in the KDC for realm A. 868 869@subsection Allowing cross-realm transits 870 871When the ticket transits through a realm to another realm, the 872destination realm adds its peer to the "transited-realms" field in the 873ticket. The field is unordered, since there is no way to know if know 874if one of the transited-realms changed the order of the list. For the 875authentication to be accepted by the final destination realm, all of 876the transited realms must be listed as trusted in the @code{[capaths]} 877configuration, either in the KDC for the destination realm or on the 878server receiving the authentication. 879 880The syntax for @code{[capaths]} section is: 881 882@example 883[capaths] 884 CLIENT-REALM = @{ 885 SERVER-REALM = PERMITTED-CROSS-REALMS ... 886 @} 887@end example 888 889In the following example, the realm @code{STACKEN.KTH.SE} only has 890direct cross-realm set up with @code{KTH.SE}. @code{KTH.SE} has 891direct cross-realm set up with @code{STACKEN.KTH.SE} and @code{SU.SE}. 892@code{DSV.SU.SE} only has direct cross-realm set up with @code{SU.SE}. 893The goal is to allow principals in the @code{DSV.SU.SE} or 894@code{SU.SE} realms to authenticate to services in 895@code{STACKEN.KTH.SE}. This is done with the following 896@code{[capaths]} entry on either the server accepting authentication 897or on the KDC for @code{STACKEN.KTH.SE}. 898 899@example 900[capaths] 901 SU.SE = @{ 902 STACKEN.KTH.SE = KTH.SE 903 @} 904 DSV.SU.SE = @{ 905 STACKEN.KTH.SE = SU.SE KTH.SE 906 @} 907@end example 908 909The first entry allows cross-realm authentication from clients in 910@code{SU.SE} transiting through @code{KTH.SE} to 911@code{STACKEN.KTH.SE}. The second entry allows cross-realm 912authentication from clients in @code{DSV.SU.SE} transiting through 913both @code{SU.SE} and @code{KTH.SE} to @code{STACKEN.KTH.SE}. 914 915Be careful of which realm goes where; it's easy to put realms in the 916wrong place. The block is tagged with the client realm (the realm of 917the principal authenticating), and the realm before the equal sign is 918the final destination realm: the realm to which the client is 919authenticating. After the equal sign go all the realms that the 920client transits through. 921 922The order of the @code{PERMITTED-CROSS-REALMS} is not important when 923doing transit cross realm verification. 924 925@subsection Configuring client cross-realm transits 926 927The @code{[capaths]} section is also used for another purpose: to tell 928clients which realm to transit through to reach a realm with which 929their local realm does not have cross-realm trust. This can be done 930by either putting a @code{[capaths]} entry in the configuration of the 931client or by putting the entry in the configuration of the KDC for the 932client's local realm. In the latter case, the KDC will then hand back 933a referral to the client when the client requests a cross-realm ticket 934to the destination realm, telling the client to try to go through an 935intermediate realm. 936 937For client configuration, the order of @code{PERMITTED-CROSS-REALMS} 938is significant, since only the first realm in this section (after the 939equal sign) is used by the client. 940 941For example, again consider the @code{[capaths]} entry above for the 942case of a client in the @code{SU.SE} realm, and assume that the client 943or the @code{SU.SE} KDC has that @code{[capaths]} entry. If the 944client attempts to authenticate to a service in the 945@code{STACKEN.KTH.SE} realm, that entry says to first authenticate 946cross-realm to the @code{KTH.SE} realm (the first realm listed in the 947@code{PERMITTED-CROSS-REALMS} section), and then from there to 948@code{STACKEN.KTH.SE}. 949 950Each entry in @code{[capaths]} can only give the next hop, since only 951the first realm in @code{PERMITTED-CROSS-REALMS} is used. If, for 952instance, a client in @code{DSV.SU.SE} had a @code{[capaths]} 953configuration as above but without the first block for @code{SU.SE}, 954they would not be able to reach @code{STACKEN.KTH.SE}. They would get 955as far as @code{SU.SE} based on the @code{DSV.SU.SE} entry in 956@code{[capaths]} and then attempt to go directly from there to 957@code{STACKEN.KTH.SE} and get stuck (unless, of course, the 958@code{SU.SE} KDC had the additional entry required to tell the client 959to go through @code{KTH.SE}). 960 961@subsection Active Directory forest example 962 963One common place where a @code{[capaths]} configuration is desirable 964is with Windows Active Directory forests. One common Active Directory 965configuration is to have one top-level Active Directory realm but then 966divide systems, services, and users into child realms (perhaps based 967on organizational unit). One generally establishes cross-realm trust 968only with the top-level realm, and then uses transit policy to permit 969authentications to and from the child realms. 970 971For example, suppose an organization has a Heimdal realm 972@code{EXAMPLE.COM}, a Windows Active Directory realm 973@code{WIN.EXAMPLE.COM}, and then child Active Directory realms 974@code{ENGR.WIN.EXAMPLE.COM} and @code{SALES.WIN.EXAMPLE.COM}. The 975goal is to allow users in any of these realms to authenticate to 976services in any of these realms. The @code{EXAMPLE.COM} KDC (and 977possibly client) configuration should therefore contain a 978@code{[capaths]} section as follows: 979 980@example 981[capaths] 982 ENGR.WIN.EXAMPLE.COM = @{ 983 EXAMPLE.COM = WIN.EXAMPLE.COM 984 @} 985 SALES.WIN.EXAMPLE.COM = @{ 986 EXAMPLE.COM = WIN.EXAMPLE.COM 987 @} 988 EXAMPLE.COM = @{ 989 ENGR.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM 990 SALES.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM 991 @} 992@end example 993 994The first two blocks allow clients in the @code{ENGR.WIN.EXAMPLE.COM} 995and @code{SALES.WIN.EXAMPLE.COM} realms to authenticate to services in 996the @code{EXAMPLE.COM} realm. The third block tells the client (or 997tells the KDC to tell the client via referrals) to transit through 998@code{WIN.EXAMPLE.COM} to reach these realms. Both sides of the 999configuration are needed for bi-directional transited cross-realm 1000authentication. 1001 1002@c To test the cross realm configuration, use: 1003@c kmumble transit-check client server transit-realms ... 1004 1005@node Setting up DNS, How clients locate Kerberos KDCs, Transit policy, Setting up a realm 1006@section Setting up DNS 1007@cindex Setting up DNS 1008 1009@subsection Using DNS to find KDC 1010 1011If there is information about where to find the KDC or kadmind for a 1012realm in the @file{krb5.conf} for a realm, that information will be 1013preferred, and DNS will not be queried. 1014 1015Heimdal will try to use DNS to find the KDCs for a realm. First it 1016will try to find a @code{SRV} resource record (RR) for the realm. If no 1017SRV RRs are found, it will fall back to looking for an @code{A} RR for 1018a machine named kerberos.REALM, and then kerberos-1.REALM, etc 1019 1020Adding this information to DNS minimises the client configuration (in 1021the common case, resulting in no configuration needed) and allows the 1022system administrator to change the number of KDCs and on what machines 1023they are running without caring about clients. 1024 1025The downside of using DNS is that the client might be fooled to use the 1026wrong server if someone fakes DNS replies/data, but storing the IP 1027addresses of the KDC on all the clients makes it very hard to change 1028the infrastructure. 1029 1030An example of the configuration for the realm @code{EXAMPLE.COM}: 1031 1032@example 1033 1034$ORIGIN example.com. 1035_kerberos._tcp SRV 10 1 88 kerberos.example.com. 1036_kerberos._udp SRV 10 1 88 kerberos.example.com. 1037_kerberos._tcp SRV 10 1 88 kerberos-1.example.com. 1038_kerberos._udp SRV 10 1 88 kerberos-1.example.com. 1039_kpasswd._udp SRV 10 1 464 kerberos.example.com. 1040_kerberos-adm._tcp SRV 10 1 749 kerberos.example.com. 1041 1042@end example 1043 1044More information about DNS SRV resource records can be found in 1045RFC-2782 (A DNS RR for specifying the location of services (DNS SRV)). 1046 1047@subsection Using DNS to map hostname to Kerberos realm 1048 1049Heimdal also supports a way to lookup a realm from a hostname. This to 1050minimise configuration needed on clients. Using this has the drawback 1051that clients can be redirected by an attacker to realms within the 1052same cross realm trust and made to believe they are talking to the 1053right server (since Kerberos authentication will succeed). 1054 1055An example configuration that informs clients that for the realms 1056it.example.com and srv.example.com, they should use the realm 1057EXAMPLE.COM: 1058 1059@example 1060 1061$ORIGIN example.com. 1062_kerberos.it TXT "EXAMPLE.COM" 1063_kerberos.srv TXT "EXAMPLE.COM" 1064 1065@end example 1066 1067@node How clients locate Kerberos KDCs, Using LDAP to store the database, Setting up DNS, Setting up a realm 1068@section How clients locate Kerberos KDCs 1069@cindex Locate KDC 1070 1071clients use the following order to search for Kerberos KDC locations: 1072 1073@enumerate 1074@item plugins 1075@item configuration files 1076 @enumerate 1077 @item $KRB5_CONFIG (if not setuid) 1078 @item ~/Library/Preferences/edu.mit.Kerberos (on Mac OS X only) 1079 @item ~/Library/Preferences/com.apple.Kerberos.plist (on Mac OS X only) 1080 @item /Library/Preferences/edu.mit.Kerberos (on Mac OS X only) 1081 @item /Library/Preferences/com.apple.Kerberos.plist (on Mac OS X only) 1082 @item /etc/krb5.conf 1083 @end enumerate 1084@item dns 1085@end enumerate 1086 1087 1088@node Using LDAP to store the database, Providing Kerberos credentials to servers and programs, How clients locate Kerberos KDCs, Setting up a realm 1089@section Using LDAP to store the database 1090@cindex Using the LDAP backend 1091 1092This document describes how to install the LDAP backend for 1093Heimdal. Note that before attempting to configure such an 1094installation, you should be aware of the implications of storing 1095private information (such as users' keys) in a directory service 1096primarily designed for public information. Nonetheless, with a 1097suitable authorisation policy, it is possible to set this up in a 1098secure fashion. A knowledge of LDAP, Kerberos, and C is necessary to 1099install this backend. The HDB schema was devised by Leif Johansson. 1100 1101This assumes, OpenLDAP 2.3 or later. 1102 1103Requirements: 1104 1105@itemize @bullet 1106 1107@item 1108A current release of Heimdal, configured with 1109@code{--with-openldap=/usr/local} (adjust according to where you have 1110installed OpenLDAP). 1111 1112You can verify that you manage to configure LDAP support by running 1113@file{kdc --builtin-hdb}, and checking that @samp{ldap:} is one entry 1114in the list. 1115 1116Its also possible to configure the ldap backend as a shared module, 1117see option --hdb-openldap-module to configure. 1118 1119@item 1120Configure OpenLDAP with @kbd{--enable-local} to enable the local transport. 1121 1122@item 1123Add the hdb schema to the LDAP server, it's included in the source-tree 1124in @file{lib/hdb/hdb.schema}. Example from slapd.conf: 1125 1126@example 1127include /usr/local/etc/openldap/schema/hdb.schema 1128@end example 1129 1130@item 1131Configure the LDAP server ACLs to accept writes from clients over the 1132local transport. For example: 1133 1134@example 1135access to * 1136 by dn.exact="uid=heimdal,dc=services,dc=example,dc=com" write 1137 ... 1138 1139authz-regexp "gidNumber=.*\\\+uidNumber=0,cn=peercred,cn=external,cn=auth'' 1140 "uid=heimdal,dc=services,dc=example,dc=com" 1141 1142@end example 1143 1144The sasl-regexp is for mapping between the SASL/EXTERNAL and a user in 1145a tree. The user that the key is mapped to should be have a 1146krb5Principal aux object with krb5PrincipalName set so that the 1147``creator'' and ``modifier'' is right in @file{kadmin}. 1148 1149Another option is to create an admins group and add the dn to that 1150group. 1151 1152Since Heimdal talks to the LDAP server over a UNIX domain socket, and 1153uses external sasl authentication, it's not possible to require 1154security layer quality (ssf in cyrus-sasl lingo). So that requirement 1155has to be turned off in OpenLDAP @command{slapd} configuration file 1156@file{slapd.conf}. 1157 1158@example 1159sasl-secprops minssf=0 1160@end example 1161 1162@item 1163 1164Start @command{slapd} with the local listener (as well as the default TCP/IP 1165listener on port 389) as follows: 1166 1167@example 1168 slapd -h "ldapi:/// ldap:///" 1169@end example 1170 1171Note: These is a bug in @command{slapd} where it appears to corrupt the krb5Key 1172binary attribute on shutdown. This may be related to our use of the V3 1173schema definition syntax instead of the old UMich-style, V2 syntax. 1174 1175@item 1176You should specify the distinguished name under which your 1177principals will be stored in @file{krb5.conf}. Also you need to 1178enter the path to the kadmin acl file: 1179 1180 1181@example 1182[kdc] 1183 database = @{ 1184 dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com 1185 hdb-ldap-structural-object = inetOrgPerson 1186 acl_file = /path/to/kadmind.acl 1187 mkey_file = /path/to/mkey 1188 @} 1189@end example 1190 1191@samp{mkey_file} can be excluded if you feel that you trust your ldap 1192directory to have the raw keys inside it. The 1193hdb-ldap-structural-object is not necessary if you do not need Samba 1194comatibility. 1195 1196 1197 1198@item 1199Once you have built Heimdal and started the LDAP server, run kadmin 1200(as usual) to initialise the database. Note that the instructions for 1201stashing a master key are as per any Heimdal installation. 1202 1203@example 1204kdc# kadmin -l 1205kadmin> init EXAMPLE.COM 1206Realm max ticket life [unlimited]: 1207Realm max renewable ticket life [unlimited]: 1208kadmin> add lukeh 1209Max ticket life [1 day]: 1210Max renewable life [1 week]: 1211Principal expiration time [never]: 1212Password expiration time [never]: 1213Attributes []: 1214lukeh@@EXAMPLE.COM's Password: 1215Verifying password - lukeh@@EXAMPLE.COM's Password: 1216kadmin> exit 1217@end example 1218 1219Verify that the principal database has indeed been stored in the 1220directory with the following command: 1221 1222@example 1223kdc# ldapsearch -L -h localhost -D cn=manager \ 1224 -w secret -b ou=KerberosPrincipals,dc=example,dc=com \ 1225 'objectclass=krb5KDCEntry' 1226@end example 1227 1228@item 1229Now consider adding indexes to the database to speed up the access, at 1230least theses should be added to slapd.conf. 1231 1232@example 1233index objectClass eq 1234index cn eq,sub,pres 1235index uid eq,sub,pres 1236index displayName eq,sub,pres 1237index krb5PrincipalName eq 1238@end example 1239 1240@end itemize 1241 1242@subsection smbk5pwd overlay 1243 1244The smbk5pwd overlay, updates the krb5Key and krb5KeyVersionNumber 1245appropriately when it receives an LDAP Password change Extended 1246Operation: 1247 1248@url{http://www.openldap.org/devel/cvsweb.cgi/contrib/slapd-modules/smbk5pwd/README?hideattic=1&sortbydate=0} 1249 1250@subsection Troubleshooting guide 1251 1252@url{https://sec.miljovern.no/bin/view/Info/TroubleshootingGuide} 1253 1254 1255@subsection Using Samba LDAP password database 1256@cindex Samba 1257 1258@c @node Using Samba LDAP password database, Providing Kerberos credentials to servers and programs, Using LDAP to store the database, Setting up a realm 1259@c @section Using Samba LDAP password database 1260 1261The Samba domain and the Kerberos realm can have different names since 1262arcfour's string to key functions principal/realm independent. So now 1263will be your first and only chance name your Kerberos realm without 1264needing to deal with old configuration files. 1265 1266First, you should set up Samba and get that working with LDAP backend. 1267 1268Now you can proceed as in @xref{Using LDAP to store the database}. 1269Heimdal will pick up the Samba LDAP entries if they are in the same 1270search space as the Kerberos entries. 1271 1272@node Providing Kerberos credentials to servers and programs, Setting up PK-INIT, Using LDAP to store the database, Setting up a realm 1273@section Providing Kerberos credentials to servers and programs 1274 1275Some services require Kerberos credentials when they start to make 1276connections to other services or need to use them when they have started. 1277 1278The easiest way to get tickets for a service is to store the key in a 1279keytab. Both ktutil get and kadmin ext can be used to get a 1280keytab. ktutil get is better in that way it changes the key/password 1281for the user. This is also the problem with ktutil. If ktutil is used 1282for the same service principal on several hosts, they keytab will only 1283be useful on the last host. In that case, run the extract command on 1284one host and then securely copy the keytab around to all other hosts 1285that need it. 1286 1287@example 1288host# ktutil -k /etc/krb5-service.keytab \ 1289 get -p lha/admin@@EXAMPLE.ORG service-principal@@EXAMPLE.ORG 1290lha/admin@@EXAMPLE.ORG's Password: 1291@end example 1292 1293To get a Kerberos credential file for the service, use kinit in the 1294@kbd{--keytab} mode. This will not ask for a password but instead fetch the 1295key from the keytab. 1296 1297@example 1298service@@host$ kinit --cache=/var/run/service_krb5_cache \ 1299 --keytab=/etc/krb5-service.keytab \ 1300 service-principal@@EXAMPLE.ORG 1301@end example 1302 1303Long running services might need credentials longer then the 1304expiration time of the tickets. kinit can run in a mode that refreshes 1305the tickets before they expire. This is useful for services that write 1306into AFS and other distributed file systems using Kerberos. To run the 1307long running script, just append the program and arguments (if any) 1308after the principal. kinit will stop refreshing credentials and remove 1309the credentials when the script-to-start-service exits. 1310 1311@example 1312service@@host$ kinit --cache=/var/run/service_krb5_cache \ 1313 --keytab=/etc/krb5-service.keytab \ 1314 service-principal@@EXAMPLE.ORG \ 1315 script-to-start-service argument1 argument2 1316@end example 1317 1318 1319@node Setting up PK-INIT, KDC maintainence, Providing Kerberos credentials to servers and programs, Setting up a realm 1320@section Setting up PK-INIT 1321 1322PK-INIT leverages an existing PKI (public key infrastructure), using 1323certificates to get the initial ticket (usually the krbtgt 1324ticket-granting ticket). 1325 1326To use PK-INIT you must first have a PKI. If you don't have one, it is 1327time to create it. You should first read the whole chapter of the 1328document to see the requirements imposed on the CA software. 1329 1330A mapping between the PKI certificate and what principals that 1331certificate is allowed to use must exist. There are several ways to do 1332this. The administrator can use a configuration file, store the 1333principal in the SubjectAltName extension of the certificate, or store 1334the mapping in the principals entry in the kerberos database. 1335 1336@section Certificates 1337 1338This section documents the requirements on the KDC and client 1339certificates and the format used in the id-pkinit-san OtherName 1340extention. 1341 1342@subsection KDC certificate 1343 1344The certificate for the KDC has serveral requirements. 1345 1346First, the certificate should have an Extended Key Usage (EKU) 1347id-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second, there must be a 1348subjectAltName otherName using OID id-pkinit-san (1.3.6.1.5.2.2) in 1349the type field and a DER encoded KRB5PrincipalName that matches the 1350name of the TGS of the target realm. Also, if the certificate has a 1351nameConstraints extention with a Generalname with dNSName or iPAdress, 1352it must match the hostname or adress of the KDC. 1353 1354The client is not required by the standard to check the server 1355certificate for this information if the client has external 1356information confirming which certificate the KDC is supposed to be 1357using. However, adding this information to the KDC certificate removes 1358the need to specially configure the client to recognize the KDC 1359certificate. 1360 1361Remember that if the client would accept any certificate as the KDC's 1362certificate, the client could be fooled into trusting something that 1363isn't a KDC and thus expose the user to giving away information (like 1364a password or other private information) that it is supposed to keep 1365secret. 1366 1367@subsection Client certificate 1368 1369The client certificate may need to have a EKU id-pkekuoid 1370(1.3.6.1.5.2.3.4) set depending on the certifiate on the KDC. 1371 1372It possible to store the principal (if allowed by the KDC) in the 1373certificate and thus delegate responsibility to do the mapping between 1374certificates and principals to the CA. 1375 1376This behavior is controlled by KDC configuration option: 1377 1378@example 1379[kdc] 1380 pkinit_principal_in_certificate = yes 1381@end example 1382 1383@subsubsection Using KRB5PrincipalName in id-pkinit-san 1384 1385The OtherName extention in the GeneralName is used to do the mapping 1386between certificate and principal. For the KDC certificate, this 1387stores the krbtgt principal name for that KDC. For the client 1388certificate, this stores the principal for which that certificate is 1389allowed to get tickets. 1390 1391The principal is stored in a SubjectAltName in the certificate using 1392OtherName. The OID in the type is id-pkinit-san. 1393 1394@example 1395id-pkinit-san OBJECT IDENTIFIER ::= @{ iso (1) org (3) dod (6) 1396internet (1) security (5) kerberosv5 (2) 2 @} 1397@end example 1398 1399The data part of the OtherName is filled with the following DER 1400encoded ASN.1 structure: 1401 1402@example 1403KRB5PrincipalName ::= SEQUENCE @{ 1404 realm [0] Realm, 1405 principalName [1] PrincipalName 1406@} 1407@end example 1408 1409where Realm and PrincipalName is defined by the Kerberos ASN.1 1410specification. 1411 1412@section Naming certificate using hx509 1413 1414hx509 is the X.509 software used in Heimdal to handle 1415certificates. hx509 supports several different syntaxes for specifying 1416certificate files or formats. Several formats may be used: PEM, 1417certificates embedded in PKCS#12 files, certificates embedded in 1418PKCS#11 devices, and raw DER encoded certificates. 1419 1420Those formats may be specified as follows: 1421 1422@table @asis 1423 1424@item DIR: 1425 1426DIR specifies a directory which contains certificates in the DER or 1427PEM format. 1428 1429The main feature of DIR is that the directory is read on demand when 1430iterating over certificates. This allows applications, in some 1431situations, to avoid having to store all certificates in memory. It's 1432very useful for tests that iterate over large numbers of certificates. 1433 1434The syntax is: 1435 1436@example 1437DIR:/path/to/der/files 1438@end example 1439 1440@item FILE: 1441 1442FILE: specifies a file that contains a certificate or private key. 1443The file can be either a PEM (openssl) file or a raw DER encoded 1444certificate. If it's a PEM file, it can contain several keys and 1445certificates and the code will try to match the private key and 1446certificate together. Multiple files may be specified, separated by 1447commas. 1448 1449It's useful to have one PEM file that contains all the trust anchors. 1450 1451The syntax is: 1452 1453@example 1454FILE:certificate.pem,private-key.key,other-cert.pem,.... 1455@end example 1456 1457@item PKCS11: 1458 1459PKCS11: is used to handle smartcards via PKCS#11 drivers, such as 1460soft-token, opensc, or muscle. The argument specifies a shared object 1461that implements the PKCS#11 API. The default is to use all slots on 1462the device/token. 1463 1464The syntax is: 1465 1466@example 1467PKCS11:shared-object.so 1468@end example 1469 1470@item PKCS12: 1471 1472PKCS12: is used to handle PKCS#12 files. PKCS#12 files commonly have 1473the extension pfx or p12. 1474 1475The syntax is: 1476 1477@example 1478PKCS12:/path/to/file.pfx 1479@end example 1480 1481@end table 1482 1483@section Configure the Kerberos software 1484 1485First configure the client's trust anchors and what parameters to 1486verify. See the subsections below for how to do that. Then, you can 1487use kinit to get yourself tickets. For example: 1488 1489@example 1490$ kinit -C FILE:$HOME/.certs/lha.crt,$HOME/.certs/lha.key lha@@EXAMPLE.ORG 1491Enter your private key passphrase: 1492: lha@@nutcracker ; klist 1493Credentials cache: FILE:/tmp/krb5cc_19100a 1494 Principal: lha@@EXAMPLE.ORG 1495 1496 Issued Expires Principal 1497Apr 20 02:08:08 Apr 20 12:08:08 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG 1498@end example 1499 1500Using PKCS#11 it can look like this instead: 1501 1502@example 1503$ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@@EXAMPLE.ORG 1504PIN code for SoftToken (slot): 1505$ klist 1506Credentials cache: API:4 1507 Principal: lha@@EXAMPLE.ORG 1508 1509 Issued Expires Principal 1510Mar 26 23:40:10 Mar 27 09:40:10 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG 1511@end example 1512 1513TODO: Write about the KDC. 1514 1515@section Configure the client 1516 1517@example 1518[appdefaults] 1519 pkinit_anchors = FILE:/path/to/trust-anchors.pem 1520 1521[realms] 1522 EXAMPLE.COM = @{ 1523 pkinit_require_eku = true 1524 pkinit_require_krbtgt_otherName = true 1525 pkinit_win2k = no 1526 pkinit_win2k_require_binding = yes 1527 @} 1528 1529@end example 1530 1531@section Configure the KDC 1532 1533@example 1534[kdc] 1535 enable-pkinit = yes 1536 pkinit_identity = FILE:/secure/kdc.crt,/secure/kdc.key 1537 pkinit_anchors = FILE:/path/to/trust-anchors.pem 1538 pkinit_pool = PKCS12:/path/to/useful-intermediate-certs.pfx 1539 pkinit_pool = FILE:/path/to/other-useful-intermediate-certs.pem 1540 pkinit_allow_proxy_certificate = no 1541 pkinit_win2k_require_binding = yes 1542 pkinit_principal_in_certificate = no 1543@end example 1544 1545@subsection Using pki-mapping file 1546 1547Note that the file name is space sensitive. 1548 1549@example 1550# cat /var/heimdal/pki-mapping 1551# comments starts with # 1552lha@@EXAMPLE.ORG:C=SE,O=Stockholm universitet,CN=Love,UID=lha 1553lha@@EXAMPLE.ORG:CN=Love,UID=lha 1554@end example 1555 1556@subsection Using the Kerberos database 1557 1558@section Use hxtool to create certificates 1559 1560@subsection Generate certificates 1561 1562First, you need to generate a CA certificate. This example creates a 1563CA certificate that will be valid for 10 years. 1564 1565You need to change --subject in the command below to something 1566appropriate for your site. 1567 1568@example 1569hxtool issue-certificate \ 1570 --self-signed \ 1571 --issue-ca \ 1572 --generate-key=rsa \ 1573 --subject="CN=CA,DC=test,DC=h5l,DC=se" \ 1574 --lifetime=10years \ 1575 --certificate="FILE:ca.pem" 1576@end example 1577 1578The KDC needs to have a certificate, so generate a certificate of the 1579type ``pkinit-kdc'' and set the PK-INIT specifial SubjectAltName to the 1580name of the krbtgt of the realm. 1581 1582You need to change --subject and --pk-init-principal in the command 1583below to something appropriate for your site. 1584 1585@example 1586hxtool issue-certificate \ 1587 --ca-certificate=FILE:ca.pem \ 1588 --generate-key=rsa \ 1589 --type="pkinit-kdc" \ 1590 --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \ 1591 --subject="uid=kdc,DC=test,DC=h5l,DC=se" \ 1592 --certificate="FILE:kdc.pem" 1593@end example 1594 1595The users also needs to have certificates. For your first client, 1596generate a certificate of type ``pkinit-client''. The client doesn't 1597need to have the PK-INIT SubjectAltName set; you can have the Subject 1598DN in the ACL file (pki-mapping) instead. 1599 1600You need to change --subject and --pk-init-principal in the command 1601below to something appropriate for your site. You can omit 1602--pk-init-principal if you're going to use the ACL file instead. 1603 1604@example 1605hxtool issue-certificate \ 1606 --ca-certificate=FILE:ca.pem \ 1607 --generate-key=rsa \ 1608 --type="pkinit-client" \ 1609 --pk-init-principal="lha@@TEST.H5L.SE" \ 1610 --subject="uid=lha,DC=test,DC=h5l,DC=se" \ 1611 --certificate="FILE:user.pem" 1612@end example 1613 1614@subsection Validate the certificate 1615 1616hxtool also contains a tool that will validate certificates according 1617to rules from the PKIX document. These checks are not complete, but 1618they provide a good test of whether you got all of the basic bits 1619right in your certificates. 1620 1621@example 1622hxtool validate FILE:user.pem 1623@end example 1624 1625@section Use OpenSSL to create certificates 1626 1627This section tries to give the CA owners hints how to create 1628certificates using OpenSSL (or CA software based on OpenSSL). 1629 1630@subsection Using OpenSSL to create certificates with krb5PrincipalName 1631 1632To make OpenSSL create certificates with krb5PrincipalName, use an 1633@file{openssl.cnf} as described below. To see a complete example of 1634creating client and KDC certificates, see the test-data generation 1635script @file{lib/hx509/data/gen-req.sh} in the source-tree. The 1636certicates it creates are used to test the PK-INIT functionality in 1637@file{tests/kdc/check-kdc.in}. 1638 1639To use this example you have to use OpenSSL 0.9.8a or later. 1640 1641@example 1642 1643[user_certificate] 1644subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name 1645 1646[princ_name] 1647realm = EXP:0, GeneralString:MY.REALM 1648principal_name = EXP:1, SEQUENCE:principal_seq 1649 1650[principal_seq] 1651name_type = EXP:0, INTEGER:1 1652name_string = EXP:1, SEQUENCE:principals 1653 1654[principals] 1655princ1 = GeneralString:userid 1656 1657@end example 1658 1659Command usage: 1660 1661@example 1662openssl x509 -extensions user_certificate 1663openssl ca -extensions user_certificate 1664@end example 1665 1666 1667@c --- ms certificate 1668@c 1669@c [ new_oids ] 1670@c msCertificateTemplateName = 1.3.6.1.4.1.311.20.2 1671@c 1672@c 1673@c [ req_smartcard ] 1674@c keyUsage = digitalSignature, keyEncipherment 1675@c extendedKeyUsage = msSmartcardLogin, clientAuth 1676@c msCertificateTemplateName = ASN1:BMP:SmartcardLogon 1677@c subjectAltName = otherName:msUPN;UTF8:lukeh@dsg.padl.com 1678@c #subjectAltName = email:copy 1679 1680 1681@section Using PK-INIT with Windows 1682 1683@subsection Client configration 1684 1685Clients using a Windows KDC with PK-INIT need configuration since 1686windows uses pre-standard format and this can't be autodetected. 1687 1688The pkinit_win2k_require_binding option requires the reply for the KDC 1689to be of the new, secure, type that binds the request to 1690reply. Before, clients could fake the reply from the KDC. To use this 1691option you have to apply a fix from Microsoft. 1692 1693@example 1694[realms] 1695 MY.MS.REALM = @{ 1696 pkinit_win2k = yes 1697 pkinit_win2k_require_binding = no 1698 @} 1699@end example 1700 1701@subsection Certificates 1702 1703The client certificates need to have the extended keyusage ``Microsoft 1704Smartcardlogin'' (openssl has the OID shortname msSmartcardLogin). 1705 1706See Microsoft Knowledge Base Article - 281245 ``Guidelines for Enabling 1707Smart Card Logon with Third-Party Certification Authorities'' for a 1708more extensive description of how set setup an external CA so that it 1709includes all the information required to make a Windows KDC happy. 1710 1711@subsection Configure Windows 2000 CA 1712 1713To enable Microsoft Smartcardlogin for certificates in your Windows 17142000 CA, you want to look at Microsoft Knowledge Base Article - 313274 1715``HOW TO: Configure a Certification Authority to Issue Smart Card 1716Certificates in Windows''. 1717 1718@node KDC maintainence, Debugging Kerberos problems, Setting up PK-INIT, Setting up a realm 1719@setting KDC maintainence 1720 1721As part of the regular maintainence of the KDC you should: 1722 1723@itemize @bullet 1724@item Backup the KDC database 1725@item Update the master key 1726@enditemize 1727 1728@subsection Backup the KDC database 1729 1730hprop can dump the data with the keys encrypted or non 1731encrypted, encrypt is default. 1732 1733For backups you should probably use encrypted backups. 1734 1735# hprop --stdout | gzip -9 > backup-$(date '+%Y%m%d-%H%M%S').gz 1736 1737Using ISO style dates are good since they sort in a senable order 1738which makes it easy to pick up the last backup or prune the first. 1739 1740@subsection Update the master key 1741 1742The master key encrypts the users keys. You should change it when 1743stronger encryption types are available or when changes in 1744maintainence of the KDC happens (KDC admin is removed from ACL, 1745removing/changing a KDC slave server, etc). 1746 1747The reason to change the master key is so you have a point in time 1748from where if an older version of the master key is compromised, all 1749changes past that point is safe to keep. 1750 1751Note that you don't need to change keys just to get new keys, modern 1752encryption ciphers can encrypt large amounts of data before needing to 1753change keys. 1754 1755Make sure you have propper backups before upgrade the master key. 1756 1757This example will dump a un-encrypted database, add a new master key 1758to the list of master keys, and then import the dump into the database 1759and re-encrypt it. 1760 1761@example 1762# hprop --decrypt --stdout > kdc-backup 1763# kadmin -l kstash --random 1764# hpropd --stdin < kdc-backup 1765@end example 1766 1767@node Debugging Kerberos problems, , KDC maintainence, Setting up a realm 1768@section Debugging Kerberos problems 1769 1770To debug Kerberos client and server problems you can enable debug 1771traceing by adding the following to @file{/etc/krb5,conf}. Note that the 1772trace logging is sparse at the moment, but will continue to improve. 1773 1774@example 1775[logging] 1776 libkrb5 = 0-/SYSLOG: 1777@end example 1778 1779 1780 1781 1782