doc/xml/AdminReference/sect8/kas_setpassword.xml

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