Clean up markup for first useful version.

doc/src/sgml/security.sgml

@@ -2,6 +2,50 @@
   <Title>Security</Title>
 
   <Para>
+   Database security is addressed at several levels:
+
+   <itemizedlist>
+    <listitem>
+     <para>
+      Data base file protection. All files stored within the database
+      are protected from reading by any account other than the
+      <productname>Postgres</productname> superuser account.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      Connections from a client to the database server are, by
+      default, allowed only via a local Unix socket, not via TCP/IP
+      sockets. The backend must be started with the
+      <literal>-i</literal> option to allow non-local clients to connect.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      Client connections can be restricted by IP address and/or user
+      name via the <filename>pg_hba.conf</filename> file in <envar>PG_DATA</envar>.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      Client connections may be authenticated vi other external packages.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      Each user in <productname>Postgres</productname> is assigned a
+      username and (optionally) a password. By default, users do not
+      have write access to databases they did not create.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      Users may be assigned to <firstterm>groups</firstterm>, and
+      table access may be restricted based on group privileges.
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
 
   <Sect1>
    <Title>User Authentication</Title>
@@ -31,6 +75,9 @@ to the user-id of user <replaceable>postgres</replaceable>.
 	The effective user-id is used
 	as the basis for access control checks.  No other authentication is
 	conducted.
+       </para>
+      </listitem>
+     </varlistentry>
 
      <varlistentry>
       <term>
@@ -50,9 +97,72 @@ systems available.  Of course, host-based authentication is not fool-proof in
 	Unix, either. It is possible for determined intruders to also
 	masquerade the origination host. Those security issues are beyond the
 	scope of <Productname>Postgres</Productname>.
-
+       </para>
+      </listitem>
+     </varlistentry>
     </variablelist>
+   </para>
+  </sect1>
+
+  <sect1>
+   <title>User Names and Groups</title>
+
+   <para>
+    To define a new user, run the
+    <application>createuser</application> utility program.
+   </para>
+
+   <para>
+    To assign a user or set of users to a new group, one must 
+    define the group itself, and assign users to that group. In
+    <application>Postgres</application> these steps are not currently
+    supported with a <command>create group</command> command. Instead, 
+    the groups are defined by inserting appropriate values into the
+    <literal>pg_group</literal> system table, and then using the
+    <command>grant</command> command to assign privileges to the
+    group.
+   </para>
+
+   <sect2>
+    <title>Creating Users</title>
+
+    <para>
+    </para>
+   </sect2>
+
+   <sect2>
+    <title>Creating Groups</title>
+
+    <para>
+     Currently, there is no easy interface to set up user groups. You 
+     have to explicitly insert/update the <literal>pg_group table</literal>.
+     For example:
 
+        jolly=> insert into pg_group (groname, grosysid, grolist)
+        jolly=>     values ('posthackers', '1234', '{5443, 8261}');
+        INSERT 548224
+        jolly=> grant insert on foo to group posthackers;
+        CHANGE
+        jolly=>
+
+   The fields in pg_group are:
+     * groname: the group name. This a name and should be purely
+       alphanumeric. Do not include underscores or other punctuation.
+     * grosysid: the group id. This is an int4. This should be unique for
+       each group.
+     * grolist: the list of pg_user id's that belong in the group. This
+       is an int4[].
+    </para>
+   </sect2>
+
+   <sect2>
+    <title>Assigning Users to Groups</title>
+
+    <para>
+    </para>
+   </sect2>
+
+  </sect1>
 
   <Sect1>
    <Title>Access Control</Title>
@@ -83,6 +193,9 @@ Access Privilege
 	The use of access privilege to limit reading, writing and setting
 	of rules on classes is covered in
 	<citetitle>grant/revoke(l)</citetitle>.
+       </para>
+      </listitem>
+     </varlistentry>
 
      <varlistentry>
       <term>
@@ -98,8 +211,12 @@ and
 	only operate for the owner of the class.  As mentioned above, these
 	operations are <emphasis>never</emphasis>
 	permitted on system catalogs.
-
+       </para>
+      </listitem>
+     </varlistentry>
     </variablelist>
+   </para>
+  </sect1>
 
   <Sect1>
    <Title>Functions and Rules</Title>
@@ -113,6 +230,7 @@ control over who can define functions (e.g., write to relations with
     SQL fields) and rules.  Audit trails and alerters on
     <literal>pg_class</literal>, <literal>pg_user</literal>
     and <literal>pg_group</literal> are also recommended.
+   </para>
 
    <Sect2>
     <Title>Functions</Title>
@@ -126,6 +244,8 @@ backend server runs with its real and effective user-id set to
      internal data structures from inside of trusted functions.  Hence,
      among many other things, such functions can circumvent any system
      access controls.  This is an inherent problem with user-defined C functions.
+    </para>
+   </sect2>
 
    <Sect2>
     <Title>Rules</Title>
@@ -133,11 +253,11 @@ access controls.  This is an inherent problem with user-defined C functions.
     <Para>
      Like SQL functions, rules always run with the identity and
      permissions of the user who invoked the backend server.
+    </para>
+   </sect2>
 
    <sect2>
-<title>
-Caveats
-</title>
+    <title>Caveats</title>
 
     <para>
      There are no plans to explicitly support encrypted data inside of
@@ -146,10 +266,30 @@ There are no plans to explicitly support encrypted data inside of
      data within user-defined functions).  There are no plans to explicitly
      support encrypted network connections, either, pending a total rewrite
      of the frontend/backend protocol.
+    </para>
     <para>
      User names, group names and associated system identifiers (e.g., the
      contents of <literal>pg_user.usesysid</literal>) are assumed to be unique
      throughout a database.  Unpredictable results may occur if they are
      not.
-
+    </para>
+   </sect2>
+  </sect1>
 </chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->