From c1611db01fec587525e88270854c4b993846dcb3 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sun, 3 Jan 2016 20:04:11 -0500 Subject: [PATCH] Do some copy-editing on the docs for row-level security. Clarifications, markup improvements, corrections of misleading or outright wrong statements. --- doc/src/sgml/ddl.sgml | 154 ++++++++++-------- doc/src/sgml/ref/alter_policy.sgml | 23 ++- doc/src/sgml/ref/create_policy.sgml | 241 +++++++++++++++------------- doc/src/sgml/ref/drop_policy.sgml | 9 +- 4 files changed, 234 insertions(+), 193 deletions(-) diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index 449b54fa67..584a618e9d 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -1512,7 +1512,7 @@ REVOKE ALL ON accounts FROM PUBLIC; Row Security Policies - row security + row-level security @@ -1520,54 +1520,68 @@ REVOKE ALL ON accounts FROM PUBLIC; - In addition to the system available through - , tables can have row security policies - which limit the rows returned for normal queries and rows which can - be added through data modification commands. By default, tables do - not have any policies and all rows are visible and able to be added, - subject to the regular system. This is - also known as Row Level Security. + In addition to the SQL-standard privilege + system available through , + tables can have row security policies that restrict, + on a per-user basis, which rows can be returned by normal queries + or inserted, updated, or deleted by data modification commands. + This feature is also known as Row-Level Security. + By default, tables do not have any policies, so that if a user has + access privileges to a table according to the SQL privilege system, + all rows within it are equally available for querying or updating. - When row security is enabled on a table with - , all normal access to the table - (excluding the owner) for selecting rows or adding rows must be through - a policy. If no policy exists for the table, a default-deny policy is - used and no rows are visible or can be added. Privileges which operate - at the whole table level such as TRUNCATE, and - REFERENCES are not subject to row security. + When row security is enabled on a table (with + ALTER TABLE ... ENABLE ROW LEVEL + SECURITY), all normal access to the table for selecting rows or + modifying rows must be allowed by a row security policy. (However, the + table's owner is typically not subject to row security policies.) If no + policy exists for the table, a default-deny policy is used, meaning that + no rows are visible or can be modified. Operations that apply to the + whole table, such as TRUNCATE and REFERENCES, + are not subject to row security. Row security policies can be specific to commands, or to roles, or to - both. The commands available are ALL, - SELECT, INSERT, UPDATE, and - DELETE. Multiple roles can be assigned to a given policy and - normal role membership and inheritance rules apply. Table owners, - superusers, and roles with the BYPASSRLS attribute bypass the - row security system when querying a table. Applications that expect to - bypass all row security through those mechanisms should - set to off. + both. A policy can be specified to apply to ALL + commands, or to SELECT, INSERT, UPDATE, + or DELETE. Multiple roles can be assigned to a given + policy, and normal role membership and inheritance rules apply. - To specify which rows are visible and what rows can be added to the - table with row level security, an expression is required which returns - a Boolean result. This expression will be evaluated for each row prior - to other conditionals or functions which are part of the query. The - one exception to this rule are leakproof functions, - which are guaranteed to not leak information. Two expressions may be - specified to provide independent control over the rows which are - visible and the rows which are allowed to be added. The expression - is run as part of the query and with the privileges of the user - running the query, however, security definer functions can be used in - the expression. + To specify which rows are visible or modifiable according to a policy, + an expression is required that returns a Boolean result. This + expression will be evaluated for each row prior to any conditions or + functions coming from the user's query. (The only exceptions to this + rule are leakproof functions, which are guaranteed to + not leak information; the optimizer may choose to apply such functions + ahead of the row-security check.) Rows for which the expression does + not return true will not be processed. Separate expressions + may be specified to provide independent control over the rows which are + visible and the rows which are allowed to be modified. Policy + expressions are run as part of the query and with the privileges of the + user running the query, although security-definer functions can be used + to access data not available to the calling user. + + + + Superusers and roles with the BYPASSRLS attribute always + bypass the row security system when accessing a table. Table owners + normally bypass row security as well, though a table owner can choose to + be subject to row security with ALTER + TABLE ... FORCE ROW LEVEL SECURITY. Even in a table with that option + selected, the table owner will bypass row security if the + configuration parameter is set + to off; this setting is typically used for purposes such as + backup and restore. Enabling and disabling row security, as well as adding policies to a - table, is always the privilege of the owner only. + table, is always the privilege of the table owner only. @@ -1587,46 +1601,40 @@ REVOKE ALL ON accounts FROM PUBLIC; When multiple policies apply to a given query, they are combined using - OR, similar to how a given role has the privileges - of all roles which they are a member of. + OR, so that a row is accessible if any policy allows + it. This is similar to the rule that a given role has the privileges + of all roles that they are a member of. Referential integrity checks, such as unique or primary key constraints - and foreign key references, will bypass row security to ensure that + and foreign key references, always bypass row security to ensure that data integrity is maintained. Care must be taken when developing - schemas and row level policies to avoid a "covert channel" leak of - information through these referential integrity checks. + schemas and row level policies to avoid covert channel leaks of + information through such referential integrity checks. - To enable row security for a table, - the ALTER TABLE is used. For example, to enable - row level security for the table accounts, use: + As a simple example, here is how to create a policy on + the account relation to allow only members of + the managers role to access rows, and only rows of their + accounts: --- Create the table first CREATE TABLE accounts (manager text, company text, contact_email text); + ALTER TABLE accounts ENABLE ROW LEVEL SECURITY; - - - To create a policy on the account relation to allow the managers role - to view the rows of their accounts, the CREATE POLICY - command can be used: - - - CREATE POLICY account_managers ON accounts TO managers USING (manager = current_user); - If no role is specified, or the special user name + If no role is specified, or the special user name PUBLIC is used, then the policy applies to all - users on the system. To allow all users to view their own row in - a user table, a simple policy can be used: + users on the system. To allow all users to access their own row in + a users table, a simple policy can be used: @@ -1635,10 +1643,10 @@ CREATE POLICY user_policy ON users - To use a different policy for rows which are being added to the - table from those rows which are visible, the WITH CHECK clause - can be used. This would allow all users to view all rows in the - users table, but only modify their own: + To use a different policy for rows that are being added to the table + compared to those rows that are visible, the WITH CHECK + clause can be used. This policy would allow all users to view all rows + in the users table, but only modify their own: @@ -1648,16 +1656,17 @@ CREATE POLICY user_policy ON users - Row security can be disabled with the ALTER TABLE - also. Note that disabling row security does not remove the - policies which are defined on the table, they are simply ignored - and all rows are visible and able to be added, subject to the - normal privileges system. + Row security can also be disabled with the ALTER TABLE + command. Disabling row security does not remove any policies that are + defined on the table; they are simply ignored. Then all rows in the + table are visible and modifiable, subject to the standard SQL privileges + system. - Below is a larger example of how this feature can be used in - production environments, based on a Unix password file. + Below is a larger example of how this feature can be used in production + environments. The table passwd emulates a Unix password + file: @@ -1726,7 +1735,7 @@ GRANT UPDATE postgres=> set role admin; SET postgres=> table passwd; - username | pwhash | uid | gid | real_name | home_phone | extra_info | home_dir | shell + username | pwhash | uid | gid | real_name | home_phone | extra_info | home_dir | shell ----------+--------+-----+-----+-----------+--------------+------------+-------------+----------- admin | xxx | 0 | 0 | Admin | 111-222-3333 | | /root | /bin/dash bob | xxx | 1 | 1 | Bob | 123-456-7890 | | /home/bob | /bin/zsh @@ -1739,7 +1748,7 @@ SET postgres=> table passwd; ERROR: permission denied for relation passwd postgres=> select username,real_name,home_phone,extra_info,home_dir,shell from passwd; - username | real_name | home_phone | extra_info | home_dir | shell + username | real_name | home_phone | extra_info | home_dir | shell ----------+-----------+--------------+------------+-------------+----------- admin | Admin | 111-222-3333 | | /root | /bin/dash bob | Bob | 123-456-7890 | | /home/bob | /bin/zsh @@ -1748,7 +1757,7 @@ postgres=> select username,real_name,home_phone,extra_info,home_dir,shell fro postgres=> update passwd set username = 'joe'; ERROR: permission denied for relation passwd --- Allowed to change her own real_name, but no others +-- Alice is allowed to change her own real_name, but no others postgres=> update passwd set real_name = 'Alice Doe'; UPDATE 1 postgres=> update passwd set real_name = 'John Doe' where username = 'admin'; @@ -1759,11 +1768,16 @@ postgres=> delete from passwd; ERROR: permission denied for relation passwd postgres=> insert into passwd (username) values ('xxx'); ERROR: permission denied for relation passwd --- Alice can change her own password +-- Alice can change her own password; RLS silently prevents updating other rows postgres=> update passwd set pwhash = 'abc'; UPDATE 1 + + For additional details see + and . + + diff --git a/doc/src/sgml/ref/alter_policy.sgml b/doc/src/sgml/ref/alter_policy.sgml index d70bc48f33..a9b1541322 100644 --- a/doc/src/sgml/ref/alter_policy.sgml +++ b/doc/src/sgml/ref/alter_policy.sgml @@ -16,13 +16,14 @@ PostgreSQL documentation ALTER POLICY - change the definition of a policy + change the definition of a row level security policy +ALTER POLICY name ON table_name RENAME TO new_name + ALTER POLICY name ON table_name - [ RENAME TO new_name ] [ TO { role_name | PUBLIC | CURRENT_USER | SESSION_USER } [, ...] ] [ USING ( using_expression ) ] [ WITH CHECK ( check_expression ) ] @@ -33,14 +34,22 @@ ALTER POLICY name ON Description - ALTER POLICY changes the - definition of an existing policy. + ALTER POLICY changes the definition of an existing + row-level security policy. To use ALTER POLICY, you must own the table that the policy applies to. + + + In the second form of ALTER POLICY, the role list, + using_expression, and + check_expression are replaced + independently if specified. When one of those clauses is omitted, the + corresponding part of the policy is unchanged. + @@ -79,9 +88,9 @@ ALTER POLICY name ON role_name - The role to which the policy applies. Multiple roles can be specified at one time. - To apply the policy to all roles, use PUBLIC, which is also - the default. + The role(s) to which the policy applies. Multiple roles can be + specified at one time. To apply the policy to all roles, + use PUBLIC. diff --git a/doc/src/sgml/ref/create_policy.sgml b/doc/src/sgml/ref/create_policy.sgml index b714cb29b4..4aaeb12102 100644 --- a/doc/src/sgml/ref/create_policy.sgml +++ b/doc/src/sgml/ref/create_policy.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation CREATE POLICY - define a new policy for a table + define a new row level security policy for a table @@ -33,40 +33,34 @@ CREATE POLICY name ON Description - The CREATE POLICY command defines a new policy for a - table. Note that row-level security must also be enabled on the table using - ALTER TABLE in order for created policies to be applied. + The CREATE POLICY command defines a new row-level + security policy for a table. Note that row-level security must be + enabled on the table (using ALTER TABLE ... ENABLE ROW LEVEL + SECURITY) in order for created policies to be applied. A policy grants the permission to select, insert, update, or delete rows that match the relevant policy expression. Existing table rows are - checked against the expression specified via USING, while new rows that - would be created via INSERT or UPDATE are checked against the expression - specified via WITH CHECK. When a USING expression returns true for a given - row then that row is visible to the user, while if a false or null is - returned then the row is not visible. When a WITH CHECK expression - returns true for a row then that row is added, while if a false or null is - returned then an error occurs. - - - - Generally, the system will enforce filter conditions imposed using - security policies prior to qualifications that appear in the query itself, - in order to prevent the inadvertent exposure of the protected data to - user-defined functions which might not be trustworthy. However, - functions and operators marked by the system (or the system - administrator) as LEAKPROOF may be evaluated before policy - expressions, as they are assumed to be trustworthy. + checked against the expression specified in USING, + while new rows that would be created via INSERT + or UPDATE are checked against the expression specified + in WITH CHECK. When a USING + expression returns true for a given row then that row is visible to the + user, while if false or null is returned then the row is not visible. + When a WITH CHECK expression returns true for a row + then that row is inserted or updated, while if false or null is returned + then an error occurs. For INSERT and UPDATE statements, WITH CHECK expressions are enforced after - BEFORE triggers are fired, and before any data modifications are made. - Thus a BEFORE ROW trigger may modify the data to be inserted, affecting - the result of the security policy check. WITH CHECK expressions are - enforced before any other constraints. + BEFORE triggers are fired, and before any actual data + modifications are made. Thus a BEFORE ROW trigger may + modify the data to be inserted, affecting the result of the security + policy check. WITH CHECK expressions are enforced + before any other constraints. @@ -79,18 +73,25 @@ CREATE POLICY name ON or (although ON CONFLICT DO + statement, they will be combined using OR (although ON CONFLICT DO UPDATE and INSERT policies are not combined in this way, but rather enforced as noted at each stage of ON CONFLICT execution). - Further, for commands that can have both USING + For commands that can have both USING and WITH CHECK policies (ALL - and UPDATE), if no WITH CHECK policy - is defined, then the USING policy will be used for both - what rows are visible (normal USING case) and which rows - will be allowed to be added (WITH CHECK case). + and UPDATE), if no WITH CHECK + policy is defined, then the USING policy will be used + both for which rows are visible (normal USING case) + and for which rows will be allowed to be added (WITH + CHECK case). + + + + If row-level security is enabled for a table, but no applicable policies + exist, a default deny policy is assumed, so that no rows will + be visible or updatable. @@ -136,7 +137,7 @@ CREATE POLICY name ON role_name - The roles to which the policy is to be applied. The default is + The role(s) to which the policy is to be applied. The default is PUBLIC, which will apply the policy to all roles. @@ -149,10 +150,13 @@ CREATE POLICY name ON SQL conditional expression (returning boolean). The conditional expression cannot contain any aggregate or window functions. This expression will be added - to queries that refer to the table if row level security is enabled - and rows for which the expression returns true will be visible. Any + to queries that refer to the table if row level security is enabled. + Rows for which the expression returns true will be visible. Any rows for which the expression returns false or null will not be - visible to the user. + visible to the user (in a SELECT), and will not be + available for modification (in an UPDATE + or DELETE). Such rows are silently suppressed; no error + is reported. @@ -163,12 +167,15 @@ CREATE POLICY name ON Any SQL conditional expression (returning boolean). The conditional expression cannot contain - any aggregate or window functions. This expression will be used with + any aggregate or window functions. This expression will be used in INSERT and UPDATE queries against - the table if row level security is enabled and only rows where the + the table if row level security is enabled. Only rows for which the expression evaluates to true will be allowed. An error will be thrown if the expression evaluates to false or null for any of the records - inserted or any of the records that result from the update. + inserted or any of the records that result from the update. Note that + the check_expression is + evaluated against the proposed new contents of the row, not the + original contents. @@ -176,7 +183,7 @@ CREATE POLICY name ON - Per-Command policies + Per-Command Policies @@ -189,25 +196,25 @@ CREATE POLICY name ON ALL policy exists and more specific policies exist, then both the ALL policy and the more specific policy (or policies) will be combined using - or, as usual for overlapping policies. + OR, as usual for overlapping policies. Additionally, ALL policies will be applied to both the selection side of a query and the modification side, using - the USING policy for both if only a USING policy has been defined. + the USING expression for both cases if only + a USING expression has been defined. As an example, if an UPDATE is issued, then the - ALL policy will be applicable to both what the - UPDATE will be able to select out as rows to be - updated (with the USING expression being applied), and it will be - applied to rows that result from the UPDATE - statement, to check if they are permitted to be added to the table - (using the WITH CHECK expression, if defined, and the USING expression - otherwise). If an INSERT or UPDATE command attempts to add rows to - the table that do not pass the ALL WITH CHECK - expression, the entire command will be aborted. Note that if only a - USING clause is specified then that clause will be - used for both USING and - WITH CHECK cases. + ALL policy will be applicable both to what the + UPDATE will be able to select as rows to be + updated (applying the USING expression), + and to the resulting updated rows, to check if they are permitted + to be added to the table (applying the WITH CHECK + expression, if defined, and the USING expression + otherwise). If an INSERT + or UPDATE command attempts to add rows to the + table that do not pass the ALL + policy's WITH CHECK expression, the entire + command will be aborted. @@ -221,13 +228,12 @@ CREATE POLICY name ON SELECT permissions are required on the relation the policy is defined for. The result is that only those records from the relation that pass the SELECT policy will be - returned during a SELECT query, even if other - records exist in the relation and that queries which require - SELECT permissions, such as + returned during a SELECT query, and that queries + that require SELECT permissions, such as UPDATE, will also only see those records - which are allowed by the SELECT policy. - The SELECT policy only accepts the - USING expression as it only applies in cases where + that are allowed by the SELECT policy. + A SELECT policy cannot have a WITH + CHECK expression, as it only applies in cases where records are being retrieved from the relation. @@ -240,16 +246,16 @@ CREATE POLICY name ON INSERT for a policy means that it will apply to INSERT commands. Rows being inserted that do not pass this policy will result in a policy violation error, and the - entire INSERT command will be aborted. The - INSERT policy only accepts the - WITH CHECK expression as it only applies in cases + entire INSERT command will be aborted. + An INSERT policy cannot have + a USING expression, as it only applies in cases where records are being added to the relation. Note that INSERT with ON CONFLICT DO - UPDATE requires that any INSERT policy - WITH CHECK expression passes for any rows appended - to the relation by the INSERT path only. + UPDATE checks INSERT policies' + WITH CHECK expressions only for rows appended + to the relation by the INSERT path. @@ -261,19 +267,15 @@ CREATE POLICY name ON UPDATE for a policy means that it will apply to UPDATE commands (or auxiliary ON CONFLICT DO UPDATE clauses of INSERT - commands). As UPDATE involves pulling an existing - record and then making changes to some portion (but possibly not all) - of the record, the UPDATE policy accepts both a - USING expression and a WITH CHECK - expression. - - - - The USING expression will be used to - determine which records the UPDATE command will see - to operate against, while the WITH CHECK expression - defines what rows are allowed to be added back into the relation - (similar to the INSERT policy). + commands). Since UPDATE involves pulling an + existing record and then making changes to some portion (but + possibly not all) of the record, UPDATE + policies accept both a USING expression and + a WITH CHECK expression. + The USING expression determines which records + the UPDATE command will see to operate against, + while the WITH CHECK expression defines which + modified rows are allowed to be stored back into the relation. @@ -285,15 +287,15 @@ CREATE POLICY name ON SELECT related policies found) with the USING clause of the UPDATE policy using AND. Therefore, in order for a user to be able to - UPDATE a specific set of rows using a - WHERE clause, the user must have access to the - row(s) through a SELECT or ALL - policy and the row(s) must be pass the UPDATE USING + UPDATE specific rows, the user must have access + to the row(s) through a SELECT + or ALL policy and the row(s) must pass + the UPDATE policy's USING expression. - + - Any rows whose resulting values do not pass the + Any rows whose updated values do not pass the WITH CHECK expression will cause an error, and the entire command will be aborted. If only a USING clause is specified, then that clause will be used for both @@ -307,9 +309,10 @@ CREATE POLICY name ON WITH CHECK expression. This UPDATE policy must always pass when the UPDATE path is taken. Any existing row that - necessitates that the UPDATE path be taken must pass - the (UPDATE or ALL) USING qualifications (combined - using or), which are always enforced as WITH CHECK + necessitates that the UPDATE path be taken must + pass the (UPDATE or ALL) + USING qualifications (combined using OR), which + are always enforced as WITH CHECK options in this context. (The UPDATE path will never be silently avoided; an error will be thrown instead.) Finally, the final row appended to the relation must pass @@ -327,8 +330,9 @@ CREATE POLICY name ON DELETE commands. Only rows that pass this policy will be seen by a DELETE command. There can be rows that are visible through a SELECT that are - not seen by a DELETE, if they do not pass the - USING expression for the DELETE. + not available for deletion, if they do not pass the + USING expression for + the DELETE policy. @@ -340,17 +344,18 @@ CREATE POLICY name ON SELECT related policies found) with the USING clause of the DELETE policy using AND. Therefore, in order for a user to be able to - DELETE a specific set of rows using a - WHERE clause, the user must have access to the - row(s) through a SELECT or ALL - policy and the row(s) must be pass the DELETE USING + DELETE specific rows, the user must have access + to the row(s) through a SELECT + or ALL policy and the row(s) must pass + the DELETE policy's USING expression. - + - The DELETE policy only accepts the - USING expression as it only applies in cases where - records are being extracted from the relation for deletion. + A DELETE policy cannot have a WITH + CHECK expression, as it only applies in cases where + records are being deleted from the relation, so that there is no + new row to check. @@ -367,45 +372,58 @@ CREATE POLICY name ON - Note that while policies will be applied for explicit queries against tables - in the system, they are not applied when the system is performing internal + While policies will be applied for explicit queries against tables + in the database, they are not applied when the system is performing internal referential integrity checks or validating constraints. This means there are indirect ways to determine that a given value exists. An example of this is - attempting to insert a duplicate value into a column which is the primary key + attempting to insert a duplicate value into a column that is a primary key or has a unique constraint. If the insert fails then the user can infer that - the value already exists. (This example assumes that the user is permitted by + the value already exists. (This example assumes that the user is permitted by policy to insert records which they are not allowed to see.) Another example is where a user is allowed to insert into a table which references another, otherwise hidden table. Existence can be determined by the user inserting values into the referencing table, where success would indicate that the value exists in the referenced table. These issues can be addressed by - carefully crafting policies that prevent users from being able to insert, + carefully crafting policies to prevent users from being able to insert, delete, or update records at all which might possibly indicate a value they are not otherwise able to see, or by using generated values (e.g., surrogate - keys) instead. + keys) instead of keys with external meanings. - Regarding how policy expressions interact with the user: as the expressions + Generally, the system will enforce filter conditions imposed using + security policies prior to qualifications that appear in user queries, + in order to prevent inadvertent exposure of the protected data to + user-defined functions which might not be trustworthy. However, + functions and operators marked by the system (or the system + administrator) as LEAKPROOF may be evaluated before + policy expressions, as they are assumed to be trustworthy. + + + + Since policy expressions are added to the user's query directly, they will be run with the rights of the user running the overall query. Therefore, users who are using a given policy must be able to access any tables or functions referenced in the expression or they will simply receive a permission denied error when - attempting to query the table that has row-level security enabled. This does not change how views + attempting to query the table that has row-level security enabled. + This does not change how views work, however. As with normal queries and views, permission checks and policies for the tables which are referenced by a view will use the view owner's rights and any policies which apply to the view owner. - When reducing the set of rows which a user has access to, through - modifications to relations referenced by Row-Level Security Policies or - Security Barrier Views, be aware that users with a currently open transaction - may be able to see updates to the rows that they are no longer allowed - access. Therefore, the best practice to avoid any possible leak of + When reducing the set of rows which users have access to, through + modifications to row-level security policies or security-barrier views, + be aware that users with a currently open transaction may be able to see + updates to rows that they are theoretically no longer allowed access to, + as the new policies may not be absorbed into existing query plans + immediately. Therefore, the best practice to avoid any possible leak of information when altering conditions that determine the visibility of specific rows is to ensure that affected users do not have any open - transactions, perhaps by ensuring they have no concurrent sessions running. + transactions, perhaps by ensuring they have no concurrent sessions + running. @@ -425,6 +443,7 @@ CREATE POLICY name ON + diff --git a/doc/src/sgml/ref/drop_policy.sgml b/doc/src/sgml/ref/drop_policy.sgml index c25bc61d9e..e5eaaa785b 100644 --- a/doc/src/sgml/ref/drop_policy.sgml +++ b/doc/src/sgml/ref/drop_policy.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation DROP POLICY - remove a policy from a table + remove a row level security policy from a table @@ -32,10 +32,9 @@ DROP POLICY [ IF EXISTS ] name ON < DROP POLICY removes the specified policy from the table. Note that if the last policy is removed for a table and the table still has row level security enabled via ALTER TABLE, then the - default-deny policy will be used. ALTER TABLE can be used - to disable row level security for a table using - DISABLE ROW SECURITY, whether policies for the table - exist or not. + default-deny policy will be used. ALTER TABLE ... DISABLE ROW + LEVEL SECURITY can be used to disable row level security for a + table, whether policies for the table exist or not.