'\" te
.\" Copyright 1987, 1989 by the Student Information Processing Board of the Massachusetts Institute of Technology. For copying and distribution information, please see the file kerberosv5/mit-sipb-copyright.h.
.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH KINIT 1 "June 20, 2021"
.SH NAME
kinit \- obtain and cache Kerberos ticket-granting ticket
.SH SYNOPSIS
.nf
\fB/usr/bin/kinit\fR [\fB-ARvV\fR] [\fB-p\fR | \fB-P\fR] [\fB-f\fR | \fB-F\fR] [\fB-a\fR] [\fB-c\fR \fIcache_name\fR]
     [\fB-k\fR [\fB-t\fR \fIkeytab_file\fR]] [\fB-l\fR \fIlifetime\fR]
     [\fB-r\fR \fIrenewable_life\fR] [\fB-s\fR \fIstart_time\fR] [\fB-S\fR \fIservice_name\fR]
     [\fIprincipal\fR]
.fi

.SH DESCRIPTION
The \fBkinit\fR command is used to obtain and cache an initial ticket-granting
ticket (credential) for \fIprincipal\fR. This ticket is used for authentication
by the Kerberos system. Only users with Kerberos principals can use the
Kerberos system. For information about Kerberos principals, see
\fBkerberos\fR(5).
.sp
.LP
When you use \fBkinit\fR without options, the utility prompts for your
\fIprincipal\fR and Kerberos password, and tries to authenticate your login
with the local Kerberos server. The \fIprincipal\fR can be specified on the
command line if desired.
.sp
.LP
If Kerberos authenticates the login attempt, \fBkinit\fR retrieves your initial
ticket-granting ticket and puts it in the ticket cache. By default your ticket
is stored in the file \fB/tmp/krb5cc_\fIuid\fR\fR, where \fIuid\fR specifies
your user identification number. Tickets expire after a specified lifetime,
after which \fBkinit\fR must be run again. Any existing contents of the cache
are destroyed by \fBkinit\fR.
.sp
.LP
Values specified in the command line override the values specified in the
Kerberos configuration file for \fIlifetime\fR and \fIrenewable_life\fR.
.sp
.LP
The \fBkdestroy\fR(1) command can be used to destroy any active tickets before
you end your login session.
.SH OPTIONS
The following options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 24n
Requests tickets with the local addresses.
.RE

.sp
.ne 2
.na
\fB\fB-A\fR\fR
.ad
.RS 24n
Requests address-less tickets.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR \fIcache_name\fR\fR
.ad
.RS 24n
Uses \fIcache_name\fR as the credentials (ticket) cache name and location. If
this option is not used, the default cache name and location are used.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 24n
Requests forwardable tickets.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR\fR
.ad
.RS 24n
Not forwardable. Does not request forwardable tickets.
.sp
Tickets that have been acquired on one host cannot normally be used on another
host. A client can request that the ticket be marked forwardable. Once the
\fBTKT_FLG_FORWARDABLE\fR flag is set on a ticket, the user can use this ticket
to request a new ticket, but with a different \fBIP\fR address. Thus, users can
use their current credentials to get credentials valid on another machine. This
option allows a user to explicitly obtain a non-forwardable ticket.
.RE

.sp
.ne 2
.na
\fB\fB-k\fR [\fB-t\fR \fIkeytab_file\fR]\fR
.ad
.RS 24n
Requests a host ticket, obtained from a key in the local host's \fIkeytab\fR
file. The name and location of the keytab file can be specified with the
\fB-t\fR \fIkeytab_file\fR option. Otherwise, the default name and location is
used.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR \fIlifetime\fR\fR
.ad
.RS 24n
Requests a ticket with the lifetime \fIlifetime\fR. If the \fB-l\fR option is
not specified, the default ticket lifetime (configured by each site) is used.
Specifying a ticket lifetime longer than the maximum ticket lifetime
(configured by each site) results in a ticket with the maximum lifetime. See
the \fBTime\fR \fBFormats\fR section for the valid time duration formats that
you can specify for \fIlifetime\fR. See \fBkdc.conf\fR(4) and \fBkadmin\fR(1M)
(for \fBgetprinc\fR command to verify the lifetime values for the server
principal).
.sp
The lifetime of the tickets returned is the minimum of the following:
.RS +4
.TP
.ie t \(bu
.el o
Value specified in the command line.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Value specified in the \fBKDC\fR configuration file.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Value specified in the Kerberos data base for the server principal. In the case
of \fBkinit\fR, it is \fBkrbtgt/\fIrealm name\fR\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Value specified in the Kerberos database for the user principal.
.RE
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 24n
Requests proxiable tickets.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.RS 24n
Not proxiable. Does not request proxiable tickets.
.sp
A proxiable ticket is a ticket that allows you to get a ticket for a service
with \fBIP\fR addresses other than the ones in the Ticket Granting Ticket. This
option allows a user to explicitly obtain a non-proxiable ticket.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR \fIrenewable_life\fR\fR
.ad
.RS 24n
Requests renewable tickets, with a total lifetime of \fIrenewable_life\fR. See
the \fBTime\fR \fBFormats\fR section for the valid time duration formats that
you can specify for \fIrenewable_life\fR. See \fBkdc.conf\fR(4) and
\fBkadmin\fR(1M) (for \fBgetprinc\fR command to verify the lifetime values for
the server principal).
.sp
The renewable lifetime of the tickets returned is the minimum of the following:
.RS +4
.TP
.ie t \(bu
.el o
Value specified in the command line.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Value specified in the \fBKDC\fR configuration file.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Value specified in the Kerberos data base for the server principal. In the case
of \fBkinit\fR, it is \fBkrbtgt/\fIrealm name\fR\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Value specified in the Kerberos database for the user principal.
.RE
.RE

.sp
.ne 2
.na
\fB\fB-R\fR\fR
.ad
.RS 24n
Requests renewal of the ticket-granting ticket. Notice that an expired ticket
cannot be renewed, even if the ticket is still within its renewable life.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIstart_time\fR\fR
.ad
.RS 24n
Requests a postdated ticket, valid starting at \fIstart_time\fR. Postdated
tickets are issued with the \fIinvalid\fR flag set, and need to be fed back to
the \fBKDC\fR before use. See the \fBTime\fR \fBFormats\fR section for either
the valid absolute time or time duration formats that you can specify for
\fIstart_time\fR. \fBkinit\fR attempts to match an absolute time first before
trying to match a time duration.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR \fIservice_name\fR\fR
.ad
.RS 24n
Specifies an alternate service name to use when getting initial tickets.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 24n
Requests that the ticket granting ticket in the cache (with the \fIinvalid\fR
flag set) be passed to the \fBKDC\fR for validation. If the ticket is within
its requested time range, the cache is replaced with the validated ticket.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.RS 24n
Verbose output. Displays further information to the user, such as confirmation
of authentication and version.
.RE

.sp
.ne 2
.na
\fB\fB-X\fR \fB\fIattribute\fR[=\fIvalue\fR]\fR\fR
.ad
.RS 24n
Specifies a pre-authentication attribute and value to be passed to
pre-authentication plugins. The acceptable \fIattribute\fR and \fIvalue\fR
values vary from pre-authentication plugin to plugin. This option can be
specified multiple times to specify multiple attributes. If no value is
specified, it is assumed to be \fByes\fR.
.sp
The following attributes are recognized by the OpenSSL \fBpkinit\fR
pre-authentication mechanism:
.sp
.ne 2
.na
\fB\fBX509_user_identity=URI\fR\fR
.ad
.RS 27n
Specifies where to find user's X509 identity information.
.sp
Valid URI types are \fBFILE\fR, \fBDIR\fR, \fBPKCS11\fR, \fBPKCS12\fR, and
\fBENV\fR. See the \fBPKINIT URI Types\fR section for details.
.RE

.sp
.ne 2
.na
\fB\fBX509_anchors=URI\fR\fR
.ad
.RS 27n
Specifies where to find trusted X509 anchor information.
.sp
Valid URI types are \fBFILE\fR and \fBDIR\fR. See the \fBPKINIT URI Types\fR
section for details.
.RE

.sp
.ne 2
.na
\fB\fBflag_RSA_PROTOCOL[=yes]\fR\fR
.ad
.RS 27n
Specifies the use of RSA, rather than the default Diffie-Hellman protocol.
.RE

.RE

.SS "PKINIT URI Types"
.ne 2
.na
\fBFILE:\fIfile-name\fR[,\fIkey-file-name\fR]\fR
.ad
.sp .6
.RS 4n
This option has context-specific behavior.
.sp
.ne 2
.na
\fBX509_user_identity\fR
.ad
.RS 22n
\fIfile-name\fR specifies the name of a PEM-format file containing the user's
certificate. If \fIkey-file-name\fR is not specified, the user's private key is
expected to be in \fIfile-name\fR as well. Otherwise, \fIkey-file-name\fR is
the name of the file containing the private key.
.RE

.sp
.ne 2
.na
\fBX509_anchors\fR
.ad
.RS 22n
\fIfile-name\fR is assumed to be the name of an OpenSSL-style ca-bundle file.
The \fBca-bundle\fR file should be base-64 encoded.
.RE

.RE

.sp
.ne 2
.na
\fBDIR:\fIdirectory-name\fR\fR
.ad
.sp .6
.RS 4n
This option has context-specific behavior.
.sp
.ne 2
.na
\fBX509_user_identity\fR
.ad
.RS 22n
\fIdirectory-name\fR specifies a directory with files named \fB*.crt\fR and
\fB*.key\fR, where the first part of the file name is the same for matching
pairs of certificate and private key files. When a file with a name ending with
\fB\&.crt\fR is found, a matching file ending with \fB\&.key\fR is assumed to
contain the private key. If no such file is found, then the certificate in the
\fB\&.crt\fR is not used.
.RE

.sp
.ne 2
.na
\fBX509_anchors\fR
.ad
.RS 22n
\fIdirectory-name\fR is assumed to be an OpenSSL-style hashed CA directory
where each CA cert is stored in a file named \fBhash-of-ca-cert.\fR\fI#\fR.
This infrastructure is encouraged, but all files in the directory are examined
and if they contain certificates (in PEM format), and are used.
.RE

.RE

.sp
.ne 2
.na
\fBPKCS12:\fIpkcs12-file-name\fR\fR
.ad
.sp .6
.RS 4n
\fIpkcs12-file-nam\fRe is the name of a \fBPKCS #12\fR format file, containing
the user's certificate and private key.
.RE

.sp
.ne 2
.na
\fBPKCS11:[slotid=\fIslot-id\fR][:token=\fItoken-label\fR][:certid=\fIcert-id\fR][:certlabel=\fIcert-label\fR]\fR
.ad
.sp .6
.RS 4n
All keyword and values are optional. PKCS11 modules (for example,
\fBopensc-pkcs11.so\fR) must be installed as a crypto provider
under \fBlibpkcs11\fR(3LIB). \fBslotid=\fR and/or \fBtoken=\fR can be specified
to force the use of a particular smard card reader or token if there is more
than one available. \fBcertid=\fR and/or \fBcertlabel=\fR can be specified to
force the selection of a particular certificate on the device. See the
\fBpkinit_cert_match\fR configuration option for more ways to select a
particular certificate to use for \fBpkinit\fR.
.RE

.sp
.ne 2
.na
\fBENV:\fIenvironment-variable-name\fR\fR
.ad
.sp .6
.RS 4n
\fIenvironment-variable-name\fR specifies the name of an environment variable
which has been set to a value conforming to one of the previous values. For
example, \fBENV:X509_PROXY\fR, where environment variable \fBX509_PROXY\fR has
been set to \fBFILE:/tmp/my_proxy.pem\fR.
.RE

.SS "Time Formats"
The following absolute time formats can be used for the \fB-s\fR
\fIstart_time\fR option. The examples are based on the date and time of July 2,
1999, 1:35:30 p.m.
.sp

.sp
.TS
box;
c c
l l .
Absolute Time Format	Example
\fIyymmddhhmm\fR[\fIss\fR]	990702133530
\fIhhmm\fR[\fIss\fR]	133530
\fIyy\fR.\fImm\fR.\fBdd\fR.\fIhh\fR.\fImm\fR.\fIss\fR	99:07:02:13:35:30
\fIhh\fR:\fImm\fR[:\fIss\fR]	13:35:30
\fIldate\fR:\fIltime\fR	07-07-99:13:35:30
\fBdd\fR-\fImonth\fR-\fIyyyy\fR:\fIhh\fR:\fImm\fR[:\fIss\fR]	02-july-1999:13:35:30
.TE

.sp

.sp
.TS
c c
l l .
Variable	Description
\fBdd\fR	day
\fIhh\fR	hour (24-hour clock)
\fImm\fR	minutes
\fIss\fR	seconds
\fIyy\fR	T{
year within century (0-68 is 2000 to 2068; 69-99 is 1969 to 1999)
T}
\fIyyyy\fR	year including century
\fImonth\fR	locale's full or abbreviated month name
\fIldate\fR	locale's appropriate date representation
\fIltime\fR	locale's appropriate time representation
.TE

.sp
.LP
The following time duration formats can be used for the \fB-l\fR
\fIlifetime\fR, \fB-r\fR \fIrenewable_life\fR, and \fB-s\fR \fIstart_time\fR
options. The examples are based on the time duration of 14 days, 7 hours, 5
minutes, and 30 seconds.
.sp

.sp
.TS
box;
c c
l l .
Time Duration Format	Example
\fI#\fRd	14d
\fI#\fRh	7h
\fI#\fRm	5m
\fI#\fRs	30s
\fI#\fRd\fI#\fRh\fI#\fRm\fI#\fRs	14d7h5m30s
\fI#\fRh\fI#\fRm[\fI#\fRs]	7h5m30s
\fIdays\fR-\fIhh\fR:\fImm\fR:\fIss\fR	14-07:05:30
\fIhours\fR:\fImm\fR[:\fIss\fR]	7:05:30
.TE

.sp

.sp
.TS
c c
l l .
Delimiter	Description
d	number of days
h	number of hours
m	number of minutes
s	number of seconds
.TE

.sp

.sp
.TS
c c
l l .
Variable	Description
\fI#\fR	number
\fIdays\fR	number of days
\fIhours\fR	number of hours
\fIhh\fR	hour (24-hour clock)
\fImm\fR	minutes
\fIss\fR	seconds
.TE

.SH ENVIRONMENT VARIABLES
\fBkinit\fR uses the following environment variable:
.sp
.ne 2
.na
\fB\fBKRB5CCNAME\fR\fR
.ad
.RS 14n
Location of the credentials (ticket) cache. See \fBkrb5envvar\fR(5) for syntax
and details.
.RE

.SH FILES
.ne 2
.na
\fB\fB/tmp/krb5cc_\fIuid\fR\fR\fR
.ad
.RS 25n
Default credentials cache (\fIuid\fR is the decimal \fBUID\fR of the user).
.RE

.sp
.ne 2
.na
\fB\fB/etc/krb5/krb5.keytab\fR\fR
.ad
.RS 25n
Default location for the local host's \fBkeytab\fR file.
.RE

.sp
.ne 2
.na
\fB\fB/etc/krb5/krb5.conf\fR\fR
.ad
.RS 25n
Default location for the local host's configuration file. See
\fBkrb5.conf\fR(4).
.RE

.SH ATTRIBUTES
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below.
.TE

.sp
.LP
The command arguments are Evolving. The command output is Unstable.
.SH SEE ALSO
\fBkdestroy\fR(1), \fBklist\fR(1), \fBkadmin\fR(1M), \fBktkt_warnd\fR(1M),
\fBlibpkcs11\fR(3LIB), \fBkdc.conf\fR(4), \fBkrb5.conf\fR(4),
\fBattributes\fR(5), \fBkerberos\fR(5), \fBkrb5envvar\fR(5), \fBpam_krb5\fR(5)
.SH NOTES
On success, \fBkinit\fR notifies \fBktkt_warnd\fR(1M) to alert the user when
the initial credentials (ticket-granting ticket) are about to expire.