Sync with head

diff --git a/doc/guide/admin/security.sdf b/doc/guide/admin/security.sdf
index 10f11d7b45a9035936d7c8ffa32dbc080b6e9cdb..a064b19e801f2e7b332831c6fb0d58427f470d5a 100644 (file)
--- a/doc/guide/admin/security.sdf
+++ b/doc/guide/admin/security.sdf
@@ -173,35 +173,51 @@ mechanism. The {{SECT:Using SASL}} section discusses the use of SASL.
 H2: Password Storage
 
 LDAP passwords are normally stored in the {{userPassword}} attribute.
-{{REF:RFC4519}} specifies that passwords are not stored in encrypted form,
-but this can create an unwanted security exposure so {{slapd}} provides
-several options for the administrator to choose from.
+{{REF:RFC4519}} specifies that passwords are not stored in encrypted
+(or hashed) form.  This allows a wide range of password-based
+authentication mechanisms, such as {{EX:DIGEST-MD5}} to be used.
+This is also the most interoperable storage scheme.
+
+However, it may be desirable to store a hash of password instead.
+{{slapd}}(8) supports a variety of storage schemes for the administrator
+to choose from.
+
+Note: Values of password attributes, regardless of storage scheme
+used, should be protected as if they were clear text.  Hashed
+passwords are subject to {{dictionary attacks}} and {{brute-force
+attacks}}.
 
 The {{userPassword}} attribute is allowed to have more than one value,
 and it is possible for each value to be stored in a different form.
 During authentication, {{slapd}} will iterate through the values
 until it finds one that matches the offered password or until it
-runs out of values to inspect. The storage scheme is stored as a prefix
-on the value, so a Unix {{crypt}}-style password might look like this:
+runs out of values to inspect.  The storage scheme is stored as a prefix
+on the value, so a hashed password using the Salted SHA1 ({{EX:SSHA}})
+scheme looks like:
 
-> userPassword: {CRYPT}.7D8U/PCF00Hw
+> userPassword: {SSHA}DkMTwBl+a/3DQTxCYEApdUtNXGgdUac3
 
-In general, it is safest to store passwords in a salted hashed format
-like SSHA. This makes it very hard for an attacker to derive passwords
-from stolen backups or by obtaining access to the on-disk {{slapd}}
-database.
+The advantage of hashed passwords is that an attacker which
+discovers the hash does not have direct access to the actual password.
+Unfortunately, as dictionary and brute force attacks are generally
+quite easy for attackers to successfully mount, this advantage is
+marginal at best (this is why all modern Unix systems use shadow
+password files).
 
-The disadvantage of hashed storage is that it prevents the use of some
-authentication mechanisms such as {{EX:DIGEST-MD5}}.
+The disadvantages of hashed storage is that they are non-standard, may
+cause interoperability problem, and generally preclude the use
+of stronger than Simple (or SASL/PLAIN) password-based authentication
+mechanisms such as {{EX:DIGEST-MD5}}.
 
-H3: CLEARTEXT password storage scheme
+H3: SSHA password storage scheme
 
-Cleartext passwords can be stored directly in the {{userPassword}}
-attribute, or can have the '{CLEARTEXT}' prefix. These two values are
-equivalent:
+This is the salted version of the SHA scheme. It is believed to be the
+most secure password storage scheme supported by {{slapd}}.
 
-> userPassword: secret
-> userPassword: {CLEARTEXT}secret
+These values represent the same password:
+
+> userPassword: {SSHA}DkMTwBl+a/3DQTxCYEApdUtNXGgdUac3
+> userPassword: {SSHA}d0Q0626PSH9VUld7yWpR0k6BlpQmtczb
 
 H3: CRYPT password storage scheme
 
@@ -218,9 +234,8 @@ transferred to or from an existing Unix password file without having
 to know the cleartext form. Both forms of {{crypt}} include salt so
 they have some resistance to dictionary attacks.
 
-
-Note: Since this scheme uses the operation system's {{crypt(3)}} hash function, 
-it is therefore operation system specific.
+Note: Since this scheme uses the operating system's {{crypt(3)}}
+hash function, it is therefore operating system specific.
 
 H3: MD5 password storage scheme
 
@@ -251,16 +266,6 @@ of salt leaves the scheme exposed to dictionary attacks.
 
 > userPassword: {SHA}5en6G6MezRroT3XKqkdPOmY/BfQ=
 
-H3: SSHA password storage scheme
-
-This is the salted version of the SHA scheme. It is believed to be the
-most secure password storage scheme supported by {{slapd}}.
-
-These values represent the same password:
-
-> userPassword: {SSHA}DkMTwBl+a/3DQTxCYEApdUtNXGgdUac3
-> userPassword: {SSHA}d0Q0626PSH9VUld7yWpR0k6BlpQmtczb
-
 H3: SASL password storage scheme
 
 This is not really a password storage scheme at all. It uses the