[PATCH] update manpage regarding "smb encrypt"
Michael Adam
obnox at samba.org
Thu Apr 23 03:34:46 MDT 2015
I observed that the description of "smb encrypt" in the
smb.conf manpage only covers the old samba-specific smb1
encryption and not the SMB3 encryption.
Attached is an attempt to fix this.
Review/push/comments appreciated...
Thanks - Michael
-------------- next part --------------
From 5f9bd5bdab582dcba0ccaf3206c294bc43be0eda Mon Sep 17 00:00:00 2001
From: Michael Adam <obnox at samba.org>
Date: Thu, 23 Apr 2015 10:38:15 +0200
Subject: [PATCH] docs: overhaul the description of "smb encrypt" to include
SMB3 encryption.
Signed-off-by: Michael Adam <obnox at samba.org>
---
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..09da786 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.1.0
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: not available
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20150423/1ff6341b/attachment.pgp>
More information about the samba-technical
mailing list