1 files changed, 463 insertions, 0 deletions
diff --git a/third_party/heimdal/kuser/kinit.1 b/third_party/heimdal/kuser/kinit.1
new file mode 100644
index 0000000..f374a7c
--- /dev/null
+++ b/third_party/heimdal/kuser/kinit.1
@@ -0,0 +1,463 @@
+.\" Copyright (c) 1998 - 2003, 2006 Kungliga Tekniska Högskolan
+.\" (Royal Institute of Technology, Stockholm, Sweden).
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" 3. Neither the name of the Institute nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $Id$
+.\"
+.Dd April 25, 2006
+.Dt KINIT 1
+.Os HEIMDAL
+.Sh NAME
+.Nm kinit
+.Nd acquire initial tickets
+.Sh SYNOPSIS
+.Nm kinit
+.Op Fl Fl no-change-default
+.Op Fl Fl default-for-principal
+.Op Fl Fl afslog
+.Oo Fl c Ar cachename \*(Ba Xo
+.Fl Fl cache= Ns Ar cachename
+.Xc
+.Oc
+.Op Fl f | Fl Fl forwardable
+.Op Fl F | Fl Fl no-forwardable
+.Oo Fl t Ar keytabname \*(Ba Xo
+.Fl Fl keytab= Ns Ar keytabname
+.Xc
+.Oc
+.Oo Fl l Ar time \*(Ba Xo
+.Fl Fl lifetime= Ns Ar time
+.Xc
+.Oc
+.Op Fl p | Fl Fl proxiable
+.Op Fl R | Fl Fl renew
+.Op Fl Fl renewable
+.Oo Fl r Ar time \*(Ba Xo
+.Fl Fl renewable-life= Ns Ar time
+.Xc
+.Oc
+.Oo Fl S Ar principal \*(Ba Xo
+.Fl Fl server= Ns Ar principal
+.Xc
+.Oc
+.Oo Fl s Ar time \*(Ba Xo
+.Fl Fl start-time= Ns Ar time
+.Xc
+.Oc
+.Op Fl k | Fl Fl use-keytab
+.Op Fl v | Fl Fl validate
+.Oo Fl e Ar enctypes \*(Ba Xo
+.Fl Fl enctypes= Ns Ar enctypes
+.Xc
+.Oc
+.Oo Fl a Ar addresses \*(Ba Xo
+.Fl Fl extra-addresses= Ns Ar addresses
+.Xc
+.Oc
+.Op Fl Fl password-file= Ns Ar filename
+.Op Fl Fl fcache-version= Ns Ar version-number
+.Op Fl A | Fl Fl no-addresses
+.Op Fl n | Fl Fl anonymous
+.Op Fl Fl enterprise
+.Op Fl Fl version
+.Op Fl Fl help
+.Op Ar principal Op Ar command
+.Sh DESCRIPTION
+.Nm
+is used to authenticate to the Kerberos server as
+.Ar principal ,
+or if none is given, a system generated default (typically your login
+name at the default realm), and acquire a ticket granting ticket that
+can later be used to obtain tickets for other services.
+.Pp
+Supported options:
+.Bl -tag -width Ds
+.It Fl c Ar cachename | Fl Fl cache= Ns Ar cachename
+The credentials cache to put the acquired ticket in, if other than
+default.
+.It Fl Fl no-change-default
+By default the principal's credentials will be stored in the default
+credential cache.  This option will cause them to instead be stored
+only in a cache whose name is derived from the principal's name.  Note
+that
+.Xr klist 1
+with the
+.Fl l
+option will list all the credential caches the user has, along with
+the name of the principal whose credentials are stored therein.  This
+option is ignored if the
+.Fl c Ar cachename | Fl Fl cache= Ns Ar cachename
+option is given.
+See also
+.Xr kswitch 1 .
+.It Fl Fl default-for-principal
+If this option is given and
+.Fl c Ar cachename | Fl Fl cache= Ns Ar cachename
+is not given, then the cache that will be used will be one that
+is appropriate for the client principal.  For example, if the
+default cache type is
+.Ar FILE
+then the default cache may be either
+.Ar FILE:/tmp/krb5cc_%{uid}+%{principal_name}
+or
+.Ar FILE:/tmp/krb5cc_%{uid}
+if the principal is the default principal for the user, meaning
+that it is of the form
+.Ar ${USER}@${user_realm}
+or
+.Ar ${USER}@${default_realm} .
+This option implies
+.Fl Fl no-change-default
+unless
+.Fl Fl change-default
+is given.  Caches for the user can be listed with the
+.Fl l
+option to
+.Xr klist 1 .
+.It Fl f Fl Fl forwardable
+Obtain a ticket than can be forwarded to another host.
+.It Fl F Fl Fl no-forwardable
+Do not obtain a forwardable ticket.
+.It Fl t Ar keytabname , Fl Fl keytab= Ns Ar keytabname
+Don't ask for a password, but instead get the key from the specified
+keytab.
+.It Fl l Ar time , Fl Fl lifetime= Ns Ar time
+Specifies the lifetime of the ticket.
+The argument can either be in seconds, or a more human readable string
+like
+.Sq 1h .
+.It Fl p , Fl Fl proxiable
+Request tickets with the proxiable flag set.
+.It Fl R , Fl Fl renew
+Try to renew a ticket.
+The ticket must have the
+.Sq renewable
+flag set, and must not be expired. If the
+.Oo Fl S Ar principal Oc
+option is specified, the ticket for the indicated service is renewed.
+If no service is explicitly specified, an attempt is made to renew the
+TGT for the client realm.  If no TGT for the client realm is found in the
+credential cache, an attempt is made to renew the TGT for the defaualt
+realm (if that is found in the credential cache), or else the first
+TGT found.  This makes it easier for users to renew forwarded tickets
+that are not issued by the origin realm.
+.It Fl Fl renewable
+The same as
+.Fl Fl renewable-life ,
+with an infinite time.
+.It Fl r Ar time , Fl Fl renewable-life= Ns Ar time
+The max renewable ticket life.
+.It Fl S Ar principal , Fl Fl server= Ns Ar principal
+Get a ticket for a service other than krbtgt/LOCAL.REALM.
+.It Fl s Ar time , Fl Fl start-time= Ns Ar time
+Obtain a ticket that starts to be valid
+.Ar time
+(which can really be a generic time specification, like
+.Sq 1h )
+seconds into the future.
+.It Fl k , Fl Fl use-keytab
+The same as
+.Fl Fl keytab ,
+but with the default keytab name (normally
+.Ar FILE:/etc/krb5.keytab ) .
+.It Fl v , Fl Fl validate
+Try to validate an invalid ticket.
+.It Fl e , Fl Fl enctypes= Ns Ar enctypes
+Request tickets with this particular enctype.
+.It Fl Fl password-file= Ns Ar filename
+read the password from the first line of
+.Ar filename .
+If the
+.Ar filename
+is
+.Ar STDIN ,
+the password will be read from the standard input.
+.It Fl Fl fcache-version= Ns Ar version-number
+Create a credentials cache of version
+.Ar version-number .
+.It Fl a , Fl Fl extra-addresses= Ns Ar enctypes
+Adds a set of addresses that will, in addition to the systems local
+addresses, be put in the ticket.
+This can be useful if all addresses a client can use can't be
+automatically figured out.
+One such example is if the client is behind a firewall.
+Also settable via
+.Li libdefaults/extra_addresses
+in
+.Xr krb5.conf 5 .
+.It Fl A , Fl Fl no-addresses
+Request a ticket with no addresses.
+.It Fl n , Fl Fl anonymous
+Request an anonymous ticket.
+With the default (false) setting of the
+.Ar historical_anon_pkinit
+configuration parameter, if the principal is specified as @REALM, then
+anonymous PKINIT will be used to acquire an unauthenticated anonymous ticket
+and both the client name and (with fully RFC-comformant KDCs) realm in the
+returned ticket will be anonymized.
+Otherwise, authentication proceeds as normal and the anonymous ticket will have
+only the client name anonymized.
+With
+.Ar historical_anon_pkinit
+set to
+.Li true ,
+the principal is interpreted as a realm even without an at-sign prefix, and it
+is not possible to obtain authenticated anonymized tickets.
+.It Fl Fl enterprise
+Parse principal as a enterprise (KRB5-NT-ENTERPRISE) name. Enterprise
+names are email like principals that are stored in the name part of
+the principal, and since there are two @ characters the parser needs
+to know that the first is not a realm.
+An example of an enterprise name is
+.Dq lha@e.kth.se@KTH.SE ,
+and this option is usually used with canonicalize so that the
+principal returned from the KDC will typically be the real principal
+name.
+.It Fl Fl gss-mech
+Enable GSS-API pre-authentication using the specified mechanism OID. Unless
+.Ar gss-name
+is also set, then the specified principal name will be used as the GSS-API
+initiator name. If the principal is specified as @REALM or left unspecified,
+then the default GSS-API credential will be used.
+.It Fl Fl gss-name
+Attempt GSS-API pre-authentication using an initiator name distinct from the
+Kerberos client principal,
+.It Fl Fl afslog
+Gets AFS tickets, converts them to version 4 format, and stores them
+in the kernel.
+Only useful if you have AFS.
+.El
+.Pp
+The
+.Ar forwardable ,
+.Ar proxiable ,
+.Ar ticket_life ,
+and
+.Ar renewable_life
+options can be set to a default value from the
+.Dv appdefaults
+section in krb5.conf, see
+.Xr krb5_appdefault 3 .
+.Pp
+If  a
+.Ar command
+is given,
+.Nm
+will set up new credentials caches, and AFS PAG, and then run the given
+command.
+When it finishes the credentials will be removed.
+.Sh CREDENTIALS CACHE TYPES
+Heimdal supports a number of credentials cache types:
+.Bl -tag -width Ds
+.It FILE
+Uses a file per-cache with a binary format common to other Kerberos
+implementations.
+.It DIR
+Uses a directory with multiple files, one per-cache in a collection.
+.It SCC
+Uses a SQLite3 database with multiple caches in the database.
+.It KEYRING
+Uses a Linux keyring.
+.It KCM
+Uses a inter-process communications (IPC) to talk to a daemon typically named
+.Nm kcm .
+.It API
+Uses KCM or else a shared object that implements the "CCAPI".
+.It MEMORY
+Uses in-process memory (which disappears on process exit, so this if of little
+use in this program,
+.Nm
+).
+.El
+.Sh CREDENTIALS CACHE COLLECTIONS
+Every credentials cache's name consists of its cache type (e.g.,
+FILE), a possibly-optional collection name, and a possibly
+optional "subsidiary" name naming a single cache in the
+collection.
+.Pp
+The convention in Heimdal is that a cache's subsidiary cache name
+is the name of the client principal whose credentials are
+expected to be stored and found in that cache, with the following
+characters replaced with a hyphen: slash, backslash, colon, and
+plus.
+.Pp
+The caches in a credentials cache collection can be listed by the
+.Xr klist 1
+command.
+The
+.Sq FILE
+credentials cache type supports listing of caches in the
+collection only when the
+.Ql enable_file_cache_iteration
+is set to
+.Ql yes
+in the
+.Ql [libdefaults]
+section of
+.Xr krb5.conf 5 .
+.Sh CREDENTIALS CACHE NAMES
+The general syntax for credentials cache names is
+.Dl TYPE:[collection-name][:subsidiary]
+except that for the FILE type it is
+.Dl FILE:collection-name[+subsidiary]
+and for the KEYRING type it is:
+.Dl KEYRING:[anchor:][collection[:subsidiary]]
+where the collection name is free-form and the anchor is one of
+.Sq process ,
+.Sq thread ,
+or
+.Sq legacy .
+.Pp
+The collection name is always absent for the
+.Ql MEMORY
+credentials cache type.
+.Pp
+When the collection name is absent then the default collection
+for the given credentials cache type is used, which are:
+.Bl -tag -compact
+.It Ql /tmp/krb5cc_{UID}
+for FILE caches, where {UID} is a numeric user ID
+.It Ql /tmp/krb5cc_{UID}_dir
+for DIR caches, where {UID} is a numeric user ID
+.It Ql /tmp/krb5scc_{UID}
+for SCC caches, where {UID} is a numeric user ID, and where the
+named file is a SQLite3 database file
+.It Ql {UID}
+for KCM caches, where {UID} is the user's numeric user ID
+.It <implementation-specific>
+for API (CCAPI) credentials caches
+.El
+.Pp
+The collection name is only optional for:
+.Ql DIR ,
+.Ql SCC ,
+.Ql KCM ,
+.Ql KEYRING
+and
+.Ql API
+credentials cache types.
+.Sh EXAMPLE CREDENTIALS CACHE NAMES
+.Bl -tag -width Ds
+.It Ql FILE:/tmp/cc
+this is a FILE cache in a file named
+.Ql /tmp/cc
+(the default would be
+.Ql /tmp/krb5cc_{UID} )
+.It Ql FILE:/tmp/cc+jane@TEST.H5L.SE
+.It Ql DIR:/tmp/ccdir
+this is a FILE cache named by
+.Ql /tmp/krb5cc_{UID}_dir/primary
+which will be of the form
+.Ql /tmp/ccdir/tkt.XXXXXX 
+.It Ql DIR:/tmp/ccdir:jane@TEST.H5L.SE
+this is a FILE ccache named
+.Ql /tmp/ccdir/tkt.jane@TEST.H5L.SE 
+.It Ql DIR::jane@TEST.H5L.SE
+this is a FILE ccache named
+.Ql /tmp/krb5cc_{UID}_dir/tkt.jane@TEST.H5L.SE
+where {UID} is the user's numeric identifier
+.It Ql SCC:
+this is the current primary cache in the SQLite3 database named
+.Ql /tmp/krb5scc_{UID}
+.It Ql SCC:/tmp/ccdb
+this is the current primary cache in the SQLite3 database named
+.Ql /tmp/ccdb
+.It Ql SCC:/tmp/ccdb:jane@TEST.H5L.SE
+this is the cache
+.Dq named jane@TEST.H5L.SE
+in the SQLite3 database
+named
+.Ql /tmp/ccdb
+.It Ql SCC::jane@TEST.H5L.SE
+this is the cache named
+.Dq jane@TEST.H5L.SE
+in the SQLite3 database named
+.Ql /tmp/krb5scc_{UID}
+.It Ql KEYRING:
+this is the primary cache in the default KEYRING collection for
+the running user
+.It Ql KEYRING:foo
+this is the primary cache in the KEYRING collection named
+.Dq foo
+.It Ql KEYRING:foo:jane@TEST.H5L.SE
+this is the cache named
+.Dq jane@TEST.H5L.SE
+in the KEYRING collection named
+.Dq foo
+.It Ql KCM:
+this is the primary cache in the default KCM collection for the
+running user
+.It Ql KCM:12345
+this is the primary cache in the default KCM collection for the
+user whose numeric identifier is 12345
+.It Ql KCM:jane@TEST.H5L.SE
+this is the cache named
+.Dq jane@TEST.H5L.SE
+in the default KCM collection for the running user
+.It Ql KCM:12345:jane@TEST.H5L.SE
+this is the cache named
+.Dq jane@TEST.H5L.SE
+in the default KCM collection for the given user
+.It Ql API:
+this is the primary cache in the default API collection for the
+running user
+.It Ql API:foo
+this is the primary cache in the API collection named
+.Dq foo
+.It Ql API:foo:jane@TEST.H5L.SE
+this is the cache named
+.Dq jane@TEST.H5L.SE
+in the KEYRING collection named
+.Dq foo
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev KRB5CCNAME
+Specifies the default credentials cache.
+.It Ev KRB5_CONFIG
+The file name of
+.Pa krb5.conf ,
+the default being
+.Pa /etc/krb5.conf .
+.El
+.\".Sh FILES
+.\".Sh EXAMPLES
+.\".Sh DIAGNOSTICS
+.Sh SEE ALSO
+.Xr kdestroy 1 ,
+.Xr klist 1 ,
+.Xr kswitch 1 ,
+.Xr kcm 8 ,
+.Xr krb5_appdefault 3 ,
+.Xr krb5.conf 5
+.\".Sh STANDARDS
+.\".Sh HISTORY
+.\".Sh AUTHORS
+.\".Sh BUGS