JCIFS

The Java CIFS Client Library

JCIFS is an Open Source client library that implements the CIFS/SMB networking protocol in 100% Java. CIFS is the standard file sharing protocol on the Microsoft Windows platform (e.g. Map Network Drive ...). This client is used extensively in production on large Intranets.

Links

Download
JCIFS NTLM HTTP Authentication
The FAQ
Mailing List Archive (GMANE)
Obtaining a Network Packet Capture

Developer Information

JCIFS API Documentation
Setting Client Properties
Setting Name Resolution Properties
Using JCIFS to Connect to Win32 Named Pipes
JCIFS Exceptions and NtlmAuthenticator
Using JCIFS NTLM Authentication for HTTP Connections
JCIFS is Licensed Under the LGPL

Related Java Projects

jcifs-ext - JCIFS Extensions
Jarapac - DCE/RPC in Java
J-Integra - DCE/RPC in Java
Davenport - WebDAV to CIFS gateway
Starlasoft's JLAN Client and Server

CIFS Authorities

http://www.samba.org/
http://www.samba-tng.org/

Other CIFS Utilities and Tools

Samba for Amiga
Sharity-Lite
SMB Browse for MacOSX
Xamba Network Integration Project

MSRPC

Rpcdump utility for querying RPC servers
OpenGroup DCE/RPC Specification
OpenGroup DCE/RPC Specification - NDR
What OLE Is Really About

Kerberos

RFC1510 - Kerberos V5 Specification
How a Kerberos Logon Works in Win2K
JGSS Example
Kerberos Explained
W2K PAC Specification

Technical Documentation

"Implementing CIFS" (complete online book)
Annotated CIFS Specification: draft-leach-cifs-v1-spec-02.html
SNIA CIFS Technical Reference (V1.0)
The NTLM Authentication Protocol
A .NET Developer's Guide to Windows Security
Windows System Error Codes
Windows Network Management Error Codes
rfc1001 - NetBIOS Concepts and Methods
rfc1002 - NetBIOS Detailed Specifications
CIFS Explained (A whitepaper by John Kleven)
SMB URL draft specification V07
NetBIOS, NetBEUI, NBF, SMB, CIFS networking links page
Microsoft Writeup on WINS behavior
Microsoft Writeup on WINS under W2K
Microsoft Server Documentation on Browsing WANs using WINS
Windows IT Library: NT Network Plumbing
Thursby Software's CIFS pages
Linux Mag: Understanding the Network Neighborhood

Other

Join the JCIFS Mailing List
Browse the Source
Batching
GNU Library General Public License
http://www.gnu.org/
http://www.opensource.org/
Microsoft's CIFS Mailing List Archives

News

jcifs-1.1.9 released / Read Error
posted by Mike, Feb 28, 2005
When multiplexing I/O, if socket buffers fill up such that packets can be read in fragments (i.e. high load), it was possible for the 4 byte NetBIOS header to be read incorrectly resulting in a bogus unexpected EOF reading netbios session header exception. This problem has been fixed. Also, some small javadoc updates have been applied.

jcifs-1.1.8 released / Blocked Threads Again, DC Lookups, Name Service, and More
posted by Mike, Feb 11, 2005
The blocked thread bug wasn't quite fixed in the last release. A lookup exception (e.g. caused by an unresponsive domain controller) could leave a thread blocked if many requests are being processed simultaneously. Similarly the fix for the DC lookup code wasn't complete enough to handle the unusual scenario where all DCs are unresponsive. Also, a malfomed NetBIOS name query response could cause the name service thread to exit incorrectly. These issues have been fixed. Finally, the URL handling of smb://@/ (meaning "null" credentials) has been fixed.

jcifs-1.1.7 released / Blocked Threads, DC Lookups, Signatures, and Other Fixes
posted by Mike, Jan 16, 2005
A bug introduced in a recent release that could cause threads to wait indefinately has been fixed. After time many threads could be blocked resulting in wasted resources. The DC lookup code has been modified to gracefully handle WINS returning an empty list (e.g. due to temporary network failure). A simple fix has been applied that premits SMB signatures to work without specifying preauthentication credentials. The getAttributes() method will now return 31 bits of attributes whereas previously it would mask the lower 6 bits that JCIFS actually uses. A bug has been fixed that under certain conditions prevented copyTo() from copying entire shares. A try/catch block has been added to copyTo() to permit the copy to continue if an error occurs.

jcifs-1.1.6 released / Minor Adjustments
posted by Mike, Dec 27, 2004
If a variable length 8 bit encoding such as Big5 was used the NTCreateAndX command could fail. This bug has been fixed. If an SmbFile{Input,Output}Stream was closed, a subsequent operation could cause the file to be reopened. This behavior is now blocked such that operations performed on a stream after it has been closed will generate an IOException (to conform to java.io streams behavior). Some transport layer synchronization has been adjusted. A getPrincipal method has been added to SmbFile that will return the NtlmPasswordAuthentication object used as credentials for the file or pipe. An adjustment has been made to the NbtAddress.firstCalledName method that streamlines communication with domain controllers. The documentation has been updated regarding transparent NTLM authentication in Mozilla and the available() method of SmbFileInputStream.

jcifs-1.1.5 released / ArrayIndexOutOfBoundsException
posted by Santa, Dec 17, 2004
It was discovered that an ArrayIndexOutOfBoundsException could occur if the list of domain controllers returned by NbtAddress.getAllByName was shorter than the list returned in the previous call (possibly because the WINS query timed out and switched to an alternate WINS server). All NTLM HTTP Authentication Filter users should upgrade to prevent this error. Also, the value of jcifs.netbios.cachePolicy set by the NTLM HTTP Filter if it is not specified has been doubled to 20 minutes. Finally, some log levels have been increased such that running with jcifs.util.loglevel = 3 temporarily is actually reasonable in a production environment (must use loglevel > 3 to see individual SMB messages and loglevel > 5 to get hexdumps).

jcifs-1.1.4 released / LMv2 Fix
posted by Mike, Dec 7, 2004
Two bugs regarding the upcasing of domain and username fields with LMv2 authentication (used with lmCompatibility = 3) have been fixed. Additionally the firstCalledName/nextCalledName methods changed in 1.1.0 have been changed back to the old behavior. The change was not warranted as it did not emulate Windows behavior.

jcifs-1.1.3 released / Concurrency Error Fixed
posted by Mike, Nov 30, 2004
A concurrency error that was introduced with the getChallengeForDomain() code used by the NTLM HTTP Filter has been repaired.

jcifs-1.1.2 released / Bogus Debugging Statement
posted by Mike, Nov 2, 2004
Opps! A harmless println statement that found it's way into the last release has been removed.

jcifs-1.1.1 released / logonShare and DCE Pipe Fixes
posted by Casper, Oct 31, 2004
The jcifs.smb.client.logonShare (and thus the JCIFSACL NTLM HTTP Filter example) did not work. It would not restrict users to those found in the ACL and would instead permit all authenticated users. This has been fixed. A bug was discovered and fixed in the named pipe code. If a specific sequence of reads were performed the pipe could become corrupted. This fix is necessary for multi-pdu DCE requests to work. A small bug in the new NbtAddress.getAllByName() method has been repaired. It will now broadcast for a name if a WINS address was not provided.

jcifs-1.1.0 released / NTLM HTTP Authentication Improvements
posted by Mike, Oct 1, 2004
There have been significant changes that should improve the reliability and overall behavior of JCIFS particularly for users of the NtlmHttpFilter.
  • NbtAddress.getAllByName - The NbtAddress.getAllByName() method has been implemented that will return all RDATA records for a NetBIOS name. Thus, you can now retrieve the full list of domain controllers with NbtAddress.getByName( "MYDOM", 0x1C, null, null ). The old behavior of returning a random entry from the getByName method has been eliminated.
  • SYN Timeout - The socket code has been modified to employ the transport thread when opening a new connection. This eliminates the annoying 1min+ hang that occurs trying to connect to a non-existant but routable addresss (i.e. the single threaded SmbCrawler example is relatively fast now).
  • SmbSession.getChallengeForDomain - A new method has been added to retrieve an object that encapsulates both the server session key (a.k.a. challenge) and the UniAddress from which it came. This method is used solely by the NTLM HTTP Authentication Filter to eliminate the possibility for a different domain controller to be queried in the middle of client nogotiation. Prior to this release this could result in temporary authentication failures. This code uses the new getAllByName method to build a list of domain controllers suitable for authenticating web clients. The clent will rotate evenly through the list and remove entries that are unresponsive. This makes the filter very resilent to domain controller failures.
  • Session Expiration - because of the above changes the client will now proactively close idle sessions. This is particularly pertainent to the NTLM HTTP Filter which really only touches the session when it is first created as the resulting credentials are cached in the user's HTTP session.
  • Read Bug - A read bug in JCIFS that affected EMC Celera servers has been fixed.
  • NetBIOS CalledName - The firstCalledName/nextCalledName methods have been modified to try SMBSERVER* first and fall back to other names. This should eliminate a round trip during session establishment in newer environments.
Finally, I have updated the sample web.xml. It should be used as a stationary in all production environments.

jcifs-1.0.1 released / Guest Account Broken
posted by Mike, Sep 6, 2004
The guest account fix released 6 hours ago broke guest access entirely. The original fix has been re-applied but with the bad test condition corrected.

jcifs-1.0.0 released / 5 Years and Beyond
posted by Mike, Sep 6, 2004
According to the freshmeat page, JCIFS is 5 years old today (vote for us!). The project has come a long way in those years. Its features now include:
  • The NTLM HTTP Authentication Filter, which adds easy Single Sign On (SSO) functionality to Java Servlet containers, is clearly the most popular feature of JCIFS. Eric did a great job of deciphering the details of that protocol. The filter is mind-numbingly easy to install as all it requires is the JCIFS jar and a filter section in your web.xml with two or three init parameters [1].
  • The performance of JCIFS is one of its more surprising achievements. Consider the client can enumerate 5GB of files and directories in less than 10 seconds [2]. To reduce memory usage and increase concurrency JCIFS automatically reuses existing transports and sessions. One nice artifact of this design is that the NTLM HTTP Authentication Filter scales to thousands of active clients. And because the negotiated credentials are cached in the user's HTTP session the number of concurrent user's supported can be many times greater than that.
  • The SmbFile.copyTo() method is a venerable feature in itself. All file and directory attributes and timestamps are mirrored perfectly [3]. It employs an extra thread to write data while the next read operation is in progress. This optimization makes JCIFS the fastest client available for copying large trees of files and directories across hosts (neither of which needs to be the local machine).
  • Accessing DFS volumes (sub-trees of files and directories that actually reside on another host) is fully transparent to the user. The client may be redirected multiple times in the middle of any operation. After a redirection has occurred the mapping is cached but the cache is only queried for transports that indicate they host DFS volumes.
  • SMB signing is robust and negotiated automatically with servers that require it.
  • The SmbRandomAccessFile implementation is a complete drop in replacement for the standard java.io.RandomAccessFile. When opened with SmbFile.FILE_NO_SHARE share access this class is a legitimate database API.
  • Named Pipes of all types are fully supported. TransactNamedPipe, CallNamedPipe, and standard file I/O style pipes are all supported using a single generic API that conforms to the InputStream/OutputStream model.
  • JCIFS' name resolution capability is very sophisticated. WINS, DNS, NetBIOS broadcast queries, and remote lmhosts files are supported well. Which services and the order in which each service is queried is fully configurable. The name service cache policy is also adjustable.
  • JCIFS implements the SMB URL Draft Specification V07 and processes all SMB URLs through an SMB URL proticol handler. This same handler is used to build standard java.net.URL objects which means once the protocol handler is registered SMB URLs can be used with any application that uses URLs (e.g. -Djava.rmi.server.codebase=smb://mymachine/c/download/myapp.jar).
Other features include NTLM and LMv2 Authentication [4], optimal request batching, NT STATUS codes, full transactions, large file support, Unicode support from the ground up [5], NTLM HTTP authentication wrappers for HTTP and HTTPS clients, a simple logging facility, and extensive documentation. If that's not enough, there's always jcifs-ext where bleeding edge JCIFS extensions live.

But the best feature of JCIFS is the simplicity of the API itself. We have diligently resisted "feature creep". The SMB URL allows addressing resources with wonderful ease. The SmbFile class is a drop in replacement for java.io.File so if you know how to use that, you know how to use JCIFS.

JCIFS is now one of the most sophisticated and powerful CIFS clients available free or otherwise. It is used in production environments by many large commercial organizations and the Open Source model has worked well for us as these users have contibuted valuable feekback that has made JCIFS rock solid.

To commemorate these achievements we are proud to release JCIFS 1.0. Aside from fixing broken links and a few packaging tweaks it is not different from 0.9.8 and we hope it stays that way. Moving forward, the 1.0 branch will only receive critical fixes.

In recent weeks a MIDL compatible IDL compiler was developed. Coupled with the Jarapac DCE/RPC framework for Java it is now practical to make MSRPC calls. This means that the Microsoft network management API functions are very close to being incorporated into JCIFS. IDL files need to be written and APIs need to be devised but we will soon be able to create users, edit groups, control NT services, reboot machines, edit the registry, execute programs on a remote host, and much much more. This will open up an entirely new level of integration between Java and Microsoft environments.

Finally, thanks goes out to Eric and Chris and everyone else that has contributed their time. JCIFS is truely a great product because we have taken full advantage of the Open Source model. We would not have made nearly as much progress without the code, bug fixes, problem reports, and solutions provided by our users.

[1] although running through web servers that also try to negotiate NTLM HTTP or do not properly support keep-alives is problematic
[2] Client Host: 500MHz Debian Linux "testing" Java 1.4 JCIFS 1.0.0; Target Workstation: 2.7GHz 5.77GB Windows NT 4 sp6; Nework: 100 Mbps full-duplex switched; Test Program: examples/T2Crawler.java with println statements commented out, default properties, ran 3 times to load up target workstation cache; Results: $ time java -Djcifs.properties=../miallen.prp T2Crawler smb://myworksta/c$/ 3 1000, real 0m9.929s user 0m5.580s sys 0m0.600s
[3] although currently extended attributes are not copied
[4] NTLMv2 is not fully supported but LMv2 permits the client to operate in NTLMv2 environments
[5] Unicode share names are not supported but will be soon now that RPCs are underway