Document SQL SECURITY

src/docs/asciidoc/en/refdocs/fblangref40/_fblangref40-security.adoc

@@ -26,3 +26,5 @@ include::security/_fblangref40-security-revoking.adoc[leveloffset=+1]
 include::security/_fblangref40-security-mapping.adoc[leveloffset=+1]
 
 include::security/_fblangref40-security-dbcrypt.adoc[leveloffset=+1]
+
+include::security/_fblangref40-security-sql-security.adoc[leveloffset=+1]

src/docs/asciidoc/en/refdocs/fblangref40/ddl/_fblangref40-ddl-database.adoc

@@ -374,9 +374,10 @@ ALTER {DATABASE | SCHEMA} <alter_db_option> [<alter_db_option> ...]
   | {ADD DIFFERENCE FILE '_diff_file_' | DROP DIFFERENCE FILE}
   | {BEGIN | END} BACKUP
   | SET DEFAULT CHARACTER SET _charset_
+  | {ENCRYPT WITH _plugin_name_ [KEY _key_name_] | DECRYPT}
   | SET LINGER TO _linger_duration_
   | DROP LINGER
-  | {ENCRYPT WITH _plugin_name_ [KEY _key_name_] | DECRYPT}
+  | SET DEFAULT SQL SECURITY {INVOKER | DEFINER}
   | {ENABLE | DISABLE} PUBLICATION
   | INCLUDE <pub_table_filter> TO PUBLICATION
   | EXCLUDE <pub_table_filter> FROM PUBLICATION
@@ -529,6 +530,12 @@ Changes the default character set of the database.
 This change does not affect existing data or columns.
 The new default character set will only be used in subsequent DDL commands.
 
+`ENCRYPT WITH`::
+See <<fblangref40-security-dbcrypt,Encrypting a Database>> in the Security chapter.
+
+`DECRYPT`::
+See <<fblangref40-security-dbcrypt-decrypt,Decrypting a Database>> in the Security chapter.
+
 `SET LINGER TO`::
 Sets the _linger_-delay.
 The _linger_-delay applies only to Firebird SuperServer, and is the number of seconds the server keeps a database file (and its caches) open after the last connection to that database was closed.
@@ -569,11 +576,9 @@ fbsvcmgr host:service_mgr user sysdba password xxx
 The `DROP LINGER` and `SET LINGER TO` clauses can be combined in a single statement, but the last clause "`wins`".
 ====
 
-`ENCRYPT WITH`::
-See <<fblangref40-security-dbcrypt,Encrypting a Database>> in the Security chapter.
-
-`DECRYPT`::
-See <<fblangref40-security-dbcrypt-decrypt,Decrypting a Database>> in the Security chapter.
+`SET DEFAULT SQL SECURITY`::
+Specifies the default `SQL SECURITY` option to apply when creating objects with a `SQL SECURITY` property.
+See also _<<fblangref40-security-sql-security,SQL Security>>_ in chapter _Security_.
 
 `ENABLE PUBLICATION`::
 Enables publication of this database for replication.

src/docs/asciidoc/en/refdocs/fblangref40/ddl/_fblangref40-ddl-function.adoc

@@ -27,10 +27,7 @@ DSQL
 CREATE FUNCTION _funcname_ [ ( [ <in_params> ] ) ]
   RETURNS <domain_or_non_array_type> [COLLATE _collation_]
   [DETERMINISTIC]
-  <module-body>
-
-<module-body> ::=
-  !! See <<fblangref40-psql-elements-body-syntax,Syntax of Module Body>> !!
+  {<psql_function> | <external-module-body>}
 
 <in_params> ::= <inparam> [, <inparam> ... ]
 
@@ -43,6 +40,16 @@ CREATE FUNCTION _funcname_ [ ( [ <in_params> ] ) ]
 
 <domain_or_non_array_type> ::=
   !! See <<fblangref40-datatypes-syntax-scalar,Scalar Data Types Syntax>> !!
+
+<psql_function> ::=
+  [SQL SECURITY {INVOKER | DEFINER}]
+  <psql-module-body>
+
+<psql-module-body> ::=
+  !! See <<fblangref40-psql-elements-body-syntax,Syntax of Module Body>> !!
+
+<external-module-body> ::=
+  !! See <<fblangref40-psql-elements-body-syntax,Syntax of Module Body>> !!
 ----
 
 [[fblangref40-ddl-tbl-createfunc]]
@@ -159,6 +166,15 @@ SELECT n, fn_t () FROM
 ----
 ====
 
+[[fblangref40-ddl-func-sqlsec]]
+=== SQL Security
+
+The `SQL SECURITY` clause specifies the security context for executing other routines or inserting into other tables.
+
+The `SQL SECURITY` clause can only be specified for PSQL functions, and is not valid for functions defined in a package.
+
+See also _<<fblangref40-security-sql-security,SQL Security>>_ in chapter _Security_.
+
 [[fblangref40-ddl-func-declarations]]
 === Variable, Cursor and Sub-Routine Declarations
 
@@ -324,6 +340,27 @@ BEGIN
 END
 ----
 
+. With `DEFINER` set for function `f`, user `US` needs only the `EXECUTE` privilege on `f`.
+If it were set for `INVOKER`, the user would also need the `INSERT` privilege on table `t`.
++
+[source]
+----
+set term ^;
+create function f (i integer) returns int SQL SECURITY DEFINER
+as
+begin
+  insert into t values (:i);
+  return i + 1;
+end^
+set term ;^
+grant execute on function f to user us;
+
+commit;
+
+connect 'localhost:/tmp/59.fdb' user us password 'pas';
+select f(3) from rdb$database;
+----
+
 .See also
 <<fblangref40-ddl-func-creatalter>>, <<fblangref40-ddl-func-alter>>, <<fblangref40-ddl-func-recreate>>, <<fblangref40-ddl-func-drop>>, <<fblangref40-ddl-extfunc-declare>>
 
@@ -343,7 +380,7 @@ ALTER FUNCTION _funcname_
   [ ( [ <in_params> ] ) ]
   RETURNS <domain_or_non_array_type> [COLLATE _collation_]
   [DETERMINISTIC]
-  <module-body>
+  {<psql_function> | <external-module-body>}
 
 !! See syntax of <<fblangref40-ddl-func-create-syntax,`CREATE FUNCTION`>> for further rules !!
 ----
@@ -408,7 +445,7 @@ CREATE OR ALTER FUNCTION _funcname_
   [ ( [ <in_params> ] ) ]
   RETURNS <domain_or_non_array_type> [COLLATE _collation_]
   [DETERMINISTIC]
-  <module-body>
+  {<psql_function> | <external-module-body>}
 
 !! See syntax of <<fblangref40-ddl-func-create-syntax,`CREATE FUNCTION`>> for further rules !!
 ----
@@ -500,7 +537,7 @@ RECREATE FUNCTION _funcname_
   [ ( [ <in_params> ] ) ]
   RETURNS <domain_or_non_array_type> [COLLATE _collation_]
   [DETERMINISTIC]
-  <module-body>
+  {<psql_function> | <external-module-body>}
 
 !! See syntax of <<fblangref40-ddl-func-create-syntax,`CREATE FUNCTION`>> for further rules !!
 ----

src/docs/asciidoc/en/refdocs/fblangref40/ddl/_fblangref40-ddl-package.adoc

@@ -17,6 +17,7 @@ DSQL
 [listing,subs="+quotes,macros"]
 ----
 CREATE PACKAGE _package_name_
+[SQL SECURITY {INVOKER | DEFINER}]
 AS
 BEGIN
   [ <package_item> ... ]
@@ -119,6 +120,15 @@ Some SQL statement editors -- specifically the _isql_ utility that comes with Fi
 This creates a conflict with PSQL syntax when coding in these environments.
 If you are unacquainted with this problem and its solution, please study the details in the PSQL chapter in the section entitled <<fblangref40-sidebar01,Switching the Terminator in _isql_>>.
 
+[[fblangref40-ddl-pkg-sqlsec]]
+=== SQL Security
+
+The `SQL SECURITY` clause specifies the security context for executing other routines or inserting into other tables from functions or procedures defined in this package.
+
+The `SQL SECURITY` clause can only be specified for the package, not for individual procedures and functions of the package.
+
+See also _<<fblangref40-security-sql-security,SQL Security>>_ in chapter _Security_.
+
 [[fblangref40-ddl-pkg-create-procfunc]]
 === Procedure and Function Parameters
 
@@ -139,7 +149,7 @@ The user who created the package header becomes its owner.
 [[fblangref40-ddl-pkg-create-example]]
 === Examples of `CREATE PACKAGE`
 
-.Create a package header
+. Create a package header
 [source]
 ----
 CREATE PACKAGE APP_VAR
@@ -152,6 +162,38 @@ BEGIN
 END
 ----
 
+. With `DEFINER` set for package `pk`, user `US` needs only the `EXECUTE` privilege on `pk`.
+If it were set for `INVOKER`, either the user or the package would also need the `INSERT` privilege on table `t`.
++
+[source]
+----
+create table t (i integer);
+set term ^;
+create package pk SQL SECURITY DEFINER
+as
+begin
+    function f(i integer) returns int;
+end^
+
+create package body pk
+as
+begin
+    function f(i integer) returns int
+    as
+    begin
+      insert into t values (:i);
+      return i + 1;
+    end
+end^
+set term ;^
+grant execute on package pk to user us;
+
+commit;
+
+connect 'localhost:/tmp/69.fdb' user us password 'pas';
+select pk.f(3) from rdb$database;
+----
+
 .See also
 <<fblangref40-ddl-pkg-body-create,`CREATE PACKAGE BODY`>>, <<fblangref40-ddl-pkg-body-recreate,`RECREATE PACKAGE BODY`>>, <<fblangref40-ddl-pkg-alter>>, <<fblangref40-ddl-pkg-drop>>, <<fblangref40-ddl-pkg-recreate>>
 
@@ -168,6 +210,7 @@ DSQL
 [listing,subs="+quotes,macros"]
 ----
 ALTER PACKAGE _package_name_
+[SQL SECURITY {INVOKER | DEFINER}]
 AS
 BEGIN
   [ <package_item> ... ]
@@ -222,6 +265,7 @@ DSQL
 [listing,subs="+quotes,macros"]
 ----
 CREATE OR ALTER PACKAGE _package_name_
+[SQL SECURITY {INVOKER | DEFINER}]
 AS
 BEGIN
   [ <package_item> ... ]
@@ -317,6 +361,7 @@ DSQL
 [listing,subs="+quotes,macros"]
 ----
 RECREATE PACKAGE _package_name_
+[SQL SECURITY {INVOKER | DEFINER}]
 AS
 BEGIN
   [ <package_item> ... ]

src/docs/asciidoc/en/refdocs/fblangref40/ddl/_fblangref40-ddl-procedure.adoc

@@ -22,10 +22,7 @@ DSQL, ESQL
 ----
 CREATE PROCEDURE _procname_ [ ( [ <in_params> ] ) ]
   [RETURNS (<out_params>)]
-  <module-body>
-
-<module-body> ::=
-  !! See <<fblangref40-psql-elements-body-syntax,Syntax of Module Body>> !!
+  {<psql_procedure> | <external-module-body>}
 
 <in_params> ::= <inparam> [, <inparam> ...]
 
@@ -47,6 +44,16 @@ CREATE PROCEDURE _procname_ [ ( [ <in_params> ] ) ]
 
 <domain_or_non_array_type> ::=
   !! See <<fblangref40-datatypes-syntax-scalar,Scalar Data Types Syntax>> !!
+
+<psql_procedure> ::=
+  [SQL SECURITY {INVOKER | DEFINER}]
+  <psql-module-body>
+
+<psql-module-body> ::=
+  !! See <<fblangref40-psql-elements-body-syntax,Syntax of Module Body>> !!
+
+<external-module-body> ::=
+  !! See <<fblangref40-psql-elements-body-syntax,Syntax of Module Body>> !!
 ----
 
 [[fblangref40-ddl-proc-createproc]]
@@ -114,6 +121,15 @@ Parameters with default values specified must be added at the end of the list of
 Output Parameters::
 The optional `RETURNS` clause is for specifying a parenthesised list of output parameters for the stored procedure.
 
+[[fblangref40-ddl-proc-sqlsec]]
+=== SQL Security
+
+The `SQL SECURITY` clause specifies the security context for executing other routines or inserting into other tables.
+
+The `SQL SECURITY` clause can only be specified for PSQL procedures, and is not valid for procedures defined in a package.
+
+See also _<<fblangref40-security-sql-security,SQL Security>>_ in chapter _Security_.
+
 [[fblangref40-ddl-proc-declarations]]
 === Variable, Cursor and Sub-Routine Declarations
 
@@ -231,6 +247,25 @@ BEGIN
            -- and makes the procedure "selectable"
 END
 ----
+. With `DEFINER` set for procedure `p`, user `US` needs only the `EXECUTE` privilege on `p`.
+If it were set for `INVOKER`, either the user or the procedure would also need the `INSERT` privilege on table `t`.
++
+[source]
+----
+set term ^;
+create procedure p (i integer) SQL SECURITY DEFINER
+as
+begin
+  insert into t values (:i);
+end^
+set term ;^
+
+grant execute on procedure p to user us;
+commit;
+
+connect 'localhost:/tmp/17.fdb' user us password 'pas';
+execute procedure p(1);
+----
 
 .See also
 <<fblangref40-ddl-proc-crtoralter>>, <<fblangref40-ddl-proc-alter>>, <<fblangref40-ddl-proc-recreate>>, <<fblangref40-ddl-proc-drop>>
@@ -249,7 +284,7 @@ DSQL, ESQL
 ----
 ALTER PROCEDURE _procname_ [ ( [ <in_params> ] ) ]
   [RETURNS (<out_params>)]
-  <module-body>
+  {<psql_procedure> | <external-module-body>}
 
 !! See syntax of <<fblangref40-ddl-proc-create-syntax,`CREATE PROCEDURE`>> for further rules !!
 ----
@@ -319,7 +354,7 @@ DSQL
 ----
 CREATE OR ALTER PROCEDURE _procname_ [ ( [ <in_params> ] ) ]
   [RETURNS (<out_params>)]
-  <module-body>
+  {<psql_procedure> | <external-module-body>}
 
 !! See syntax of <<fblangref40-ddl-proc-create-syntax,`CREATE PROCEDURE`>> for further rules !!
 ----
@@ -419,7 +454,7 @@ DSQL
 ----
 RECREATE PROCEDURE _procname_ [ ( [ <in_params> ] ) ]
   [RETURNS (<out_params>)]
-  <module-body>
+  {<psql_procedure> | <external-module-body>}
 
 !! See syntax of <<fblangref40-ddl-proc-create-syntax,`CREATE PROCEDURE`>> for further rules !!
 ----