This is an automated email from the ASF dual-hosted git repository. brads pushed a commit to branch trunk in repository https://gitbox.apache.org/repos/asf/cassandra.git
commit 756af29b7a7271f70e85e18b51f1b1906f33c1ff Author: Brad Schoening <[email protected]> AuthorDate: Wed Apr 23 15:25:25 2025 -0400 Update and syncronize cql_singlefile.adoc with CQL.textile updates. patch by Brad Schoening; reviewed by Jyothsna Konisa for CASSANDRA-20405 --- .../examples/BNF/alter_role_statement.bnf | 13 +- .../examples/BNF/alter_user_statement.bnf | 8 +- .../examples/BNF/create_role_statement.bnf | 15 +- .../examples/BNF/create_user_statement.bnf | 10 +- doc/modules/cassandra/examples/CQL/alter_role.cql | 5 +- doc/modules/cassandra/examples/CQL/create_role.cql | 5 +- doc/modules/cassandra/examples/CQL/create_user.cql | 1 + .../cassandra/examples/CQL/create_user_role.cql | 4 +- .../cassandra/examples/CQL/select_range.cql | 2 +- .../pages/developing/cql/cql_singlefile.adoc | 862 +-------------------- .../cassandra/pages/developing/cql/security.adoc | 57 +- 11 files changed, 105 insertions(+), 877 deletions(-) diff --git a/doc/modules/cassandra/examples/BNF/alter_role_statement.bnf b/doc/modules/cassandra/examples/BNF/alter_role_statement.bnf index 7b67608a55..4138a74c36 100644 --- a/doc/modules/cassandra/examples/BNF/alter_role_statement.bnf +++ b/doc/modules/cassandra/examples/BNF/alter_role_statement.bnf @@ -1 +1,12 @@ -alter_role_statement ::= ALTER ROLE [ IF EXISTS ] role_name WITH role_options +alter_role_statement ::= ALTER ROLE [ IF EXISTS ] role_name ( WITH <option> ( AND <option> )* )? + +<option> ::= PASSWORD = <string> + | HASHED PASSWORD = <string> + | GENERATED PASSWORD + | LOGIN = <boolean> + | SUPERUSER = <boolean> + | OPTIONS = <map_literal> + | ACCESS TO DATACENTERS <set_literal> + | ACCESS TO ALL DATACENTERS + | ACCESS FROM CIDRS <set_literal> + | ACCESS FROM ALL CIDRS diff --git a/doc/modules/cassandra/examples/BNF/alter_user_statement.bnf b/doc/modules/cassandra/examples/BNF/alter_user_statement.bnf index 06bef1b4dd..7b68de9083 100644 --- a/doc/modules/cassandra/examples/BNF/alter_user_statement.bnf +++ b/doc/modules/cassandra/examples/BNF/alter_user_statement.bnf @@ -1 +1,7 @@ -alter_user_statement ::= ALTER USER [ IF EXISTS ] role_name [ WITH [ HASHED ] PASSWORD string] [ user_option] +alter_user_statement ::= ALTER USER [ IF EXISTS ] role_name ( WITH <option> ( AND <option> )* )? + +<option> ::= PASSWORD = <string> + | HASHED PASSWORD = <string> + | GENERATED PASSWORD + | SUPERUSER + | NOSUPERUSER diff --git a/doc/modules/cassandra/examples/BNF/create_role_statement.bnf b/doc/modules/cassandra/examples/BNF/create_role_statement.bnf index 8e4e0cda80..9da5d0940f 100644 --- a/doc/modules/cassandra/examples/BNF/create_role_statement.bnf +++ b/doc/modules/cassandra/examples/BNF/create_role_statement.bnf @@ -1,12 +1,13 @@ create_role_statement ::= CREATE ROLE [ IF NOT EXISTS ] role_name [ WITH role_options# ] role_options ::= role_option ( AND role_option)* -role_option ::= PASSWORD '=' string - | HASHED PASSWORD '=' string - | LOGIN '=' boolean - | SUPERUSER '=' boolean - | OPTIONS '=' map_literal - | ACCESS TO DATACENTERS set_literal +role_option ::= PASSWORD = <string> + | HASHED PASSWORD = <string> + | GENERATED PASSWORD + | LOGIN = <boolean> + | SUPERUSER = <boolean> + | OPTIONS = <map_literal> + | ACCESS TO DATACENTERS <set_literal> | ACCESS TO ALL DATACENTERS - | ACCESS FROM CIDRS set_literal + | ACCESS FROM CIDRS <set_literal> | ACCESS FROM ALL CIDRS diff --git a/doc/modules/cassandra/examples/BNF/create_user_statement.bnf b/doc/modules/cassandra/examples/BNF/create_user_statement.bnf index e090e38413..060e63c4c4 100644 --- a/doc/modules/cassandra/examples/BNF/create_user_statement.bnf +++ b/doc/modules/cassandra/examples/BNF/create_user_statement.bnf @@ -1,4 +1,6 @@ -create_user_statement ::= CREATE USER [ IF NOT EXISTS ] role_name - [ WITH [ HASHED ] PASSWORD string ] - [ user_option ] -user_option: SUPERUSER | NOSUPERUSER +create_user_statement ::= CREATE USER [ IF NOT EXISTS ] role_name ( WITH <option> ( AND <option> )* )? +<option> ::= PASSWORD = <string> + | HASHED PASSWORD = <string> + | GENERATED PASSWORD + | SUPERUSER + | NOSUPERUSER diff --git a/doc/modules/cassandra/examples/CQL/alter_role.cql b/doc/modules/cassandra/examples/CQL/alter_role.cql index 516262152c..269561aaaa 100644 --- a/doc/modules/cassandra/examples/CQL/alter_role.cql +++ b/doc/modules/cassandra/examples/CQL/alter_role.cql @@ -1,4 +1,5 @@ ALTER ROLE bob WITH PASSWORD = 'PASSWORD_B' AND SUPERUSER = false; ALTER ROLE bob WITH HASHED PASSWORD = '$2a$10$JSJEMFm6GeaW9XxT5JIheuEtPvat6i7uKbnTcxX3c1wshIIsGyUtG' AND SUPERUSER = false; -ALTER ROLE rob WITH LOGIN = true and PASSWORD = 'password_c' AND ACCESS FROM ALL CIDRS; -ALTER ROLE hob WITH LOGIN = true and PASSWORD = 'password_d' AND ACCESS FROM CIDRS { 'region1' }; +ALTER ROLE rob WITH LOGIN = true AND PASSWORD = 'password_c' AND ACCESS FROM ALL CIDRS; +ALTER ROLE IF EXISTS hob WITH LOGIN = true AND PASSWORD = 'password_d' AND ACCESS FROM CIDRS { 'region1' }; +ALTER ROLE IF EXISTS hob WITH LOGIN = true AND GENERATED PASSWORD; diff --git a/doc/modules/cassandra/examples/CQL/create_role.cql b/doc/modules/cassandra/examples/CQL/create_role.cql index 593556039e..01ee8ebb80 100644 --- a/doc/modules/cassandra/examples/CQL/create_role.cql +++ b/doc/modules/cassandra/examples/CQL/create_role.cql @@ -5,5 +5,6 @@ CREATE ROLE bob WITH PASSWORD = 'password_b' AND LOGIN = true AND SUPERUSER = tr CREATE ROLE carlos WITH OPTIONS = { 'custom_option1' : 'option1_value', 'custom_option2' : 99 }; CREATE ROLE alice WITH PASSWORD = 'password_a' AND LOGIN = true AND ACCESS TO DATACENTERS {'DC1', 'DC3'}; CREATE ROLE alice WITH PASSWORD = 'password_a' AND LOGIN = true AND ACCESS TO ALL DATACENTERS; -CREATE ROLE bob WITH LOGIN = true and PASSWORD = 'password_d' AND ACCESS FROM CIDRS { 'region1', 'region2' }; -CREATE ROLE hob WITH LOGIN = true and PASSWORD = 'password_c' AND ACCESS FROM ALL CIDRS; +CREATE ROLE bob WITH LOGIN = true AND PASSWORD = 'password_d' AND ACCESS FROM CIDRS { 'region1', 'region2' }; +CREATE ROLE hob WITH LOGIN = true AND PASSWORD = 'password_c' AND ACCESS FROM ALL CIDRS; +CREATE ROLE tom WITH LOGIN = true AND GENERATED PASSWORD; diff --git a/doc/modules/cassandra/examples/CQL/create_user.cql b/doc/modules/cassandra/examples/CQL/create_user.cql index d7542271bd..7136976c86 100644 --- a/doc/modules/cassandra/examples/CQL/create_user.cql +++ b/doc/modules/cassandra/examples/CQL/create_user.cql @@ -1,3 +1,4 @@ CREATE USER alice WITH PASSWORD 'password_a' SUPERUSER; CREATE USER bob WITH PASSWORD 'password_b' NOSUPERUSER; CREATE USER bob WITH HASHED PASSWORD '$2a$10$JSJEMFm6GeaW9XxT5JIheuEtPvat6i7uKbnTcxX3c1wshIIsGyUtG' NOSUPERUSER; +CREATE USER tom WITH GENERATED PASSWORD; diff --git a/doc/modules/cassandra/examples/CQL/create_user_role.cql b/doc/modules/cassandra/examples/CQL/create_user_role.cql index ff44c75a51..a03ada975e 100644 --- a/doc/modules/cassandra/examples/CQL/create_user_role.cql +++ b/doc/modules/cassandra/examples/CQL/create_user_role.cql @@ -13,5 +13,5 @@ CREATE ROLE alice WITH PASSWORD = 'password_a' AND LOGIN = true; CREATE USER alice WITH PASSWORD 'password_a'; CREATE ROLE alice WITH PASSWORD = 'password_a' AND LOGIN = true; -CREATE ROLE rob WITH LOGIN = true and PASSWORD = 'password_c' AND ACCESS FROM ALL CIDRS; -CREATE ROLE hob WITH LOGIN = true and PASSWORD = 'password_d' AND ACCESS FROM CIDRS { 'region1' }; +CREATE ROLE rob WITH LOGIN = true AND PASSWORD = 'password_c' AND ACCESS FROM ALL CIDRS; +CREATE ROLE hob WITH LOGIN = true AND PASSWORD = 'password_d' AND ACCESS FROM CIDRS { 'region1' }; diff --git a/doc/modules/cassandra/examples/CQL/select_range.cql b/doc/modules/cassandra/examples/CQL/select_range.cql index fcf3bd5833..eab1d5dd43 100644 --- a/doc/modules/cassandra/examples/CQL/select_range.cql +++ b/doc/modules/cassandra/examples/CQL/select_range.cql @@ -1 +1 @@ -SELECT * FROM t2 WHERE a = 0 AND b > 0 and b <= 3; +SELECT * FROM t2 WHERE a = 0 AND b > 0 AND b <= 3; diff --git a/doc/modules/cassandra/pages/developing/cql/cql_singlefile.adoc b/doc/modules/cassandra/pages/developing/cql/cql_singlefile.adoc index f2bf215906..87cd9cba22 100644 --- a/doc/modules/cassandra/pages/developing/cql/cql_singlefile.adoc +++ b/doc/modules/cassandra/pages/developing/cql/cql_singlefile.adoc @@ -377,7 +377,7 @@ link:#createKeyspaceStmt[`CREATE KEYSPACE`] statement. _Syntax:_ [source,bnf] -::= DROP KEYSPACE ( IF EXISTS )? +::= DROP KEYSPACE [ IF EXISTS ] _Sample:_ @@ -1066,10 +1066,10 @@ _Syntax:_ [source,bnf] ---- -::= ALTER TYPE (IF EXISTS)? +::= ALTER TYPE [ IF EXISTS ] -::= ADD (IF NOT EXISTS)? -| RENAME (IF EXISTS)? TO ( AND TO )* +::= ADD [ IF NOT EXISTS ] +| RENAME [ IF EXISTS ] TO ( AND TO )* ---- _Sample:_ @@ -1090,7 +1090,7 @@ type of existing fields. If the type does not exist, the statement will return a _Syntax:_ [source,bnf] -::= DROP TYPE ( IF EXISTS )? +::= DROP TYPE [ IF EXISTS ] The `DROP TYPE` statement results in the immediate, irreversible removal of a type. Attempting to drop a type that is still in use by another @@ -1787,632 +1787,7 @@ doing'', you can force the execution of this query by using SELECT firstname, lastname FROM users WHERE birth_year = 1981 AND country = 'FR' ALLOW FILTERING; -[[databaseRoles]] -=== Database Roles - -[[createRoleStmt]] -==== CREATE ROLE - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/create_role_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/create_role.cql[] - -By default roles do not possess `LOGIN` privileges or `SUPERUSER` -status. - -link:#permissions[Permissions] on database resources are granted to -roles; types of resources include keyspaces, tables, functions and roles -themselves. Roles may be granted to other roles to create hierarchical -permissions structures; in these hierarchies, permissions and -`SUPERUSER` status are inherited, but the `LOGIN` privilege is not. - -If a role has the `LOGIN` privilege, clients may identify as that role -when connecting. For the duration of that connection, the client will -acquire any roles and privileges granted to that role. - -Only a client with the `CREATE` permission on the database roles -resource may issue `CREATE ROLE` requests (see the -link:#permissions[relevant section] below), unless the client is a -`SUPERUSER`. Role management in Cassandra is pluggable and custom -implementations may support only a subset of the listed options. - -Role names should be quoted if they contain non-alphanumeric characters. - -[[createRolePwd]] -===== Setting credentials for internal authentication - -Use the `WITH PASSWORD` clause to set a password for internal -authentication, enclosing the password in single quotation marks. + -If internal authentication has not been set up or the role does not have -`LOGIN` privileges, the `WITH PASSWORD` clause is not necessary. - -[[createRoleConditional]] -===== Creating a role conditionally - -Attempting to create an existing role results in an invalid query -condition unless the `IF NOT EXISTS` option is used. If the option is -used and the role exists, the statement is a no-op. - -[source,sql] -include::cassandra:example$CQL/create_role_ifnotexists.cql[] - -[[alterRoleStmt]] -==== ALTER ROLE - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/alter_role_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/alter_role.cql[] - -If the role does not exist, the statement will return an error, unless `IF EXISTS` is used in which case the operation is a no-op. - -Conditions on executing `ALTER ROLE` statements: - -* A client must have `SUPERUSER` status to alter the `SUPERUSER` status -of another role -* A client cannot alter the `SUPERUSER` status of any role it currently -holds -* A client can only modify certain properties of the role with which it -identified at login (e.g. `PASSWORD`) -* To modify properties of a role, the client must be granted `ALTER` -link:#permissions[permission] on that role - -[[dropRoleStmt]] -==== DROP ROLE - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/drop_role_statement.bnf[] - -_Sample:_ - -[source,sql] ----- -DROP ROLE alice; -DROP ROLE IF EXISTS bob; ----- - -`DROP ROLE` requires the client to have `DROP` -link:#permissions[permission] on the role in question. In addition, -client may not `DROP` the role with which it identified at login. -Finally, only a client with `SUPERUSER` status may `DROP` another -`SUPERUSER` role. + -Attempting to drop a role which does not exist results in an invalid -query condition unless the `IF EXISTS` option is used. If the option is -used and the role does not exist the statement is a no-op. - -[[grantRoleStmt]] -==== GRANT ROLE - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/grant_role_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/grant_role.cql[] - -This statement grants the `report_writer` role to `alice`. Any -permissions granted to `report_writer` are also acquired by `alice`. + -Roles are modelled as a directed acyclic graph, so circular grants are -not permitted. The following examples result in error conditions: - -[source,sql] ----- -GRANT role_a TO role_b; -GRANT role_b TO role_a; ----- - -[source,sql] ----- -GRANT role_a TO role_b; -GRANT role_b TO role_c; -GRANT role_c TO role_a; ----- - -[[revokeRoleStmt]] -==== REVOKE ROLE - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/revoke_role_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/revoke_role.cql[] - -This statement revokes the `report_writer` role from `alice`. Any -permissions that `alice` has acquired via the `report_writer` role are -also revoked. - -[[listRolesStmt]] -===== LIST ROLES - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/list_roles_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/list_roles.cql[] - -Return all known roles in the system, this requires `DESCRIBE` -permission on the database roles resource. - -[source,sql] -include::cassandra:example$CQL/list_roles_of.cql[] - -Enumerate all roles granted to `alice`, including those transitively -acquired. - -[source,sql] -include::cassandra:example$CQL/list_roles_nonrecursive.cql[] - -List all roles directly granted to `bob`. - -[[createUserStmt]] -==== CREATE USER - -Prior to the introduction of roles in Cassandra 2.2, authentication and -authorization were based around the concept of a `USER`. For backward -compatibility, the legacy syntax has been preserved with `USER` centric -statements becoming synonyms for the `ROLE` based equivalents. - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/create_user_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/create_user.cql[] - -`CREATE USER` is equivalent to `CREATE ROLE` where the `LOGIN` option is -`true`. So, the following pairs of statements are equivalent: - -[source,sql] ----- -include::cassandra:example$CQL/create_user_role.cql[] ----- - -[[alterUserStmt]] -==== ALTER USER - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/alter_user_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/alter_user.cql[] - -If the user does not exist, the statement will return an error, unless `IF EXISTS` is used in which case the operation is a no-op. - -[[dropUserStmt]] -==== DROP USER - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/drop_user_statement.bnf[] - -_Sample:_ - -[source,sql] ----- -DROP USER alice; -DROP USER IF EXISTS bob; ----- - -[[listUsersStmt]] -==== LIST USERS - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/list_users_statement.bnf[] - -_Sample:_ - -[source,sql] -LIST USERS; - -This statement is equivalent to - -[source,sql] -LIST ROLES; - -but only roles with the `LOGIN` privilege are included in the output. - -[[databaseIdentity]] -=== Database Identities - -[[AddIdentityStmt]] -==== ADD IDENTITY - -_Syntax:_ - -[source,bnf] -::= ADD IDENTITY ( IF NOT EXISTS )? TO ROLE ? - -_Sample:_ - -[source,sql] -ADD IDENTITY 'id1' TO ROLE 'role1'; - -Only a user with privileges to add roles can add identities - -Role names & Identity names should be quoted if they contain non-alphanumeric characters. - -[[addIdentityConditional]] -===== Adding an identity conditionally - -Attempting to add an existing identity results in an invalid query -condition unless the `IF NOT EXISTS` option is used. If the option is -used and the identity exists, the statement is a no-op. - -[source,sql] -ADD IDENTITY IF NOT EXISTS 'id1' TO ROLE 'role1'; - -[[dropIdentityStmt]] -==== DROP IDENTITY - -_Syntax:_ - -[source,bnf] -::= DROP IDENTITY ( IF EXISTS )? - -_Sample:_ - -[source,sql] ----- -DROP IDENTITY 'testIdentity'; -DROP IDENTITY IF EXISTS 'testIdentity'; ----- - -Only a user with privileges to drop roles can remove identities - -Attempting to drop an Identity which does not exist results in an invalid -query condition unless the `IF EXISTS` option is used. If the option is -used and the identity does not exist the statement is a no-op. - -[[dataControl]] -=== Data Control - -==== Permissions - -Permissions on resources are granted to roles; there are several -types of resources in Cassandra and each type is modelled -hierarchically: - -* The hierarchy of Data resources, Keyspaces and Tables has the -structure `ALL KEYSPACES` -> `KEYSPACE` -> `TABLE` -* Function resources have the structure `ALL FUNCTIONS` -> `KEYSPACE` -> -`FUNCTION` -* Resources representing roles have the structure `ALL ROLES` -> `ROLE` -* Resources representing JMX ObjectNames, which map to sets of -MBeans/MXBeans, have the structure `ALL MBEANS` -> `MBEAN` - -Permissions can be granted at any level of these hierarchies, and they -flow downwards. So granting a permission on a resource higher up the -chain automatically grants that same permission on all resources lower -down. For example, granting `SELECT` on a `KEYSPACE` automatically -grants it on all `TABLES` in that `KEYSPACE`. Likewise, granting a -permission on `ALL FUNCTIONS` grants it on every defined function, -regardless of which keyspace it is scoped in. It is also possible to -grant permissions on all functions scoped to a particular keyspace. - -Modifications to permissions are visible to existing client sessions; -that is, connections need not be re-established following permissions -changes. - -The full set of available permissions is: - -* `CREATE` -* `ALTER` -* `DROP` -* `SELECT` -* `MODIFY` -* `AUTHORIZE` -* `DESCRIBE` -* `EXECUTE` -* `UNMASK` -* `SELECT_MASKED` - -Not all permissions are applicable to every type of resource. For -instance, `EXECUTE` is only relevant in the context of functions or -mbeans; granting `EXECUTE` on a resource representing a table is -nonsensical. Attempting to `GRANT` a permission on resource to which it -cannot be applied results in an error response. The following -illustrates which permissions can be granted on which types of resource, -and which statements are enabled by that permission. - -[cols=",,,,,",options="header",] -|=== -|permission |resource |operations | | | -|`CREATE` |`ALL KEYSPACES` |`CREATE KEYSPACE` <br> `CREATE TABLE` in any -keyspace | | | - -|`CREATE` |`KEYSPACE` |`CREATE TABLE` in specified keyspace | | | - -|`CREATE` |`ALL FUNCTIONS` |`CREATE FUNCTION` in any keyspace <br> -`CREATE AGGREGATE` in any keyspace | | | - -|`CREATE` |`ALL FUNCTIONS IN KEYSPACE` |`CREATE FUNCTION` in keyspace -<br> `CREATE AGGREGATE` in keyspace | | | - -|`CREATE` |`ALL ROLES` |`CREATE ROLE` | | | - -|`ALTER` |`ALL KEYSPACES` |`ALTER KEYSPACE` <br> `ALTER TABLE` in any -keyspace | | | - -|`ALTER` |`KEYSPACE` |`ALTER KEYSPACE` <br> `ALTER TABLE` in keyspace | -| | - -|`ALTER` |`TABLE` |`ALTER TABLE` | | | - -|`ALTER` |`ALL FUNCTIONS` |`CREATE FUNCTION` replacing any existing <br> -`CREATE AGGREGATE` replacing any existing | | | - -|`ALTER` |`ALL FUNCTIONS IN KEYSPACE` |`CREATE FUNCTION` replacing -existing in keyspace <br> `CREATE AGGREGATE` replacing any existing in -keyspace | | | - -|`ALTER` |`FUNCTION` |`CREATE FUNCTION` replacing existing <br> -`CREATE AGGREGATE` replacing existing | | | - -|`ALTER` |`ALL ROLES` |`ALTER ROLE` on any role | | | - -|`ALTER` |`ROLE` |`ALTER ROLE` | | | - -|`DROP` |`ALL KEYSPACES` |`DROP KEYSPACE` <br> `DROP TABLE` in any -keyspace | | | - -|`DROP` |`KEYSPACE` |`DROP TABLE` in specified keyspace | | | - -|`DROP` |`TABLE` |`DROP TABLE` | | | - -|`DROP` |`ALL FUNCTIONS` |`DROP FUNCTION` in any keyspace <br> -`DROP AGGREGATE` in any existing | | | - -|`DROP` |`ALL FUNCTIONS IN KEYSPACE` |`DROP FUNCTION` in keyspace <br> -`DROP AGGREGATE` in existing | | | - -|`DROP` |`FUNCTION` |`DROP FUNCTION` | | | - -|`DROP` |`ALL ROLES` |`DROP ROLE` on any role | | | - -|`DROP` |`ROLE` |`DROP ROLE` | | | - -|`SELECT` |`ALL KEYSPACES` |`SELECT` on any table | | | - -|`SELECT` |`KEYSPACE` |`SELECT` on any table in keyspace | | | - -|`SELECT` |`TABLE` |`SELECT` on specified table | | | - -|`SELECT` |`ALL MBEANS` |Call getter methods on any mbean | | | - -|`SELECT` |`MBEANS` |Call getter methods on any mbean matching a -wildcard pattern | | | - -|`SELECT` |`MBEAN` |Call getter methods on named mbean | | | - -|`MODIFY` |`ALL KEYSPACES` |`INSERT` on any table <br> `UPDATE` on any -table <br> `DELETE` on any table <br> `TRUNCATE` on any table | | | - -|`MODIFY` |`KEYSPACE` |`INSERT` on any table in keyspace <br> `UPDATE` -on any table in keyspace <br> `DELETE` on any table in keyspace <br> -`TRUNCATE` on any table in keyspace |`MODIFY` |`TABLE` |`INSERT` <br> -`UPDATE` <br> `DELETE` <br> `TRUNCATE` - -|`MODIFY` |`ALL MBEANS` |Call setter methods on any mbean | | | - -|`MODIFY` |`MBEANS` |Call setter methods on any mbean matching a -wildcard pattern | | | - -|`MODIFY` |`MBEAN` |Call setter methods on named mbean | | | - -|`AUTHORIZE` |`ALL KEYSPACES` |`GRANT PERMISSION` on any table <br> -`REVOKE PERMISSION` on any table | | | - -|`AUTHORIZE` |`KEYSPACE` |`GRANT PERMISSION` on table in keyspace <br> -`REVOKE PERMISSION` on table in keyspace | | | - -|`AUTHORIZE` |`TABLE` |`GRANT PERMISSION` <br> `REVOKE PERMISSION` | | | - -|`AUTHORIZE` |`ALL FUNCTIONS` |`GRANT PERMISSION` on any function <br> -`REVOKE PERMISSION` on any function | | | - -|`AUTHORIZE` |`ALL FUNCTIONS IN KEYSPACE` |`GRANT PERMISSION` in -keyspace <br> `REVOKE PERMISSION` in keyspace | | | - -|`AUTHORIZE` |`ALL FUNCTIONS IN KEYSPACE` |`GRANT PERMISSION` in -keyspace <br> `REVOKE PERMISSION` in keyspace | | | - -|`AUTHORIZE` |`FUNCTION` |`GRANT PERMISSION` <br> `REVOKE PERMISSION` | -| | - -|`AUTHORIZE` |`ALL MBEANS` |`GRANT PERMISSION` on any mbean <br> -`REVOKE PERMISSION` on any mbean | | | - -|`AUTHORIZE` |`MBEANS` |`GRANT PERMISSION` on any mbean matching a -wildcard pattern <br> `REVOKE PERMISSION` on any mbean matching a -wildcard pattern | | | - -|`AUTHORIZE` |`MBEAN` |`GRANT PERMISSION` on named mbean <br> -`REVOKE PERMISSION` on named mbean | | | - -|`AUTHORIZE` |`ALL ROLES` |`GRANT ROLE` grant any role <br> -`REVOKE ROLE` revoke any role | | | - -|`AUTHORIZE` |`ROLES` |`GRANT ROLE` grant role <br> `REVOKE ROLE` revoke -role | | | - -|`DESCRIBE` |`ALL ROLES` |`LIST ROLES` all roles or only roles granted -to another, specified role | | | - -|`DESCRIBE` |@ALL MBEANS |Retrieve metadata about any mbean from the -platform’s MBeanServer | | | - -|`DESCRIBE` |@MBEANS |Retrieve metadata about any mbean matching a -wildcard patter from the platform’s MBeanServer | | | - -|`DESCRIBE` |@MBEAN |Retrieve metadata about a named mbean from the -platform’s MBeanServer | | | - -|`EXECUTE` |`ALL FUNCTIONS` |`SELECT`, `INSERT`, `UPDATE` using any -function <br> use of any function in `CREATE AGGREGATE` | | | - -|`EXECUTE` |`ALL FUNCTIONS IN KEYSPACE` |`SELECT`, `INSERT`, `UPDATE` -using any function in keyspace <br> use of any function in keyspace in -`CREATE AGGREGATE` | | | - -|`EXECUTE` |`FUNCTION` |`SELECT`, `INSERT`, `UPDATE` using function <br> -use of function in `CREATE AGGREGATE` | | | - -|`EXECUTE` |`ALL MBEANS` |Execute operations on any mbean | | | - -|`EXECUTE` |`MBEANS` |Execute operations on any mbean matching a -wildcard pattern | | | - -|`EXECUTE` |`MBEAN` |Execute operations on named mbean | | | - -|`UNMASK` |`ALL KEYSPACES` |See the clear contents of masked columns on any table | | | - -|`UNMASK` |`KEYSPACE` |See the clear contents of masked columns on any table in keyspace | | | - -|`UNMASK` |`TABLE` |See the clear contents of masked columns on the specified table | | | - -|`SELECT_MASKED` | `ALL KEYSPACES` | `SELECT` restricting masked columns on any table | | | - -|`SELECT_MASKED` | `KEYSPACE` | `SELECT` restricting masked columns on any table in specified keyspace | | | - -|`SELECT_MASKED` | `TABLE` | `SELECT` restricting masked columns on the specified table | | | -|=== - -[[grantPermissionsStmt]] -==== GRANT PERMISSION - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/grant_permission_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/grant_perm.cql[] - -This gives any user with the role `data_reader` permission to execute -`SELECT` statements on any table across all keyspaces - -[source,sql] -GRANT MODIFY ON KEYSPACE keyspace1 TO data_writer; - -This give any user with the role `data_writer` permission to perform -`UPDATE`, `INSERT`, `UPDATE`, `DELETE` and `TRUNCATE` queries on all -tables in the `keyspace1` keyspace - -[source,sql] -GRANT DROP ON keyspace1.table1 TO schema_owner; - -This gives any user with the `schema_owner` role permissions to `DROP` -`keyspace1.table1`. - -[source,sql] -include::cassandra:example$CQL/grant_execute.cql[] - -This grants any user with the `report_writer` role permission to execute -`SELECT`, `INSERT` and `UPDATE` queries which use the function -`keyspace1.user_function( int )` - -[source,sql] -include::cassandra:example$CQL/grant_describe.cql[] - -This grants any user with the `role_admin` role permission to view any -and all roles in the system with a `LIST ROLES` statement - -[[grantAll]] -===== GRANT ALL - -When the `GRANT ALL` form is used, the appropriate set of permissions is -determined automatically based on the target resource. - -[[autoGrantPermissions]] -===== Automatic Granting - -When a resource is created, via a `CREATE KEYSPACE`, `CREATE TABLE`, -`CREATE FUNCTION`, `CREATE AGGREGATE` or `CREATE ROLE` statement, the -creator (the role the database user who issues the statement is -identified as), is automatically granted all applicable permissions on -the new resource. - -[[revokePermissionsStmt]] -==== REVOKE PERMISSION - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/revoke_permission_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/revoke_perm.cql[] - -[[listPermissionsStmt]] -===== LIST PERMISSIONS - -_Syntax:_ - -[source,bnf] -include::cassandra:example$BNF/list_permissions_statement.bnf[] - -_Sample:_ - -[source,sql] -include::cassandra:example$CQL/list_perm.cql[] - -Show all permissions granted to `alice`, including those acquired -transitively from any other roles. - -[source,sql] -include::cassandra:example$CQL/list_all_perm.cql[] - -Show all permissions on `keyspace1.table1` granted to `bob`, including -those acquired transitively from any other roles. This also includes any -permissions higher up the resource hierarchy which can be applied to -`keyspace1.table1`. For example, should `bob` have `ALTER` permission on -`keyspace1`, that would be included in the results of this query. Adding -the `NORECURSIVE` switch restricts the results to only those permissions -which were directly granted to `bob` or one of `bob`’s roles. - -[source,sql] -include::cassandra:example$CQL/list_select_perm.cql[] - -Show any permissions granted to `carlos` or any of `carlos`’s roles, -limited to `SELECT` permissions on any resource. +include::security.adoc[] [[types]] === Data Types @@ -3582,227 +2957,4 @@ names as their name. |`macaddr` |=== -=== Changes - -The following describes the changes in each version of CQL. - -==== 3.4.3 - -* Support for `GROUP BY`. See link:#selectGroupBy[`<group-by>`] (see -https://issues.apache.org/jira/browse/CASSANDRA-10707)[CASSANDRA-10707]. - -==== 3.4.2 - -* Support for selecting elements and slices of a collection -(https://issues.apache.org/jira/browse/CASSANDRA-7396)[CASSANDRA-7396]. - -==== 3.4.2 - -* link:#updateOptions[`INSERT/UPDATE options`] for tables having a -default_time_to_live specifying a TTL of 0 will remove the TTL from the -inserted or updated values -* link:#alterTableStmt[`ALTER TABLE`] `ADD` and `DROP` now allow multiple -columns to be added/removed -* New link:#selectLimit[`PER PARTITION LIMIT`] option (see -https://issues.apache.org/jira/browse/CASSANDRA-7017)[CASSANDRA-7017]. -* link:#udfs[User-defined functions] can now instantiate `UDTValue` and -`TupleValue` instances via the new `UDFContext` interface (see -https://issues.apache.org/jira/browse/CASSANDRA-10818)[CASSANDRA-10818]. -* ``User-defined types''#createTypeStmt may now be stored in a -non-frozen form, allowing individual fields to be updated and deleted in -link:#updateStmt[`UPDATE` statements] and link:#deleteStmt[`DELETE` -statements], respectively. -(https://issues.apache.org/jira/browse/CASSANDRA-7423)[CASSANDRA-7423] - -==== 3.4.1 - -* Adds `CAST` functions. See link:#castFun[`Cast`]. - -==== 3.4.0 - -* Support for link:#createMVStmt[materialized views] -* link:#deleteStmt[`DELETE`] support for inequality expressions and `IN` -restrictions on any primary key columns -* link:#updateStmt[`UPDATE`] support for `IN` restrictions on any -primary key columns - -==== 3.3.1 - -* The syntax `TRUNCATE TABLE X` is now accepted as an alias for -`TRUNCATE X` - -==== 3.3.0 - -* Adds new link:#aggregates[aggregates] -* User-defined functions are now supported through -link:#createFunctionStmt[`CREATE FUNCTION`] and -link:#dropFunctionStmt[`DROP FUNCTION`]. -* User-defined aggregates are now supported through -link:#createAggregateStmt[`CREATE AGGREGATE`] and -link:#dropAggregateStmt[`DROP AGGREGATE`]. -* Allows double-dollar enclosed strings literals as an alternative to -single-quote enclosed strings. -* Introduces Roles to supersede user based authentication and access -control -* link:#usingdates[`Date`] and link:usingtime[`Time`] data types have -been added -* link:#json[`JSON`] support has been added -* `Tinyint` and `Smallint` data types have been added -* Adds new time conversion functions and deprecate `dateOf` and -`unixTimestampOf`. See link:#timeFun[`Time conversion functions`] - -==== 3.2.0 - -* User-defined types are now supported through -link:#createTypeStmt[`CREATE TYPE`], link:#alterTypeStmt[`ALTER TYPE`], -and link:#dropTypeStmt[`DROP TYPE`] -* link:#createIndexStmt[`CREATE INDEX`] now supports indexing collection -columns, including indexing the keys of map collections through the -`keys()` function -* Indexes on collections may be queried using the new `CONTAINS` and -`CONTAINS KEY` operators -* Tuple types were added to hold fixed-length sets of typed positional -fields (see the section on link:#types[types] ) -* link:#dropIndexStmt[`DROP INDEX`] now supports optionally specifying a -keyspace - -==== 3.1.7 - -* `SELECT` statements now support selecting multiple rows in a single -partition using an `IN` clause on combinations of clustering columns. -See link:#selectWhere[SELECT WHERE] clauses. -* `IF NOT EXISTS` and `IF EXISTS` syntax is now supported by -`CREATE USER` and `DROP USER` statements, respectively. - -==== 3.1.6 - -* A new link:#uuidFun[`uuid` method] has been added. -* Support for `DELETE ... IF EXISTS` syntax. - -==== 3.1.5 - -* It is now possible to group clustering columns in a relatiion, see -link:#selectWhere[SELECT WHERE] clauses. -* Added support for `STATIC` columns, see link:#createTableStatic[static -in CREATE TABLE]. - -==== 3.1.4 - -* `CREATE INDEX` now allows specifying options when creating CUSTOM -indexes (see link:#createIndexStmt[CREATE INDEX reference] ). - -==== 3.1.3 - -* Millisecond precision formats have been added to the timestamp parser -(see link:#usingtimestamps[working with dates] ). - -==== 3.1.2 - -* `NaN` and `Infinity` has been added as valid float constants. They are -now reserved keywords. In the unlikely case you we're using them as a -column identifier (or keyspace/table one), you will now need to double -quote them (see link:#identifiers[quote identifiers] ). - -==== 3.1.1 - -* `SELECT` statement now allows listing the partition keys (using the -`DISTINCT` modifier). See -https://issues.apache.org/jira/browse/CASSANDRA-4536[CASSANDRA-4536]. -* The syntax `c IN ?` is now supported in `WHERE` clauses. In that case, -the value expected for the bind variable will be a list of whatever type -`c` is. -* It is now possible to use named bind variables (using `:name` instead -of `?`). - -==== 3.1.0 - -* link:#alterTableStmt[ALTER TABLE] `DROP` option has been re-enabled for -CQL3 tables and has new semantics now: the space formerly used by -dropped columns will now be eventually reclaimed (post-compaction). You -should not read previously dropped columns unless you use timestamps -with microsecond precision (see -https://issues.apache.org/jira/browse/CASSANDRA-3919[CASSANDRA-3919] for -more details). -* `SELECT` statement now supports aliases in select clause. Aliases in -WHERE and ORDER BY clauses are not supported. See the -link:#selectStmt[section on select] for details. -* `CREATE` statements for `KEYSPACE`, `TABLE` and `INDEX` now supports -an `IF NOT EXISTS` condition. Similarly, `DROP` statements support a -`IF EXISTS` condition. -* `INSERT` statements optionally supports a `IF NOT EXISTS` condition -and `UPDATE` supports `IF` conditions. - -==== 3.0.5 - -* `SELECT`, `UPDATE`, and `DELETE` statements now allow empty `IN` -relations (see -https://issues.apache.org/jira/browse/CASSANDRA-5626)[CASSANDRA-5626]. - -==== 3.0.4 - -* Updated the syntax for custom link:#createIndexStmt[secondary -indexes]. -* Non-equal condition on the partition key are now never supported, even -for ordering partitioner as this was not correct (the order was *not* -the one of the type of the partition key). Instead, the `token` method -should always be used for range queries on the partition key (see -link:#selectWhere[WHERE clauses] ). - -==== 3.0.3 - -* Support for custom link:#createIndexStmt[secondary indexes] has been -added. - -==== 3.0.2 - -* Type validation for the link:#constants[constants] has been fixed. For -instance, the implementation used to allow `'2'` as a valid value for an -`int` column (interpreting it has the equivalent of `2`), or `42` as a -valid `blob` value (in which case `42` was interpreted as a hexadecimal -representation of the blob). This is no longer the case, type validation -of constants is now stricter. See the link:#types[data types] section -for details on which constant is allowed for which type. -* The type validation fixed of the previous point has lead to the -introduction of link:#constants[blobs constants] to allow inputing -blobs. Do note that while inputing blobs as strings constant is still -supported by this version (to allow smoother transition to blob -constant), it is now deprecated (in particular the link:#types[data -types] section does not list strings constants as valid blobs) and will -be removed by a future version. If you were using strings as blobs, you -should thus update your client code ASAP to switch blob constants. -* A number of functions to convert native types to blobs have also been -introduced. Furthermore, the token function is now also allowed in select -clauses. See the link:#functions[section on functions] for details. - -==== 3.0.1 - -* link:#usingtimestamps[Date strings] (and timestamps) are no longer -accepted as valid `timeuuid` values. Doing so was a bug in the sense -that date string are not valid `timeuuid`, and it was thus resulting in -https://issues.apache.org/jira/browse/CASSANDRA-4936[confusing -behaviors]. However, the following new methods have been added to help -working with `timeuuid`: `now`, `minTimeuuid`, `maxTimeuuid` , `dateOf` -and `unixTimestampOf`. See the link:#timeuuidFun[section dedicated to -these methods] for more detail. -* ``Float constants''#constants now support the exponent notation. In -other words, `4.2E10` is now a valid floating point value. - -=== Versioning - -Versioning of the CQL language adheres to the http://semver.org[Semantic -Versioning] guidelines. Versions take the form X.Y.Z where X, Y, and Z -are integer values representing major, minor, and patch level -respectively. There is no correlation between Cassandra release versions -and the CQL language version. - -[cols=",",options="header",] -|=== -|version |description -|Major |The major version _must_ be bumped when backward incompatible -changes are introduced. This should rarely occur. - -|Minor |Minor version increments occur when new, but backward -compatible, functionality is introduced. - -|Patch |The patch version is incremented when bugs are fixed. -|=== +include::changes.adoc[] diff --git a/doc/modules/cassandra/pages/developing/cql/security.adoc b/doc/modules/cassandra/pages/developing/cql/security.adoc index 2d438b9815..f34d391040 100644 --- a/doc/modules/cassandra/pages/developing/cql/security.adoc +++ b/doc/modules/cassandra/pages/developing/cql/security.adoc @@ -167,9 +167,9 @@ used and the role does not exist the statement is a no-op. DROP ROLE intentionally does not terminate any open user sessions. Currently connected sessions will remain connected and will retain the ability to perform any database actions which do not require -xref:cassandra:developing/cql/security.adoc#authorization[authorization]. +xref:cassandra:managing/operating/authorization/security.adoc#authorization[authorization]. However, if authorization is enabled, xref:cassandra:developing/cql/security.adoc#cql-permissions[permissions] of the dropped role are also revoked, -subject to the xref:cassandra:developing/cql/security.adoc#auth-caching[caching options] configured in xref:cassandra:developing/cql/configuring.adoc#cassandra.yaml[cassandra-yaml] file. +subject to the xref:cassandra:managing/operating/security.adoc#auth-caching[caching options] configured in xref:cassandra:developing/cql/configuring.adoc#cassandra.yaml[cassandra-yaml] file. Should a dropped role be subsequently recreated and have new xref:security.adoc#grant-permission-statement[permissions] or xref:security.adoc#grant-role-statement[roles]` granted to it, any client sessions still connected will acquire the newly granted permissions and roles. @@ -346,6 +346,59 @@ include::cassandra:example$BNF/list_users_statement.bnf[] Note that this statement is equivalent to xref:security.adoc#list-roles-statement[`LIST ROLES], but only roles with the `LOGIN` privilege are included in the output. +[[databaseIdentity]] +=== Database Identities + +[[AddIdentityStmt]] +==== ADD IDENTITY + +_Syntax:_ + +[source,bnf] +::= ADD IDENTITY [ IF NOT EXISTS ] id_name TO ROLE role_name + +_Sample:_ + +[source,sql] +ADD IDENTITY 'id1' TO ROLE 'role1'; + +Only a user with privileges to add roles can add identities. + +Role names & Identity names should be quoted if they contain non-alphanumeric characters. + +[[addIdentityConditional]] +===== Adding an identity conditionally + +Attempting to add an existing identity results in an invalid query +condition unless the `IF NOT EXISTS` option is used. If the option is +used and the identity exists, the statement is a no-op. + +[source,sql] +ADD IDENTITY [ IF NOT EXISTS ] 'id1' TO ROLE 'role1'; + +[[dropIdentityStmt]] +==== DROP IDENTITY + +_Syntax:_ + +[source,bnf] +::= DROP IDENTITY [ IF EXISTS ] + +_Sample:_ + +[source,sql] +---- +DROP IDENTITY 'testIdentity'; +DROP IDENTITY IF EXISTS 'testIdentity'; +---- + +Only a user with privileges to drop roles can remove identities + +Attempting to drop an identity which does not exist results in an invalid +query condition unless the `IF EXISTS` option is used. If the option is +used and the identity does not exist the statement is a no-op. + +[[dataControl]] == Data Control [[cql-permissions]] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
