| blob | 98085f126638c09e52ab96007c4a5867209ca5cb |
1 '\" te
2 .\" 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.
3 .\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
4 .\" 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.
5 .\" 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.
6 .\" 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]
7 .TH KINIT 1 "Nov 12, 2008"
8 .SH NAME
9 kinit \- obtain and cache Kerberos ticket-granting ticket
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \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]
14 [\fB-k\fR [\fB-t\fR \fIkeytab_file\fR]] [\fB-l\fR \fIlifetime\fR]
15 [\fB-r\fR \fIrenewable_life\fR] [\fB-s\fR \fIstart_time\fR] [\fB-S\fR \fIservice_name\fR]
16 [\fIprincipal\fR]
17 .fi
19 .SH DESCRIPTION
20 .LP
21 The \fBkinit\fR command is used to obtain and cache an initial ticket-granting
22 ticket (credential) for \fIprincipal\fR. This ticket is used for authentication
23 by the Kerberos system. Only users with Kerberos principals can use the
24 Kerberos system. For information about Kerberos principals, see
25 \fBkerberos\fR(5).
26 .sp
27 .LP
28 When you use \fBkinit\fR without options, the utility prompts for your
29 \fIprincipal\fR and Kerberos password, and tries to authenticate your login
30 with the local Kerberos server. The \fIprincipal\fR can be specified on the
31 command line if desired.
32 .sp
33 .LP
34 If Kerberos authenticates the login attempt, \fBkinit\fR retrieves your initial
35 ticket-granting ticket and puts it in the ticket cache. By default your ticket
36 is stored in the file \fB/tmp/krb5cc_\fIuid\fR\fR, where \fIuid\fR specifies
37 your user identification number. Tickets expire after a specified lifetime,
38 after which \fBkinit\fR must be run again. Any existing contents of the cache
39 are destroyed by \fBkinit\fR.
40 .sp
41 .LP
42 Values specified in the command line override the values specified in the
43 Kerberos configuration file for \fIlifetime\fR and \fIrenewable_life\fR.
44 .sp
45 .LP
46 The \fBkdestroy\fR(1) command can be used to destroy any active tickets before
47 you end your login session.
48 .SH OPTIONS
49 .LP
50 The following options are supported:
51 .sp
52 .ne 2
53 .na
54 \fB\fB-a\fR\fR
55 .ad
56 .RS 24n
57 Requests tickets with the local addresses.
58 .RE
60 .sp
61 .ne 2
62 .na
63 \fB\fB-A\fR\fR
64 .ad
65 .RS 24n
66 Requests address-less tickets.
67 .RE
69 .sp
70 .ne 2
71 .na
72 \fB\fB-c\fR \fIcache_name\fR\fR
73 .ad
74 .RS 24n
75 Uses \fIcache_name\fR as the credentials (ticket) cache name and location. If
76 this option is not used, the default cache name and location are used.
77 .RE
79 .sp
80 .ne 2
81 .na
82 \fB\fB-f\fR\fR
83 .ad
84 .RS 24n
85 Requests forwardable tickets.
86 .RE
88 .sp
89 .ne 2
90 .na
91 \fB\fB-F\fR\fR
92 .ad
93 .RS 24n
94 Not forwardable. Does not request forwardable tickets.
95 .sp
96 Tickets that have been acquired on one host cannot normally be used on another
97 host. A client can request that the ticket be marked forwardable. Once the
98 \fBTKT_FLG_FORWARDABLE\fR flag is set on a ticket, the user can use this ticket
99 to request a new ticket, but with a different \fBIP\fR address. Thus, users can
100 use their current credentials to get credentials valid on another machine. This
101 option allows a user to explicitly obtain a non-forwardable ticket.
102 .RE
104 .sp
105 .ne 2
106 .na
107 \fB\fB-k\fR [\fB-t\fR \fIkeytab_file\fR]\fR
108 .ad
109 .RS 24n
110 Requests a host ticket, obtained from a key in the local host's \fIkeytab\fR
111 file. The name and location of the keytab file can be specified with the
112 \fB-t\fR \fIkeytab_file\fR option. Otherwise, the default name and location is
113 used.
114 .RE
116 .sp
117 .ne 2
118 .na
119 \fB\fB-l\fR \fIlifetime\fR\fR
120 .ad
121 .RS 24n
122 Requests a ticket with the lifetime \fIlifetime\fR. If the \fB-l\fR option is
123 not specified, the default ticket lifetime (configured by each site) is used.
124 Specifying a ticket lifetime longer than the maximum ticket lifetime
125 (configured by each site) results in a ticket with the maximum lifetime. See
126 the \fBTime\fR \fBFormats\fR section for the valid time duration formats that
127 you can specify for \fIlifetime\fR. See \fBkdc.conf\fR(4) and \fBkadmin\fR(1M)
128 (for \fBgetprinc\fR command to verify the lifetime values for the server
129 principal).
130 .sp
131 The lifetime of the tickets returned is the minimum of the following:
132 .RS +4
133 .TP
134 .ie t \(bu
135 .el o
136 Value specified in the command line.
137 .RE
138 .RS +4
139 .TP
140 .ie t \(bu
141 .el o
142 Value specified in the \fBKDC\fR configuration file.
143 .RE
144 .RS +4
145 .TP
146 .ie t \(bu
147 .el o
148 Value specified in the Kerberos data base for the server principal. In the case
149 of \fBkinit\fR, it is \fBkrbtgt/\fIrealm name\fR\fR.
150 .RE
151 .RS +4
152 .TP
153 .ie t \(bu
154 .el o
155 Value specified in the Kerberos database for the user principal.
156 .RE
157 .RE
159 .sp
160 .ne 2
161 .na
162 \fB\fB-p\fR\fR
163 .ad
164 .RS 24n
165 Requests proxiable tickets.
166 .RE
168 .sp
169 .ne 2
170 .na
171 \fB\fB-P\fR\fR
172 .ad
173 .RS 24n
174 Not proxiable. Does not request proxiable tickets.
175 .sp
176 A proxiable ticket is a ticket that allows you to get a ticket for a service
177 with \fBIP\fR addresses other than the ones in the Ticket Granting Ticket. This
178 option allows a user to explicitly obtain a non-proxiable ticket.
179 .RE
181 .sp
182 .ne 2
183 .na
184 \fB\fB-r\fR \fIrenewable_life\fR\fR
185 .ad
186 .RS 24n
187 Requests renewable tickets, with a total lifetime of \fIrenewable_life\fR. See
188 the \fBTime\fR \fBFormats\fR section for the valid time duration formats that
189 you can specify for \fIrenewable_life\fR. See \fBkdc.conf\fR(4) and
190 \fBkadmin\fR(1M) (for \fBgetprinc\fR command to verify the lifetime values for
191 the server principal).
192 .sp
193 The renewable lifetime of the tickets returned is the minimum of the following:
194 .RS +4
195 .TP
196 .ie t \(bu
197 .el o
198 Value specified in the command line.
199 .RE
200 .RS +4
201 .TP
202 .ie t \(bu
203 .el o
204 Value specified in the \fBKDC\fR configuration file.
205 .RE
206 .RS +4
207 .TP
208 .ie t \(bu
209 .el o
210 Value specified in the Kerberos data base for the server principal. In the case
211 of \fBkinit\fR, it is \fBkrbtgt/\fIrealm name\fR\fR.
212 .RE
213 .RS +4
214 .TP
215 .ie t \(bu
216 .el o
217 Value specified in the Kerberos database for the user principal.
218 .RE
219 .RE
221 .sp
222 .ne 2
223 .na
224 \fB\fB-R\fR\fR
225 .ad
226 .RS 24n
227 Requests renewal of the ticket-granting ticket. Notice that an expired ticket
228 cannot be renewed, even if the ticket is still within its renewable life.
229 .RE
231 .sp
232 .ne 2
233 .na
234 \fB\fB-s\fR \fIstart_time\fR\fR
235 .ad
236 .RS 24n
237 Requests a postdated ticket, valid starting at \fIstart_time\fR. Postdated
238 tickets are issued with the \fIinvalid\fR flag set, and need to be fed back to
239 the \fBKDC\fR before use. See the \fBTime\fR \fBFormats\fR section for either
240 the valid absolute time or time duration formats that you can specify for
241 \fIstart_time\fR. \fBkinit\fR attempts to match an absolute time first before
242 trying to match a time duration.
243 .RE
245 .sp
246 .ne 2
247 .na
248 \fB\fB-S\fR \fIservice_name\fR\fR
249 .ad
250 .RS 24n
251 Specifies an alternate service name to use when getting initial tickets.
252 .RE
254 .sp
255 .ne 2
256 .na
257 \fB\fB-v\fR\fR
258 .ad
259 .RS 24n
260 Requests that the ticket granting ticket in the cache (with the \fIinvalid\fR
261 flag set) be passed to the \fBKDC\fR for validation. If the ticket is within
262 its requested time range, the cache is replaced with the validated ticket.
263 .RE
265 .sp
266 .ne 2
267 .na
268 \fB\fB-V\fR\fR
269 .ad
270 .RS 24n
271 Verbose output. Displays further information to the user, such as confirmation
272 of authentication and version.
273 .RE
275 .sp
276 .ne 2
277 .na
278 \fB\fB-X\fR \fB\fIattribute\fR[=\fIvalue\fR]\fR\fR
279 .ad
280 .RS 24n
281 Specifies a pre-authentication attribute and value to be passed to
282 pre-authentication plugins. The acceptable \fIattribute\fR and \fIvalue\fR
283 values vary from pre-authentication plugin to plugin. This option can be
284 specified multiple times to specify multiple attributes. If no value is
285 specified, it is assumed to be \fByes\fR.
286 .sp
287 The following attributes are recognized by the OpenSSL \fBpkinit\fR
288 pre-authentication mechanism:
289 .sp
290 .ne 2
291 .na
292 \fB\fBX509_user_identity=URI\fR\fR
293 .ad
294 .RS 27n
295 Specifies where to find user's X509 identity information.
296 .sp
297 Valid URI types are \fBFILE\fR, \fBDIR\fR, \fBPKCS11\fR, \fBPKCS12\fR, and
298 \fBENV\fR. See the \fBPKINIT URI Types\fR section for details.
299 .RE
301 .sp
302 .ne 2
303 .na
304 \fB\fBX509_anchors=URI\fR\fR
305 .ad
306 .RS 27n
307 Specifies where to find trusted X509 anchor information.
308 .sp
309 Valid URI types are \fBFILE\fR and \fBDIR\fR. See the\fBPKINIT URI Types\fR
310 section for details.
311 .RE
313 .sp
314 .ne 2
315 .na
316 \fB\fBflag_RSA_PROTOCOL[=yes]\fR\fR
317 .ad
318 .RS 27n
319 Specifies the use of RSA, rather than the default Diffie-Hellman protocol.
320 .RE
322 .RE
324 .SS "PKINIT URI Types"
325 .ne 2
326 .na
327 \fBFILE:\fIfile-name\fR[,\fIkey-file-name\fR]\fR
328 .ad
329 .sp .6
330 .RS 4n
331 This option has context-specific behavior.
332 .sp
333 .ne 2
334 .na
335 \fBX509_user_identity\fR
336 .ad
337 .RS 22n
338 \fIfile-name\fR specifies the name of a PEM-format file containing the user's
339 certificate. If \fIkey-file-name\fR is not specified, the user's private key is
340 expected to be in \fIfile-name\fR as well. Otherwise, \fIkey-file-name\fR is
341 the name of the file containing the private key.
342 .RE
344 .sp
345 .ne 2
346 .na
347 \fBX509_anchors\fR
348 .ad
349 .RS 22n
350 \fIfile-name\fR is assumed to be the name of an OpenSSL-style ca-bundle file.
351 The \fBca-bundle\fR file should be base-64 encoded.
352 .RE
354 .RE
356 .sp
357 .ne 2
358 .na
359 \fBDIR:\fIdirectory-name\fR\fR
360 .ad
361 .sp .6
362 .RS 4n
363 This option has context-specific behavior.
364 .sp
365 .ne 2
366 .na
367 \fBX509_user_identity\fR
368 .ad
369 .RS 22n
370 \fIdirectory-name\fR specifies a directory with files named \fB*.crt\fR and
371 \fB*.key\fR, where the first part of the file name is the same for matching
372 pairs of certificate and private key files. When a file with a name ending with
373 \fB\&.crt\fR is found, a matching file ending with \fB\&.key\fR is assumed to
374 contain the private key. If no such file is found, then the certificate in the
375 \fB\&.crt\fR is not used.
376 .RE
378 .sp
379 .ne 2
380 .na
381 \fBX509_anchors\fR
382 .ad
383 .RS 22n
384 \fIdirectory-name\fR is assumed to be an OpenSSL-style hashed CA directory
385 where each CA cert is stored in a file named \fBhash-of-ca-cert.\fR\fI#\fR.
386 This infrastructure is encouraged, but all files in the directory are examined
387 and if they contain certificates (in PEM format), and are used.
388 .RE
390 .RE
392 .sp
393 .ne 2
394 .na
395 \fBPKCS12:\fIpkcs12-file-name\fR\fR
396 .ad
397 .sp .6
398 .RS 4n
399 \fIpkcs12-file-nam\fRe is the name of a \fBPKCS #12\fR format file, containing
400 the user's certificate and private key.
401 .RE
403 .sp
404 .ne 2
405 .na
406 \fBPKCS11:[slotid=\fIslot-id\fR][:token=\fItoken-label\fR][:certid=\fIcert-id\fR][:certlabel=\fIcert-label\fR]\fR
407 .ad
408 .sp .6
409 .RS 4n
410 All keyword and values are optional. PKCS11 modules (for example,
411 \fBopensc-pkcs11.so\fR) must be installed as a crypto provider
412 under\fBlibpkcs11\fR(3LIB). \fBslotid=\fR and/or \fBtoken=\fR can be specified
413 to force the use of a particular smard card reader or token if there is more
414 than one available. \fBcertid=\fR and/or \fBcertlabel=\fR can be specified to
415 force the selection of a particular certificate on the device. See the
416 \fBpkinit_cert_match\fR configuration option for more ways to select a
417 particular certificate to use for \fBpkinit\fR.
418 .RE
420 .sp
421 .ne 2
422 .na
423 \fBENV:\fIenvironment-variable-name\fR\fR
424 .ad
425 .sp .6
426 .RS 4n
427 \fIenvironment-variable-name\fR specifies the name of an environment variable
428 which has been set to a value conforming to one of the previous values. For
429 example, \fBENV:X509_PROXY\fR, where environment variable \fBX509_PROXY\fR has
430 been set to \fBFILE:/tmp/my_proxy.pem\fR.
431 .RE
433 .SS "Time Formats"
434 .LP
435 The following absolute time formats can be used for the \fB-s\fR
436 \fIstart_time\fR option. The examples are based on the date and time of July 2,
437 1999, 1:35:30 p.m.
438 .sp
440 .sp
441 .TS
442 box;
443 c c
444 l l .
445 Absolute Time Format Example
446 \fIyymmddhhmm\fR[\fIss\fR] 990702133530
447 \fIhhmm\fR[\fIss\fR] 133530
448 \fIyy\fR.\fImm\fR.\fBdd\fR.\fIhh\fR.\fImm\fR.\fIss\fR 99:07:02:13:35:30
449 \fIhh\fR:\fImm\fR[:\fIss\fR] 13:35:30
450 \fIldate\fR:\fIltime\fR 07-07-99:13:35:30
451 \fBdd\fR-\fImonth\fR-\fIyyyy\fR:\fIhh\fR:\fImm\fR[:\fIss\fR] 02-july-1999:13:35:30
452 .TE
454 .sp
456 .sp
457 .TS
458 c c
459 l l .
460 Variable Description
461 \fBdd\fR day
462 \fIhh\fR hour (24-hour clock)
463 \fImm\fR minutes
464 \fIss\fR seconds
465 \fIyy\fR T{
466 year within century (0-68 is 2000 to 2068; 69-99 is 1969 to 1999)
467 T}
468 \fIyyyy\fR year including century
469 \fImonth\fR locale's full or abbreviated month name
470 \fIldate\fR locale's appropriate date representation
471 \fIltime\fR locale's appropriate time representation
472 .TE
474 .sp
475 .LP
476 The following time duration formats can be used for the \fB-l\fR
477 \fIlifetime\fR, \fB-r\fR \fIrenewable_life\fR, and \fB-s\fR \fIstart_time\fR
478 options. The examples are based on the time duration of 14 days, 7 hours, 5
479 minutes, and 30 seconds.
480 .sp
482 .sp
483 .TS
484 box;
485 c c
486 l l .
487 Time Duration Format Example
488 \fI#\fRd 14d
489 \fI#\fRh 7h
490 \fI#\fRm 5m
491 \fI#\fRs 30s
492 \fI#\fRd\fI#\fRh\fI#\fRm\fI#\fRs 14d7h5m30s
493 \fI#\fRh\fI#\fRm[\fI#\fRs] 7h5m30s
494 \fIdays\fR-\fIhh\fR:\fImm\fR:\fIss\fR 14-07:05:30
495 \fIhours\fR:\fImm\fR[:\fIss\fR] 7:05:30
496 .TE
498 .sp
500 .sp
501 .TS
502 c c
503 l l .
504 Delimiter Description
505 d number of days
506 h number of hours
507 m number of minutes
508 s number of seconds
509 .TE
511 .sp
513 .sp
514 .TS
515 c c
516 l l .
517 Variable Description
518 \fI#\fR number
519 \fIdays\fR number of days
520 \fIhours\fR number of hours
521 \fIhh\fR hour (24-hour clock)
522 \fImm\fR minutes
523 \fIss\fR seconds
524 .TE
526 .SH ENVIRONMENT VARIABLES
527 .LP
528 \fBkinit\fR uses the following environment variable:
529 .sp
530 .ne 2
531 .na
532 \fB\fBKRB5CCNAME\fR\fR
533 .ad
534 .RS 14n
535 Location of the credentials (ticket) cache. See \fBkrb5envvar\fR(5) for syntax
536 and details.
537 .RE
539 .SH FILES
540 .ne 2
541 .na
542 \fB\fB/tmp/krb5cc_\fIuid\fR\fR\fR
543 .ad
544 .RS 25n
545 Default credentials cache (\fIuid\fR is the decimal \fBUID\fR of the user).
546 .RE
548 .sp
549 .ne 2
550 .na
551 \fB\fB/etc/krb5/krb5.keytab\fR\fR
552 .ad
553 .RS 25n
554 Default location for the local host's \fBkeytab\fR file.
555 .RE
557 .sp
558 .ne 2
559 .na
560 \fB\fB/etc/krb5/krb5.conf\fR\fR
561 .ad
562 .RS 25n
563 Default location for the local host's configuration file. See
564 \fBkrb5.conf\fR(4).
565 .RE
567 .SH ATTRIBUTES
568 .LP
569 See \fBattributes\fR(5) for descriptions of the following attributes:
570 .sp
572 .sp
573 .TS
574 box;
575 c | c
576 l | l .
577 ATTRIBUTE TYPE ATTRIBUTE VALUE
578 _
579 Interface Stability See below.
580 .TE
582 .sp
583 .LP
584 The command arguments are Evolving. The command output is Unstable.
585 .SH SEE ALSO
586 .LP
587 \fBkdestroy\fR(1), \fBklist\fR(1), \fBkadmin\fR(1M), \fBktkt_warnd\fR(1M),
588 \fBlibpkcs11\fR(3LIB), \fBkdc.conf\fR(4), \fBkrb5.conf\fR(4),
589 \fBattributes\fR(5), \fBkerberos\fR(5), \fBkrb5envvar\fR(5), \fBpam_krb5\fR(5)
590 .SH NOTES
591 .LP
592 On success, \fBkinit\fR notifies \fBktkt_warnd\fR(1M) to alert the user when
593 the initial credentials (ticket-granting ticket) are about to expire.