Document changes in large-object privilege checking.

Commit 5ecc0d738 removed the hard-wired superuser checks in lo_import
and lo_export in favor of protecting them with SQL permissions, but
failed to adjust the documentation to match.  Fix that, and add a
<caution> paragraph pointing out the nontrivial security hazards
involved with actually granting such permissions.  (It's still better
than ALLOW_DANGEROUS_LO_FUNCTIONS, though.)

Also, commit ae20b23a9 caused large object read/write privilege to
be checked during lo_open() rather than in the actual read or write
calls.  Document that.

Discussion: https://postgr.es/m/CAB7nPqRHmNOYbETnc_2EjsuzSM00Z+BWKv9sy6tnvSd5gWT_JA@mail.gmail.com

2 files changed, 38 insertions, 7 deletions

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index d360fc4d58a..996e82534ab 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -7540,9 +7540,6 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
         Setting this variable does not disable all security checks related to
         large objects — only those for which the default behavior has
         changed in <productname>PostgreSQL</productname> 9.0.
-        For example, <literal>lo_import()</literal> and
-        <literal>lo_export()</literal> need superuser privileges regardless
-        of this setting.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml
index c743b5c0baa..e11c8e0f8b1 100644
--- a/doc/src/sgml/lobj.sgml
+++ b/doc/src/sgml/lobj.sgml
@@ -293,6 +293,18 @@ int lo_open(PGconn *conn, Oid lobjId, int mode);
     </para>
 
     <para>
+     <function>lo_open</function> will fail if <literal>SELECT</literal>
+     privilege is not available for the large object, or
+     if <symbol>INV_WRITE</symbol> is specified and <literal>UPDATE</literal>
+     privilege is not available.
+     (Prior to <productname>PostgreSQL</productname> 11, these privilege
+     checks were instead performed at the first actual read or write call
+     using the descriptor.)
+     These privilege checks can be disabled with the
+     <xref linkend="guc-lo-compat-privileges"> run-time parameter.
+    </para>
+
+    <para>
      An example:
 <programlisting>
 inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE);
@@ -634,12 +646,34 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image
     <function>lo_export</function> functions behave considerably differently
     from their client-side analogs.  These two functions read and write files
     in the server's file system, using the permissions of the database's
-    owning user.  Therefore, their use is restricted to superusers.  In
-    contrast, the client-side import and export functions read and write files
-    in the client's file system, using the permissions of the client program.
-    The client-side functions do not require superuser privilege.
+    owning user.  Therefore, by default their use is restricted to superusers.
+    In contrast, the client-side import and export functions read and write
+    files in the client's file system, using the permissions of the client
+    program.  The client-side functions do not require any database
+    privileges, except the privilege to read or write the large object in
+    question.
   </para>
 
+  <caution>
+   <para>
+    It is possible to <xref linkend="sql-grant"> use of the
+    server-side <function>lo_import</function>
+    and <function>lo_export</function> functions to non-superusers, but
+    careful consideration of the security implications is required.  A
+    malicious user of such privileges could easily parlay them into becoming
+    superuser (for example by rewriting server configuration files), or could
+    attack the rest of the server's file system without bothering to obtain
+    database superuser privileges as such.  <emphasis>Access to roles having
+    such privilege must therefore be guarded just as carefully as access to
+    superuser roles.</emphasis>  Nonetheless, if use of
+    server-side <function>lo_import</function>
+    or <function>lo_export</function> is needed for some routine task, it's
+    safer to use a role with such privileges than one with full superuser
+    privileges, as that helps to reduce the risk of damage from accidental
+    errors.
+   </para>
+  </caution>
+
   <para>
     The functionality of <function>lo_read</function> and
     <function>lo_write</function> is also available via server-side calls,