docs-xml/smbdotconf/security/smbencrypt.xml

   1 <samba:parameter name="smb encrypt"
   2                  context="S"
   3                  type="enum"
   4                  enumlist="enum_smb_signing_vals"
   5                  xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
   6 <description>
   7         <para>
   8         This parameter controls whether a remote client is allowed or required
   9         to use SMB encryption. It has different effects depending on whether
  10         the connection uses SMB1 or SMB2 and newer:
  11         </para>
  12
  13         <itemizedlist>
  14         <listitem>
  15                 <para>
  16                 If the connection uses SMB1, then this option controls the use
  17                 of a Samba-specific extension to the SMB protocol introduced in
  18                 Samba 3.2 that makes use of the Unix extensions.
  19                 </para>
  20         </listitem>
  21
  22         <listitem>
  23                 <para>
  24                 If the connection uses SMB2 or newer, then this option controls
  25                 the use of the SMB-level encryption that is supported in SMB
  26                 version 3.0 and above and available in Windows 8 and newer.
  27                 </para>
  28         </listitem>
  29         </itemizedlist>
  30
  31         <para>
  32                 This parameter can be set globally and on a per-share bases.
  33                 Possible values are
  34                 <emphasis>off</emphasis> (or <emphasis>disabled</emphasis>),
  35                 <emphasis>enabled</emphasis> (or <emphasis>auto</emphasis>, or
  36                 <emphasis>if_required</emphasis>),
  37                 <emphasis>desired</emphasis>,
  38                 and
  39                 <emphasis>required</emphasis>
  40                 (or <emphasis>mandatory</emphasis>).
  41                 A special value is <emphasis>default</emphasis> which is
  42                 the implicit default setting of <emphasis>enabled</emphasis>.
  43         </para>
  44
  45         <variablelist>
  46                 <varlistentry>
  47                 <term><emphasis>Effects for SMB1</emphasis></term>
  48                 <listitem>
  49                 <para>
  50                 The Samba-specific encryption of SMB1 connections is an
  51                 extension to the SMB protocol negotiated as part of the UNIX
  52                 extensions.  SMB encryption uses the GSSAPI (SSPI on Windows)
  53                 ability to encrypt and sign every request/response in a SMB
  54                 protocol stream. When enabled it provides a secure method of
  55                 SMB/CIFS communication, similar to an ssh protected session, but
  56                 using SMB/CIFS authentication to negotiate encryption and
  57                 signing keys. Currently this is only supported smbclient of by
  58                 Samba 3.2 and newer, and hopefully soon Linux CIFSFS and MacOS/X
  59                 clients. Windows clients do not support this feature.
  60                 </para>
  61
  62                 <para>This may be set on a per-share
  63                 basis, but clients may chose to encrypt the entire session, not
  64                 just traffic to a specific share. If this is set to mandatory
  65                 then all traffic to a share <emphasis>must</emphasis>
  66                 be encrypted once the connection has been made to the share.
  67                 The server would return "access denied" to all non-encrypted
  68                 requests on such a share. Selecting encrypted traffic reduces
  69                 throughput as smaller packet sizes must be used (no huge UNIX
  70                 style read/writes allowed) as well as the overhead of encrypting
  71                 and signing all the data.
  72                 </para>
  73
  74                 <para>
  75                 If SMB encryption is selected, Windows style SMB signing (see
  76                 the <smbconfoption name="server signing"/> option) is no longer
  77                 necessary, as the GSSAPI flags use select both signing and
  78                 sealing of the data.
  79                 </para>
  80
  81                 <para>
  82                 When set to auto or default, SMB encryption is offered, but not
  83                 enforced.  When set to mandatory, SMB encryption is required and
  84                 if set to disabled, SMB encryption can not be negotiated.
  85                 </para>
  86                 </listitem>
  87                 </varlistentry>
  88
  89                 <varlistentry>
  90                 <term><emphasis>Effects for SMB2</emphasis></term>
  91                 <listitem>
  92                 <para>
  93                 Native SMB transport encryption is available in SMB version 3.0
  94                 or newer. It is only offered by Samba if
  95                 <emphasis>server max protocol</emphasis> is set to
  96                 <emphasis>SMB3</emphasis> or newer.
  97                 Clients supporting this type of encryption include
  98                 Windows 8 and newer,
  99                 Windows server 2012 and newer,
 100                 and smbclient of Samba 4.1 and newer.
 101                 </para>
 102
 103                 <para>
 104                 The protocol implementation offers various options:
 105                 </para>
 106
 107                 <itemizedlist>
 108                         <listitem>
 109                         <para>
 110                         The capability to perform SMB encryption can be
 111                         negotiated during protocol negotiation.
 112                         </para>
 113                         </listitem>
 114
 115                         <listitem>
 116                         <para>
 117                         Data encryption can be enabled globally. In that case,
 118                         an encryption-capable connection will have all traffic
 119                         in all its sessions encrypted. In particular all share
 120                         connections will be encrypted.
 121                         </para>
 122                         </listitem>
 123
 124                         <listitem>
 125                         <para>
 126                         Data encryption can also be enabled per share if not
 127                         enabled globally. For an encryption-capable connection,
 128                         all connections to an encryption-enabled share will be
 129                         encrypted.
 130                         </para>
 131                         </listitem>
 132
 133                         <listitem>
 134                         <para>
 135                         Encryption can be enforced. This means that session
 136                         setups will be denied on non-encryption-capable
 137                         connections if data encryption has been enabled
 138                         globally. And tree connections will be denied for
 139                         non-encryption capable connections to shares with data
 140                         encryption enabled.
 141                         </para>
 142                         </listitem>
 143                 </itemizedlist>
 144
 145                 <para>
 146                 These features can be controlled with settings of
 147                 <emphasis>smb encrypt</emphasis> as follows:
 148                 </para>
 149
 150                 <itemizedlist>
 151                         <listitem>
 152                         <para>
 153                         Leaving it as default, explicitly setting
 154                         <emphasis>default</emphasis>, or setting it to
 155                         <emphasis>enabled</emphasis> globally will enable
 156                         negotiation of encryption but will not turn on
 157                         data encryption globally or per share.
 158                         </para>
 159                         </listitem>
 160
 161                         <listitem>
 162                         <para>
 163                         Setting it to <emphasis>desired</emphasis> globally
 164                         will enable negotiation and will turn on data encryption
 165                         on sessions and share connections for those clients
 166                         that support it.
 167                         </para>
 168                         </listitem>
 169
 170                         <listitem>
 171                         <para>
 172                         Setting it to <emphasis>required</emphasis> globally
 173                         will enable negotiation and turn on data encryption
 174                         on sessions and share connections. Clients that do
 175                         not support encryption will be denied access to the
 176                         server.
 177                         </para>
 178                         </listitem>
 179
 180                         <listitem>
 181                         <para>
 182                         Setting it to <emphasis>off</emphasis> globally will
 183                         completely disable the encryption feature for all
 184                         connections. Setting <parameter>smb encrypt =
 185                         required</parameter> for individual shares (while it's
 186                         globally off) will deny access to this shares for all
 187                         clients.
 188                         </para>
 189                         </listitem>
 190
 191                         <listitem>
 192                         <para>
 193                         Setting it to <emphasis>desired</emphasis> on a share
 194                         will turn on data encryption for this share for clients
 195                         that support encryption if negotiation has been
 196                         enabled globally.
 197                         </para>
 198                         </listitem>
 199
 200                         <listitem>
 201                         <para>
 202                         Setting it to <emphasis>required</emphasis> on a share
 203                         will enforce data encryption for this share if
 204                         negotiation has been enabled globally. I.e. clients that
 205                         do not support encryption will be denied access to the
 206                         share.
 207                         </para>
 208                         <para>
 209                         Note that this allows per-share enforcing to be
 210                         controlled in Samba differently from Windows:
 211                         In Windows, <emphasis>RejectUnencryptedAccess</emphasis>
 212                         is a global setting, and if it is set, all shares with
 213                         data encryption turned on
 214                         are automatically enforcing encryption. In order to
 215                         achieve the same effect in Samba, one
 216                         has to globally set <emphasis>smb encrypt</emphasis> to
 217                         <emphasis>enabled</emphasis>, and then set all shares
 218                         that should be encrypted to
 219                         <emphasis>required</emphasis>.
 220                         Additionally, it is possible in Samba to have some
 221                         shares with encryption <emphasis>required</emphasis>
 222                         and some other shares with encryption only
 223                         <emphasis>desired</emphasis>, which is not possible in
 224                         Windows.
 225                         </para>
 226                         </listitem>
 227
 228                         <listitem>
 229                         <para>
 230                         Setting it to <emphasis>off</emphasis> or
 231                         <emphasis>enabled</emphasis> for a share has
 232                         no effect.
 233                         </para>
 234                         </listitem>
 235                 </itemizedlist>
 236                 </listitem>
 237                 </varlistentry>
 238         </variablelist>
 239 </description>
 240
 241 <value type="default">default</value>
 242 </samba:parameter>