smb-kotlin Documentation

Introduction

smb-kotlin is a pure Kotlin SMB2/SMB3 client library for the JVM and Android. It provides a modern, coroutine-based API for connecting to SMB file shares and performing file operations — listing directories, reading and writing files, creating and deleting entries — with support for password-based authentication and optional SMB3 encryption. As a pure Kotlin SMB library, it has zero native dependencies and runs anywhere the JVM does.

smb-kotlin works with any server that speaks SMB2 or SMB3, including Windows file shares, Samba on Linux, and NAS devices from Synology, QNAP, and others. Whether you need a Java SMB library for a backend service or an SMB Android client for a mobile file manager, smb-kotlin provides a single, consistent API across platforms.

Installation

smb-kotlin is published to Maven Central. Add it to your project with Gradle or any Maven-compatible build system.

Gradle (Kotlin DSL)

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.ctreesoft:smb-kotlin:1.3.0")
}

Gradle (Groovy DSL)

repositories {
    mavenCentral()
}

dependencies {
    implementation "com.ctreesoft:smb-kotlin:1.3.0"
}

Runtime Dependencies

smb-kotlin pulls in the following transitive dependencies. You do not need to declare them yourself unless you need to override a version.

Licensing

smb-kotlin requires a valid license file at runtime. License files are issued by CTreeSoft and use the .lic extension. Each file is a signed plain-text document with key-value headers followed by an Ed25519 signature block.

License File Format

LicenseId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Product: smb-kotlin
Type: commercial
Expiry: 2027-01-01
---
<base64-encoded Ed25519 signature>

Loading a License

You can load a license from a file path, an InputStream, or a raw string. The license is passed to SmbConfig before creating a session.

From a File

import com.ctreesoft.smb.SmbConfig
import com.ctreesoft.smb.license.License

val license = License.fromFile("/path/to/smb.lic")
val config = SmbConfig.builder()
    .license(license)
    .build()

From an InputStream

val stream = context.assets.open("smb.lic") // Android example
val license = License.fromStream(stream)
val config = SmbConfig.builder()
    .license(license)
    .build()

From a String

val licenseText = """
    LicenseId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    Product: smb-kotlin
    ...
""".trimIndent()
val license = License.fromString(licenseText)
val config = SmbConfig.builder()
    .license(license)
    .build()

Embedding in Resources

The recommended approach is to bundle the license file as a resource in your application so it loads automatically.

On the JVM, load from the classpath:

val stream = Thread.currentThread().contextClassLoader
    .getResourceAsStream("smb.lic")
val license = License.fromStream(stream!!)

On Android, load from assets:

val stream = context.assets.open("smb.lic")
val license = License.fromStream(stream)

Platform Requirements

smb-kotlin targets JVM bytecode level 17. On Android, API 26 is required for the java.security and javax.crypto APIs used by the NTLM and SMB3 encryption layers. No JNI or platform-specific native code is involved — the library is pure Kotlin from transport to crypto.