doc/man-pages/pod8/kas_examine.pod

   1 =head1 NAME
   2
   3 kas_examine - Displays information from an Authentication Database entry
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<kas examine> S<<< B<-name> <I<name of user>> >>> [B<-showkey>]
  11     S<<< [B<-admin_username> <I<admin principal to use for authentication>>] >>>
  12     S<<< [B<-password_for_admin> <I<admin password>>] >>> S<<< [B<-cell> <I<cell name>>] >>>
  13     S<<< [B<-servers> <I<explicit list of authentication servers>>+] >>>
  14     [B<-noauth>] [B<-help>]
  15
  16 B<kas e> S<<< B<-na> <I<name of user>> >>> [B<-sh>]
  17     S<<< [B<-a> <I<admin principal to use for authentication>>] >>>
  18     S<<< [B<-p> <I<admin password>>] >>> S<<< [B<-c> <I<cell name>>] >>>
  19     S<<< [B<-se> <I<explicit list of authentication servers>>+] >>> [B<-no>] [B<-h>]
  20
  21 =for html
  22 </div>
  23
  24 =head1 DESCRIPTION
  25
  26 The B<kas examine> command formats and displays information from the
  27 Authentication Database entry of the user named by the B<-name> argument.
  28
  29 To alter the settings displayed with this command, issue the B<kas
  30 setfields> command.
  31
  32 =head1 CAUTIONS
  33
  34 Displaying actual keys on the standard output stream by including the
  35 B<-showkey> flag constitutes a security exposure. For most purposes, it is
  36 sufficient to display a checksum.
  37
  38 =head1 OPTIONS
  39
  40 =over 4
  41
  42 =item B<-name> <I<name of user>>
  43
  44 Names the Authentication Database entry from which to display information.
  45
  46 =item B<-showkey>
  47
  48 Displays the octal digits that constitute the key. The issuer must have
  49 the C<ADMIN> flag on his or her Authentication Database entry.
  50
  51 =item B<-admin_username> <I<admin principal>>
  52
  53 Specifies the user identity under which to authenticate with the
  54 Authentication Server for execution of the command. For more details, see
  55 L<kas(8)>.
  56
  57 =item B<-password_for_admin> <I<admin password>>
  58
  59 Specifies the password of the command's issuer. If it is omitted (as
  60 recommended), the B<kas> command interpreter prompts for it and does not
  61 echo it visibly. For more details, see L<kas(8)>.
  62
  63 =item B<-cell> <I<cell name>>
  64
  65 Names the cell in which to run the command. For more details, see
  66 L<kas(8)>.
  67
  68 =item B<-servers> <I<authentication servers>>+
  69
  70 Names each machine running an Authentication Server with which to
  71 establish a connection. For more details, see L<kas(8)>.
  72
  73 =item B<-noauth>
  74
  75 Assigns the unprivileged identity C<anonymous> to the issuer. For more
  76 details, see L<kas(8)>.
  77
  78 =item B<-help>
  79
  80 Prints the online help for this command. All other valid options are
  81 ignored.
  82
  83 =back
  84
  85 =head1 OUTPUT
  86
  87 The output includes:
  88
  89 =over 4
  90
  91 =item *
  92
  93 The entry name, following the string C<User data for>.
  94
  95 =item *
  96
  97 One or more status flags in parentheses; they appear only if an
  98 administrator has used the B<kas setfields> command to change them from
  99 their default values. A plus sign (C<+>) separates the flags if there is
 100 more than one. The nondefault values that can appear, and their meanings,
 101 are as follows:
 102
 103 =over 4
 104
 105 =item ADMIN
 106
 107 Enables the user to issue privileged B<kas> commands (default is
 108 C<NOADMIN>).
 109
 110 =item NOTGS
 111
 112 Prevents the user from obtaining tickets from the Authentication Server's
 113 Ticket Granting Service (default is C<TGS>).
 114
 115 =item NOSEAL
 116
 117 Prevents the Ticket Granting Service from using the entry's key field as
 118 an encryption key (default is C<SEAL>).
 119
 120 =item NOCPW
 121
 122 Prevents the user from changing his or her password (default is C<CPW>).
 123
 124 =back
 125
 126 =item *
 127
 128 The key version number, in parentheses, following the word C<key>, then
 129 one of the following.
 130
 131 =over 4
 132
 133 =item *
 134
 135 A checksum equivalent of the key, following the string C<cksum is>, if the
 136 B<-showkey> flag is not included. The checksum is a decimal number derived
 137 by encrypting a constant with the key. In the case of the C<afs> entry,
 138 this number must match the checksum with the corresponding key version
 139 number in the output of the B<bos listkeys> command; if not, follow the
 140 instructions in the I<OpenAFS Administration Guide> for creating a new
 141 server encryption key.
 142
 143 =item *
 144
 145 The actual key, following a colon, if the B<-showkey> flag is
 146 included. The key consists of eight octal numbers, each represented as a
 147 backslash followed by three decimal digits.
 148
 149 =back
 150
 151 =item *
 152
 153 The date the user last changed his or her own password, following the
 154 string C<last cpw> (which stands for "last change of password").
 155
 156 =item *
 157
 158 The string C<password will never expire> indicates that the associated
 159 password never expires; the string C<password will expire> is followed by
 160 the password's expiration date. After the indicated date, the user cannot
 161 authenticate, but has 30 days after it in which to use the B<kpasswd> or
 162 B<kas setpassword> command to set a new password. After 30 days, only an
 163 administrator (one whose account is marked with the C<ADMIN> flag) can
 164 change the password by using the B<kas setpassword> command. To set the
 165 password expiration date, use the B<kas setfields> command's B<-pwexpires>
 166 argument.
 167
 168 =item *
 169
 170 The number of times the user can fail to provide the correct password
 171 before the account locks, followed by the string C<consecutive
 172 unsuccessful authentications are permitted>, or the string C<An unlimited
 173 number of unsuccessful authentications is permitted> to indicate that
 174 there is no limit. To set the limit, use the B<kas setfields> command's
 175 B<-attempts> argument. To unlock a locked account, use the B<kas unlock>
 176 command. The B<kas setfields> reference page discusses how the
 177 implementation of the lockout feature interacts with this setting.
 178
 179 =item *
 180
 181 The number of minutes for which the Authentication Server refuses the
 182 user's login attempts after the limit on consecutive unsuccessful
 183 authentication attempts is exceeded, following the string C<The lock time
 184 for this user is>. Use the B<kas> command's B<-locktime> argument to set
 185 the lockout time. This line appears only if a limit on the number of
 186 unsuccessful authentication attempts has been set with the the B<kas
 187 setfields> command's B<-attempts> argument.
 188
 189 =item *
 190
 191 An indication of whether the Authentication Server is currently refusing
 192 the user's login attempts. The string C<User is not locked> indicates that
 193 authentication can succeed, whereas the string C<User is locked until>
 194 I<time> indicates that the user cannot authenticate until the indicated
 195 time. Use the B<kas unlock> command to enable a user to attempt
 196 authentication. This line appears only if a limit on the number of
 197 unsuccessful authentication attempts has been set with the B<kas
 198 setfields> command's B<-attempts> argument.
 199
 200 =item *
 201
 202 The date on which the Authentication Server entry expires, or the string
 203 C<entry never expires> to indicate that the entry does not expire. A user
 204 becomes unable to authenticate when his or her entry expires. Use the
 205 B<kas setfields> command's B<-expiration> argument to set the expiration
 206 date.
 207
 208 =item *
 209
 210 The maximum possible lifetime of the tokens that the Authentication Server
 211 grants the user. This value interacts with several others to determine the
 212 actual lifetime of the token, as described in L<klog(1)>.  Use the B<kas
 213 setfields> command's B<-lifetime> argument to set this value.
 214
 215 =item *
 216
 217 The date on which the entry was last modified, following the string C<last
 218 mod on> and the user name of the administrator who modified it. The date
 219 on which a user changed his or her own password is recorded on the second
 220 line of output as C<last cpw> instead.
 221
 222 =item *
 223
 224 An indication of whether the user can reuse one of his or her last twenty
 225 passwords when issuing the B<kpasswd>, B<kas setpassword>, or B<kas
 226 setkey> commands. Use the B<kas setfields> command's B<-reuse> argument to
 227 set this restriction.
 228
 229 =back
 230
 231 =head1 EXAMPLES
 232
 233 The following example command shows the user smith displaying her own
 234 Authentication Database entry. Note the C<ADMIN> flag, which shows that
 235 C<smith> is privileged.
 236
 237    % kas examine smith
 238    Password for smith:
 239    User data for smith (ADMIN)
 240     key (0) cksum is 3414844392,  last cpw: Thu Mar 25 16:05:44 1999
 241     password will expire:  Fri Apr 30 20:44:36 1999
 242     5 consecutive unsuccessful authentications are permitted.
 243     The lock time for this user is 25.5 minutes.
 244     User is not locked.
 245     entry never expires. Max ticket lifetime 100.00 hours.
 246     last mod on Tue Jan 5 08:22:29 1999 by admin
 247     permit password reuse
 248
 249 In the following example, the user C<pat> examines his Authentication
 250 Database entry to determine when the account lockout currently in effect
 251 will end.
 252
 253    % kas examine pat
 254    Password for pat:
 255    User data for pat
 256     key (0) cksum is 73829292912,  last cpw: Wed Apr 7 11:23:01 1999
 257     password will expire:  Fri  Jun 11 11:23:01 1999
 258     5 consecutive unsuccessful authentications are permitted.
 259     The lock time for this user is 25.5 minutes.
 260     User is locked until Tue Sep 21 12:25:07 1999
 261     entry expires on never. Max ticket lifetime 100.00 hours.
 262     last mod on Thu Feb 4 08:22:29 1999 by admin
 263     permit password reuse
 264
 265 In the following example, an administrator logged in as C<admin> uses the
 266 B<-showkey> flag to display the octal digits that constitute the key in
 267 the C<afs> entry.
 268
 269    % kas examine -name afs -showkey
 270    Password for admin: I<admin_password>
 271    User data for afs
 272     key (12): \357\253\304\352\234\236\253\352, last cpw: no date
 273     entry never expires. Max ticket lifetime 100.00 hours.
 274     last mod on Thu Mar 25 14:53:29 1999 by admin
 275     permit password reuse
 276
 277 =head1 PRIVILEGE REQUIRED
 278
 279 A user can examine his or her own entry. To examine others' entries or to
 280 include the B<-showkey> flag, the issuer must have the C<ADMIN> flag set
 281 in his or her Authentication Database entry.
 282
 283 =head1 SEE ALSO
 284
 285 L<bos_addkey(8)>,
 286 L<bos_listkeys(8)>,
 287 L<bos_setauth(8)>,
 288 L<kas(8)>,
 289 L<kas_setfields(8)>,
 290 L<kas_setpassword(8)>,
 291 L<kas_unlock(8)>,
 292 L<klog(1)>,
 293 L<kpasswd(1)>
 294
 295 =head1 COPYRIGHT
 296
 297 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 298
 299 This documentation is covered by the IBM Public License Version 1.0.  It was
 300 converted from HTML to POD by software written by Chas Williams and Russ
 301 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.