1233294Sstas@c $Id$ 272445Sassar 3178825Sdfr@node Setting up a realm, Applications, Building and Installing, Top 472445Sassar 555682Smarkm@chapter Setting up a realm 655682Smarkm 7178825SdfrA 8178825Sdfr@cindex realm 9178825Sdfrrealm is an administrative domain. The name of a Kerberos realm is 10178825Sdfrusually the Internet domain name in uppercase. Call your realm the same 11178825Sdfras your Internet domain name if you do not have strong reasons for not 12178825Sdfrdoing so. It will make life easier for you and everyone else. 13178825Sdfr 1472445Sassar@menu 15178825Sdfr* Configuration file:: 16178825Sdfr* Creating the database:: 17178825Sdfr* Modifying the database:: 18178825Sdfr* Checking the setup:: 19178825Sdfr* keytabs:: 20178825Sdfr* Remote administration:: 21178825Sdfr* Password changing:: 22178825Sdfr* Testing clients and servers:: 23178825Sdfr* Slave Servers:: 24178825Sdfr* Incremental propagation:: 25178825Sdfr* Encryption types and salting:: 26233294Sstas* Credential cache server - KCM:: 27127808Snectar* Cross realm:: 28127808Snectar* Transit policy:: 29127808Snectar* Setting up DNS:: 30178825Sdfr* Using LDAP to store the database:: 31178825Sdfr* Providing Kerberos credentials to servers and programs:: 32178825Sdfr* Setting up PK-INIT:: 33233294Sstas* Debugging Kerberos problems:: 3472445Sassar@end menu 3572445Sassar 3672445Sassar@node Configuration file, Creating the database, Setting up a realm, Setting up a realm 3755682Smarkm@section Configuration file 3855682Smarkm 3955682SmarkmTo setup a realm you will first have to create a configuration file: 4055682Smarkm@file{/etc/krb5.conf}. The @file{krb5.conf} file can contain many 4155682Smarkmconfiguration options, some of which are described here. 4255682Smarkm 4355682SmarkmThere is a sample @file{krb5.conf} supplied with the distribution. 4455682Smarkm 4555682SmarkmThe configuration file is a hierarchical structure consisting of 4655682Smarkmsections, each containing a list of bindings (either variable 4755682Smarkmassignments or subsections). A section starts with 48178825Sdfr@samp{[@samp{section-name}]}. A binding consists of a left hand side, an equal sign 4955682Smarkm(@samp{=}) and a right hand side (the left hand side tag must be 50178825Sdfrseparated from the equal sign with some whitespace). Subsections have a 51178825Sdfr@samp{@{} as the first non-whitespace character after the equal sign. All 5255682Smarkmother bindings are treated as variable assignments. The value of a 5355682Smarkmvariable extends to the end of the line. 5455682Smarkm 5555682Smarkm@example 5655682Smarkm[section1] 5755682Smarkm a-subsection = @{ 5855682Smarkm var = value1 5955682Smarkm other-var = value with @{@} 60178825Sdfr sub-sub-section = @{ 6155682Smarkm var = 123 6255682Smarkm @} 6355682Smarkm @} 6455682Smarkm var = some other value 6555682Smarkm[section2] 6655682Smarkm var = yet another value 6755682Smarkm@end example 6855682Smarkm 6955682SmarkmIn this manual, names of sections and bindings will be given as strings 7055682Smarkmseparated by slashes (@samp{/}). The @samp{other-var} variable will thus 7155682Smarkmbe @samp{section1/a-subsection/other-var}. 7255682Smarkm 73127808SnectarFor in-depth information about the contents of the configuration file, refer to 7455682Smarkmthe @file{krb5.conf} manual page. Some of the more important sections 7555682Smarkmare briefly described here. 7655682Smarkm 7755682SmarkmThe @samp{libdefaults} section contains a list of library configuration 78127808Snectarparameters, such as the default realm and the timeout for KDC 7955682Smarkmresponses. The @samp{realms} section contains information about specific 80178825Sdfrrealms, such as where they hide their KDC@. This section serves the same 8155682Smarkmpurpose as the Kerberos 4 @file{krb.conf} file, but can contain more 8255682Smarkminformation. Finally the @samp{domain_realm} section contains a list of 8355682Smarkmmappings from domains to realms, equivalent to the Kerberos 4 8455682Smarkm@file{krb.realms} file. 8555682Smarkm 86127808SnectarTo continue with the realm setup, you will have to create a configuration file, 8755682Smarkmwith contents similar to the following. 8855682Smarkm 8955682Smarkm@example 9055682Smarkm[libdefaults] 9155682Smarkm default_realm = MY.REALM 9255682Smarkm[realms] 9355682Smarkm MY.REALM = @{ 94127808Snectar kdc = my.kdc my.slave.kdc 95127808Snectar kdc = my.third.kdc 96233294Sstas kdc = 130.237.237.17 97233294Sstas kdc = [2001:6b0:1:ea::100]:88 9855682Smarkm @} 9955682Smarkm[domain_realm] 10055682Smarkm .my.domain = MY.REALM 10155682Smarkm 10255682Smarkm@end example 10355682Smarkm 10455682SmarkmIf you use a realm name equal to your domain name, you can omit the 105178825Sdfr@samp{libdefaults}, and @samp{domain_realm}, sections. If you have a DNS 106178825SdfrSRV-record for your realm, or your Kerberos server has DNS CNAME 10755682Smarkm@samp{kerberos.my.realm}, you can omit the @samp{realms} section too. 10855682Smarkm 109233294Sstas@cindex KRB5_CONFIG 110233294SstasIf you want to use a different configuration file then the default you 111233294Sstascan point a file with the enviroment variable @samp{KRB5_CONFIG}. 112233294Sstas 113233294Sstas@example 114233294Sstasenv KRB5_CONFIG=$HOME/etc/krb5.conf kinit user@@REALM 115233294Sstas@end example 116233294Sstas 117178825Sdfr@node Creating the database, Modifying the database, Configuration file, Setting up a realm 11855682Smarkm@section Creating the database 11955682Smarkm 120127808SnectarThe database library will look for the database in the directory 121178825Sdfr@file{@value{dbdir}}, so you should probably create that directory. 122178825SdfrMake sure the directory has restrictive permissions. 12355682Smarkm 124127808Snectar@example 125127808Snectar# mkdir /var/heimdal 126127808Snectar@end example 127127808Snectar 12855682SmarkmThe keys of all the principals are stored in the database. If you 12955682Smarkmchoose to, these can be encrypted with a master key. You do not have to 13055682Smarkmremember this key (or password), but just to enter it once and it will 13155682Smarkmbe stored in a file (@file{/var/heimdal/m-key}). If you want to have a 13255682Smarkmmaster key, run @samp{kstash} to create this master key: 13355682Smarkm 13455682Smarkm@example 13555682Smarkm# kstash 136178825SdfrMaster key: 137178825SdfrVerifying password - Master key: 13855682Smarkm@end example 13955682Smarkm 140178825SdfrIf you want to generate a random master key you can use the 141178825Sdfr@kbd{--random-key} flag to kstash. This will make sure you have a good key 142178825Sdfron which attackers can't do a dictionary attack. 143178825Sdfr 144178825SdfrIf you have a master key, make sure you make a backup of your master 145178825Sdfrkey file; without it backups of the database are of no use. 146178825Sdfr 147178825SdfrTo initialise the database use the @command{kadmin} program, with the 148178825Sdfr@kbd{-l} option (to enable local database mode). First issue a 14955682Smarkm@kbd{init MY.REALM} command. This will create the database and insert 15055682Smarkmdefault principals for that realm. You can have more than one realm in 15155682Smarkmone database, so @samp{init} does not destroy any old database. 15255682Smarkm 15355682SmarkmBefore creating the database, @samp{init} will ask you some questions 154178825Sdfrabout maximum ticket lifetimes. 15555682Smarkm 15655682SmarkmAfter creating the database you should probably add yourself to it. You 15755682Smarkmdo this with the @samp{add} command. It takes as argument the name of a 158178825Sdfrprincipal. The principal should contain a realm, so if you haven't set up 15955682Smarkma default realm, you will need to explicitly include the realm. 16055682Smarkm 16155682Smarkm@example 16255682Smarkm# kadmin -l 16355682Smarkmkadmin> init MY.REALM 16455682SmarkmRealm max ticket life [unlimited]: 16555682SmarkmRealm max renewable ticket life [unlimited]: 166178825Sdfrkadmin> add me 16755682SmarkmMax ticket life [unlimited]: 16855682SmarkmMax renewable life [unlimited]: 16955682SmarkmAttributes []: 170178825SdfrPassword: 171178825SdfrVerifying password - Password: 17255682Smarkm@end example 17355682Smarkm 17455682SmarkmNow start the KDC and try getting a ticket. 17555682Smarkm 17655682Smarkm@example 17755682Smarkm# kdc & 17855682Smarkm# kinit me 17955682Smarkmme@@MY.REALMS's Password: 18055682Smarkm# klist 18155682SmarkmCredentials cache: /tmp/krb5cc_0 18255682Smarkm Principal: me@@MY.REALM 18355682Smarkm 18455682Smarkm Issued Expires Principal 18555682SmarkmAug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@@MY.REALM 18655682Smarkm@end example 18755682Smarkm 18855682SmarkmIf you are curious you can use the @samp{dump} command to list all the 18955682Smarkmentries in the database. It should look something similar to the 19055682Smarkmfollowing example (note that the entries here are truncated for 19155682Smarkmtypographical reasons): 19255682Smarkm 19355682Smarkm@smallexample 19455682Smarkmkadmin> dump 19555682Smarkmme@@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ... 19655682Smarkmkadmin/admin@@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ... 19755682Smarkmkrbtgt/MY.REALM@@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ... 19855682Smarkmkadmin/changepw@@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ... 19955682Smarkm@end smallexample 20055682Smarkm 201178825Sdfr@node Modifying the database, Checking the setup, Creating the database, Setting up a realm 202178825Sdfr@section Modifying the database 203178825Sdfr 204178825SdfrAll modifications of principals are done with with kadmin. 205178825Sdfr 206178825SdfrA principal has several attributes and lifetimes associated with it. 207178825Sdfr 208178825SdfrPrincipals are added, renamed, modified, and deleted with the kadmin 209178825Sdfrcommands @samp{add}, @samp{rename}, @samp{modify}, @samp{delete}. 210178825SdfrBoth interactive editing and command line flags can be used (use --help 211178825Sdfrto list the available options). 212178825Sdfr 213178825SdfrThere are different kinds of types for the fields in the database; 214178825Sdfrattributes, absolute time times and relative times. 215178825Sdfr 216178825Sdfr@subsection Attributes 217178825Sdfr 218178825SdfrWhen doing interactive editing, attributes are listed with @samp{?}. 219178825Sdfr 220178825SdfrThe attributes are given in a comma (@samp{,}) separated list. 221178825SdfrAttributes are removed from the list by prefixing them with @samp{-}. 222178825Sdfr 223178825Sdfr@smallexample 224178825Sdfrkadmin> modify me 225178825SdfrMax ticket life [1 day]: 226178825SdfrMax renewable life [1 week]: 227178825SdfrPrincipal expiration time [never]: 228178825SdfrPassword expiration time [never]: 229178825SdfrAttributes [disallow-renewable]: requires-pre-auth,-disallow-renewable 230178825Sdfrkadmin> get me 231178825Sdfr Principal: me@@MY.REALM 232178825Sdfr[...] 233178825Sdfr Attributes: requires-pre-auth 234178825Sdfr@end smallexample 235178825Sdfr 236178825Sdfr@subsection Absolute times 237178825Sdfr 238178825SdfrThe format for absolute times are any of the following: 239178825Sdfr 240178825Sdfr@smallexample 241178825Sdfrnever 242178825Sdfrnow 243178825SdfrYYYY-mm-dd 244178825SdfrYYYY-mm-dd HH:MM:SS 245178825Sdfr@end smallexample 246178825Sdfr 247178825Sdfr 248178825Sdfr@subsection Relative times 249178825Sdfr 250178825SdfrThe format for relative times are any of the following combined: 251178825Sdfr 252178825Sdfr@smallexample 253178825SdfrN year 254178825SdfrM month 255178825SdfrO day 256178825SdfrP hour 257178825SdfrQ minute 258178825SdfrR second 259178825Sdfr@end smallexample 260178825Sdfr 261178825Sdfr@c Describe more of kadmin commands here... 262178825Sdfr 263178825Sdfr@node Checking the setup, keytabs, Modifying the database, Setting up a realm 264178825Sdfr@section Checking the setup 265178825Sdfr 266178825SdfrThere are two tools that can check the consistency of the Kerberos 267178825Sdfrconfiguration file and the Kerberos database. 268178825Sdfr 269178825SdfrThe Kerberos configuration file is checked using 270178825Sdfr@command{verify_krb5_conf}. The tool checks for common errors, but 271178825Sdfrcommonly there are several uncommon configuration entries that are 272178825Sdfrnever added to the tool and thus generates ``unknown entry'' warnings. 273178825SdfrThis is usually nothing to worry about. 274178825Sdfr 275178825SdfrThe database check is built into the kadmin tool. It will check for 276178825Sdfrcommon configuration error that will cause problems later. Common 277178825Sdfrcheck are for existence and flags on important principals. The 278178825Sdfrdatabase check by run by the following command : 279178825Sdfr 280178825Sdfr@example 281233294Sstaskadmin -l check REALM.EXAMPLE.ORG 282178825Sdfr@end example 283178825Sdfr 284234027Sstas@node keytabs, Remote administration, Checking the setup, Setting up a realm 28555682Smarkm@section keytabs 28655682Smarkm 287178825SdfrTo extract a service ticket from the database and put it in a keytab, you 288233294Sstasneed to first create the principal in the database with @samp{add} 28972445Sassar(using the @kbd{--random-key} flag to get a random key) and then 29055682Smarkmextract it with @samp{ext_keytab}. 29155682Smarkm 29255682Smarkm@example 29372445Sassarkadmin> add --random-key host/my.host.name 29455682SmarkmMax ticket life [unlimited]: 29555682SmarkmMax renewable life [unlimited]: 29655682SmarkmAttributes []: 29755682Smarkmkadmin> ext host/my.host.name 298178825Sdfrkadmin> exit 29955682Smarkm# ktutil list 30055682SmarkmVersion Type Principal 30155682Smarkm 1 des-cbc-md5 host/my.host.name@@MY.REALM 30255682Smarkm 1 des-cbc-md4 host/my.host.name@@MY.REALM 30355682Smarkm 1 des-cbc-crc host/my.host.name@@MY.REALM 30455682Smarkm 1 des3-cbc-sha1 host/my.host.name@@MY.REALM 30555682Smarkm@end example 30655682Smarkm 307234027Sstas@node Remote administration, Password changing, keytabs, Setting up a realm 30855682Smarkm@section Remote administration 30955682Smarkm 310178825SdfrThe administration server, @command{kadmind}, can be started by 311178825Sdfr@command{inetd} (which isn't recommended) or run as a normal daemon. If you 312178825Sdfrwant to start it from @command{inetd} you should add a line similar to the 31372445Sassarone below to your @file{/etc/inetd.conf}. 31455682Smarkm 31555682Smarkm@example 31655682Smarkmkerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind 31755682Smarkm@end example 31855682Smarkm 31955682SmarkmYou might need to add @samp{kerberos-adm} to your @file{/etc/services} 320178825Sdfras @samp{749/tcp}. 32155682Smarkm 322178825SdfrAccess to the administration server is controlled by an ACL file, 323178825Sdfr(default @file{/var/heimdal/kadmind.acl}.) The file has the following 324178825Sdfrsyntax: 32555682Smarkm@smallexample 32672445Sassarprincipal [priv1,priv2,...] [glob-pattern] 32755682Smarkm@end smallexample 32855682Smarkm 329178825SdfrThe matching is from top to bottom for matching principals (and if given, 330178825Sdfrglob-pattern). When there is a match, the access rights of that line are 331178825Sdfrapplied. 33290926Snectar 33355682SmarkmThe privileges you can assign to a principal are: @samp{add}, 33455682Smarkm@samp{change-password} (or @samp{cpw} for short), @samp{delete}, 33555682Smarkm@samp{get}, @samp{list}, and @samp{modify}, or the special privilege 336178825Sdfr@samp{all}. All of these roughly correspond to the different commands 337178825Sdfrin @command{kadmin}. 33855682Smarkm 339178825SdfrIf a @var{glob-pattern} is given on a line, it restricts the access 340178825Sdfrrights for the principal to only apply for subjects that match the 341178825Sdfrpattern. The patterns are of the same type as those used in shell 342178825Sdfrglobbing, see @url{none,,fnmatch(3)}. 34372445Sassar 34472445SassarIn the example below @samp{lha/admin} can change every principal in the 34572445Sassardatabase. @samp{jimmy/admin} can only modify principals that belong to 34672445Sassarthe realm @samp{E.KTH.SE}. @samp{mille/admin} is working at the 347127808Snectarhelp desk, so he should only be able to change the passwords for single 34872445Sassarcomponent principals (ordinary users). He will not be able to change any 34972445Sassar@samp{/admin} principal. 35072445Sassar 35172445Sassar@example 35272445Sassarlha/admin@@E.KTH.SE all 35372445Sassarjimmy/admin@@E.KTH.SE all *@@E.KTH.SE 35472445Sassarjimmy/admin@@E.KTH.SE all */*@@E.KTH.SE 35572445Sassarmille/admin@@E.KTH.SE change-password *@@E.KTH.SE 35672445Sassar@end example 35772445Sassar 35872445Sassar@node Password changing, Testing clients and servers, Remote administration, Setting up a realm 35955682Smarkm@section Password changing 36055682Smarkm 361178825SdfrTo allow users to change their passwords, you should run @command{kpasswdd}. 362178825SdfrIt is not run from @command{inetd}. 36355682Smarkm 36455682SmarkmYou might need to add @samp{kpasswd} to your @file{/etc/services} as 365233294Sstas@samp{464/udp}. If your realm is not setup to use DNS, you might also 366233294Sstasneed to add a @samp{kpasswd_server} entry to the realm configuration 367233294Sstasin @file{/etc/krb5.conf} on client machines: 36855682Smarkm 369233294Sstas@example 370233294Sstas[realms] 371233294Sstas MY.REALM = @{ 372233294Sstas kdc = my.kdc my.slave.kdc 373233294Sstas kpasswd_server = my.kdc 374233294Sstas @} 375233294Sstas@end example 376233294Sstas 37755682Smarkm@subsection Password quality assurance 37855682Smarkm 37955682SmarkmIt is important that users have good passwords, both to make it harder 380178825Sdfrto guess them and to avoid off-line attacks (although 381178825Sdfrpre-authentication provides some defence against off-line attacks). 382178825SdfrTo ensure that the users choose good passwords, you can enable 383178825Sdfrpassword quality controls in @command{kpasswdd} and @command{kadmind}. 384178825SdfrThe controls themselves are done in a shared library or an external 385178825Sdfrprogram that is used by @command{kpasswdd}. To configure in these 386178825Sdfrcontrols, add lines similar to the following to your 387178825Sdfr@file{/etc/krb5.conf}: 38855682Smarkm 38955682Smarkm@example 39055682Smarkm[password_quality] 391233294Sstas policies = external-check builtin:minimum-length modulename:policyname 392178825Sdfr external_program = /bin/false 393178825Sdfr policy_libraries = @var{library1.so} @var{library2.so} 39455682Smarkm@end example 39555682Smarkm 396178825SdfrIn @samp{[password_quality]policies} the module name is optional if 397178825Sdfrthe policy name is unique in all modules (members of 398233294Sstas@samp{policy_libraries}). All built-in policies can be qualified with 399233294Sstasa module name of @samp{builtin} to unambiguously specify the built-in 400233294Sstaspolicy and not a policy by the same name from a loaded module. 40155682Smarkm 402233294SstasThe built-in policies are 403178825Sdfr 404178825Sdfr@itemize @bullet 405178825Sdfr 406178825Sdfr@item external-check 407178825Sdfr 408178825SdfrExecutes the program specified by @samp{[password_quality]external_program}. 409178825Sdfr 410178825SdfrA number of key/value pairs are passed as input to the program, one per 411178825Sdfrline, ending with the string @samp{end}. The key/value lines are of 412178825Sdfrthe form 41355682Smarkm@example 414178825Sdfrprincipal: @var{principal} 415178825Sdfrnew-password: @var{password} 41655682Smarkm@end example 417178825Sdfrwhere @var{password} is the password to check for the previous 418178825Sdfr@var{principal}. 41955682Smarkm 420178825SdfrIf the external application approves the password, it should return 421178825Sdfr@samp{APPROVED} on standard out and exit with exit code 0. If it 422178825Sdfrdoesn't approve the password, an one line error message explaining the 423178825Sdfrproblem should be returned on standard error and the application 424178825Sdfrshould exit with exit code 0. In case of a fatal error, the 425178825Sdfrapplication should, if possible, print an error message on standard 426178825Sdfrerror and exit with a non-zero error code. 42755682Smarkm 428178825Sdfr@item minimum-length 429178825Sdfr 430178825SdfrThe minimum length password quality check reads the configuration file 431178825Sdfrstanza @samp{[password_quality]min_length} and requires the password 432178825Sdfrto be at least this length. 433178825Sdfr 434178825Sdfr@item character-class 435178825Sdfr 436178825SdfrThe character-class password quality check reads the configuration 437178825Sdfrfile stanza @samp{[password_quality]min_classes}. The policy requires 438178825Sdfrthe password to have characters from at least that many character 439178825Sdfrclasses. Default value if not given is 3. 440178825Sdfr 441178825SdfrThe four different characters classes are, uppercase, lowercase, 442178825Sdfrnumber, special characters. 443178825Sdfr 444178825Sdfr@end itemize 445178825Sdfr 446178825SdfrIf you want to write your own shared object to check password 447178825Sdfrpolicies, see the manual page @manpage{kadm5_pwcheck,3}. 448178825Sdfr 44955682SmarkmCode for a password quality checking function that uses the cracklib 450178825Sdfrlibrary can be found in @file{lib/kadm5/sample_password_check.c} in 451178825Sdfrthe source code distribution. It requires that the cracklib library 452178825Sdfrbe built with the patch available at 45355682Smarkm@url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}. 45455682Smarkm 455178825SdfrA sample policy external program is included in 456178825Sdfr@file{lib/kadm5/check-cracklib.pl}. 45755682Smarkm 458178825SdfrIf no password quality checking function is configured, the only check 459178825Sdfrperformed is that the password is at least six characters long. 460178825Sdfr 461178825SdfrTo check the password policy settings, use the command 462233294Sstas@command{verify-password-quality} in @command{kadmin} program. The password 463178825Sdfrverification is only performed locally, on the client. It may be 464178825Sdfrconvenient to set the environment variable @samp{KRB5_CONFIG} to point 465178825Sdfrto a test version of @file{krb5.conf} while you're testing the 466178825Sdfr@samp{[password_quality]} stanza that way. 467178825Sdfr 46872445Sassar@node Testing clients and servers, Slave Servers, Password changing, Setting up a realm 46955682Smarkm@section Testing clients and servers 47055682Smarkm 47155682SmarkmNow you should be able to run all the clients and servers. Refer to the 47255682Smarkmappropriate man pages for information on how to use them. 47372445Sassar 47472445Sassar@node Slave Servers, Incremental propagation, Testing clients and servers, Setting up a realm 47572445Sassar@section Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm 47672445Sassar 47772445SassarIt is desirable to have at least one backup (slave) server in case the 47872445Sassarmaster server fails. It is possible to have any number of such slave 47972445Sassarservers but more than three usually doesn't buy much more redundancy. 48072445Sassar 481178825SdfrAll Kerberos servers for a realm must have the same database so that 482178825Sdfrthey present the same service to the users. The 48372445Sassar@pindex hprop 484178825Sdfr@command{hprop} program, running on the master, will propagate the database 48572445Sassarto the slaves, running 48672445Sassar@pindex hpropd 487178825Sdfr@command{hpropd} processes. 48872445Sassar 489127808SnectarEvery slave needs a database directory, the master key (if it was used 490127808Snectarfor the database) and a keytab with the principal 491127808Snectar@samp{hprop/@var{hostname}}. Add the principal with the 49272445Sassar@pindex ktutil 493178825Sdfr@command{ktutil} command and start 49472445Sassar@pindex hpropd 495178825Sdfr@command{hpropd}, as follows: 49672445Sassar 49772445Sassar@example 498120945Snectarslave# ktutil get -p foo/admin hprop/`hostname` 499127808Snectarslave# mkdir /var/heimdal 50072445Sassarslave# hpropd 50172445Sassar@end example 50272445Sassar 50372445SassarThe master will use the principal @samp{kadmin/hprop} to authenticate to 50472445Sassarthe slaves. This principal should be added when running @kbd{kadmin -l 50572445Sassarinit} but if you do not have it in your database for whatever reason, 50672445Sassarplease add it with @kbd{kadmin -l add}. 50772445Sassar 50872445SassarThen run 50972445Sassar@pindex hprop 51072445Sassar@code{hprop} on the master: 51172445Sassar 51272445Sassar@example 51372445Sassarmaster# hprop slave 51472445Sassar@end example 51572445Sassar 516178825SdfrThis was just an hands-on example to make sure that everything was 517178825Sdfrworking properly. Doing it manually is of course the wrong way, and to 51872445Sassarautomate this you will want to start 51972445Sassar@pindex hpropd 520178825Sdfr@command{hpropd} from @command{inetd} on the slave(s) and regularly run 52172445Sassar@pindex hprop 522178825Sdfr@command{hprop} on the master to regularly propagate the database. 523178825SdfrStarting the propagation once an hour from @command{cron} is probably a 52472445Sassargood idea. 52572445Sassar 526178825Sdfr@node Incremental propagation, Encryption types and salting, Slave Servers, Setting up a realm 52772445Sassar@section Incremental propagation 52872445Sassar 529233294SstasThere is also a newer mechanism for 53072445Sassardoing incremental propagation in Heimdal. Instead of sending the whole 53172445Sassardatabase regularly, it sends the changes as they happen on the master to 532178825Sdfrthe slaves. The master keeps track of all the changes by assigning a 53372445Sassarversion number to every change to the database. The slaves know which 53472445Sassarwas the latest version they saw and in this way it can be determined if 535178825Sdfrthey are in sync or not. A log of all the changes is kept on the master, 536178825Sdfrand when a slave is at an older version than the oldest one in the 53772445Sassarlog, the whole database has to be sent. 53872445Sassar 539178825SdfrProtocol-wise, all the slaves connect to the master and as a greeting 54072445Sassartell it the latest version that they have (@samp{IHAVE} message). The 54172445Sassarmaster then responds by sending all the changes between that version and 54272445Sassarthe current version at the master (a series of @samp{FORYOU} messages) 543178825Sdfror the whole database in a @samp{TELLYOUEVERYTHING} message. There is 544178825Sdfralso a keep-alive protocol that makes sure all slaves are up and running. 54572445Sassar 546233294SstasIn addition on listening on the network to get connection from new 547233294Sstasslaves, the ipropd-master also listens on a status unix 548233294Sstassocket. kadmind and kpasswdd both open that socket when a transation 549233294Sstasis done and written a notification to the socket. That cause 550233294Sstasipropd-master to check for new version in the log file. As a fallback in 551233294Sstascase a notification is lost by the unix socket, the log file is 552233294Sstaschecked after 30 seconds of no event. 553233294Sstas 55472445Sassar@subsection Configuring incremental propagation 55572445Sassar 556178825SdfrThe program that runs on the master is @command{ipropd-master} and all 557178825Sdfrclients run @command{ipropd-slave}. 55872445Sassar 55972445SassarCreate the file @file{/var/heimdal/slaves} on the master containing all 56072445Sassarthe slaves that the database should be propagated to. Each line contains 56172445Sassarthe full name of the principal (for example 56272445Sassar@samp{iprop/hemligare.foo.se@@FOO.SE}). 56372445Sassar 56472445SassarYou should already have @samp{iprop/tcp} defined as 2121, in your 56572445Sassar@file{/etc/services}. Otherwise, or if you need to use a different port 56672445Sassarfor some peculiar reason, you can use the @kbd{--port} option. This is 56772445Sassaruseful when you have multiple realms to distribute from one server. 56872445Sassar 569178825SdfrThen you need to create those principals that you added in the 57072445Sassarconfiguration file. Create one @samp{iprop/hostname} for the master and 57172445Sassarfor every slave. 57272445Sassar 57372445Sassar 57472445Sassar@example 57572445Sassarmaster# /usr/heimdal/sbin/ktutil get iprop/`hostname` 57672445Sassar@end example 57772445Sassar 578233294Sstas@example 579233294Sstasslave# /usr/heimdal/sbin/ktutil get iprop/`hostname` 580233294Sstas@end example 581233294Sstas 582233294Sstas 583178825SdfrThe next step is to start the @command{ipropd-master} process on the master 584178825Sdfrserver. The @command{ipropd-master} listens on the UNIX domain socket 58572445Sassar@file{/var/heimdal/signal} to know when changes have been made to the 58672445Sassardatabase so they can be propagated to the slaves. There is also a 58772445Sassarsafety feature of testing the version number regularly (every 30 58872445Sassarseconds) to see if it has been modified by some means that do not raise 589178825Sdfrthis signal. Then, start @command{ipropd-slave} on all the slaves: 59072445Sassar 59172445Sassar@example 59272445Sassarmaster# /usr/heimdal/libexec/ipropd-master & 59372445Sassarslave# /usr/heimdal/libexec/ipropd-slave master & 59472445Sassar@end example 59572445Sassar 596178825SdfrTo manage the iprop log file you should use the @command{iprop-log} 597178825Sdfrcommand. With it you can dump, truncate and replay the logfile. 598178825Sdfr 599233294Sstas@node Encryption types and salting, Credential cache server - KCM, Incremental propagation, Setting up a realm 600178825Sdfr@section Encryption types and salting 60172445Sassar@cindex Salting 602178825Sdfr@cindex Encryption types 60372445Sassar 604178825SdfrThe encryption types that the KDC is going to assign by default is 605178825Sdfrpossible to change. Since the keys used for user authentication is 606178825Sdfrsalted the encryption types are described together with the salt 607178825Sdfrstrings. 608178825Sdfr 609178825SdfrSalting is used to make it harder to pre-calculate all possible 61072445Sassarkeys. Using a salt increases the search space to make it almost 611178825Sdfrimpossible to pre-calculate all keys. Salting is the process of mixing a 61290926Snectarpublic string (the salt) with the password, then sending it through an 613178825Sdfrencryption type specific string-to-key function that will output the 61490926Snectarfixed size encryption key. 61572445Sassar 616178825SdfrIn Kerberos 5 the salt is determined by the encryption type, except in 617178825Sdfrsome special cases. 61890926Snectar 61990926SnectarIn @code{des} there is the Kerberos 4 salt 62090926Snectar(none at all) or the afs-salt (using the cell (realm in 621178825SdfrAFS lingo)). 62290926Snectar 62390926SnectarIn @code{arcfour} (the encryption type that Microsoft Windows 2000 uses) 62490926Snectarthere is no salt. This is to be compatible with NTLM keys in Windows 62590926SnectarNT 4. 62690926Snectar 62790926Snectar@code{[kadmin]default_keys} in @file{krb5.conf} controls 628178825Sdfrwhat salting to use. 62972445Sassar 63072445SassarThe syntax of @code{[kadmin]default_keys} is 63172445Sassar@samp{[etype:]salt-type[:salt-string]}. @samp{etype} is the encryption 632178825Sdfrtype (des-cbc-crc, arcfour-hmac-md5, aes256-cts-hmac-sha1-96), 633178825Sdfr@code{salt-type} is the type of salt (pw-salt or afs3-salt), and the 634178825Sdfrsalt-string is the string that will be used as salt (remember that if 635178825Sdfrthe salt is appended/prepended, the empty salt "" is the same thing as 636178825Sdfrno salt at all). 63772445Sassar 638178825SdfrCommon types of salting include 63972445Sassar 64078527Sassar@itemize @bullet 64172445Sassar@item @code{v4} (or @code{des:pw-salt:}) 64272445Sassar 643178825SdfrThe Kerberos 4 salting is using no salt at all. Reason there is colon 644178825Sdfrat the end of the salt string is that it makes the salt the empty 645120945Snectarstring (same as no salt). 64672445Sassar 64772445Sassar@item @code{v5} (or @code{pw-salt}) 64872445Sassar 649178825Sdfr@code{pw-salt} uses the default salt for each encryption type is 650178825Sdfrspecified for. If the encryption type @samp{etype} isn't given, all 651178825Sdfrdefault encryption will be used. 65272445Sassar 65372445Sassar@item @code{afs3-salt} 65472445Sassar 655178825Sdfr@code{afs3-salt} is the salt that is used with Transarc kaserver. It's 656178825Sdfrthe cell name appended to the password. 65772445Sassar 65872445Sassar@end itemize 659127808Snectar 660233294Sstas@node Credential cache server - KCM, Cross realm, Encryption types and salting, Setting up a realm 661233294Sstas@section Credential cache server - KCM 662233294Sstas@cindex KCM 663233294Sstas@cindex Credential cache server 664233294Sstas 665233294SstasWhen KCM running is easy for users to switch between different 666233294Sstaskerberos principals using @file{kswitch} or built in support in 667233294Sstasapplication, like OpenSSH's GSSAPIClientIdentity. 668233294Sstas 669233294SstasOther advantages are that there is the long term credentials are not 670233294Sstaswritten to disk and on reboot the credential is removed when kcm 671233294Sstasprocess stopps running. 672233294Sstas 673233294SstasConfigure the system startup script to start the kcm process, 674233294Sstas@file{/usr/heimdal/libexec/kcm} and then configure the system to use kcm in @file{krb5.conf}. 675233294Sstas 676233294Sstas@example 677233294Sstas[libdefaults] 678233294Sstas default_cc_type = KCM 679233294Sstas@end example 680233294Sstas 681233294SstasNow when you run @command{kinit} it doesn't overwrite your existing 682233294Sstascredentials but rather just add them to the set of 683233294Sstascredentials. @command{klist -l} lists the credentials and the star 684233294Sstasmarks the default credential. 685233294Sstas 686233294Sstas@example 687233294Sstas$ kinit lha@@KTH.SE 688233294Sstaslha@@KTH.SE's Password: 689233294Sstas$ klist -l 690233294Sstas Name Cache name Expires 691233294Sstaslha@@KTH.SE 0 Nov 22 23:09:40 * 692233294Sstaslha@@SU.SE Initial default ccache Nov 22 14:14:24 693233294Sstas@end example 694233294Sstas 695233294SstasWhen switching between credentials you can use @command{kswitch}. 696233294Sstas 697233294Sstas@example 698233294Sstas$ kswitch -i 699233294Sstas Principal 700233294Sstas1 lha@@KTH.SE 701233294Sstas2 lha@@SU.SE 702233294SstasSelect number: 2 703233294Sstas@end example 704233294Sstas 705233294SstasAfter switching, a new set of credentials are used as default. 706233294Sstas 707233294Sstas@example 708233294Sstas$ klist -l 709233294Sstas Name Cache name Expires 710233294Sstaslha@@SU.SE Initial default ccache Nov 22 14:14:24 * 711233294Sstaslha@@KTH.SE 0 Nov 22 23:09:40 712233294Sstas@end example 713233294Sstas 714233294SstasSom applications, like openssh with Simon Wilkinsons patch applied, 715233294Sstassupport specifiying that credential to use. The example below will 716233294Sstaslogin to the host computer.kth.se using lha@@KTH.SE (not the current 717233294Sstasdefault credential). 718233294Sstas 719233294Sstas@example 720233294Sstas$ ssh \ 721233294Sstas -o GSSAPIAuthentication=yes \ 722233294Sstas -o GSSAPIKeyExchange=yes \ 723233294Sstas -o GSSAPIClientIdentity=lha@@KTH.SE \ 724233294Sstas computer.kth.se 725233294Sstas@end example 726233294Sstas 727233294Sstas 728233294Sstas 729233294Sstas@node Cross realm, Transit policy, Credential cache server - KCM, Setting up a realm 730127808Snectar@section Cross realm 731127808Snectar@cindex Cross realm 732127808Snectar 733178825SdfrSuppose you reside in the realm @samp{MY.REALM}, how do you 734127808Snectarauthenticate to a server in @samp{OTHER.REALM}? Having valid tickets in 735178825Sdfr@samp{MY.REALM} allows you to communicate with Kerberised services in that 736127808Snectarrealm. However, the computer in the other realm does not have a secret 737127808Snectarkey shared with the Kerberos server in your realm. 738127808Snectar 739178825SdfrIt is possible to share keys between two realms that trust each 740178825Sdfrother. When a client program, such as @command{telnet} or @command{ssh}, 741127808Snectarfinds that the other computer is in a different realm, it will try to 742127808Snectarget a ticket granting ticket for that other realm, but from the local 743127808SnectarKerberos server. With that ticket granting ticket, it will then obtain 744127808Snectarservice tickets from the Kerberos server in the other realm. 745127808Snectar 746127808SnectarFor a two way trust between @samp{MY.REALM} and @samp{OTHER.REALM} 747127808Snectaradd the following principals to each realm. The principals should be 748127808Snectar@samp{krbtgt/OTHER.REALM@@MY.REALM} and 749127808Snectar@samp{krbtgt/MY.REALM@@OTHER.REALM} in @samp{MY.REALM}, and 750127808Snectar@samp{krbtgt/MY.REALM@@OTHER.REALM} and 751127808Snectar@samp{krbtgt/OTHER.REALM@@MY.REALM}in @samp{OTHER.REALM}. 752127808Snectar 753178825SdfrIn Kerberos 5 the trust can be configured to be one way. So that 754127808Snectarusers from @samp{MY.REALM} can authenticate to services in 755127808Snectar@samp{OTHER.REALM}, but not the opposite. In the example above, the 756127808Snectar@samp{krbtgt/MY.REALM@@OTHER.REALM} then should be removed. 757127808Snectar 758127808SnectarThe two principals must have the same key, key version number, and the 759127808Snectarsame set of encryption types. Remember to transfer the two keys in a 760127808Snectarsafe manner. 761127808Snectar 762127808Snectar@example 763127808Snectarvr$ klist 764127808SnectarCredentials cache: FILE:/tmp/krb5cc_913.console 765127808Snectar Principal: lha@@E.KTH.SE 766127808Snectar 767178825Sdfr Issued Expires Principal 768178825SdfrMay 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE 769127808Snectar 770127808Snectarvr$ telnet -l lha hummel.it.su.se 771127808SnectarTrying 2001:6b0:5:1095:250:fcff:fe24:dbf... 772127808SnectarConnected to hummel.it.su.se. 773127808SnectarEscape character is '^]'. 774127808SnectarWaiting for encryption to be negotiated... 775127808Snectar[ Trying mutual KERBEROS5 (host/hummel.it.su.se@@SU.SE)... ] 776127808Snectar[ Kerberos V5 accepts you as ``lha@@E.KTH.SE'' ] 777127808SnectarEncryption negotiated. 778127808SnectarLast login: Sat May 3 14:11:47 from vr.l.nxs.se 779127808Snectarhummel$ exit 780127808Snectar 781127808Snectarvr$ klist 782127808SnectarCredentials cache: FILE:/tmp/krb5cc_913.console 783127808Snectar Principal: lha@@E.KTH.SE 784127808Snectar 785178825Sdfr Issued Expires Principal 786178825SdfrMay 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE 787178825SdfrMay 3 13:55:56 May 3 23:55:54 krbtgt/SU.SE@@E.KTH.SE 788178825SdfrMay 3 14:10:54 May 3 23:55:54 host/hummel.it.su.se@@SU.SE 789127808Snectar 790127808Snectar@end example 791127808Snectar 792178825Sdfr@node Transit policy, Setting up DNS, Cross realm, Setting up a realm 793127808Snectar@section Transit policy 794127808Snectar@cindex Transit policy 795127808Snectar 796233294SstasUnder some circumstances, you may not wish to set up direct 797233294Sstascross-realm trust with every realm to which you wish to authenticate 798233294Sstasor from which you wish to accept authentications. Kerberos supports 799233294Sstasmulti-hop cross-realm trust where a client principal in realm A 800233294Sstasauthenticates to a service in realm C through a realm B with which 801233294Sstasboth A and C have cross-realm trust relationships. In this situation, 802233294SstasA and C need not set up cross-realm principals between each other. 803233294Sstas 804233294SstasIf you want to use cross-realm authentication through an intermediate 805233294Sstasrealm, it must be explicitly allowed by either the KDCs for the realm 806233294Sstasto which the client is authenticating (in this case, realm C), or the 807233294Sstasserver receiving the request. This is done in @file{krb5.conf} in the 808127808Snectar@code{[capaths]} section. 809127808Snectar 810233294SstasIn addition, the client in realm A need to be configured to know how 811233294Sstasto reach realm C via realm B. This can be done either on the client or 812233294Sstasvia KDC configuration in the KDC for realm A. 813233294Sstas 814233294Sstas@subsection Allowing cross-realm transits 815233294Sstas 816127808SnectarWhen the ticket transits through a realm to another realm, the 817127808Snectardestination realm adds its peer to the "transited-realms" field in the 818233294Sstasticket. The field is unordered, since there is no way to know if know 819233294Sstasif one of the transited-realms changed the order of the list. For the 820233294Sstasauthentication to be accepted by the final destination realm, all of 821233294Sstasthe transited realms must be listed as trusted in the @code{[capaths]} 822233294Sstasconfiguration, either in the KDC for the destination realm or on the 823233294Sstasserver receiving the authentication. 824127808Snectar 825233294SstasThe syntax for @code{[capaths]} section is: 826127808Snectar 827127808Snectar@example 828127808Snectar[capaths] 829127808Snectar CLIENT-REALM = @{ 830127808Snectar SERVER-REALM = PERMITTED-CROSS-REALMS ... 831127808Snectar @} 832127808Snectar@end example 833127808Snectar 834233294SstasIn the following example, the realm @code{STACKEN.KTH.SE} only has 835233294Sstasdirect cross-realm set up with @code{KTH.SE}. @code{KTH.SE} has 836233294Sstasdirect cross-realm set up with @code{STACKEN.KTH.SE} and @code{SU.SE}. 837233294Sstas@code{DSV.SU.SE} only has direct cross-realm set up with @code{SU.SE}. 838233294SstasThe goal is to allow principals in the @code{DSV.SU.SE} or 839233294Sstas@code{SU.SE} realms to authenticate to services in 840233294Sstas@code{STACKEN.KTH.SE}. This is done with the following 841233294Sstas@code{[capaths]} entry on either the server accepting authentication 842233294Sstasor on the KDC for @code{STACKEN.KTH.SE}. 843127808Snectar 844127808Snectar@example 845127808Snectar[capaths] 846127808Snectar SU.SE = @{ 847127808Snectar STACKEN.KTH.SE = KTH.SE 848127808Snectar @} 849127808Snectar DSV.SU.SE = @{ 850127808Snectar STACKEN.KTH.SE = SU.SE KTH.SE 851127808Snectar @} 852127808Snectar@end example 853127808Snectar 854233294SstasThe first entry allows cross-realm authentication from clients in 855233294Sstas@code{SU.SE} transiting through @code{KTH.SE} to 856233294Sstas@code{STACKEN.KTH.SE}. The second entry allows cross-realm 857233294Sstasauthentication from clients in @code{DSV.SU.SE} transiting through 858233294Sstasboth @code{SU.SE} and @code{KTH.SE} to @code{STACKEN.KTH.SE}. 859233294Sstas 860233294SstasBe careful of which realm goes where; it's easy to put realms in the 861233294Sstaswrong place. The block is tagged with the client realm (the realm of 862233294Sstasthe principal authenticating), and the realm before the equal sign is 863233294Sstasthe final destination realm: the realm to which the client is 864233294Sstasauthenticating. After the equal sign go all the realms that the 865233294Sstasclient transits through. 866233294Sstas 867178825SdfrThe order of the @code{PERMITTED-CROSS-REALMS} is not important when 868178825Sdfrdoing transit cross realm verification. 869178825Sdfr 870233294Sstas@subsection Configuring client cross-realm transits 871178825Sdfr 872233294SstasThe @code{[capaths]} section is also used for another purpose: to tell 873233294Sstasclients which realm to transit through to reach a realm with which 874233294Sstastheir local realm does not have cross-realm trust. This can be done 875233294Sstasby either putting a @code{[capaths]} entry in the configuration of the 876233294Sstasclient or by putting the entry in the configuration of the KDC for the 877233294Sstasclient's local realm. In the latter case, the KDC will then hand back 878233294Sstasa referral to the client when the client requests a cross-realm ticket 879233294Sstasto the destination realm, telling the client to try to go through an 880233294Sstasintermediate realm. 881233294Sstas 882233294SstasFor client configuration, the order of @code{PERMITTED-CROSS-REALMS} 883233294Sstasis significant, since only the first realm in this section (after the 884233294Sstasequal sign) is used by the client. 885233294Sstas 886233294SstasFor example, again consider the @code{[capaths]} entry above for the 887233294Sstascase of a client in the @code{SU.SE} realm, and assume that the client 888233294Sstasor the @code{SU.SE} KDC has that @code{[capaths]} entry. If the 889233294Sstasclient attempts to authenticate to a service in the 890233294Sstas@code{STACKEN.KTH.SE} realm, that entry says to first authenticate 891233294Sstascross-realm to the @code{KTH.SE} realm (the first realm listed in the 892233294Sstas@code{PERMITTED-CROSS-REALMS} section), and then from there to 893233294Sstas@code{STACKEN.KTH.SE}. 894233294Sstas 895233294SstasEach entry in @code{[capaths]} can only give the next hop, since only 896233294Sstasthe first realm in @code{PERMITTED-CROSS-REALMS} is used. If, for 897233294Sstasinstance, a client in @code{DSV.SU.SE} had a @code{[capaths]} 898233294Sstasconfiguration as above but without the first block for @code{SU.SE}, 899233294Sstasthey would not be able to reach @code{STACKEN.KTH.SE}. They would get 900233294Sstasas far as @code{SU.SE} based on the @code{DSV.SU.SE} entry in 901233294Sstas@code{[capaths]} and then attempt to go directly from there to 902233294Sstas@code{STACKEN.KTH.SE} and get stuck (unless, of course, the 903233294Sstas@code{SU.SE} KDC had the additional entry required to tell the client 904233294Sstasto go through @code{KTH.SE}). 905233294Sstas 906233294Sstas@subsection Active Directory forest example 907233294Sstas 908233294SstasOne common place where a @code{[capaths]} configuration is desirable 909233294Sstasis with Windows Active Directory forests. One common Active Directory 910233294Sstasconfiguration is to have one top-level Active Directory realm but then 911233294Sstasdivide systems, services, and users into child realms (perhaps based 912233294Sstason organizational unit). One generally establishes cross-realm trust 913233294Sstasonly with the top-level realm, and then uses transit policy to permit 914233294Sstasauthentications to and from the child realms. 915233294Sstas 916233294SstasFor example, suppose an organization has a Heimdal realm 917233294Sstas@code{EXAMPLE.COM}, a Windows Active Directory realm 918233294Sstas@code{WIN.EXAMPLE.COM}, and then child Active Directory realms 919233294Sstas@code{ENGR.WIN.EXAMPLE.COM} and @code{SALES.WIN.EXAMPLE.COM}. The 920233294Sstasgoal is to allow users in any of these realms to authenticate to 921233294Sstasservices in any of these realms. The @code{EXAMPLE.COM} KDC (and 922233294Sstaspossibly client) configuration should therefore contain a 923233294Sstas@code{[capaths]} section as follows: 924233294Sstas 925233294Sstas@example 926233294Sstas[capaths] 927233294Sstas ENGR.WIN.EXAMPLE.COM = @{ 928233294Sstas EXAMPLE.COM = WIN.EXAMPLE.COM 929233294Sstas @} 930233294Sstas SALES.WIN.EXAMPLE.COM = @{ 931233294Sstas EXAMPLE.COM = WIN.EXAMPLE.COM 932233294Sstas @} 933233294Sstas EXAMPLE.COM = @{ 934233294Sstas ENGR.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM 935233294Sstas SALES.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM 936233294Sstas @} 937233294Sstas@end example 938233294Sstas 939233294SstasThe first two blocks allow clients in the @code{ENGR.WIN.EXAMPLE.COM} 940233294Sstasand @code{SALES.WIN.EXAMPLE.COM} realms to authenticate to services in 941233294Sstasthe @code{EXAMPLE.COM} realm. The third block tells the client (or 942233294Sstastells the KDC to tell the client via referrals) to transit through 943233294Sstas@code{WIN.EXAMPLE.COM} to reach these realms. Both sides of the 944233294Sstasconfiguration are needed for bi-directional transited cross-realm 945233294Sstasauthentication. 946233294Sstas 947127808Snectar@c To test the cross realm configuration, use: 948127808Snectar@c kmumble transit-check client server transit-realms ... 949127808Snectar 950178825Sdfr@node Setting up DNS, Using LDAP to store the database, Transit policy, Setting up a realm 951127808Snectar@section Setting up DNS 952127808Snectar@cindex Setting up DNS 953127808Snectar 954178825Sdfr@subsection Using DNS to find KDC 955178825Sdfr 956127808SnectarIf there is information about where to find the KDC or kadmind for a 957127808Snectarrealm in the @file{krb5.conf} for a realm, that information will be 958178825Sdfrpreferred, and DNS will not be queried. 959127808Snectar 960127808SnectarHeimdal will try to use DNS to find the KDCs for a realm. First it 961178825Sdfrwill try to find a @code{SRV} resource record (RR) for the realm. If no 962178825SdfrSRV RRs are found, it will fall back to looking for an @code{A} RR for 963127808Snectara machine named kerberos.REALM, and then kerberos-1.REALM, etc 964127808Snectar 965178825SdfrAdding this information to DNS minimises the client configuration (in 966178825Sdfrthe common case, resulting in no configuration needed) and allows the 967127808Snectarsystem administrator to change the number of KDCs and on what machines 968127808Snectarthey are running without caring about clients. 969127808Snectar 970178825SdfrThe downside of using DNS is that the client might be fooled to use the 971127808Snectarwrong server if someone fakes DNS replies/data, but storing the IP 972127808Snectaraddresses of the KDC on all the clients makes it very hard to change 973127808Snectarthe infrastructure. 974127808Snectar 975178825SdfrAn example of the configuration for the realm @code{EXAMPLE.COM}: 976127808Snectar 977127808Snectar@example 978127808Snectar 979127808Snectar$ORIGIN example.com. 980127808Snectar_kerberos._tcp SRV 10 1 88 kerberos.example.com. 981127808Snectar_kerberos._udp SRV 10 1 88 kerberos.example.com. 982127808Snectar_kerberos._tcp SRV 10 1 88 kerberos-1.example.com. 983127808Snectar_kerberos._udp SRV 10 1 88 kerberos-1.example.com. 984127808Snectar_kpasswd._udp SRV 10 1 464 kerberos.example.com. 985127808Snectar_kerberos-adm._tcp SRV 10 1 749 kerberos.example.com. 986127808Snectar 987127808Snectar@end example 988127808Snectar 989127808SnectarMore information about DNS SRV resource records can be found in 990127808SnectarRFC-2782 (A DNS RR for specifying the location of services (DNS SRV)). 991127808Snectar 992178825Sdfr@subsection Using DNS to map hostname to Kerberos realm 993178825Sdfr 994178825SdfrHeimdal also supports a way to lookup a realm from a hostname. This to 995178825Sdfrminimise configuration needed on clients. Using this has the drawback 996178825Sdfrthat clients can be redirected by an attacker to realms within the 997178825Sdfrsame cross realm trust and made to believe they are talking to the 998178825Sdfrright server (since Kerberos authentication will succeed). 999178825Sdfr 1000178825SdfrAn example configuration that informs clients that for the realms 1001178825Sdfrit.example.com and srv.example.com, they should use the realm 1002178825SdfrEXAMPLE.COM: 1003178825Sdfr 1004178825Sdfr@example 1005178825Sdfr 1006178825Sdfr$ORIGIN example.com. 1007178825Sdfr_kerberos.it TXT "EXAMPLE.COM" 1008178825Sdfr_kerberos.srv TXT "EXAMPLE.COM" 1009178825Sdfr 1010178825Sdfr@end example 1011178825Sdfr 1012178825Sdfr@node Using LDAP to store the database, Providing Kerberos credentials to servers and programs, Setting up DNS, Setting up a realm 1013178825Sdfr@section Using LDAP to store the database 1014178825Sdfr@cindex Using the LDAP backend 1015178825Sdfr 1016178825SdfrThis document describes how to install the LDAP backend for 1017178825SdfrHeimdal. Note that before attempting to configure such an 1018178825Sdfrinstallation, you should be aware of the implications of storing 1019178825Sdfrprivate information (such as users' keys) in a directory service 1020178825Sdfrprimarily designed for public information. Nonetheless, with a 1021178825Sdfrsuitable authorisation policy, it is possible to set this up in a 1022178825Sdfrsecure fashion. A knowledge of LDAP, Kerberos, and C is necessary to 1023178825Sdfrinstall this backend. The HDB schema was devised by Leif Johansson. 1024178825Sdfr 1025233294SstasThis assumes, OpenLDAP 2.3 or later. 1026233294Sstas 1027178825SdfrRequirements: 1028178825Sdfr 1029178825Sdfr@itemize @bullet 1030178825Sdfr 1031178825Sdfr@item 1032178825SdfrA current release of Heimdal, configured with 1033178825Sdfr@code{--with-openldap=/usr/local} (adjust according to where you have 1034178825Sdfrinstalled OpenLDAP). 1035178825Sdfr 1036178825SdfrYou can verify that you manage to configure LDAP support by running 1037178825Sdfr@file{kdc --builtin-hdb}, and checking that @samp{ldap:} is one entry 1038178825Sdfrin the list. 1039178825Sdfr 1040178825SdfrIts also possible to configure the ldap backend as a shared module, 1041178825Sdfrsee option --hdb-openldap-module to configure. 1042178825Sdfr 1043178825Sdfr@item 1044233294SstasConfigure OpenLDAP with @kbd{--enable-local} to enable the local transport. 1045178825Sdfr 1046178825Sdfr@item 1047178825SdfrAdd the hdb schema to the LDAP server, it's included in the source-tree 1048178825Sdfrin @file{lib/hdb/hdb.schema}. Example from slapd.conf: 1049178825Sdfr 1050178825Sdfr@example 1051178825Sdfrinclude /usr/local/etc/openldap/schema/hdb.schema 1052178825Sdfr@end example 1053178825Sdfr 1054178825Sdfr@item 1055178825SdfrConfigure the LDAP server ACLs to accept writes from clients over the 1056178825Sdfrlocal transport. For example: 1057178825Sdfr 1058178825Sdfr@example 1059178825Sdfraccess to * 1060178825Sdfr by dn.exact="uid=heimdal,dc=services,dc=example,dc=com" write 1061178825Sdfr ... 1062178825Sdfr 1063233294Sstasauthz-regexp "gidNumber=.*\\\+uidNumber=0,cn=peercred,cn=external,cn=auth'' 1064178825Sdfr "uid=heimdal,dc=services,dc=example,dc=com" 1065178825Sdfr 1066178825Sdfr@end example 1067178825Sdfr 1068178825SdfrThe sasl-regexp is for mapping between the SASL/EXTERNAL and a user in 1069178825Sdfra tree. The user that the key is mapped to should be have a 1070178825Sdfrkrb5Principal aux object with krb5PrincipalName set so that the 1071178825Sdfr``creator'' and ``modifier'' is right in @file{kadmin}. 1072178825Sdfr 1073178825SdfrAnother option is to create an admins group and add the dn to that 1074178825Sdfrgroup. 1075178825Sdfr 1076178825SdfrSince Heimdal talks to the LDAP server over a UNIX domain socket, and 1077178825Sdfruses external sasl authentication, it's not possible to require 1078178825Sdfrsecurity layer quality (ssf in cyrus-sasl lingo). So that requirement 1079178825Sdfrhas to be turned off in OpenLDAP @command{slapd} configuration file 1080178825Sdfr@file{slapd.conf}. 1081178825Sdfr 1082178825Sdfr@example 1083178825Sdfrsasl-secprops minssf=0 1084178825Sdfr@end example 1085178825Sdfr 1086178825Sdfr@item 1087178825Sdfr 1088178825SdfrStart @command{slapd} with the local listener (as well as the default TCP/IP 1089178825Sdfrlistener on port 389) as follows: 1090178825Sdfr 1091178825Sdfr@example 1092178825Sdfr slapd -h "ldapi:/// ldap:///" 1093178825Sdfr@end example 1094178825Sdfr 1095178825SdfrNote: These is a bug in @command{slapd} where it appears to corrupt the krb5Key 1096178825Sdfrbinary attribute on shutdown. This may be related to our use of the V3 1097178825Sdfrschema definition syntax instead of the old UMich-style, V2 syntax. 1098178825Sdfr 1099178825Sdfr@item 1100178825SdfrYou should specify the distinguished name under which your 1101178825Sdfrprincipals will be stored in @file{krb5.conf}. Also you need to 1102178825Sdfrenter the path to the kadmin acl file: 1103178825Sdfr 1104178825Sdfr 1105178825Sdfr@example 1106178825Sdfr[kdc] 1107178825Sdfr database = @{ 1108178825Sdfr dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com 1109178825Sdfr hdb-ldap-structural-object = inetOrgPerson 1110178825Sdfr acl_file = /path/to/kadmind.acl 1111178825Sdfr mkey_file = /path/to/mkey 1112178825Sdfr @} 1113178825Sdfr@end example 1114178825Sdfr 1115178825Sdfr@samp{mkey_file} can be excluded if you feel that you trust your ldap 1116178825Sdfrdirectory to have the raw keys inside it. The 1117178825Sdfrhdb-ldap-structural-object is not necessary if you do not need Samba 1118178825Sdfrcomatibility. 1119178825Sdfr 1120178825Sdfr 1121178825Sdfr 1122178825Sdfr@item 1123178825SdfrOnce you have built Heimdal and started the LDAP server, run kadmin 1124178825Sdfr(as usual) to initialise the database. Note that the instructions for 1125178825Sdfrstashing a master key are as per any Heimdal installation. 1126178825Sdfr 1127178825Sdfr@example 1128178825Sdfrkdc# kadmin -l 1129178825Sdfrkadmin> init EXAMPLE.COM 1130178825SdfrRealm max ticket life [unlimited]: 1131178825SdfrRealm max renewable ticket life [unlimited]: 1132233294Sstaskadmin> add lukeh 1133178825SdfrMax ticket life [1 day]: 1134178825SdfrMax renewable life [1 week]: 1135178825SdfrPrincipal expiration time [never]: 1136178825SdfrPassword expiration time [never]: 1137178825SdfrAttributes []: 1138178825Sdfrlukeh@@EXAMPLE.COM's Password: 1139178825SdfrVerifying password - lukeh@@EXAMPLE.COM's Password: 1140178825Sdfrkadmin> exit 1141178825Sdfr@end example 1142178825Sdfr 1143178825SdfrVerify that the principal database has indeed been stored in the 1144178825Sdfrdirectory with the following command: 1145178825Sdfr 1146178825Sdfr@example 1147178825Sdfrkdc# ldapsearch -L -h localhost -D cn=manager \ 1148178825Sdfr -w secret -b ou=KerberosPrincipals,dc=example,dc=com \ 1149178825Sdfr 'objectclass=krb5KDCEntry' 1150178825Sdfr@end example 1151178825Sdfr 1152178825Sdfr@item 1153178825SdfrNow consider adding indexes to the database to speed up the access, at 1154178825Sdfrleast theses should be added to slapd.conf. 1155178825Sdfr 1156178825Sdfr@example 1157178825Sdfrindex objectClass eq 1158178825Sdfrindex cn eq,sub,pres 1159178825Sdfrindex uid eq,sub,pres 1160178825Sdfrindex displayName eq,sub,pres 1161178825Sdfrindex krb5PrincipalName eq 1162178825Sdfr@end example 1163178825Sdfr 1164178825Sdfr@end itemize 1165178825Sdfr 1166233294Sstas@subsection smbk5pwd overlay 1167233294Sstas 1168233294SstasThe smbk5pwd overlay, updates the krb5Key and krb5KeyVersionNumber 1169233294Sstasappropriately when it receives an LDAP Password change Extended 1170233294SstasOperation: 1171233294Sstas 1172233294Sstas@url{http://www.openldap.org/devel/cvsweb.cgi/contrib/slapd-modules/smbk5pwd/README?hideattic=1&sortbydate=0} 1173233294Sstas 1174178825Sdfr@subsection Troubleshooting guide 1175178825Sdfr 1176178825Sdfr@url{https://sec.miljovern.no/bin/view/Info/TroubleshootingGuide} 1177178825Sdfr 1178178825Sdfr 1179178825Sdfr@subsection Using Samba LDAP password database 1180178825Sdfr@cindex Samba 1181178825Sdfr 1182178825Sdfr@c @node Using Samba LDAP password database, Providing Kerberos credentials to servers and programs, Using LDAP to store the database, Setting up a realm 1183178825Sdfr@c @section Using Samba LDAP password database 1184178825Sdfr 1185178825SdfrThe Samba domain and the Kerberos realm can have different names since 1186178825Sdfrarcfour's string to key functions principal/realm independent. So now 1187178825Sdfrwill be your first and only chance name your Kerberos realm without 1188178825Sdfrneeding to deal with old configuration files. 1189178825Sdfr 1190178825SdfrFirst, you should set up Samba and get that working with LDAP backend. 1191178825Sdfr 1192178825SdfrNow you can proceed as in @xref{Using LDAP to store the database}. 1193178825SdfrHeimdal will pick up the Samba LDAP entries if they are in the same 1194178825Sdfrsearch space as the Kerberos entries. 1195178825Sdfr 1196178825Sdfr@node Providing Kerberos credentials to servers and programs, Setting up PK-INIT, Using LDAP to store the database, Setting up a realm 1197178825Sdfr@section Providing Kerberos credentials to servers and programs 1198178825Sdfr 1199178825SdfrSome services require Kerberos credentials when they start to make 1200178825Sdfrconnections to other services or need to use them when they have started. 1201178825Sdfr 1202178825SdfrThe easiest way to get tickets for a service is to store the key in a 1203178825Sdfrkeytab. Both ktutil get and kadmin ext can be used to get a 1204178825Sdfrkeytab. ktutil get is better in that way it changes the key/password 1205178825Sdfrfor the user. This is also the problem with ktutil. If ktutil is used 1206178825Sdfrfor the same service principal on several hosts, they keytab will only 1207178825Sdfrbe useful on the last host. In that case, run the extract command on 1208178825Sdfrone host and then securely copy the keytab around to all other hosts 1209178825Sdfrthat need it. 1210178825Sdfr 1211178825Sdfr@example 1212178825Sdfrhost# ktutil -k /etc/krb5-service.keytab \ 1213178825Sdfr get -p lha/admin@@EXAMPLE.ORG service-principal@@EXAMPLE.ORG 1214178825Sdfrlha/admin@@EXAMPLE.ORG's Password: 1215178825Sdfr@end example 1216178825Sdfr 1217178825SdfrTo get a Kerberos credential file for the service, use kinit in the 1218178825Sdfr@kbd{--keytab} mode. This will not ask for a password but instead fetch the 1219178825Sdfrkey from the keytab. 1220178825Sdfr 1221178825Sdfr@example 1222178825Sdfrservice@@host$ kinit --cache=/var/run/service_krb5_cache \ 1223178825Sdfr --keytab=/etc/krb5-service.keytab \ 1224178825Sdfr service-principal@@EXAMPLE.ORG 1225178825Sdfr@end example 1226178825Sdfr 1227178825SdfrLong running services might need credentials longer then the 1228178825Sdfrexpiration time of the tickets. kinit can run in a mode that refreshes 1229178825Sdfrthe tickets before they expire. This is useful for services that write 1230178825Sdfrinto AFS and other distributed file systems using Kerberos. To run the 1231178825Sdfrlong running script, just append the program and arguments (if any) 1232178825Sdfrafter the principal. kinit will stop refreshing credentials and remove 1233178825Sdfrthe credentials when the script-to-start-service exits. 1234178825Sdfr 1235178825Sdfr@example 1236178825Sdfrservice@@host$ kinit --cache=/var/run/service_krb5_cache \ 1237178825Sdfr --keytab=/etc/krb5-service.keytab \ 1238178825Sdfr service-principal@@EXAMPLE.ORG \ 1239178825Sdfr script-to-start-service argument1 argument2 1240178825Sdfr@end example 1241178825Sdfr 1242178825Sdfr 1243233294Sstas@node Setting up PK-INIT, Debugging Kerberos problems, Providing Kerberos credentials to servers and programs, Setting up a realm 1244178825Sdfr@section Setting up PK-INIT 1245178825Sdfr 1246233294SstasPK-INIT leverages an existing PKI (public key infrastructure), using 1247233294Sstascertificates to get the initial ticket (usually the krbtgt 1248233294Sstasticket-granting ticket). 1249178825Sdfr 1250233294SstasTo use PK-INIT you must first have a PKI. If you don't have one, it is 1251233294Sstastime to create it. You should first read the whole chapter of the 1252233294Sstasdocument to see the requirements imposed on the CA software. 1253178825Sdfr 1254233294SstasA mapping between the PKI certificate and what principals that 1255233294Sstascertificate is allowed to use must exist. There are several ways to do 1256233294Sstasthis. The administrator can use a configuration file, store the 1257233294Sstasprincipal in the SubjectAltName extension of the certificate, or store 1258233294Sstasthe mapping in the principals entry in the kerberos database. 1259178825Sdfr 1260178825Sdfr@section Certificates 1261178825Sdfr 1262178825SdfrThis section documents the requirements on the KDC and client 1263178825Sdfrcertificates and the format used in the id-pkinit-san OtherName 1264178825Sdfrextention. 1265178825Sdfr 1266178825Sdfr@subsection KDC certificate 1267178825Sdfr 1268233294SstasThe certificate for the KDC has serveral requirements. 1269178825Sdfr 1270233294SstasFirst, the certificate should have an Extended Key Usage (EKU) 1271233294Sstasid-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second, there must be a 1272233294SstassubjectAltName otherName using OID id-pkinit-san (1.3.6.1.5.2.2) in 1273178825Sdfrthe type field and a DER encoded KRB5PrincipalName that matches the 1274233294Sstasname of the TGS of the target realm. Also, if the certificate has a 1275233294SstasnameConstraints extention with a Generalname with dNSName or iPAdress, 1276233294Sstasit must match the hostname or adress of the KDC. 1277178825Sdfr 1278233294SstasThe client is not required by the standard to check the server 1279233294Sstascertificate for this information if the client has external 1280233294Sstasinformation confirming which certificate the KDC is supposed to be 1281233294Sstasusing. However, adding this information to the KDC certificate removes 1282233294Sstasthe need to specially configure the client to recognize the KDC 1283233294Sstascertificate. 1284178825Sdfr 1285178825SdfrRemember that if the client would accept any certificate as the KDC's 1286178825Sdfrcertificate, the client could be fooled into trusting something that 1287178825Sdfrisn't a KDC and thus expose the user to giving away information (like 1288233294Sstasa password or other private information) that it is supposed to keep 1289233294Sstassecret. 1290178825Sdfr 1291178825Sdfr@subsection Client certificate 1292178825Sdfr 1293178825SdfrThe client certificate may need to have a EKU id-pkekuoid 1294178825Sdfr(1.3.6.1.5.2.3.4) set depending on the certifiate on the KDC. 1295178825Sdfr 1296178825SdfrIt possible to store the principal (if allowed by the KDC) in the 1297178825Sdfrcertificate and thus delegate responsibility to do the mapping between 1298178825Sdfrcertificates and principals to the CA. 1299178825Sdfr 1300233294SstasThis behavior is controlled by KDC configuration option: 1301233294Sstas 1302233294Sstas@example 1303233294Sstas[kdc] 1304233294Sstas pkinit_principal_in_certificate = yes 1305233294Sstas@end example 1306233294Sstas 1307178825Sdfr@subsubsection Using KRB5PrincipalName in id-pkinit-san 1308178825Sdfr 1309233294SstasThe OtherName extention in the GeneralName is used to do the mapping 1310233294Sstasbetween certificate and principal. For the KDC certificate, this 1311233294Sstasstores the krbtgt principal name for that KDC. For the client 1312233294Sstascertificate, this stores the principal for which that certificate is 1313233294Sstasallowed to get tickets. 1314178825Sdfr 1315178825SdfrThe principal is stored in a SubjectAltName in the certificate using 1316233294SstasOtherName. The OID in the type is id-pkinit-san. 1317178825Sdfr 1318178825Sdfr@example 1319178825Sdfrid-pkinit-san OBJECT IDENTIFIER ::= @{ iso (1) org (3) dod (6) 1320178825Sdfrinternet (1) security (5) kerberosv5 (2) 2 @} 1321178825Sdfr@end example 1322178825Sdfr 1323178825SdfrThe data part of the OtherName is filled with the following DER 1324178825Sdfrencoded ASN.1 structure: 1325178825Sdfr 1326178825Sdfr@example 1327178825SdfrKRB5PrincipalName ::= SEQUENCE @{ 1328178825Sdfr realm [0] Realm, 1329178825Sdfr principalName [1] PrincipalName 1330178825Sdfr@} 1331178825Sdfr@end example 1332178825Sdfr 1333233294Sstaswhere Realm and PrincipalName is defined by the Kerberos ASN.1 1334233294Sstasspecification. 1335178825Sdfr 1336178825Sdfr@section Naming certificate using hx509 1337178825Sdfr 1338178825Sdfrhx509 is the X.509 software used in Heimdal to handle 1339233294Sstascertificates. hx509 supports several different syntaxes for specifying 1340233294Sstascertificate files or formats. Several formats may be used: PEM, 1341233294Sstascertificates embedded in PKCS#12 files, certificates embedded in 1342233294SstasPKCS#11 devices, and raw DER encoded certificates. 1343178825Sdfr 1344233294SstasThose formats may be specified as follows: 1345178825Sdfr 1346178825Sdfr@table @asis 1347178825Sdfr 1348178825Sdfr@item DIR: 1349178825Sdfr 1350233294SstasDIR specifies a directory which contains certificates in the DER or 1351233294SstasPEM format. 1352178825Sdfr 1353178825SdfrThe main feature of DIR is that the directory is read on demand when 1354233294Sstasiterating over certificates. This allows applications, in some 1355233294Sstassituations, to avoid having to store all certificates in memory. It's 1356233294Sstasvery useful for tests that iterate over large numbers of certificates. 1357178825Sdfr 1358233294SstasThe syntax is: 1359178825Sdfr 1360178825Sdfr@example 1361178825SdfrDIR:/path/to/der/files 1362178825Sdfr@end example 1363178825Sdfr 1364178825Sdfr@item FILE: 1365178825Sdfr 1366233294SstasFILE: specifies a file that contains a certificate or private key. 1367233294SstasThe file can be either a PEM (openssl) file or a raw DER encoded 1368233294Sstascertificate. If it's a PEM file, it can contain several keys and 1369178825Sdfrcertificates and the code will try to match the private key and 1370233294Sstascertificate together. Multiple files may be specified, separated by 1371233294Sstascommas. 1372178825Sdfr 1373233294SstasIt's useful to have one PEM file that contains all the trust anchors. 1374178825Sdfr 1375233294SstasThe syntax is: 1376178825Sdfr 1377178825Sdfr@example 1378178825SdfrFILE:certificate.pem,private-key.key,other-cert.pem,.... 1379178825Sdfr@end example 1380178825Sdfr 1381178825Sdfr@item PKCS11: 1382178825Sdfr 1383233294SstasPKCS11: is used to handle smartcards via PKCS#11 drivers, such as 1384233294Sstassoft-token, opensc, or muscle. The argument specifies a shared object 1385233294Sstasthat implements the PKCS#11 API. The default is to use all slots on 1386233294Sstasthe device/token. 1387178825Sdfr 1388233294SstasThe syntax is: 1389178825Sdfr 1390178825Sdfr@example 1391178825SdfrPKCS11:shared-object.so 1392178825Sdfr@end example 1393178825Sdfr 1394178825Sdfr@item PKCS12: 1395178825Sdfr 1396233294SstasPKCS12: is used to handle PKCS#12 files. PKCS#12 files commonly have 1397233294Sstasthe extension pfx or p12. 1398178825Sdfr 1399233294SstasThe syntax is: 1400178825Sdfr 1401178825Sdfr@example 1402178825SdfrPKCS12:/path/to/file.pfx 1403178825Sdfr@end example 1404178825Sdfr 1405178825Sdfr@end table 1406178825Sdfr 1407178825Sdfr@section Configure the Kerberos software 1408178825Sdfr 1409178825SdfrFirst configure the client's trust anchors and what parameters to 1410233294Sstasverify. See the subsections below for how to do that. Then, you can 1411233294Sstasuse kinit to get yourself tickets. For example: 1412178825Sdfr 1413178825Sdfr@example 1414178825Sdfr$ kinit -C FILE:$HOME/.certs/lha.crt,$HOME/.certs/lha.key lha@@EXAMPLE.ORG 1415178825SdfrEnter your private key passphrase: 1416178825Sdfr: lha@@nutcracker ; klist 1417178825SdfrCredentials cache: FILE:/tmp/krb5cc_19100a 1418178825Sdfr Principal: lha@@EXAMPLE.ORG 1419178825Sdfr 1420178825Sdfr Issued Expires Principal 1421178825SdfrApr 20 02:08:08 Apr 20 12:08:08 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG 1422178825Sdfr@end example 1423178825Sdfr 1424233294SstasUsing PKCS#11 it can look like this instead: 1425178825Sdfr 1426178825Sdfr@example 1427233294Sstas$ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@@EXAMPLE.ORG 1428178825SdfrPIN code for SoftToken (slot): 1429178825Sdfr$ klist 1430178825SdfrCredentials cache: API:4 1431178825Sdfr Principal: lha@@EXAMPLE.ORG 1432178825Sdfr 1433178825Sdfr Issued Expires Principal 1434178825SdfrMar 26 23:40:10 Mar 27 09:40:10 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG 1435178825Sdfr@end example 1436178825Sdfr 1437233294SstasTODO: Write about the KDC. 1438178825Sdfr 1439178825Sdfr@section Configure the client 1440178825Sdfr 1441178825Sdfr@example 1442178825Sdfr[appdefaults] 1443178825Sdfr pkinit_anchors = FILE:/path/to/trust-anchors.pem 1444178825Sdfr 1445178825Sdfr[realms] 1446178825Sdfr EXAMPLE.COM = @{ 1447178825Sdfr pkinit_require_eku = true 1448178825Sdfr pkinit_require_krbtgt_otherName = true 1449178825Sdfr pkinit_win2k = no 1450178825Sdfr pkinit_win2k_require_binding = yes 1451178825Sdfr @} 1452178825Sdfr 1453178825Sdfr@end example 1454178825Sdfr 1455178825Sdfr@section Configure the KDC 1456178825Sdfr 1457178825Sdfr@example 1458178825Sdfr[kdc] 1459178825Sdfr enable-pkinit = yes 1460178825Sdfr pkinit_identity = FILE:/secure/kdc.crt,/secure/kdc.key 1461178825Sdfr pkinit_anchors = FILE:/path/to/trust-anchors.pem 1462178825Sdfr pkinit_pool = PKCS12:/path/to/useful-intermediate-certs.pfx 1463178825Sdfr pkinit_pool = FILE:/path/to/other-useful-intermediate-certs.pem 1464233294Sstas pkinit_allow_proxy_certificate = no 1465178825Sdfr pkinit_win2k_require_binding = yes 1466233294Sstas pkinit_principal_in_certificate = no 1467178825Sdfr@end example 1468178825Sdfr 1469178825Sdfr@subsection Using pki-mapping file 1470178825Sdfr 1471178825SdfrNote that the file name is space sensitive. 1472178825Sdfr 1473178825Sdfr@example 1474178825Sdfr# cat /var/heimdal/pki-mapping 1475178825Sdfr# comments starts with # 1476178825Sdfrlha@@EXAMPLE.ORG:C=SE,O=Stockholm universitet,CN=Love,UID=lha 1477178825Sdfrlha@@EXAMPLE.ORG:CN=Love,UID=lha 1478178825Sdfr@end example 1479178825Sdfr 1480178825Sdfr@subsection Using the Kerberos database 1481178825Sdfr 1482178825Sdfr@section Use hxtool to create certificates 1483178825Sdfr 1484178825Sdfr@subsection Generate certificates 1485178825Sdfr 1486233294SstasFirst, you need to generate a CA certificate. This example creates a 1487233294SstasCA certificate that will be valid for 10 years. 1488178825Sdfr 1489233294SstasYou need to change --subject in the command below to something 1490233294Sstasappropriate for your site. 1491178825Sdfr 1492178825Sdfr@example 1493178825Sdfrhxtool issue-certificate \ 1494178825Sdfr --self-signed \ 1495178825Sdfr --issue-ca \ 1496178825Sdfr --generate-key=rsa \ 1497178825Sdfr --subject="CN=CA,DC=test,DC=h5l,DC=se" \ 1498178825Sdfr --lifetime=10years \ 1499178825Sdfr --certificate="FILE:ca.pem" 1500178825Sdfr@end example 1501178825Sdfr 1502178825SdfrThe KDC needs to have a certificate, so generate a certificate of the 1503178825Sdfrtype ``pkinit-kdc'' and set the PK-INIT specifial SubjectAltName to the 1504178825Sdfrname of the krbtgt of the realm. 1505178825Sdfr 1506233294SstasYou need to change --subject and --pk-init-principal in the command 1507233294Sstasbelow to something appropriate for your site. 1508178825Sdfr 1509178825Sdfr@example 1510178825Sdfrhxtool issue-certificate \ 1511178825Sdfr --ca-certificate=FILE:ca.pem \ 1512178825Sdfr --generate-key=rsa \ 1513178825Sdfr --type="pkinit-kdc" \ 1514178825Sdfr --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \ 1515178825Sdfr --subject="uid=kdc,DC=test,DC=h5l,DC=se" \ 1516178825Sdfr --certificate="FILE:kdc.pem" 1517178825Sdfr@end example 1518178825Sdfr 1519233294SstasThe users also needs to have certificates. For your first client, 1520233294Sstasgenerate a certificate of type ``pkinit-client''. The client doesn't 1521233294Sstasneed to have the PK-INIT SubjectAltName set; you can have the Subject 1522233294SstasDN in the ACL file (pki-mapping) instead. 1523178825Sdfr 1524233294SstasYou need to change --subject and --pk-init-principal in the command 1525233294Sstasbelow to something appropriate for your site. You can omit 1526233294Sstas--pk-init-principal if you're going to use the ACL file instead. 1527178825Sdfr 1528178825Sdfr@example 1529178825Sdfrhxtool issue-certificate \ 1530178825Sdfr --ca-certificate=FILE:ca.pem \ 1531178825Sdfr --generate-key=rsa \ 1532178825Sdfr --type="pkinit-client" \ 1533178825Sdfr --pk-init-principal="lha@@TEST.H5L.SE" \ 1534178825Sdfr --subject="uid=lha,DC=test,DC=h5l,DC=se" \ 1535178825Sdfr --certificate="FILE:user.pem" 1536178825Sdfr@end example 1537178825Sdfr 1538178825Sdfr@subsection Validate the certificate 1539178825Sdfr 1540233294Sstashxtool also contains a tool that will validate certificates according 1541233294Sstasto rules from the PKIX document. These checks are not complete, but 1542233294Sstasthey provide a good test of whether you got all of the basic bits 1543233294Sstasright in your certificates. 1544178825Sdfr 1545178825Sdfr@example 1546178825Sdfrhxtool validate FILE:user.pem 1547178825Sdfr@end example 1548178825Sdfr 1549178825Sdfr@section Use OpenSSL to create certificates 1550178825Sdfr 1551178825SdfrThis section tries to give the CA owners hints how to create 1552178825Sdfrcertificates using OpenSSL (or CA software based on OpenSSL). 1553178825Sdfr 1554178825Sdfr@subsection Using OpenSSL to create certificates with krb5PrincipalName 1555178825Sdfr 1556233294SstasTo make OpenSSL create certificates with krb5PrincipalName, use an 1557178825Sdfr@file{openssl.cnf} as described below. To see a complete example of 1558178825Sdfrcreating client and KDC certificates, see the test-data generation 1559178825Sdfrscript @file{lib/hx509/data/gen-req.sh} in the source-tree. The 1560178825Sdfrcerticates it creates are used to test the PK-INIT functionality in 1561178825Sdfr@file{tests/kdc/check-kdc.in}. 1562178825Sdfr 1563178825SdfrTo use this example you have to use OpenSSL 0.9.8a or later. 1564178825Sdfr 1565178825Sdfr@example 1566178825Sdfr 1567178825Sdfr[user_certificate] 1568178825SdfrsubjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name 1569178825Sdfr 1570178825Sdfr[princ_name] 1571178825Sdfrrealm = EXP:0, GeneralString:MY.REALM 1572178825Sdfrprincipal_name = EXP:1, SEQUENCE:principal_seq 1573178825Sdfr 1574178825Sdfr[principal_seq] 1575178825Sdfrname_type = EXP:0, INTEGER:1 1576178825Sdfrname_string = EXP:1, SEQUENCE:principals 1577178825Sdfr 1578178825Sdfr[principals] 1579178825Sdfrprinc1 = GeneralString:userid 1580178825Sdfr 1581178825Sdfr@end example 1582178825Sdfr 1583233294SstasCommand usage: 1584178825Sdfr 1585178825Sdfr@example 1586178825Sdfropenssl x509 -extensions user_certificate 1587178825Sdfropenssl ca -extensions user_certificate 1588178825Sdfr@end example 1589178825Sdfr 1590178825Sdfr 1591178825Sdfr@c --- ms certificate 1592178825Sdfr@c 1593178825Sdfr@c [ new_oids ] 1594178825Sdfr@c msCertificateTemplateName = 1.3.6.1.4.1.311.20.2 1595178825Sdfr@c 1596178825Sdfr@c 1597178825Sdfr@c [ req_smartcard ] 1598178825Sdfr@c keyUsage = digitalSignature, keyEncipherment 1599178825Sdfr@c extendedKeyUsage = msSmartcardLogin, clientAuth 1600178825Sdfr@c msCertificateTemplateName = ASN1:BMP:SmartcardLogon 1601178825Sdfr@c subjectAltName = otherName:msUPN;UTF8:lukeh@dsg.padl.com 1602178825Sdfr@c #subjectAltName = email:copy 1603178825Sdfr 1604178825Sdfr 1605178825Sdfr@section Using PK-INIT with Windows 1606178825Sdfr 1607178825Sdfr@subsection Client configration 1608178825Sdfr 1609178825SdfrClients using a Windows KDC with PK-INIT need configuration since 1610178825Sdfrwindows uses pre-standard format and this can't be autodetected. 1611178825Sdfr 1612178825SdfrThe pkinit_win2k_require_binding option requires the reply for the KDC 1613233294Sstasto be of the new, secure, type that binds the request to 1614233294Sstasreply. Before, clients could fake the reply from the KDC. To use this 1615233294Sstasoption you have to apply a fix from Microsoft. 1616178825Sdfr 1617178825Sdfr@example 1618178825Sdfr[realms] 1619178825Sdfr MY.MS.REALM = @{ 1620178825Sdfr pkinit_win2k = yes 1621178825Sdfr pkinit_win2k_require_binding = no 1622178825Sdfr @} 1623178825Sdfr@end example 1624178825Sdfr 1625178825Sdfr@subsection Certificates 1626178825Sdfr 1627178825SdfrThe client certificates need to have the extended keyusage ``Microsoft 1628233294SstasSmartcardlogin'' (openssl has the OID shortname msSmartcardLogin). 1629178825Sdfr 1630178825SdfrSee Microsoft Knowledge Base Article - 281245 ``Guidelines for Enabling 1631178825SdfrSmart Card Logon with Third-Party Certification Authorities'' for a 1632233294Sstasmore extensive description of how set setup an external CA so that it 1633233294Sstasincludes all the information required to make a Windows KDC happy. 1634178825Sdfr 1635178825Sdfr@subsection Configure Windows 2000 CA 1636178825Sdfr 1637233294SstasTo enable Microsoft Smartcardlogin for certificates in your Windows 1638233294Sstas2000 CA, you want to look at Microsoft Knowledge Base Article - 313274 1639233294Sstas``HOW TO: Configure a Certification Authority to Issue Smart Card 1640233294SstasCertificates in Windows''. 1641233294Sstas 1642233294Sstas@node Debugging Kerberos problems, , Setting up PK-INIT, Setting up a realm 1643233294Sstas@section Debugging Kerberos problems 1644233294Sstas 1645233294SstasTo debug Kerberos client and server problems you can enable debug 1646233294Sstastraceing by adding the following to @file{/etc/krb5,conf}. Note that the 1647233294Sstastrace logging is sparse at the moment, but will continue to improve. 1648233294Sstas 1649233294Sstas@example 1650233294Sstas[logging] 1651233294Sstas libkrb5 = 0-/SYSLOG: 1652233294Sstas@end example 1653233294Sstas 1654233294Sstas 1655233294Sstas 1656233294Sstas 1657