docs-xml/smbdotconf/security/serversmbencrypt.xml

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