JCIFS is a comprehensive, pure Java implementation of the CIFS/SMB networking protocol suite, providing seamless access to Windows file shares and SMB servers. This library enables Java applications to interact with SMB resources across all major protocol versions while maintaining excellent compatibility with legacy systems.
- SMB1/CIFS: Legacy protocol support for older devices and systems
- SMB2: Full SMB 2.0.2, 2.1 support with enhanced performance
- SMB3: Complete SMB 3.0, 3.0.2, 3.1.1 implementation featuring:
- AES-128-CCM encryption (SMB 3.0/3.0.2)
- AES-128-GCM encryption (SMB 3.1.1)
- Pre-Authentication Integrity (SMB 3.1.1)
- AES-CMAC signing for data integrity
- Automatic protocol negotiation
- Transparent encryption when required by server
- Multi-method Authentication: NTLMSSP, Kerberos, SPNEGO
- Enterprise Security: Domain authentication with credential renewal
- Guest & Anonymous Access: Flexible credential management
- Per-context Configuration: No global state, thread-safe operations
- Large File Support: Efficient ReadX/WriteX operations for multi-GB files
- Streaming Operations: Memory-efficient directory listings and file transfers
- Connection Pooling: Intelligent transport management and reuse
- Buffer Caching: Optimized memory management for high-throughput scenarios
- DFS Support: Distributed File System path resolution
- Java 17+ Requirement: Modern language features and performance
- SLF4J Logging: Configurable, enterprise-grade logging
- AutoCloseable Resources: Proper resource management patterns
- Jakarta EE Support: Compatible with modern servlet containers
- Java: 17 or higher (LTS recommended)
- Dependencies: SLF4J for logging, Bouncy Castle for cryptography
- Network: SMB/CIFS protocol access (typically ports 139/445)
<dependency>
<groupId>org.codelibs</groupId>
<artifactId>jcifs</artifactId>
<version>3.0.0</version>
</dependency>
implementation 'org.codelibs:jcifs:3.0.0'
Check Maven Central for the most recent releases.
import org.codelibs.jcifs.smb.CIFSContext;
import org.codelibs.jcifs.smb.context.SingletonContext;
import org.codelibs.jcifs.smb.impl.SmbFile;
// Using default context
CIFSContext context = SingletonContext.getInstance();
// Access a file
try (SmbFile file = new SmbFile("smb://server/share/file.txt", context)) {
if (file.exists()) {
System.out.println("File size: " + file.length());
System.out.println("Last modified: " + new Date(file.lastModified()));
}
}
try (SmbFile file = new SmbFile("smb://server/share/document.txt", context);
InputStream is = file.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(is, StandardCharsets.UTF_8))) {
String line;
while ((line = reader.readLine()) != null) {
System.out.println(line);
}
}
try (SmbFile dir = new SmbFile("smb://server/share/", context)) {
for (SmbFile file : dir.listFiles()) {
System.out.printf("%s %10d %s%n",
file.isDirectory() ? "[DIR]" : "[FILE]",
file.length(),
file.getName());
}
}
import org.codelibs.jcifs.smb.context.BaseContext;
import org.codelibs.jcifs.smb.impl.NtlmPasswordAuthenticator;
import org.codelibs.jcifs.smb.config.PropertyConfiguration;
// Create context with domain credentials
Properties props = new Properties();
// Optional: Set SMB protocol preferences
props.setProperty("jcifs.smb.client.minVersion", "SMB202");
props.setProperty("jcifs.smb.client.maxVersion", "SMB311");
CIFSContext baseContext = new BaseContext(new PropertyConfiguration(props));
NtlmPasswordAuthenticator auth = new NtlmPasswordAuthenticator(
"DOMAIN", // Domain name
"username", // Username
"password" // Password
);
CIFSContext authContext = baseContext.withCredentials(auth);
// Use authenticated context
try (SmbFile file = new SmbFile("smb://server/share/", authContext)) {
// Authenticated operations...
}
import org.codelibs.jcifs.smb.impl.KerberosCredentials;
// Kerberos authentication (requires proper Kerberos setup)
KerberosCredentials kerbCreds = new KerberosCredentials("user@DOMAIN.COM");
CIFSContext kerbContext = baseContext.withCredentials(kerbCreds);
// Guest access for servers that allow it
CIFSContext guestContext = baseContext.withGuestCredentials();
// Efficient large file copying
try (SmbFile source = new SmbFile("smb://server/share/largefile.zip", context);
SmbFile dest = new SmbFile("smb://server/backup/largefile.zip", context);
InputStream is = source.getInputStream();
OutputStream os = dest.getOutputStream()) {
byte[] buffer = new byte[65536]; // 64KB buffer
int bytesRead;
while ((bytesRead = is.read(buffer)) != -1) {
os.write(buffer, 0, bytesRead);
}
}
import org.codelibs.jcifs.smb.SmbWatchHandle;
// Monitor directory for changes
try (SmbFile dir = new SmbFile("smb://server/share/monitored/", context);
SmbWatchHandle watch = dir.watch(
SmbConstants.FILE_NOTIFY_CHANGE_FILE_NAME |
SmbConstants.FILE_NOTIFY_CHANGE_SIZE, true)) {
FileNotifyInformation[] notifications = watch.read();
for (FileNotifyInformation info : notifications) {
System.out.println("File changed: " + info.getFileName());
}
}
// Advanced configuration
Properties config = new Properties();
config.setProperty("jcifs.smb.client.minVersion", "SMB300"); // Require SMB3+
config.setProperty("jcifs.smb.client.maxVersion", "SMB311");
config.setProperty("jcifs.smb.client.enableSMB2Signing", "true"); // Enable signing
config.setProperty("jcifs.smb.client.signingPreferred", "true");
config.setProperty("jcifs.resolveOrder", "LMHOSTS,DNS,WINS,BCAST");
CIFSContext customContext = new BaseContext(new PropertyConfiguration(config));
JCIFS follows a layered architecture designed for flexibility and performance:
Context Layer (org.codelibs.jcifs.smb.context
)
CIFSContext
: Main entry point encapsulating configuration and credentialsBaseContext
: Primary implementation with full feature support- Context wrappers for credential management and configuration isolation
Resource Layer (org.codelibs.jcifs.smb.impl
)
SmbFile
: Primary implementation for files and directoriesSmbResource
: Interface for all SMB network resources- Resource locators and handles for connection management
Protocol Implementation (org.codelibs.jcifs.smb.internal
)
smb1/
: Legacy SMB1/CIFS protocol supportsmb2/
: Modern SMB2/SMB3 protocol implementation- Protocol-specific message handling and transport
Authentication (org.codelibs.jcifs.smb.ntlmssp
, org.codelibs.jcifs.smb.pac
, org.codelibs.jcifs.smb.spnego
)
- Multiple authentication mechanisms with automatic negotiation
- Credential management and renewal capabilities
- Enterprise security integration
- Java 17+: JDK 17 or higher for building
- Maven 3.6+: Build system and dependency management
# Clone the repository
git clone https://github.com/codelibs/jcifs.git
cd jcifs
# Compile the project
mvn clean compile
# Run tests
mvn test
# Create JAR file
mvn package
# Install to local repository
mvn install
# Format code according to project standards
mvn formatter:format
# Check license headers
mvn apache-rat:check
# Generate test coverage report
mvn jacoco:report
# Check API compatibility
mvn clirr:check
The project includes comprehensive test coverage:
# Run all tests
mvn test
# Run specific test class
mvn test -Dtest=SmbFileTest
# Run integration tests
mvn verify
# Generate coverage report (target/site/jacoco/index.html)
mvn jacoco:report
- Reuse contexts: Create one context per configuration, reuse across operations
- Connection pooling: JCIFS automatically pools and reuses connections
- Proper cleanup: Always use try-with-resources for automatic resource management
// Use appropriate buffer sizes for your use case
byte[] buffer = new byte[1024 * 1024]; // 1MB for large files
byte[] buffer = new byte[64 * 1024]; // 64KB for general use
// For very large files, consider streaming
try (InputStream is = smbFile.getInputStream()) {
// Process in chunks to avoid memory issues
}
// For maximum performance on modern servers
props.setProperty("jcifs.smb.client.minVersion", "SMB300");
props.setProperty("jcifs.smb.client.maxVersion", "SMB311");
// For maximum compatibility (default)
props.setProperty("jcifs.smb.client.minVersion", "SMB1");
props.setProperty("jcifs.smb.client.maxVersion", "SMB311");
- Use domain authentication when possible for better security
- Enable SMB signing for data integrity:
jcifs.smb.client.signingPreferred=true
- Prefer SMB3 for encryption:
jcifs.smb.client.minVersion=SMB300
- Rotate credentials regularly and implement credential renewal
- Use encrypted connections when available (SMB3 encryption is automatic)
- Limit protocol versions to minimum required for your environment
- Monitor failed authentication attempts in logs
- Use VPN or secure networks when accessing SMB over public networks
// Secure configuration example
Properties secureConfig = new Properties();
secureConfig.setProperty("jcifs.smb.client.minVersion", "SMB300");
secureConfig.setProperty("jcifs.smb.client.enableSMB2Signing", "true");
secureConfig.setProperty("jcifs.smb.client.signingPreferred", "true");
secureConfig.setProperty("jcifs.smb.client.ipcSigningEnforced", "true");
Connection Timeouts
// Increase timeout values
props.setProperty("jcifs.smb.client.soTimeout", "35000"); // 35 seconds
props.setProperty("jcifs.smb.client.connTimeout", "10000"); // 10 seconds
props.setProperty("jcifs.smb.client.responseTimeout", "30000"); // 30 seconds
Authentication Failures
- Verify domain name, username, and password
- Check if the account has necessary permissions
- Ensure the server allows the authentication method
- For Kerberos, verify proper DNS and time synchronization
Protocol Negotiation Issues
// Debug protocol negotiation
props.setProperty("jcifs.util.loglevel", "3"); // Enable debug logging
// Force specific protocol version if needed
props.setProperty("jcifs.smb.client.minVersion", "SMB202");
props.setProperty("jcifs.smb.client.maxVersion", "SMB202");
Performance Issues
- Use connection pooling (enabled by default)
- Adjust buffer sizes for your use case
- Consider enabling SMB3 for better performance
- Monitor network latency and bandwidth
JCIFS uses SLF4J for logging. Configure your logging framework accordingly:
<!-- logback.xml example -->
<configuration>
<logger name="org.codelibs.jcifs.smb" level="INFO"/>
<logger name="org.codelibs.jcifs.smb.internal" level="WARN"/>
<!-- Enable debug for troubleshooting -->
<logger name="org.codelibs.jcifs.smb.internal.smb2" level="DEBUG"/>
</configuration>
- Java 17+ required: Update your runtime environment
- Package changes: All classes moved to
org.codelibs.jcifs.smb
- Enhanced SMB3 support: New encryption and signing capabilities
- Improved authentication: Enhanced credential management
- Context-based API: Replace global configuration with contexts
- Modern authentication: Update to new credential classes
- Resource management: Use try-with-resources patterns
- Maximum compatibility with legacy SMB devices is required
- SMB3 encryption and security features are needed
- Connecting to diverse SMB implementations
- Using in applications like Fess that need broad SMB support
- Only connecting to modern SMB servers
- SMB3 encryption features are not required
- Working in controlled environments with specific SMB devices
We welcome contributions! Please follow these steps:
- Fork the repository and create a feature branch
- Make your changes with appropriate tests
- Follow coding standards: Use
mvn formatter:format
- Run tests: Ensure
mvn clean test
passes - Update documentation if needed
- Submit a pull request with a clear description
git clone https://github.com/your-username/jcifs.git
cd jcifs
mvn clean compile
mvn test
- Follow existing code style and patterns
- Add JavaDoc comments for public APIs
- Include unit tests for new functionality
- Ensure all tests pass before submitting
JCIFS is licensed under the GNU Lesser General Public License (LGPL) v2.1.