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