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