third_party/heimdal/kuser/kgetcred.1

   1 .\" Copyright (c) 1999, 2001 - 2002 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 March 12, 2004
  35 .Dt KGETCRED 1
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm kgetcred
  39 .Nd "get a ticket for a particular service"
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl Fl canonicalize
  43 .Op Fl Fl canonical
  44 .Oo Fl c cache \*(Ba Xo
  45 .Fl Fl cache= Ns Ar cache
  46 .Xc
  47 .Oc
  48 .Oo Fl e Ar enctype \*(Ba Xo
  49 .Fl Fl enctype= Ns Ar enctype
  50 .Xc
  51 .Oc
  52 .Op Fl Fl debug
  53 .Oo Fl H \*(Ba Xo
  54 .Fl Fl hostbased
  55 .Xc
  56 .Oc
  57 .Op Fl Fl name-type= Ns Ar name-type
  58 .Op Fl Fl no-transit-check
  59 .Op Fl Fl no-store
  60 .Op Fl Fl cached-only
  61 .Op Fl n \*(Ba Fl Fl anonymous
  62 .Op Fl Fl version
  63 .Op Fl Fl help
  64 .Ar principal
  65 .Nm
  66 .Op options
  67 .Fl Fl hostbased
  68 .Ar principal
  69 .Nm
  70 .Op options
  71 .Fl Fl hostbased
  72 .Ar service
  73 .Ar hostname
  74 .Ar [extra-components]
  75 .Sh DESCRIPTION
  76 .Nm
  77 obtains a ticket for the given service principal.
  78 Usually tickets for services are obtained automatically when needed
  79 but sometimes for some odd reason you want to obtain a particular
  80 ticket or of a special type.
  81 .Pp
  82 If
  83 .Fl Fl hostbased
  84 is given then the given service principal name will be canonicalized
  85 (see below).
  86 .Pp
  87 The third form constructs a host-based principal from the given service
  88 name and hostname.  The service name "host" is used if the given
  89 .Ar service
  90 name in the third usage is the empty string.
  91 .Pp
  92 For host-based names, the local host's hostname is used if the given
  93 .Ar hostname
  94 is the empty string or if the
  95 .Ar principal
  96 has a single component.
  97 .Pp
  98 Any additional components will be included, even for host-based service
  99 principal names, but there are no defaults nor local canonicalization
 100 rules for additional components.
 101 .Pp
 102 Local name canonicalization rules are applied unless the
 103 .Fl Fl canonical
 104 option is given.  Currently local name canonicalization rules are
 105 supported only for host-based principal names' hostname component.
 106 .Pp
 107 The principal's realm name may be canonicalized by following Kerberos
 108 referrals from the client principal's home realm if the
 109 .Fl Fl canonicalize
 110 option is given or if the local name canonicalization rules are
 111 configured to use referrals.
 112 .Pp
 113 Supported options:
 114 .Bl -tag -width Ds
 115 .It Fl Fl canonicalize
 116 requests that the KDC canonicalize the principal.  Currently this only
 117 canonicalizes the realm by chasing referrals from the user's start
 118 realm, but in the future this may also enable the KDC to canonicalize
 119 the complete principal name.
 120 .It Fl Fl canonical
 121 turns off local canonicalization of the principal name.
 122 .It Fl Fl name-type= Ns Ar name-type
 123 the name-type to use when parsing the principal name.
 124 .It Fl Fl hostbased
 125 is short for
 126 .Fl Fl name-type=srv_hst .
 127 .It Fl c Ar cache , Fl Fl cache= Ns Ar cache
 128 the credential cache to use.
 129 .It Fl Fl delegation-credential-cache= Ns Ar cache
 130 the credential cache to use for delegation.
 131 .It Fl e Ar enctype , Fl Fl enctype= Ns Ar enctype
 132 encryption type to use.
 133 .It Fl Fl no-transit-check
 134 requests that the KDC doesn't do transit checking.
 135 .It Fl Fl no-store
 136 do not store tickets in the ccache.
 137 .It Fl Fl cached-only
 138 do not talk the TGS, search only the ccache.
 139 .It Fl Fl anonymous
 140 obtain an anonymous service ticket.
 141 .It Fl Fl forwardable
 142 .It Fl Fl debug
 143 enables debug output to stderr.
 144 .It Fl Fl version
 145 .It Fl Fl help
 146 .El
 147 .Pp
 148 If the
 149 .Fl Fl canonical
 150 option is used, then no further canonicalization should be done locally
 151 by the client (for example, DNS), but if
 152 .Fl Fl canonicalize
 153 is used, then the client will ask that the KDC canonicalize the name.
 154 .Pp
 155 If the
 156 .Fl Fl canonicalize
 157 option is used with
 158 .Fl Fl hostbased
 159 a host-based name-type, and
 160 .Fl Fl canonical
 161 is not used, then the hostname will be canonicalized according to the
 162 name canonicalization rules in
 163 .Va krb5.conf .
 164 .Pp
 165 GSS-API initiator applications with host-based services will get the
 166 same behavior as using the
 167 .Fl Fl canonicalize
 168 .Fl Fl hostbased
 169 options here.
 170 .Sh ENVIRONMENT
 171 .Bl -tag -width Ds
 172 .It Ev KRB5CCNAME
 173 Specifies the default credentials cache.
 174 .It Ev KRB5_CONFIG
 175 The file name of
 176 .Pa krb5.conf ,
 177 the default being
 178 .Pa /etc/krb5.conf .
 179 .It Ev KRB5_NO_TICKET_STORE
 180 If this variable is present in the environment, any service tickets obtained
 181 are not added to the credential cache.  This affects all heimdal applications
 182 and library clients, not just kgetcred.
 183 .El
 184 .Sh SEE ALSO
 185 .Xr kinit 1 ,
 186 .Xr klist 1 ,
 187 .Xr krb5.conf 5 ,
 188 .Xr krb5_openlog 3