openafs/doc/xml/AdminReference/sect8/kas_setpassword.xml

<?xml version="1.0" encoding="UTF-8"?>
<refentry id="kas_setpassword8">
  <refmeta>
    <refentrytitle>kas setpassword</refentrytitle>
    <manvolnum>8</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>kas setpassword</refname>
    <refpurpose>Changes the key field in an Authentication Database entry</refpurpose>
  </refnamediv>
  <refsect1>
    <title>Synopsis</title>
    <para><emphasis role="bold">kas setpassword</emphasis> <emphasis role="bold">-name</emphasis> &lt;<emphasis>name of user</emphasis>&gt;
        [<emphasis role="bold">-new_password</emphasis> &lt;<emphasis>new password</emphasis>&gt;] [<emphasis role="bold">-kvno</emphasis> &lt;<emphasis>key version number</emphasis>&gt;]
        [<emphasis role="bold">-admin_username</emphasis> &lt;<emphasis>admin principal to use for authentication</emphasis>&gt;]
        [<emphasis role="bold">-password_for_admin</emphasis> &lt;<emphasis>admin password</emphasis>&gt;] [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
        [<emphasis role="bold">-servers</emphasis> &lt;<emphasis>explicit list of authentication servers</emphasis>&gt;+]
        [<emphasis role="bold">-noauth</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>

    <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;]
        [<emphasis role="bold">-k</emphasis> &lt;<emphasis>key version number</emphasis>&gt;]
        [<emphasis role="bold">-a</emphasis> &lt;<emphasis>admin principal to use for authentication</emphasis>&gt;]
        [<emphasis role="bold">-p</emphasis> &lt;<emphasis>admin password</emphasis>&gt;] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
        [<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>

    <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;]
        [<emphasis role="bold">-k</emphasis> &lt;<emphasis>key version number</emphasis>&gt;]
        [<emphasis role="bold">-a</emphasis> &lt;<emphasis>admin principal to use for authentication</emphasis>&gt;]
        [<emphasis role="bold">-p</emphasis> &lt;<emphasis>admin password</emphasis>&gt;] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
        [<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>

    <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;]
        [<emphasis role="bold">-k</emphasis> &lt;<emphasis>key version number</emphasis>&gt;]
        [<emphasis role="bold">-a</emphasis> &lt;<emphasis>admin principal to use for authentication</emphasis>&gt;]
        [<emphasis role="bold">-p</emphasis> &lt;<emphasis>admin password</emphasis>&gt;] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
        [<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>

  </refsect1>
  <refsect1>
    <title>Description</title>
    <para>The <emphasis role="bold">kas setpassword</emphasis> command accepts a character string of unlimited
    length, scrambles it into a form suitable for use as an encryption key,
    places it in the key field of the Authentication Database entry named by
    the <emphasis role="bold">-name</emphasis> argument, and assigns it the key version number specified by
    the <emphasis role="bold">-kvno</emphasis> argument.</para>

    <para>To avoid making the password string visible at the shell prompt, omit the
    <emphasis role="bold">-new_password</emphasis> argument. Prompts then appear at the shell which do not
    echo the password visibly.</para>

    <para>When changing the <emphasis role="bold">afs</emphasis> server key, also issue <emphasis role="bold">bos addkey</emphasis> command to
    add the key (with the same key version number) to the
    <replaceable>/usr/afs/etc/KeyFile</replaceable> file. See the <emphasis>IBM AFS Administration Guide</emphasis> for
    instructions.</para>

    <para>The command interpreter checks the password string subject to the
    following conditions:</para>

    <itemizedlist>
      <listitem>
        <para>If there is a program called kpwvalid in the same directory as the <emphasis role="bold">kas</emphasis>
        binary, the command interpreter invokes it to process the password. For
        details, see <link linkend="kpwvalid8">kpwvalid(8)</link>.</para>

      </listitem>
      <listitem>
        <para>If the <emphasis role="bold">-reuse</emphasis> argument to the <emphasis role="bold">kas setfields</emphasis> command has been used to
        prohibit reuse of previous passwords, the command interpreter verifies
        that the password is not too similar too any of the user's previous 20
        passwords. It generates the following error message at the shell:</para>

<programlisting>
   Password was not changed because it seems like a reused password

</programlisting>
          <para>To prevent a user from subverting this restriction by changing the
          password twenty times in quick succession (manually or by running a
          script), use the <emphasis role="bold">-minhours</emphasis> argument on the <emphasis role="bold">kaserver</emphasis> initialization
          command. The following error message appears if a user attempts to change
          a password before the minimum time has passed:</para>

<programlisting>
   Password was not changed because you changed it too
   recently; see your systems administrator

</programlisting>
          </listitem>
        </itemizedlist>
      </refsect1>
      <refsect1>
        <title>Options</title>
        <variablelist>
          <varlistentry>
            <term><emphasis role="bold">-name</emphasis> &lt;<emphasis>name of user</emphasis>&gt;</term>
            <listitem>
              <para>Names the entry in which to record the new key.</para>

            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis role="bold">-new_password</emphasis> &lt;<emphasis>new password</emphasis>&gt;</term>
            <listitem>
              <para>Specifies the character string the user types when authenticating to
              AFS. Omit this argument and type the string at the resulting prompts so
              that the password does not echo visibly. Note that some non-AFS programs
              cannot handle passwords longer than eight characters.</para>

            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis role="bold">-kvno</emphasis> &lt;<emphasis>key version number</emphasis>&gt;</term>
            <listitem>
              <para>Specifies the key version number associated with the new key.  Provide an
              integer in the range from <computeroutput>0</computeroutput> through <computeroutput>255</computeroutput>. If omitted, the default is
              <computeroutput>0</computeroutput> (zero), which is probably not desirable for server keys.</para>

            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis role="bold">-admin_username</emphasis> &lt;<emphasis>admin principal</emphasis>&gt;</term>
            <listitem>
              <para>Specifies the user identity under which to authenticate with the
              Authentication Server for execution of the command. For more details, see
              <link linkend="kas8">kas(8)</link>.</para>

            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis role="bold">-password_for_admin</emphasis> &lt;<emphasis>admin password</emphasis>&gt;</term>
            <listitem>
              <para>Specifies the password of the command's issuer. If it is omitted (as
              recommended), the <emphasis role="bold">kas</emphasis> command interpreter prompts for it and does not
              echo it visibly. For more details, see <link linkend="kas8">kas(8)</link>.</para>

            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
            <listitem>
              <para>Names the cell in which to run the command. For more details, see
              <link linkend="kas8">kas(8)</link>.</para>

            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis role="bold">-servers</emphasis> &lt;<emphasis>authentication servers</emphasis>&gt;+</term>
            <listitem>
              <para>Names each machine running an Authentication Server with which to
              establish a connection. For more details, see <link linkend="kas8">kas(8)</link>.</para>

            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis role="bold">-noauth</emphasis></term>
            <listitem>
              <para>Assigns the unprivileged identity <computeroutput>anonymous</computeroutput> to the issuer. For more
              details, see <link linkend="kas8">kas(8)</link>.</para>

            </listitem>
          </varlistentry>
          <varlistentry>
            <term><emphasis role="bold">-help</emphasis></term>
            <listitem>
              <para>Prints the online help for this command. All other valid options are
              ignored.</para>

            </listitem>
          </varlistentry>
        </variablelist>
      </refsect1>
      <refsect1>
        <title>Examples</title>
        <para>In the following example, an administrator using the <computeroutput>admin</computeroutput> account
        changes the password for <computeroutput>pat</computeroutput> (presumably because <computeroutput>pat</computeroutput> forgot the
        former password or got locked out of his account in some other way).</para>

<programlisting>
   % kas setpassword pat
   Password for admin:
   new_password:
   Verifying, please re-enter new_password:

</programlisting>
        </refsect1>
        <refsect1>
          <title>Privilege Required</title>
          <para>Individual users can change their own passwords. To change another user's
          password or the password (server encryption key) for server entries such
          as <computeroutput>afs</computeroutput>, the issuer must have the <computeroutput>ADMIN</computeroutput> flag set in his or her
          Authentication Database entry.</para>

        </refsect1>
        <refsect1>
          <title>See Also</title>
          <para><link linkend="bos_addkey8">bos_addkey(8)</link>,
          <link linkend="kas8">kas(8)</link>,
          <link linkend="kaserver8">kaserver(8)</link>,
          <link linkend="kpwvalid8">kpwvalid(8)</link></para>

        </refsect1>
        <refsect1>
          <title>Copyright</title>
          <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>

          <para>This documentation is covered by the IBM Public License Version 1.0.  It was
          converted from HTML to POD by software written by Chas Williams and Russ
          Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>

        </refsect1>
      </refentry>