pod-updates-20060227
[openafs.git] / doc / man-pages / pod8 / kas_setpassword.pod
1 =head1 NAME
2
3 kas setpassword - Changes the key field in an Authentication Database entry
4
5 =head1 SYNOPSIS
6
7 B<kas setpassword> B<-name> <I<name of user>>
8     [B<-new_password> <I<new password>>] [B<-kvno> <I<key version number>>]
9     [B<-admin_username> <I<admin principal to use for authentication>>]
10     [B<-password_for_admin> <I<admin password>>] [B<-cell> <I<cell name>>]
11     [B<-servers> <I<explicit list of authentication servers>>+]
12     [B<-noauth>] [B<-help>]
13
14 B<kas setpasswd> B<-na> <I<name of user>> [B<-ne> <I<new password>>]
15     [B<-k> <I<key version number>>]
16     [B<-a> <I<admin principal to use for authentication>>]
17     [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
18     [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
19
20 B<kas setp> B<-na> <I<name of user>> [B<-ne> <I<new password>>]
21     [B<-k> <I<key version number>>]
22     [B<-a> <I<admin principal to use for authentication>>]
23     [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
24     [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
25
26 B<kas sp> B<-na> <I<name of user>> [B<-ne> <I<new password>>]
27     [B<-k> <I<key version number>>]
28     [B<-a> <I<admin principal to use for authentication>>]
29     [B<-p> <I<admin password>>] [B<-c> <I<cell name>>]
30     [B<-s> <I<explicit list of authentication servers>>+] [B<-no>] [B<-h>]
31
32 =head1 DESCRIPTION
33
34 The B<kas setpassword> command accepts a character string of unlimited
35 length, scrambles it into a form suitable for use as an encryption key,
36 places it in the key field of the Authentication Database entry named by
37 the B<-name> argument, and assigns it the key version number specified by
38 the B<-kvno> argument.
39
40 To avoid making the password string visible at the shell prompt, omit the
41 B<-new_password> argument. Prompts then appear at the shell which do not
42 echo the password visibly.
43
44 When changing the B<afs> server key, also issue B<bos addkey> command to
45 add the key (with the same key version number) to the
46 F</usr/afs/etc/KeyFile> file. See the I<IBM AFS Administration Guide> for
47 instructions.
48
49 The command interpreter checks the password string subject to the
50 following conditions:
51
52 =over 4
53
54 =item *
55
56 If there is a program called kpwvalid in the same directory as the B<kas>
57 binary, the command interpreter invokes it to process the password. For
58 details, see L<kpwvalid(8)>.
59
60 =item *
61
62 If the B<-reuse> argument to the B<kas setfields> command has been used to
63 prohibit reuse of previous passwords, the command interpreter verifies
64 that the password is not too similar too any of the user's previous 20
65 passwords. It generates the following error message at the shell:
66
67    Password was not changed because it seems like a reused password
68
69 To prevent a user from subverting this restriction by changing the
70 password twenty times in quick succession (manually or by running a
71 script), use the B<-minhours> argument on the B<kaserver> initialization
72 command. The following error message appears if a user attempts to change
73 a password before the minimum time has passed:
74
75    Password was not changed because you changed it too
76    recently; see your systems administrator
77
78 =back
79
80 =head1 OPTIONS
81
82 =over 4
83
84 =item B<-name> <I<name of user>>
85
86 Names the entry in which to record the new key.
87
88 =item B<-new_password> <I<new password>>
89
90 Specifies the character string the user types when authenticating to
91 AFS. Omit this argument and type the string at the resulting prompts so
92 that the password does not echo visibly. Note that some non-AFS programs
93 cannot handle passwords longer than eight characters.
94
95 =item B<-kvno> <I<key version number>>
96
97 Specifies the key version number associated with the new key.  Provide an
98 integer in the range from C<0> through C<255>. If omitted, the default is
99 C<0> (zero), which is probably not desirable for server keys.
100
101 =item B<-admin_username> <I<admin principal>>
102
103 Specifies the user identity under which to authenticate with the
104 Authentication Server for execution of the command. For more details, see
105 L<kas(8)>.
106
107 =item B<-password_for_admin> <I<admin password>>
108
109 Specifies the password of the command's issuer. If it is omitted (as
110 recommended), the B<kas> command interpreter prompts for it and does not
111 echo it visibly. For more details, see L<kas(8)>.
112
113 =item B<-cell> <I<cell name>>
114
115 Names the cell in which to run the command. For more details, see
116 L<kas(8)>.
117
118 =item B<-servers> <I<authentication servers>>+
119
120 Names each machine running an Authentication Server with which to
121 establish a connection. For more details, see L<kas(8)>.
122
123 =item B<-noauth>
124
125 Assigns the unprivileged identity C<anonymous> to the issuer. For more
126 details, see L<kas(8)>.
127
128 =item B<-help>
129
130 Prints the online help for this command. All other valid options are
131 ignored.
132
133 =back
134
135 =head1 EXAMPLES
136
137 In the following example, an administrator using the C<admin> account
138 changes the password for C<pat> (presumably because C<pat> forgot the
139 former password or got locked out of his account in some other way).
140
141    % kas setpassword pat
142    Password for admin:
143    new_password:
144    Verifying, please re-enter new_password:
145
146 =head1 PRIVILEGE REQUIRED
147
148 Individual users can change their own passwords. To change another user's
149 password or the password (server encryption key) for server entries such
150 as C<afs>, the issuer must have the C<ADMIN> flag set in his or her
151 Authentication Database entry.
152
153 =head1 SEE ALSO
154
155 L<bos_addkey(8)>,
156 L<kas(8)>,
157 L<kaserver(8)>,
158 L<kpwvalid(8)>
159
160 =head1 COPYRIGHT
161
162 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
163
164 This documentation is covered by the IBM Public License Version 1.0.  It was
165 converted from HTML to POD by software written by Chas Williams and Russ
166 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.