Adding docs for pre hashed passwords

patch by Berenguer Blasi; reviewed by Andres de la Peña for CASSANDRA-17494

doc/modules/cassandra/examples/BNF/alter_user_statement.bnf

@@ -1 +1 @@
-alter_user_statement ::= ALTER USER role_name [ WITH PASSWORD string] [ user_option]
+alter_user_statement ::= ALTER USER role_name [ WITH [ HASHED ] PASSWORD string] [ user_option]

doc/modules/cassandra/examples/BNF/create_role_statement.bnf

@@ -2,6 +2,7 @@ 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

doc/modules/cassandra/examples/BNF/create_user_statement.bnf

@@ -1,4 +1,4 @@
 create_user_statement ::= CREATE USER [ IF NOT EXISTS ] role_name
-                          [ WITH PASSWORD string ]
+                          [ WITH [ HASHED ] PASSWORD string ]
                           [ user_option ]
 user_option: SUPERUSER | NOSUPERUSER

doc/modules/cassandra/examples/CQL/alter_role.cql

@@ -1 +1,2 @@
 ALTER ROLE bob WITH PASSWORD = 'PASSWORD_B' AND SUPERUSER = false;
+ALTER ROLE bob WITH HASHED PASSWORD = '$2a$10$JSJEMFm6GeaW9XxT5JIheuEtPvat6i7uKbnTcxX3c1wshIIsGyUtG' AND SUPERUSER = false;

doc/modules/cassandra/examples/CQL/alter_user.cql

@@ -1,2 +1,3 @@
 ALTER USER alice WITH PASSWORD 'PASSWORD_A';
+ALTER USER alice WITH HASHED PASSWORD '$2a$10$JSJEMFm6GeaW9XxT5JIheuEtPvat6i7uKbnTcxX3c1wshIIsGyUtG';
 ALTER USER bob SUPERUSER;

doc/modules/cassandra/examples/CQL/create_role.cql

@@ -1,5 +1,6 @@
 CREATE ROLE new_role;
 CREATE ROLE alice WITH PASSWORD = 'password_a' AND LOGIN = true;
+CREATE ROLE alice WITH HASHED PASSWORD = '$2a$10$JSJEMFm6GeaW9XxT5JIheuEtPvat6i7uKbnTcxX3c1wshIIsGyUtG' AND LOGIN = true;
 CREATE ROLE bob WITH PASSWORD = 'password_b' AND LOGIN = true AND SUPERUSER = true;
 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'};

doc/modules/cassandra/examples/CQL/create_user.cql

@@ -1,2 +1,3 @@
 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;

doc/modules/cassandra/pages/cql/security.adoc

@@ -58,6 +58,8 @@ 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.
 
+USE `WITH HASHED PASSWORD` to provide the jBcrypt hashed password directly. See the `hash_password` tool.
+
 ==== Restricting connections to specific datacenters
 
 If a `network_authorizer` has been configured, you can restrict login
@@ -95,6 +97,8 @@ For example:
 include::example$CQL/alter_role.cql[]
 ----
 
+USE `WITH HASHED PASSWORD` to provide the jBcrypt hashed password directly. See the `hash_password` tool.
+
 ==== Restricting connections to specific datacenters
 
 If a `network_authorizer` has been configured, you can restrict login

doc/modules/cassandra/pages/tools/hash_password.adoc

@@ -0,0 +1,31 @@
+= Hash password
+
+The `hash_password` tool is used to get the jBcrypt hash of a password. This hash 
+can be used in CREATE/ALTER ROLE/USER statements for improved security.
+
+This feature can be useful if we want to make sure no intermediate system, logging or 
+any other possible plain text password leak can happen.
+
+== Usage
+
+hash_password <options>
+
+[cols=",",]
+|===
+
+|-h,--help |Displays help message
+
+|-e,--environment-var <arg> |Use value of the specified environment
+variable as the password
+
+|-i,--input <arg> |Input is a file (or - for stdin) to read the
+password from. Make sure that the whole input including newlines is
+considered. For example, the shell command `echo -n foobar \| hash_password
+-i -` will work as intended and just hash 'foobar'.
+
+|-p,--plain <arg> |Argument is the plain text password
+
+|-r,--logrounds <arg> |Number of hash rounds (default: 10).
+|===
+
+One of the options --environment-var, --plain or --input must be used.

doc/modules/cassandra/pages/tools/index.adoc

@@ -7,3 +7,4 @@ Cassandra.
 * xref:tools/nodetool/nodetool.adoc[nodetool]
 * xref:tools/sstable/index.adoc[SSTable tools] 
 * xref:tools/cassandra_stress.adoc[cassandra-stress tool]
+* xref:tools/hash_password.adoc[hash password tool]