From 742f46d26e8dfe79de56223ee9999059bad55922 Mon Sep 17 00:00:00 2001
From: Michael Adam <obnox@samba.org>
Date: Thu, 23 Apr 2015 10:38:15 +0200
Subject: [PATCH] docs: overhaul the description of "smb encrypt" to include
 SMB3 encryption.

BUG: https://bugzilla.samba.org/show_bug.cgi?id=11366

Signed-off-by: Michael Adam <obnox@samba.org>
Reviewed-by: Jeremy Allison <jra@samba.org>

Autobuild-User(master): Jeremy Allison <jra@samba.org>
Autobuild-Date(master): Fri Apr 24 00:53:20 CEST 2015 on sn-devel-104

(cherry picked from commit 51ae17b0703eaa481d602ffc7d8231a629fcb5fd)
---
 docs-xml/smbdotconf/security/smbencrypt.xml | 232 ++++++++++++++++++++++++----
 1 file changed, 199 insertions(+), 33 deletions(-)

diff --git a/docs-xml/smbdotconf/security/smbencrypt.xml b/docs-xml/smbdotconf/security/smbencrypt.xml
index b55af85..14b32c2 100644
--- a/docs-xml/smbdotconf/security/smbencrypt.xml
+++ b/docs-xml/smbdotconf/security/smbencrypt.xml
@@ -4,40 +4,206 @@
                  basic="1"
 		 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
 <description>
+	<para>
+	This parameter controls whether a remote client is allowed or required
+	to use SMB encryption. It has different effects depending on whether
+	the connection uses SMB1 or SMB2 and newer:
+	</para>
 
-    <para>This is a new feature introduced with Samba 3.2 and above. It is an
-    extension to the SMB/CIFS protocol negotiated as part of the UNIX extensions.
-    SMB encryption uses the GSSAPI (SSPI on Windows) ability to encrypt
-    and sign every request/response in a SMB protocol stream. When
-    enabled it provides a secure method of SMB/CIFS communication,
-    similar to an ssh protected session, but using SMB/CIFS authentication
-    to negotiate encryption and signing keys. Currently this is only
-    supported by Samba 3.2 smbclient, and hopefully soon Linux CIFSFS
-    and MacOS/X clients. Windows clients do not support this feature.
-    </para>
-
-    <para>This controls whether the remote client is allowed or required to use SMB encryption. Possible values 
-    are <emphasis>auto</emphasis>, <emphasis>mandatory</emphasis> 
-    and <emphasis>disabled</emphasis>. This may be set on a per-share
-    basis, but clients may chose to encrypt the entire session, not
-    just traffic to a specific share. If this is set to mandatory
-    then all traffic to a share <emphasis>must</emphasis>
-    be encrypted once the connection has been made to the share.
-    The server would return "access denied" to all non-encrypted
-    requests on such a share. Selecting encrypted traffic reduces
-    throughput as smaller packet sizes must be used (no huge UNIX
-    style read/writes allowed) as well as the overhead of encrypting
-    and signing all the data.
-    </para>
-
-    <para>If SMB encryption is selected, Windows style SMB signing (see
-    the <smbconfoption name="server signing"/> option) is no longer necessary,
-    as the GSSAPI flags use select both signing and sealing of the data.
-    </para>
-
-    <para>When set to auto or default, SMB encryption is offered, but not enforced.
-    When set to mandatory, SMB encryption is required and if set 
-    to disabled, SMB encryption can not be negotiated.</para>
+	<itemizedlist>
+	<listitem>
+		<para>
+		If the connection uses SMB1, then this option controls the use
+		of a Samba-specific extension to the SMB protocol introduced in
+		Samba 3.2 that makes use of the Unix extensions.
+		</para>
+	</listitem>
+
+	<listitem>
+		<para>
+		If the connection uses SMB2 or newer, then this option controls
+		the use of the SMB-level encryption that is supported in SMB
+		version 3.0 and above and available in Windows 8 and newer.
+		</para>
+	</listitem>
+	</itemizedlist>
+
+	<para>
+		This parameter can be set globally and on a per-share bases.
+		Possible values are
+		<emphasis>off</emphasis> or <emphasis>disabled</emphasis>,
+		<emphasis>auto</emphasis> or <emphasis>enabled</emphasis>, and
+		<emphasis>mandatory</emphasis> or <emphasis>required</emphasis>.
+		A special value is <emphasis>default</emphasis> which is
+		the implicit default setting.
+	</para>
+
+	<variablelist>
+		<varlistentry>
+		<term><emphasis>Effects for SMB1</emphasis></term>
+		<listitem>
+		<para>
+		The Samba-specific encryption of SMB1 connections is an
+		extension to the SMB protocol negotiated as part of the UNIX
+		extensions.  SMB encryption uses the GSSAPI (SSPI on Windows)
+		ability to encrypt and sign every request/response in a SMB
+		protocol stream. When enabled it provides a secure method of
+		SMB/CIFS communication, similar to an ssh protected session, but
+		using SMB/CIFS authentication to negotiate encryption and
+		signing keys. Currently this is only supported smbclient of by
+		Samba 3.2 and newer, and hopefully soon Linux CIFSFS and MacOS/X
+		clients. Windows clients do not support this feature.
+		</para>
+
+		<para>This may be set on a per-share
+		basis, but clients may chose to encrypt the entire session, not
+		just traffic to a specific share. If this is set to mandatory
+		then all traffic to a share <emphasis>must</emphasis>
+		be encrypted once the connection has been made to the share.
+		The server would return "access denied" to all non-encrypted
+		requests on such a share. Selecting encrypted traffic reduces
+		throughput as smaller packet sizes must be used (no huge UNIX
+		style read/writes allowed) as well as the overhead of encrypting
+		and signing all the data.
+		</para>
+
+		<para>
+		If SMB encryption is selected, Windows style SMB signing (see
+		the <smbconfoption name="server signing"/> option) is no longer
+		necessary, as the GSSAPI flags use select both signing and
+		sealing of the data.
+		</para>
+
+		<para>
+		When set to auto or default, SMB encryption is offered, but not
+		enforced.  When set to mandatory, SMB encryption is required and
+		if set to disabled, SMB encryption can not be negotiated.
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term><emphasis>Effects for SMB2</emphasis></term>
+		<listitem>
+		<para>
+		Native SMB transport encryption is available in SMB version 3.0
+		or newer. It is only offered by Samba if
+		<emphasis>server max protocol</emphasis> is set to
+		<emphasis>SMB3</emphasis> or newer.
+		Clients supporting this type of encryption include
+		Windows 8 and newer,
+		Windows server 2012 and newer,
+		and smbclient of Samba 4.1 and newer.
+		</para>
+
+		<para>
+		The protocol implementation offers various options:
+		</para>
+
+		<itemizedlist>
+			<listitem>
+			<para>
+			The capability to perform SMB encryption can be
+			negotiated during prorocol negotiation.
+			</para>
+			</listitem>
+
+			<listitem>
+			<para>
+			Data encryption can be enabled globally. In that case,
+			an encryption-capable connection will have all traffic
+			in all its sessions encrypted. In particular all share
+			connections will be encrypted.
+			</para>
+			</listitem>
+
+			<listitem>
+			<para>
+			Data encryption can also be enabled per share if not
+			enabled globally. For an encryption-capable connection,
+			all connections to an encryption-enabled share will be
+			encrypted.
+			</para>
+			</listitem>
+
+			<listitem>
+			<para>
+			Encryption can be enforced. This means that session
+			setups will be denied on non-encryption-capable
+			connections if data encryption has been enabled
+			globally. And tree connections will be denied for
+			non-encryption capable connections to shares with data
+			encryption enabled.
+			</para>
+			</listitem>
+		</itemizedlist>
+
+		<para>
+		These features can be crontrolled with settings of
+		<emphasis>smb encrypt</emphasis> as follows:
+		</para>
+
+		<itemizedlist>
+			<listitem>
+			<para>
+			Leaving it as default or explicitly setting
+			<emphasis>default</emphasis> globally will enable
+			negotiation of encryption but will not turn on
+			data encryption globally or per share.
+			</para>
+			</listitem>
+
+			<listitem>
+			<para>
+			Setting it to <emphasis>enabled</emphasis> globally will
+			enable negotiation and turn on data encryption globally.
+			</para>
+			</listitem>
+
+			<listitem>
+			<para>
+			Setting it to <emphasis>required</emphasis> globally
+			will enable negotiation and enforce data encryption
+			globally.
+			</para>
+			</listitem>
+
+			<listitem>
+			<para>
+			Setting it to <emphasis>off</emphasis> globally will
+			completely disable the encryption feature.
+			</para>
+			</listitem>
+
+			<listitem>
+			<para>
+			Setting it to <emphasis>enabled</emphasis> on a share
+			will turn on data encryption for this share if
+			negotiation has been enabled globally.
+			</para>
+			</listitem>
+
+			<listitem>
+			<para>
+			Setting it to <emphasis>required</emphasis> on a share
+			will enforce data encryption for this share if
+			negotiation has been enabled globally. Note that this
+			allows enforcing to be controlled in Samba more
+			fine-grainedly than in Windows.  This is a small
+			deviation from the MS-SMB2 protocol document.
+			</para>
+			</listitem>
+
+			<listitem>
+			<para>
+			Setting it to <emphasis>off</emphasis> for a share has
+			no effect.
+			</para>
+			</listitem>
+		</itemizedlist>
+		</listitem>
+		</varlistentry>
+	</variablelist>
 </description>
 
 <value type="default">default</value>
-- 
2.4.3