Code review for MD5 authorization patch. Clean up some breakage

(salts were always zero!?), add much missing documentation.

5 files changed, 212 insertions, 99 deletions

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index f1914fe9d36..33dba495df8 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.19 2001/09/09 23:52:12 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.20 2001/09/21 20:31:41 tgl Exp $ -->
 
 <chapter id="client-authentication">
  <title>Client Authentication</title>
@@ -219,7 +219,13 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
         <listitem>
          <para>
           Like the <literal>md5</literal> method but uses older crypt
-          authentication for pre-7.2 clients.
+          authentication for pre-7.2 clients.  <literal>md5</literal>
+	  is preferred, unless you need to support old clients that
+	  do not have <literal>md5</literal>.  The <literal>crypt</>
+	  method is not compatible with encrypting passwords in
+	  <filename>pg_shadow</>, and it has been observed to fail
+	  when client and server machines have different implementations
+	  of the crypt() library routine.
          </para>
         </listitem>
        </varlistentry>
@@ -284,7 +290,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
         <term><literal>pam</></term>
         <listitem>
          <para>
-          This authentication type operates similar to
+          This authentication type operates similarly to
           <firstterm>password</firstterm>, with the main difference that
           it will use PAM (Pluggable Authentication Modules) as the
           authentication mechanism. The <replaceable>authentication
@@ -448,9 +454,9 @@ host         all        192.168.0.0    255.255.0.0        ident     omicron
 
    <para>
     Alternative passwords cannot be used when using the <literal>md5</>
-    or <literal>crypt</> methods. The file will still be evaluated as
-    usual but the password field will simply be ignored and the
-    <literal>pg_shadow</> password will be used.
+    or <literal>crypt</> methods. The file will be read as
+    usual, but the password field will simply be ignored and the
+    <literal>pg_shadow</> password will always be used.
    </para>
 
    <para>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index b69719f7b93..83b03792829 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/protocol.sgml,v 1.20 2001/09/13 15:55:23 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/protocol.sgml,v 1.21 2001/09/21 20:31:42 tgl Exp $ -->
 
 <chapter id="protocol">
  <title>Frontend/Backend Protocol</title>
@@ -142,10 +142,11 @@
      </VarListEntry>
 
      <VarListEntry>
-      <Term>AuthenticationUnencryptedPassword</Term>
+      <Term>AuthenticationCleartextPassword</Term>
       <ListItem>
        <Para>
-        The frontend must then send an UnencryptedPasswordPacket.  If
+        The frontend must then send a PasswordPacket containing the
+	password in clear-text form.  If
         this is the correct password, the server responds with an
         AuthenticationOk, otherwise it responds with an ErrorResponse.
        </Para>
@@ -153,16 +154,47 @@
      </VarListEntry>
 
      <VarListEntry>
-      <Term>AuthenticationEncryptedPassword</Term>
+      <Term>AuthenticationCryptPassword</Term>
       <ListItem>
        <Para>
-        The frontend must then send an EncryptedPasswordPacket.  If
+        The frontend must then send a PasswordPacket containing the
+	password encrypted via crypt(3), using the 2-character salt
+	specified in the AuthenticationCryptPassword packet.  If
         this is the correct password, the server responds with an
         AuthenticationOk, otherwise it responds with an ErrorResponse.
        </Para>
       </ListItem>
      </VarListEntry>
 
+     <VarListEntry>
+      <Term>AuthenticationMD5Password</Term>
+      <ListItem>
+       <Para>
+        The frontend must then send a PasswordPacket containing the
+	password encrypted via MD5, using the 4-character salt
+	specified in the AuthenticationMD5Password packet.  If
+        this is the correct password, the server responds with an
+        AuthenticationOk, otherwise it responds with an ErrorResponse.
+       </Para>
+      </ListItem>
+     </VarListEntry>
+
+     <VarListEntry>
+      <Term>AuthenticationSCMCredential</Term>
+      <ListItem>
+       <Para>
+        This method is only possible for local Unix-domain connections
+	on platforms that support SCM credential messages.  The frontend
+	must issue an SCM credential message and then send a single data
+	byte.  (The contents of the data byte are uninteresting; it's
+	only used to ensure that the server waits long enough to receive
+	the credential message.)  If the credential is acceptable,
+	the server responds with an
+        AuthenticationOk, otherwise it responds with an ErrorResponse.
+       </Para>
+      </ListItem>
+     </VarListEntry>
+
     </VariableList>
    </Para>
 
@@ -857,7 +889,7 @@ AuthenticationKerberosV5 (B)
 </VarListEntry>
 <VarListEntry>
 <Term>
-AuthenticationUnencryptedPassword (B)
+AuthenticationCleartextPassword (B)
 </Term>
 <ListItem>
 <Para>
@@ -879,19 +911,18 @@ AuthenticationUnencryptedPassword (B)
 </Term>
 <ListItem>
 <Para>
-                Specifies that an unencrypted password is required.
+                Specifies that a cleartext password is required.
 </Para>
 </ListItem>
 </VarListEntry>
 </VariableList>
-
-
 </Para>
 </ListItem>
 </VarListEntry>
+
 <VarListEntry>
 <Term>
-AuthenticationEncryptedPassword (B)
+AuthenticationCryptPassword (B)
 </Term>
 <ListItem>
 <Para>
@@ -913,7 +944,7 @@ AuthenticationEncryptedPassword (B)
 </Term>
 <ListItem>
 <Para>
-                Specifies that an encrypted password is required.
+                Specifies that a crypt()-encrypted password is required.
 </Para>
 </ListItem>
 </VarListEntry>
@@ -932,6 +963,85 @@ AuthenticationEncryptedPassword (B)
 </Para>
 </ListItem>
 </VarListEntry>
+
+<VarListEntry>
+<Term>
+AuthenticationMD5Password (B)
+</Term>
+<ListItem>
+<Para>
+
+<VariableList>
+<VarListEntry>
+<Term>
+        Byte1('R')
+</Term>
+<ListItem>
+<Para>
+                Identifies the message as an authentication request.
+</Para>
+</ListItem>
+</VarListEntry>
+<VarListEntry>
+<Term>
+        Int32(5)
+</Term>
+<ListItem>
+<Para>
+                Specifies that an MD5-encrypted password is required.
+</Para>
+</ListItem>
+</VarListEntry>
+<VarListEntry>
+<Term>
+        Byte4
+</Term>
+<ListItem>
+<Para>
+                The salt to use when encrypting the password.
+</Para>
+</ListItem>
+</VarListEntry>
+</VariableList>
+
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry>
+<Term>
+AuthenticationSCMCredential (B)
+</Term>
+<ListItem>
+<Para>
+
+<VariableList>
+<VarListEntry>
+<Term>
+        Byte1('R')
+</Term>
+<ListItem>
+<Para>
+                Identifies the message as an authentication request.
+</Para>
+</ListItem>
+</VarListEntry>
+<VarListEntry>
+<Term>
+        Int32(6)
+</Term>
+<ListItem>
+<Para>
+                Specifies that an SCM credentials message is required.
+</Para>
+</ListItem>
+</VarListEntry>
+</VariableList>
+
+</Para>
+</ListItem>
+</VarListEntry>
+
 <VarListEntry>
 <Term>
 BackendKeyData (B)
@@ -1271,40 +1381,7 @@ EmptyQueryResponse (B)
 </Para>
 </ListItem>
 </VarListEntry>
-<VarListEntry>
-<Term>
-EncryptedPasswordPacket (F)
-</Term>
-<ListItem>
-<Para>
-
-<VariableList>
-<VarListEntry>
-<Term>
-        Int32
-</Term>
-<ListItem>
-<Para>
-                The size of the packet in bytes.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>
-        String
-</Term>
-<ListItem>
-<Para>
-                The encrypted (using MD5 or crypt()) password.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
 
-
-</Para>
-</ListItem>
-</VarListEntry>
 <VarListEntry>
 <Term>
 ErrorResponse (B)
@@ -1602,6 +1679,40 @@ NotificationResponse (B)
 </Para>
 </ListItem>
 </VarListEntry>
+
+<VarListEntry>
+<Term>
+PasswordPacket (F)
+</Term>
+<ListItem>
+<Para>
+
+<VariableList>
+<VarListEntry>
+<Term>
+        Int32
+</Term>
+<ListItem>
+<Para>
+                The size of the packet in bytes.
+</Para>
+</ListItem>
+</VarListEntry>
+<VarListEntry>
+<Term>
+        String
+</Term>
+<ListItem>
+<Para>
+                The password (encrypted, if requested).
+</Para>
+</ListItem>
+</VarListEntry>
+</VariableList>
+</Para>
+</ListItem>
+</VarListEntry>
+
 <VarListEntry>
 <Term>
 Query (F)
@@ -1852,39 +1963,7 @@ Terminate (F)
 </Para>
 </ListItem>
 </VarListEntry>
-<VarListEntry>
-<Term>
-UnencryptedPasswordPacket (F)
-</Term>
-<ListItem>
-<Para>
-
-<VariableList>
-<VarListEntry>
-<Term>
-        Int32
-</Term>
-<ListItem>
-<Para>
-                The size of the packet in bytes.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>
-        String
-</Term>
-<ListItem>
-<Para>
-                The unencrypted password.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
 
-</Para>
-</ListItem>
-</VarListEntry>
 </VariableList>
 
 </sect1>
diff --git a/doc/src/sgml/ref/alter_user.sgml b/doc/src/sgml/ref/alter_user.sgml
index e8258f762d8..e7f650f3882 100644
--- a/doc/src/sgml/ref/alter_user.sgml
+++ b/doc/src/sgml/ref/alter_user.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.16 2001/09/03 12:57:49 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.17 2001/09/21 20:31:45 tgl Exp $
 Postgres documentation
 -->
 
@@ -53,13 +53,23 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
      </varlistentry>
 
      <varlistentry>
-      <term><replaceable class="PARAMETER">[ encrypted | unencrypted ] password</replaceable></term>
+      <term><replaceable class="PARAMETER">password</replaceable></term>
       <listitem>
        <para>
 	The new password to be used for this account.
-	<literal>Encrypted</literal>/ <literal>unencrypted</literal>
-	controls whether the password is stored encrypted in the
-	database.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>ENCRYPTED</term>
+      <term>UNENCRYPTED</term>
+      <listitem>
+       <para> 
+	These keywords control whether the
+	password is stored encrypted in <literal>pg_shadow</>.  (See
+	<xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
+	for more information about this choice.)
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/create_user.sgml b/doc/src/sgml/ref/create_user.sgml
index 3bf744f2c37..34e210c70e8 100644
--- a/doc/src/sgml/ref/create_user.sgml
+++ b/doc/src/sgml/ref/create_user.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.20 2001/09/14 08:24:29 ishii Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.21 2001/09/21 20:31:45 tgl Exp $
 Postgres documentation
 -->
 
@@ -66,28 +66,45 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
        </para>
        <para>
         If this is not specified, the highest assigned user id plus one
-        will be used as default.
+	(with a minimum of 100) will be used as default.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><replaceable class="parameter">[ encrypted | unencrypted ] password</replaceable></term>
+      <term><replaceable class="parameter">password</replaceable></term>
       <listitem>
        <para>
         Sets the user's password. If you do not plan to use password
-        authentication you can omit this option, otherwise the user
+        authentication you can omit this option, but the user
         won't be able to connect to a password-authenticated server.
-	</para>
-	<para>
-	<literal>ENCRYPTED/UNENCRYPTED</literal> controls whether the
-	password is stored encrypted in the database. Older clients may
-	have trouble communicating using encrypted password storage.
+	The password can be set or changed later, using
+	<xref linkend="SQL-ALTERUSER" endterm="SQL-ALTERUSER-title">.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>ENCRYPTED</term>
+      <term>UNENCRYPTED</term>
+      <listitem>
+       <para> 
+	These keywords control whether the
+	password is stored encrypted in <literal>pg_shadow</>.  (If neither
+	is specified, the default behavior is determined by the
+	<varname>PASSWORD_ENCRYPTION</varname> server parameter.)
+	If the presented string is already in MD5-encrypted format,
+	then it is stored as-is, regardless of whether
+	ENCRYPTED or UNENCRYPTED
+	is specified.  This allows reloading of encrypted passwords
+	during dump/restore.
 	</para>
 	<para>
         See the chapter on client authentication in the
 	<citetitle>Administrator's Guide</citetitle> for details on
-        how to set up authentication mechanisms.
+        how to set up authentication mechanisms.  Note that older clients
+	may lack support for the MD5 authentication mechanism that's needed
+	to work with passwords that are stored encrypted.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index e6095f26996..a1a1be8b1a9 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.83 2001/09/21 17:06:12 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.84 2001/09/21 20:31:43 tgl Exp $
 -->
 
 <Chapter Id="runtime">
@@ -1260,7 +1260,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
        <para>
         When a password is specified in <command>CREATE USER</> or
 	<command>ALTER USER</> without writing either ENCRYPTED or
-	UNENCRYPTED, this flag determines whether the password is encrypted.
+	UNENCRYPTED, this flag determines whether the password is to be
+	encrypted.
 	The default is off (do not encrypt the password), but this choice
 	may change in a future release.
        </para>