From f48ab4f4642816162e03a255e98fd2b33be932a6 Mon Sep 17 00:00:00 2001
From: Dolph Mathews <dolph.mathews@gmail.com>
Date: Wed, 13 Jul 2016 20:39:10 +0000
Subject: [PATCH] Improve keystone.conf [security_compliance] documentation

Change-Id: I216a8ada2e4ba7700b872737d351366644d15c22
---
 keystone/conf/security_compliance.py | 58 ++++++++++++++++++----------
 1 file changed, 38 insertions(+), 20 deletions(-)

diff --git a/keystone/conf/security_compliance.py b/keystone/conf/security_compliance.py
index e92c6b4074..ad0cf63e48 100644
--- a/keystone/conf/security_compliance.py
+++ b/keystone/conf/security_compliance.py
@@ -20,61 +20,79 @@ disable_user_account_days_inactive = cfg.IntOpt(
     default=None,
     min=1,
     help=utils.fmt("""
-Number of days for which a user can be inactive before the account becomes
-disabled. This feature is disabled by default. Note: this feature is only
-supported via the SQL backend driver for identity. In addition, whether or
-not a user is disabled will be handled by the API and may not match the
-user table enabled column in the database.
+The maximum number of days a user can go without authenticating before being
+considered "inactive" and automatically disabled (locked). This feature is
+disabled by default; set any value to enable it. This feature depends on the
+`sql` backend for the `[identity] driver`. When a user exceeds this threshold
+and is considered "inactive", the user's `enabled` attribute in the HTTP API
+may not match the value of the user's `enabled` column in the user table.
 """))
 
 lockout_failure_attempts = cfg.IntOpt(
     'lockout_failure_attempts',
     default=0,
+    min=0,
     help=utils.fmt("""
-Number of times a user can fail login attempts until the user account is
-locked. Setting the value to 0  disables this feature.
+The maximum number of times that a user can fail to authenticate before the
+user account is locked for the number of seconds specified by
+`[security_compliance] lockout_duration`. Setting this value to zero (the
+default) disables this feature. This feature depends on the `sql` backend for
+the `[identity] driver`.
 """))
 
 lockout_duration = cfg.IntOpt(
     'lockout_duration',
     default=1800,
+    min=1,
     help=utils.fmt("""
-Number of seconds a user account will be locked.
+The number of seconds a user account will be locked when the maximum number of
+failed authentication attempts (as specified by `[security_compliance]
+lockout_failure_attempts`) is exceeded. Setting this option will have no effect
+unless you also set `[security_compliance] lockout_failure_attempts` to a
+non-zero value. This feature depends on the `sql` backend for the `[identity]
+driver`.
 """))
 
 password_expires_days = cfg.IntOpt(
     'password_expires_days',
     default=0,
+    min=0,
     help=utils.fmt("""
-Number of days for which a password will be considered valid before requiring
-the user to change it. Setting the value to 0 disables this feature. Note: this
-feature is only supported via the SQL backend driver for identity.
+The number of days which a password will be considered valid before requiring
+the user to change it. Setting the value to zero (the default) disables this
+feature. This feature depends on the `sql` backend for the `[identity] driver`.
 """))
 
 unique_last_password_count = cfg.IntOpt(
     'unique_last_password_count',
     default=0,
+    min=0,
     help=utils.fmt("""
-Number of latest password iterations for which the password must be unique.
-Setting the value to 0 disables this feature. Note: this feature is only
-supported via the SQL backend driver for identity.
+This controls the number of previous user password iterations to keep in
+history, in order to enforce that newly created passwords are unique. Setting
+the value to zero (the default) disables this feature. This feature depends on
+the `sql` backend for the `[identity] driver`.
 """))
 
 password_change_limit_per_day = cfg.IntOpt(
     'password_change_limit_per_day',
     default=0,
+    min=0,
     help=utils.fmt("""
-Maximum number of times a user can change their password in a day. Setting the
-value to 0 disables this feature.
+The maximum number of times a user can change their password in a single day.
+Setting the value to zero (the default) disables this feature. This feature
+depends on the `sql` backend for the `[identity] driver`.
 """))
 
 password_regex = cfg.StrOpt(
     'password_regex',
+    default='^$',
     help=utils.fmt("""
-Regular expression used to validate password strength requirements. Setting the
-value to None disables this feature. The following is an example of a pattern
-which requires at least 1 letter, 1 digit, and have a minimum length of 7
-characters: ^(?=.*\d)(?=.*[a-zA-Z]).{7,}$
+The regular expression used to validate password strength requirements. By
+default, the regular expression will match any password. The following is an
+example of a pattern which requires at least 1 letter, 1 digit, and have a
+minimum length of 7 characters: ^(?=.*\d)(?=.*[a-zA-Z]).{7,}$ This feature
+depends on the `sql` backend for the `[identity] driver`.
 """))