kuser/kinit.1

   1 .\" Copyright (c) 1998 - 2003, 2006 Kungliga Tekniska Högskolan
   2 .\" (Royal Institute of Technology, Stockholm, Sweden).
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\"
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" 3. Neither the name of the Institute nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $Id$
  33 .\"
  34 .Dd April 25, 2006
  35 .Dt KINIT 1
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm kinit
  39 .Nd acquire initial tickets
  40 .Sh SYNOPSIS
  41 .Nm kinit
  42 .Op Fl Fl no-change-default
  43 .Op Fl Fl default-for-principal
  44 .Op Fl Fl afslog
  45 .Oo Fl c Ar cachename \*(Ba Xo
  46 .Fl Fl cache= Ns Ar cachename
  47 .Xc
  48 .Oc
  49 .Op Fl f | Fl Fl forwardable
  50 .Op Fl F | Fl Fl no-forwardable
  51 .Oo Fl t Ar keytabname \*(Ba Xo
  52 .Fl Fl keytab= Ns Ar keytabname
  53 .Xc
  54 .Oc
  55 .Oo Fl l Ar time \*(Ba Xo
  56 .Fl Fl lifetime= Ns Ar time
  57 .Xc
  58 .Oc
  59 .Op Fl p | Fl Fl proxiable
  60 .Op Fl R | Fl Fl renew
  61 .Op Fl Fl renewable
  62 .Oo Fl r Ar time \*(Ba Xo
  63 .Fl Fl renewable-life= Ns Ar time
  64 .Xc
  65 .Oc
  66 .Oo Fl S Ar principal \*(Ba Xo
  67 .Fl Fl server= Ns Ar principal
  68 .Xc
  69 .Oc
  70 .Oo Fl s Ar time \*(Ba Xo
  71 .Fl Fl start-time= Ns Ar time
  72 .Xc
  73 .Oc
  74 .Op Fl k | Fl Fl use-keytab
  75 .Op Fl v | Fl Fl validate
  76 .Oo Fl e Ar enctypes \*(Ba Xo
  77 .Fl Fl enctypes= Ns Ar enctypes
  78 .Xc
  79 .Oc
  80 .Oo Fl a Ar addresses \*(Ba Xo
  81 .Fl Fl extra-addresses= Ns Ar addresses
  82 .Xc
  83 .Oc
  84 .Op Fl Fl password-file= Ns Ar filename
  85 .Op Fl Fl fcache-version= Ns Ar version-number
  86 .Op Fl A | Fl Fl no-addresses
  87 .Op Fl n | Fl Fl anonymous
  88 .Op Fl Fl enterprise
  89 .Op Fl Fl version
  90 .Op Fl Fl help
  91 .Op Ar principal Op Ar command
  92 .Sh DESCRIPTION
  93 .Nm
  94 is used to authenticate to the Kerberos server as
  95 .Ar principal ,
  96 or if none is given, a system generated default (typically your login
  97 name at the default realm), and acquire a ticket granting ticket that
  98 can later be used to obtain tickets for other services.
  99 .Pp
 100 Supported options:
 101 .Bl -tag -width Ds
 102 .It Fl c Ar cachename | Fl Fl cache= Ns Ar cachename
 103 The credentials cache to put the acquired ticket in, if other than
 104 default.
 105 .It Fl Fl no-change-default
 106 By default the principal's credentials will be stored in the default
 107 credential cache.  This option will cause them to instead be stored
 108 only in a cache whose name is derived from the principal's name.  Note
 109 that
 110 .Xr klist 1
 111 with the
 112 .Fl l
 113 option will list all the credential caches the user has, along with
 114 the name of the principal whose credentials are stored therein.  This
 115 option is ignored if the
 116 .Fl c Ar cachename | Fl Fl cache= Ns Ar cachename
 117 option is given.
 118 See also
 119 .Xr kswitch 1 .
 120 .It Fl Fl default-for-principal
 121 If this option is given and
 122 .Fl c Ar cachename | Fl Fl cache= Ns Ar cachename
 123 is not given, then the cache that will be used will be one that
 124 is appropriate for the client principal.  For example, if the
 125 default cache type is
 126 .Ar FILE
 127 then the default cache may be either
 128 .Ar FILE:/tmp/krb5cc_%{uid}+%{principal_name}
 129 or
 130 .Ar FILE:/tmp/krb5cc_%{uid}
 131 if the principal is the default principal for the user, meaning
 132 that it is of the form
 133 .Ar ${USER}@${user_realm}
 134 or
 135 .Ar ${USER}@${default_realm} .
 136 This option implies
 137 .Fl Fl no-change-default
 138 unless
 139 .Fl Fl change-default
 140 is given.  Caches for the user can be listed with the
 141 .Fl l
 142 option to
 143 .Xr klist 1 .
 144 .It Fl f Fl Fl forwardable
 145 Obtain a ticket than can be forwarded to another host.
 146 .It Fl F Fl Fl no-forwardable
 147 Do not obtain a forwardable ticket.
 148 .It Fl t Ar keytabname , Fl Fl keytab= Ns Ar keytabname
 149 Don't ask for a password, but instead get the key from the specified
 150 keytab.
 151 .It Fl l Ar time , Fl Fl lifetime= Ns Ar time
 152 Specifies the lifetime of the ticket.
 153 The argument can either be in seconds, or a more human readable string
 154 like
 155 .Sq 1h .
 156 .It Fl p , Fl Fl proxiable
 157 Request tickets with the proxiable flag set.
 158 .It Fl R , Fl Fl renew
 159 Try to renew a ticket.
 160 The ticket must have the
 161 .Sq renewable
 162 flag set, and must not be expired. If the
 163 .Oo Fl S Ar principal Oc
 164 option is specified, the ticket for the indicated service is renewed.
 165 If no service is explicitly specified, an attempt is made to renew the
 166 TGT for the client realm.  If no TGT for the client realm is found in the
 167 credential cache, an attempt is made to renew the TGT for the defaualt
 168 realm (if that is found in the credential cache), or else the first
 169 TGT found.  This makes it easier for users to renew forwarded tickets
 170 that are not issued by the origin realm.
 171 .It Fl Fl renewable
 172 The same as
 173 .Fl Fl renewable-life ,
 174 with an infinite time.
 175 .It Fl r Ar time , Fl Fl renewable-life= Ns Ar time
 176 The max renewable ticket life.
 177 .It Fl S Ar principal , Fl Fl server= Ns Ar principal
 178 Get a ticket for a service other than krbtgt/LOCAL.REALM.
 179 .It Fl s Ar time , Fl Fl start-time= Ns Ar time
 180 Obtain a ticket that starts to be valid
 181 .Ar time
 182 (which can really be a generic time specification, like
 183 .Sq 1h )
 184 seconds into the future.
 185 .It Fl k , Fl Fl use-keytab
 186 The same as
 187 .Fl Fl keytab ,
 188 but with the default keytab name (normally
 189 .Ar FILE:/etc/krb5.keytab ) .
 190 .It Fl v , Fl Fl validate
 191 Try to validate an invalid ticket.
 192 .It Fl e , Fl Fl enctypes= Ns Ar enctypes
 193 Request tickets with this particular enctype.
 194 .It Fl Fl password-file= Ns Ar filename
 195 read the password from the first line of
 196 .Ar filename .
 197 If the
 198 .Ar filename
 199 is
 200 .Ar STDIN ,
 201 the password will be read from the standard input.
 202 .It Fl Fl fcache-version= Ns Ar version-number
 203 Create a credentials cache of version
 204 .Ar version-number .
 205 .It Fl a , Fl Fl extra-addresses= Ns Ar enctypes
 206 Adds a set of addresses that will, in addition to the systems local
 207 addresses, be put in the ticket.
 208 This can be useful if all addresses a client can use can't be
 209 automatically figured out.
 210 One such example is if the client is behind a firewall.
 211 Also settable via
 212 .Li libdefaults/extra_addresses
 213 in
 214 .Xr krb5.conf 5 .
 215 .It Fl A , Fl Fl no-addresses
 216 Request a ticket with no addresses.
 217 .It Fl n , Fl Fl anonymous
 218 Request an anonymous ticket.
 219 With the default (false) setting of the
 220 .Ar historical_anon_pkinit
 221 configuration parameter, if the principal is specified as @REALM, then
 222 anonymous PKINIT will be used to acquire an unauthenticated anonymous ticket
 223 and both the client name and (with fully RFC-comformant KDCs) realm in the
 224 returned ticket will be anonymized.
 225 Otherwise, authentication proceeds as normal and the anonymous ticket will have
 226 only the client name anonymized.
 227 With
 228 .Ar historical_anon_pkinit
 229 set to
 230 .Li true ,
 231 the principal is interpreted as a realm even without an at-sign prefix, and it
 232 is not possible to obtain authenticated anonymized tickets.
 233 .It Fl Fl enterprise
 234 Parse principal as a enterprise (KRB5-NT-ENTERPRISE) name. Enterprise
 235 names are email like principals that are stored in the name part of
 236 the principal, and since there are two @ characters the parser needs
 237 to know that the first is not a realm.
 238 An example of an enterprise name is
 239 .Dq lha@e.kth.se@KTH.SE ,
 240 and this option is usually used with canonicalize so that the
 241 principal returned from the KDC will typically be the real principal
 242 name.
 243 .It Fl Fl gss-mech
 244 Enable GSS-API pre-authentication using the specified mechanism OID. Unless
 245 .Ar gss-name
 246 is also set, then the specified principal name will be used as the GSS-API
 247 initiator name. If the principal is specified as @REALM or left unspecified,
 248 then the default GSS-API credential will be used.
 249 .It Fl Fl gss-name
 250 Attempt GSS-API pre-authentication using an initiator name distinct from the
 251 Kerberos client principal,
 252 .It Fl Fl afslog
 253 Gets AFS tickets, converts them to version 4 format, and stores them
 254 in the kernel.
 255 Only useful if you have AFS.
 256 .El
 257 .Pp
 258 The
 259 .Ar forwardable ,
 260 .Ar proxiable ,
 261 .Ar ticket_life ,
 262 and
 263 .Ar renewable_life
 264 options can be set to a default value from the
 265 .Dv appdefaults
 266 section in krb5.conf, see
 267 .Xr krb5_appdefault 3 .
 268 .Pp
 269 If  a
 270 .Ar command
 271 is given,
 272 .Nm
 273 will set up new credentials caches, and AFS PAG, and then run the given
 274 command.
 275 When it finishes the credentials will be removed.
 276 .Sh CREDENTIALS CACHE TYPES
 277 Heimdal supports a number of credentials cache types:
 278 .Bl -tag -width Ds
 279 .It FILE
 280 Uses a file per-cache with a binary format common to other Kerberos
 281 implementations.
 282 .It DIR
 283 Uses a directory with multiple files, one per-cache in a collection.
 284 .It SCC
 285 Uses a SQLite3 database with multiple caches in the database.
 286 .It KEYRING
 287 Uses a Linux keyring.
 288 .It KCM
 289 Uses a inter-process communications (IPC) to talk to a daemon typically named
 290 .Nm kcm .
 291 .It API
 292 Uses KCM or else a shared object that implements the "CCAPI".
 293 .It MEMORY
 294 Uses in-process memory (which disappears on process exit, so this if of little
 295 use in this program,
 296 .Nm
 297 ).
 298 .El
 299 .Sh CREDENTIALS CACHE COLLECTIONS
 300 Every credentials cache's name consists of its cache type (e.g.,
 301 FILE), a possibly-optional collection name, and a possibly
 302 optional "subsidiary" name naming a single cache in the
 303 collection.
 304 .Pp
 305 The convention in Heimdal is that a cache's subsidiary cache name
 306 is the name of the client principal whose credentials are
 307 expected to be stored and found in that cache, with the following
 308 characters replaced with a hyphen: slash, backslash, colon, and
 309 plus.
 310 .Pp
 311 The caches in a credentials cache collection can be listed by the
 312 .Xr klist 1
 313 command.
 314 The
 315 .Sq FILE
 316 credentials cache type supports listing of caches in the
 317 collection only when the
 318 .Ql enable_file_cache_iteration
 319 is set to
 320 .Ql yes
 321 in the
 322 .Ql [libdefaults]
 323 section of
 324 .Xr krb5.conf 5 .
 325 .Sh CREDENTIALS CACHE NAMES
 326 The general syntax for credentials cache names is
 327 .Dl TYPE:[collection-name][:subsidiary]
 328 except that for the FILE type it is
 329 .Dl FILE:collection-name[+subsidiary]
 330 and for the KEYRING type it is:
 331 .Dl KEYRING:[anchor:][collection[:subsidiary]]
 332 where the collection name is free-form and the anchor is one of
 333 .Sq process ,
 334 .Sq thread ,
 335 or
 336 .Sq legacy .
 337 .Pp
 338 The collection name is always absent for the
 339 .Ql MEMORY
 340 credentials cache type.
 341 .Pp
 342 When the collection name is absent then the default collection
 343 for the given credentials cache type is used, which are:
 344 .Bl -tag -compact
 345 .It Ql /tmp/krb5cc_{UID}
 346 for FILE caches, where {UID} is a numeric user ID
 347 .It Ql /tmp/krb5cc_{UID}_dir
 348 for DIR caches, where {UID} is a numeric user ID
 349 .It Ql /tmp/krb5scc_{UID}
 350 for SCC caches, where {UID} is a numeric user ID, and where the
 351 named file is a SQLite3 database file
 352 .It Ql {UID}
 353 for KCM caches, where {UID} is the user's numeric user ID
 354 .It <implementation-specific>
 355 for API (CCAPI) credentials caches
 356 .El
 357 .Pp
 358 The collection name is only optional for:
 359 .Ql DIR ,
 360 .Ql SCC ,
 361 .Ql KCM ,
 362 .Ql KEYRING
 363 and
 364 .Ql API
 365 credentials cache types.
 366 .Sh EXAMPLE CREDENTIALS CACHE NAMES
 367 .Bl -tag -width Ds
 368 .It Ql FILE:/tmp/cc
 369 this is a FILE cache in a file named
 370 .Ql /tmp/cc
 371 (the default would be
 372 .Ql /tmp/krb5cc_{UID} )
 373 .It Ql FILE:/tmp/cc+jane@TEST.H5L.SE
 374 .It Ql DIR:/tmp/ccdir
 375 this is a FILE cache named by
 376 .Ql /tmp/krb5cc_{UID}_dir/primary
 377 which will be of the form
 378 .Ql /tmp/ccdir/tkt.XXXXXX
 379 .It Ql DIR:/tmp/ccdir:jane@TEST.H5L.SE
 380 this is a FILE ccache named
 381 .Ql /tmp/ccdir/tkt.jane@TEST.H5L.SE
 382 .It Ql DIR::jane@TEST.H5L.SE
 383 this is a FILE ccache named
 384 .Ql /tmp/krb5cc_{UID}_dir/tkt.jane@TEST.H5L.SE
 385 where {UID} is the user's numeric identifier
 386 .It Ql SCC:
 387 this is the current primary cache in the SQLite3 database named
 388 .Ql /tmp/krb5scc_{UID}
 389 .It Ql SCC:/tmp/ccdb
 390 this is the current primary cache in the SQLite3 database named
 391 .Ql /tmp/ccdb
 392 .It Ql SCC:/tmp/ccdb:jane@TEST.H5L.SE
 393 this is the cache
 394 .Dq named jane@TEST.H5L.SE
 395 in the SQLite3 database
 396 named
 397 .Ql /tmp/ccdb
 398 .It Ql SCC::jane@TEST.H5L.SE
 399 this is the cache named
 400 .Dq jane@TEST.H5L.SE
 401 in the SQLite3 database named
 402 .Ql /tmp/krb5scc_{UID}
 403 .It Ql KEYRING:
 404 this is the primary cache in the default KEYRING collection for
 405 the running user
 406 .It Ql KEYRING:foo
 407 this is the primary cache in the KEYRING collection named
 408 .Dq foo
 409 .It Ql KEYRING:foo:jane@TEST.H5L.SE
 410 this is the cache named
 411 .Dq jane@TEST.H5L.SE
 412 in the KEYRING collection named
 413 .Dq foo
 414 .It Ql KCM:
 415 this is the primary cache in the default KCM collection for the
 416 running user
 417 .It Ql KCM:12345
 418 this is the primary cache in the default KCM collection for the
 419 user whose numeric identifier is 12345
 420 .It Ql KCM:jane@TEST.H5L.SE
 421 this is the cache named
 422 .Dq jane@TEST.H5L.SE
 423 in the default KCM collection for the running user
 424 .It Ql KCM:12345:jane@TEST.H5L.SE
 425 this is the cache named
 426 .Dq jane@TEST.H5L.SE
 427 in the default KCM collection for the given user
 428 .It Ql API:
 429 this is the primary cache in the default API collection for the
 430 running user
 431 .It Ql API:foo
 432 this is the primary cache in the API collection named
 433 .Dq foo
 434 .It Ql API:foo:jane@TEST.H5L.SE
 435 this is the cache named
 436 .Dq jane@TEST.H5L.SE
 437 in the KEYRING collection named
 438 .Dq foo
 439 .El
 440 .Sh ENVIRONMENT
 441 .Bl -tag -width Ds
 442 .It Ev KRB5CCNAME
 443 Specifies the default credentials cache.
 444 .It Ev KRB5_CONFIG
 445 The file name of
 446 .Pa krb5.conf ,
 447 the default being
 448 .Pa /etc/krb5.conf .
 449 .El
 450 .\".Sh FILES
 451 .\".Sh EXAMPLES
 452 .\".Sh DIAGNOSTICS
 453 .Sh SEE ALSO
 454 .Xr kdestroy 1 ,
 455 .Xr klist 1 ,
 456 .Xr kswitch 1 ,
 457 .Xr kcm 8 ,
 458 .Xr krb5_appdefault 3 ,
 459 .Xr krb5.conf 5
 460 .\".Sh STANDARDS
 461 .\".Sh HISTORY
 462 .\".Sh AUTHORS
 463 .\".Sh BUGS