docs: configuration options for extra password hashes

Add the configuration options for the generation and storage of crypt()
based sha256 and sha512 password hashes in supplementalCredentials

Signed-off-by: Gary Lockyer <gary@catalyst.net.nz>
Reviewed-by: Garming Sam <garming@catalyst.net.nz>
Reviewed-by: Andrew Bartlett <abartlet@samba.org>

diff --git a/docs-xml/smbdotconf/security/passwordhashuserpasswordschemes.xml b/docs-xml/smbdotconf/security/passwordhashuserpasswordschemes.xml
new file mode 100644 (file)
index 0000000..18a43f9
--- /dev/null
+++ b/docs-xml/smbdotconf/security/passwordhashuserpasswordschemes.xml
@@ -0,0 +1,67 @@
+<samba:parameter name="password hash userPassword schemes"
+                 context="G"
+                 type="cmdlist"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+
+<para>This parameter determines whether or not
+<citerefentry><refentrytitle>samba</refentrytitle>
+<manvolnum>8</manvolnum></citerefentry> acting as an Active
+Directory Domain Controller will attempt to store additional
+passwords hash types for the user</para>
+
+<para>The values are stored as 'Primary:userPassword' in the
+<command moreinfo="none">supplementalCredentials</command>
+attribute.  The value of this option is a hash type.</para>
+
+<para>The currently supported hash types are:</para>
+<itemizedlist>
+   <listitem>
+       <para><constant>CryptSHA256</constant></para>
+   </listitem>
+   <listitem>
+       <para><constant>CryptSHA512</constant></para>
+   </listitem>
+</itemizedlist>
+
+<para>Multiple instances of a hash type may be computed and stored.
+The password hashes are calculated using the
+<citerefentry><refentrytitle>crypt</refentrytitle>
+<manvolnum>3</manvolnum></citerefentry> call.
+The number of rounds used to compute the hash can be specified by adding
+':rounds=xxxx' to the hash type, i.e. CryptSHA512:rounds=4500 would calculate
+an SHA512 hash using 4500 rounds.  If not specified the Operating System
+defaults for
+<citerefentry><refentrytitle>crypt</refentrytitle>
+<manvolnum>3</manvolnum></citerefentry> are used.
+</para>
+
+<para>As password changes can occur on any domain controller,
+you should configure this on each of them. Note that this feature is
+currently available only on Samba domain controllers.</para>
+
+<para>Currently the NT Hash of the password is recorded when these hashes
+are calculated and stored.  When retrieving the hashes the current value of the
+NT Hash is checked against the stored NT Hash. This detects password changes
+that have not updated the password hashes.  In this case
+<command moreinfo="none">samba-tool user</command> will ignore the stored
+hash values.
+</para>
+
+<para>Being able to obtain the hashed password helps, when
+they need to be imported into other authentication systems
+later (see <command moreinfo="none">samba-tool user
+getpassword</command>) or you want to keep the passwords in
+sync with another system, e.g. an OpenLDAP server (see
+<command moreinfo="none">samba-tool user
+syncpasswords</command>).</para>
+
+<related>unix password sync</related>
+
+</description>
+
+<value type="default"></value>
+<value type="example">CryptSHA256</value>
+<value type="example">CryptSHA256 CryptSHA512</value>
+<value type="example">CryptSHA256:rounds=5000 CryptSHA512:rounds=7000</value>
+</samba:parameter>