third_party/heimdal/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 ENVIRONMENT
 277 .Bl -tag -width Ds
 278 .It Ev KRB5CCNAME
 279 Specifies the default credentials cache.
 280 .It Ev KRB5_CONFIG
 281 The file name of
 282 .Pa krb5.conf ,
 283 the default being
 284 .Pa /etc/krb5.conf .
 285 .El
 286 .\".Sh FILES
 287 .\".Sh EXAMPLES
 288 .\".Sh DIAGNOSTICS
 289 .Sh SEE ALSO
 290 .Xr kdestroy 1 ,
 291 .Xr klist 1 ,
 292 .Xr kswitch 1 ,
 293 .Xr krb5_appdefault 3 ,
 294 .Xr krb5.conf 5
 295 .\".Sh STANDARDS
 296 .\".Sh HISTORY
 297 .\".Sh AUTHORS
 298 .\".Sh BUGS