Improve documentation about search_path for SECURITY DEFINER functions.

Clarify that the reason for recommending that pg_temp be put last is to
prevent temporary tables from capturing unqualified table names.  Per
discussion with Albe Laurenz.

Discussion: <A737B7A37273E048B164557ADEF4A58B5386C6E1@ntex2010i.host.magwien.gv.at>

diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml
index 097e2bd0f0b772a96287fc71efc3192404cc52c5..abb0d33031e37b35138a78741e100abc90ef5920 100644 (file)
--- a/doc/src/sgml/ref/create_function.sgml
+++ b/doc/src/sgml/ref/create_function.sgml
@@ -750,14 +750,14 @@ SELECT * FROM dup(42);
     ensure that the function cannot be misused.  For security,
      should be set to exclude any schemas
     writable by untrusted users.  This prevents
-    malicious users from creating objects that mask objects used by the
-    function.  Particularly important in this regard is the
+    malicious users from creating objects (e.g., tables, functions, and
+    operators) that mask objects intended to be used by the function.
+    Particularly important in this regard is the
     temporary-table schema, which is searched first by default, and
     is normally writable by anyone.  A secure arrangement can be obtained
     by forcing the temporary schema to be searched last.  To do this,
     write pg_temppg_tempsecuring functions as the last entry in search_path.
     This function illustrates safe usage:
-   
 
 
 CREATE FUNCTION check_password(uname TEXT, pass TEXT)
@@ -776,11 +776,17 @@ $$  LANGUAGE plpgsql
     SET search_path = admin, pg_temp;
 
 
+    This function's intention is to access a table admin.pwds.
+    But without the SET clause, or with a SET clause
+    mentioning only admin, the function could be subverted by
+    creating a temporary table named pwds.
+   
+
    
     Before PostgreSQL version 8.3, the
-    SET option was not available, and so older functions may
+    SET clause was not available, and so older functions may
     contain rather complicated logic to save, set, and restore
-    search_path.  The SET option is far easier
+    search_path.  The SET clause is far easier
     to use for this purpose.