SMB3 Encryption

How SMB3 Encryption Works

SMB3 encryption protects all data in transit between your application and the file server. After the initial session setup and authentication, every subsequent SMB message is encrypted using AES-128-CCM. This includes file content, directory listings, metadata operations, and all other protocol messages.

Encryption is negotiated during the SMB3 session setup phase. It requires that both the client and server support SMB 3.x. If the server only supports SMB2, encryption is not available and the connection will either proceed unencrypted or fail, depending on your configuration.

Because encryption operates at the SMB protocol layer, it does not require TLS or any external certificate infrastructure. The encryption keys are derived from the authenticated session, so there is nothing extra to configure beyond enabling the feature.

Enabling Encryption

There are two ways encryption gets enabled on an SMB3 connection:

Server-Required (Automatic)

When the server is configured to require encryption — for example, through Windows Group Policy or Samba's smb encrypt = required setting — smb-kotlin will automatically enable encryption during session setup. No client-side configuration is needed. The server signals its requirement and the client complies.

Client-Forced

To force encryption from the client side, regardless of server settings, set forceEncryption = true in your SmbConfig:

val config = SmbConfig(
    forceEncryption = true
)

val client = SmbClient(config)
val share = client.connectShare(
    host = "fileserver.corp.com",
    shareName = "secure-data",
    username = "appuser",
    password = "s3cureP@ss"
)

When forceEncryption is enabled and the server does not support SMB3, the connection will fail with an error. This ensures your application never falls back to an unencrypted connection.

Server Compatibility

Code Example

A complete example that forces encryption and handles the case where the server does not support it:

import com.ctreesoft.smb.SmbClient
import com.ctreesoft.smb.SmbConfig
import com.ctreesoft.smb.SmbEncryptionException
import kotlinx.coroutines.flow.toList

suspend fun secureFileList(host: String, share: String, user: String, pass: String) {
    val config = SmbConfig(
        forceEncryption = true
    )

    val client = SmbClient(config)

    try {
        val smbShare = client.connectShare(
            host = host,
            shareName = share,
            username = user,
            password = pass
        )

        val files = smbShare.listDirectory("").toList()
        println("Encrypted connection established. Found ${files.size} items.")

        for (entry in files) {
            println("  ${entry.name} — ${entry.size} bytes")
        }

        smbShare.close()
    } catch (e: SmbEncryptionException) {
        println("Server does not support SMB3 encryption: ${e.message}")
    } finally {
        client.close()
    }
}

When to Force Encryption

Untrusted Networks

If your application communicates with file servers over networks you do not fully control — such as the public internet, shared Wi-Fi, or cross-datacenter links — forcing encryption prevents eavesdropping on file content and credentials.

Compliance Requirements

Regulatory frameworks like HIPAA, PCI-DSS, and SOC 2 often require encryption of data in transit. Enabling SMB3 encryption satisfies this requirement for SMB file transfers without needing a separate VPN or TLS tunnel.

Sensitive Data

For applications that handle financial records, personal information, medical data, or intellectual property, forcing encryption is a straightforward way to add defense in depth.

Performance Considerations

SMB3 encryption adds a small overhead to every message due to AES encryption and decryption. For most workloads this is negligible — modern CPUs handle AES very efficiently, especially with hardware AES-NI instructions. For extremely high-throughput bulk transfers, you may notice a modest reduction in peak transfer speed. In practice, network bandwidth is almost always the bottleneck rather than encryption overhead.