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