samba-mirror/docs-xml/smbdotconf/security/smbencrypt.xml

<samba:parameter name="smb encrypt"
                 context="S"
                 type="enum"
                 enumlist="enum_smb_signing_vals"
                 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>

	<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>enabled</emphasis> (or <emphasis>auto</emphasis>, or
		<emphasis>if_required</emphasis>),
		<emphasis>desired</emphasis>,
		and
		<emphasis>required</emphasis>
		(or <emphasis>mandatory</emphasis>).
		A special value is <emphasis>default</emphasis> which is
		the implicit default setting of <emphasis>enabled</emphasis>.
	</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 protocol 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 controlled with settings of
		<emphasis>smb encrypt</emphasis> as follows:
		</para>

		<itemizedlist>
			<listitem>
			<para>
			Leaving it as default, explicitly setting
			<emphasis>default</emphasis>, or setting it to
			<emphasis>enabled</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>desired</emphasis> globally
			will enable negotiation and will turn on data encryption
			on sessions and share connections for those clients
			that support it.
			</para>
			</listitem>

			<listitem>
			<para>
			Setting it to <emphasis>required</emphasis> globally
			will enable negotiation and turn on data encryption
			on sessions and share connections. Clients that do
			not support encryption will be denied access to the
			server.
			</para>
			</listitem>

			<listitem>
			<para>
			Setting it to <emphasis>off</emphasis> globally will
			completely disable the encryption feature for all
			connections. Setting <parameter>smb encrypt =
			required</parameter> for individual shares (while it's
			globally off) will deny access to this shares for all
			clients.
			</para>
			</listitem>

			<listitem>
			<para>
			Setting it to <emphasis>desired</emphasis> on a share
			will turn on data encryption for this share for clients
			that support encryption 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. I.e. clients that
			do not support encryption will be denied access to the
			share.
			</para>
			<para>
			Note that this allows per-share enforcing to be
			controlled in Samba differently from Windows:
			In Windows, <emphasis>RejectUnencryptedAccess</emphasis>
			is a global setting, and if it is set, all shares with
			data encryption turned on
			are automatically enforcing encryption. In order to
			achieve the same effect in Samba, one
			has to globally set <emphasis>smb encrypt</emphasis> to
			<emphasis>enabled</emphasis>, and then set all shares
			that should be encrypted to
			<emphasis>required</emphasis>.
			Additionally, it is possible in Samba to have some
			shares with encryption <emphasis>required</emphasis>
			and some other shares with encryption only
			<emphasis>desired</emphasis>, which is not possible in
			Windows.
			</para>
			</listitem>

			<listitem>
			<para>
			Setting it to <emphasis>off</emphasis> or
			<emphasis>enabled</emphasis> for a share has
			no effect.
			</para>
			</listitem>
		</itemizedlist>
		</listitem>
		</varlistentry>
	</variablelist>
</description>

<value type="default">default</value>
</samba:parameter>