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