jcifs-0-7.3 from tgz

Wed Feb 12 01:23:02 EST 2003

A  security issue regarding the SmbSession.logon() method used by NTLM HTTP
Authentication  has  been fixed and a modification has been made to trigger
MSIE  to  redisplay  the  Network  Password dialog repeatedly until correct
credentials are supplied. The change was made in the core jcifs.smb package
however so test this in your dev environments.

Wed Feb  5 00:41:32 EST 2003

The   jcifs-0.7.0   and   0.7.1   releases   will   incorrectly   throw  an
ArrayIndexOutOfBounds  exception  if  a write of 1501 to 1504 is performed.
This release fixes that bug. You may also set jcifs.smb.client.snd_buf_size
=  1300  as  a  temporary work-around. It is also now possible to specify a
"ShareAccess"  with  SmbFileOutputStream  and  SmbFile  to  restrict  other
processes  from  accessing files jCIFS opens. Also, SmbFileOutputStream now
supports writing files larger than 4GB.

Wed Jan 15 22:34:14 EST 2003

jcifs-0.7.1 released

Three  bugs have been fixed regarding filenames with '#' signs in them, the
getInputStream(),   getLastModified(),  getDate(),  and  getContentLength()
methods  of  the  URLConnection  implementation, and isExists() incorrectly
returning false.

Thu Jan  9 00:06:23 EST 2003

jcifs-0.7.0 released

This  is  the  0.7.0  release  of  jCIFS, the Java SMB client. There is new
functionality  specifically  targeting  Web  applications  as  well as some
critical SMB URL fixes and feature improvements:

o The  new  jcifs.http package is very handy when building Web applications
  that need to integrate with MS corporate intranets. Adding a hyperlink to
  a  document  on  a  network drive is easy with Network Explorer (pictured
  right)  and  will transparently negotiate credentials with MSIE to browse
  SMB  resources  (really, no password dialog necessary). This package also
  boasts an NTLM HTTP Authentication servlet Filter for authenticating MSIE
  clients.  These are useful features because many of the tasks surrounding
  user  management  now  fall  back  to  computer support and HR. It is not
  necessary  to  add  and  remove users as they join and leave the company.
  Perhaps  most  important from the user's perspective; they do not need to
  enter  a username or password if their workstation is a member of an NTLM
  domain.  The  password  hashes  generated  when  they  logged on to their
  workstation  will be negotiated during the initial request for a session,
  passed through jCIFS, and validated against a PDC or BDC. This also makes
  the  user's domain, username, and password available for managing session
  information, profiles, preferences, etc.

o The  functionality used to authenticate and manage arbitrary creadentials
  has   been  exposed  in  the  SmbSession  and  NtlmPasswordAuthentication
  classes.  This permits NTLM password authentication to be integrated into
  applications without requiring Microsoft components or JNI.

o With  the  introduction  of the jcifs.encoding property the client is now
  truely  internationalized.  It  has been used successfully on OS/390 with
  native  EBCDIC  character  encoding.  See the Sun JRE documentation for a
  list of supported encodings.

o The  URL  issues  remaining  in  the 0.6 series have been fixed in 0.7 by
  converting  all SMB URL handling internally to use the java.net.URL class
  (Note:  directories  must  now  have  a  trailing  slash  and Java 1.3 is
  required).  Also  a  deadlock in the name service code was identified and
  fixed (repaired in 0.6.8 as well).

o A  copyTo() method has been added to SmbFile that is very fast at copying
  large directories across hosts.

o There  have  been  numerous  other  changes  including  the  mkdirs() and
  getType() methods, plain text password support (disabled by default), the
  available()  method and close() fix for Named Pipes, reading files larger
  than 4 GB, the NtlmAuthenticator class, and more.

All documentation has been completely reviewed and updated.

jcifs-0.6b from tgz

Fri Nov 16 04:07:05 EST 2001

jcifs-0.6b released

This is the first beta of 0.6.

jcifs-0.5.2 from tgz

jcifs-0.5.2 from tgz

 There have been significant changes under the hood. The primitives such as packet encoding/decoding and transport have proven very sturdy however
 the top level glue and logic driving the client really needed an overhaul in hindsight. The client is much smarter now whereas previously jCIFS
 was quite chatty and used some messages abusively (NodeStatusRequest). Some other cleanups that took into account allocation of buffers and large
 numbers of objects have resulted in measureable performance improvements. All of this should be transparent to the user however my confidence in
 the stabilty of 0.5.1 no longer applies. It will take some time to confirm everything works as advertised. I am confident however that any bugs
 will only require minor adjustments to fix. Of course the name resolution bug that triggered this crusade has been fixed.

 There are some API changes. Most methods of SmbFile throw the now public SmbException. Natrually, this will require changes to existing code. For
 example, if your code was:

 if( r.delete() ) {
   System.out.println( "delete successfull" );
 } else {
   System.out.println( "error!" );
 }

 you might replace this with:

 try {
   f.delete();
   System.out.println( "delete successfull" );
 } catch( SmbException se ) {
   System.out.println( "error: " + se.getMessage() );
 }

 There are quite a few different messages that can be provoked such as:

 The file is being used by another process
 The device is not ready
 All pipe instances are busy
 ...

 not all of which have text messages (and which ones do have messages are in only English at the moment). You can test and make dicisions based on the
 errorClass and errorCode of an SmbException. All SmbExceptions are thrown through these methods unless an object implementing the AuthHandler
 interface has been called with the static SmbFile.setAuthHanler method. If an AuthHandler has been specified the following authentication related
 SmbExceptions:

 Access denied
 Bad password
 The client does not have the necessary access rights for the requested function
 The user account has expired
 The user is not allowed to access this server from this client
 The user is not permitted to access the server at this time
 The password of the user has expired

 will not be thrown by SmbFile methods but rather passed in the AuthInfo object to the AuthHandler's authenticate() method along with the username,
 password,
 domain, and target URL if one of these SmbExceptions occurs. See http://lists.samba.org/pipermail/jcifs/2001-October/001553.html for a related
 discussion. I
 believe this is a powerfull feature in itself. This provides for sophisticated error handling and consistent error messages (the messages are the
 same as those reported by Windows clients). There is also an oppurunity to introduce a ResourceBundle of text messages here. I beleive it will work
 quite well and in practice I do not believe code will be cluttered with try/catch.

 The NbtAddress class was designed to handle NetBIOS name queries similarly to the common InetAddress class. Unfortunately a lapse in judgment
 integrated DNS
 queries into this class in jcifs-0.5 (thus the name service bug). The solution is to remove this DNS code and provide a wrapper class that handles
 both DNS queries as well as NetBIOS queries mainly delegating the work to InetAddress and NbtAddress. This class is UniAddress. Here is how each of
 these classes should be used:

 o InetAddress - Lookup a DNS name
 o NbtAddress - Lookup a NetBIOS name or perform NetBIOS specific
     queries (NodeStatus with getAllByAddress)
 o UniAddress - Don't know or care what type of name it is, try to
     find the name with both DNS and NetBIOS queries if necessary. Query
     behavior is governed by the jcifs.resolveOrder property.

 So generally the UniAddress class should be used if you wish to interface
 with name services directly (normally not necessary when working with
 the jcifs.smb package).

jcifs-0.5.1 from tgz

Mon Aug 27 00:29:02 EDT 2001

jcifs-0.5.1

Chris did some great testing at the CIFS Conference Interoperability
Lab and found three minor bugs. They are described in detail here:

http://lists.samba.org/pipermail/jcifs/2001-August/001428.html

These packages will now work with Java 1.1 as well as Java 2.

Sun Jul 29 04:01:18 EDT 2001

jcifs-0.5

This is the final release of the 0.5 series. It is the most stable and
complete product the jCIFS team has to offer. There are no known bugs. A bug
in the renameTo operation (would not always return false when it should have)
has been fixed, API documentation improvements have been made, and a
entry to the FAQ has been added.

Fri Jul 13 18:54:37 EDT 2001

jcifs-0.5b2

Thanks to Rob for realizing that attempting to read the same file from
different processes/threads yielded an "The file is being used by another
process" exception. We had the share flags and access masks wrong. A
Log.CRITICAL_EXCEPTIONS mask has been added for logging messages to the
console. If:

    Log.setMask( Log.CRITICAL_EXCEPTIONS );

is set, the "Access denied", "Bad password", and "The device is not
ready" sorts of exceptions will NOT be printed. The default is still
Log.EXCEPTIONS which encompasses both Log.CRITICAL_EXCEPTIONS and regular
Log.EXCEPTIONS so existing code will not be affected.

Thu Jun 28 21:04:15 EDT 2001

jcifs-0.5b

This is the beta release of jcifs-0.5. The 0.5 series has already been
through a stable release and there are no know bugs so we are confident
that it will perform well. New features since jcifs-0.4 include:

o SmbFile.list() Bug Fix - The jcifs-0.4 package had a serious bug that
  caused a TRANS2_FIND_FIRST2/NEXT2 endless loop. It has been properly
  fixed. This should be the first *complete* stable release.
o Share, Server, and Workroup Enumeration - jCIFS can now list the shares
  on a server, servers of a workgroup, and workgroups on a network.
o CallNamedPipe, TransactNamedPipe, and CreateFile Named Pipe API (Paul)
o Complete SMB Filesharing URL Scheme IETF Draft Support - The smb://
  URL scheme has been fully implemented. (Chris)
o Transactions and RAP API
o Transactions - Full multi-part Transaction requests(used by Transact
  Named Pipes)
o Daylight Savings Bug Fix - jCIFS was not properly correcting for
  daylight savings. (Urban)
o Full SmbComNTCreateAndX Support - We now look just like NT 4 instead
  of Winblows 95 :~)
o Unicode Alignment Bug Fix - Unicode alignment was generally not
  correct and caused many problems in early 0.5dev releases.
o SmbFile Method Behaviors - Fixed canRead() and re-thought and soul
  searched over the meaning of each of these methods and their behavior
  in the smb://, smb://name, and Named Pipe contexts. These methods
  should start to get pretty stable at this point.
o Clean, No Wait Exiting - Examples and other programs would wait 15
  seconds before exiting. This has been fixed by making the Transport
  thread setDaemon( true ). Same for the NameServiceClient Thread.
o Full Tuneable Batching
o NetBIOS Scope Fix
o New getServer, getShare, isWorkgroup Methods
o SmbShell and SmbCrawler Utilities

Thanks deserved for this release to Chris, Steve, Paul, The DJ, Urban,
James, Thierry, savaJe Technologies, and Josef.

FILES:

   jcifs-0.5b.tgz      jar and javadoc only for UNIX
   jcifs-0.5b.zip      jar and javadoc only for WINDOWS
   jcifs-0.5b.jar      jar file only

NOTE: The source code is included in the above packages. If
you would like to actually build jCIFS the ANT jar files are packaged
separately:

   ant.tgz             ant jar files
   ant.zip             ditto

Just unpack one of the above in the jcifs_0.5b directory, set JAVA_HOME in
build.{sh,bat} to bootstrap Ant, and run $ ./build.sh smb or > build smb.

IMPORTANT:

The jcifs.netbios.ns.nameserver has been changed to jcifs.netbios.wins
and the jcifs.util.Config class should now be referenced as
jcifs.Config. Programs written for jcifs-0.4 will not run without making
these two changes at least.

The jCIFS project uses the 'Ant' build tool available here:

    http://jakarta.apache.org/ant/

If you have *any* trouble please let us know on the mailing list by
sending mail to jcifs@samba.org or to myself at mballen@erols.com.

Enjoy,
Michael B. Allen <mballen@erols.com>

--8<--

                               JCIFS
           Common Internet File System Client in 100% Java
                      http://jcifs.samba.org

This is the JCIFS SMB client library written in Java. In short it
will enable Java applications to remotely access shared directories
on SMB file servers(i.e. a Microsoft Windows "share"). It is a fairly
religious implementation of the CIFS specification supporting Unicode,
batching, multiplexing, encrypted authentication, transactions, named
pipes, share/server/workgroup enumeration, and more. It is licensed
under LGPL which means commercial organizations can legitimately use it
with their propertietary code(you just can't modify the library itself
without reciprocation).

REQUIREMENTS:

Java 1.1 or above - http://java.sun.com/products/

INSTALLATION

Just add the jar file to you classpath as you would with any other
jar. More specifically:

UNIX:

1) Go to http://jcifs.samba.org and download jcifs-0.5b.tgz
2) Put it someplace reasonable and extract it with:

  $ gunzip jcifs-0.5b.tgz
  $ tar -xvf jcifs-0.5b.tar

3) Add the jar to your classpath. There are two ways to do this. One is to
explicitly set it on the command line when you run your application like:

  $ java -cp path/to/jcifs-0.4b.jar MyApplication

or perhaps export it in your .profile/.bash_profile like:

  CLASSPATH=$CLASSPATH:/home/miallen/path/to/jcifs-0.5b.jar
  export CLASSPATH

WINDOWS:

1) Go to http://jcifs.samba.org and download jcifs-0.5b.zip
2) Extract it with winzip and put the files someplace reasonable.
3) Add the jar to your classpath. There are two ways to do this. One is to
explicitly set it on the command line when you run your application like:

  C:\jcifs> java -cp jcifs-0.4b.jar MyApplication

The other way is to alter your system environment but I'm not confident
I can tell you accurately how to do that.

It is also common that the CLASSPATH be specified in a shell script or
batch file. See build.{sh,bat} as a hint.

RUNNING JCIFS:

In general the public API is extremely simple. The jcifs.smb.SmbFile,
jcifs.smb.SmbFileInputStream, and jcifs.smb.SmbFileOutputStream
classes are analogous to the java.io.File, java.io.FileInputStream,
and java.io.FileOutputStream classes so if you know how to use those it
should be quite obvious how to use JCIFS provided you set any necessary
properties(such as wins) and understand the smb:// URL syntax.

Here's an example to retrieve a file:

  import jcifs.smb.*;

  jcifs.Config.setProperty( "wins", "192.168.1.230" );
  SmbFileInputStream in = new SmbFileInputStream(
       "smb://username:password@host/c/My Documents/report.txt" );
  byte[] b = new byte[65535];
  int n;
  while(( n = in.read( b )) > 0 ) {
      System.out.write( b, 0, n );
  }

You can also write, rename, list contents of a directory, enumerate
shares, communicate with Win32 Named Pipe Servers, ...etc.

The protocol handler for java.net.URL is also in place which means you
retrieve files using the URL class as you would with other protocols. For
example:

  Class.forName( "jcifs.Config" ); //ensure protocol handler is loaded
  URL url = new URL( "smb://user:pass@host/share/dir/file.txt" );
  InputStream in = url.openStream();

This will also work with whatever else uses the URL class internally. For
example if you use RMI you can serve class files from an SMB share and
use the codebase property:

  -Djava.rmi.server.codebase=smb://mymachine/c/download/myapp.jar

To execute the Put example you might do:

$ java -cp examples:jcifs-0.4b.jar Put smb://usr:pass@host/share/file.zip
582K transfered

API documentation is included.

WHAT IS SMB AND CIFS?

Server Message Block (SMB) is an application layer networking protocol
for file and print sharing. It is the de-facto networking protocol for
Microsoft Windows platforms. The Common Internet File System (CIFS)
is the more generic name for all that encompasses the protocol and its
many layers. Collectively this is the networking protocol used when you
"Map Network Drive...", issue "net use * \\server\share" commands, use
smbclient on UNIX, smbfs on Linux, Sharity, OS2, server vendors such as
Network Appliance, EMC, and others.

WHY DO YOU NEED JCIFS?

This client is 100% Java and will work the same in a variety of
environments from Palm Pilots and applets to any UNIX that supports
Java. Naturally you can choose to run your applications on a platform
that supports mapping or mounting remote volumes into the local
filesystem but this assumes you know what shares you are accessing in
advance and what platform your application is running on(do you use
/mnt/pnt or H:\dir). Such an approach is not portable, unstable due to
unnecessary dependencies, and can be difficult to manage. JCIFS offers
Java applications that require access to SMB file services portability
and therefore the added stability that the UNIX environment can
provide. The JCIFS infrastructure is also highly extensible. If there
is a demand it will include a great deal of additional functionality
not available through a filesystem API such as printing, RPC, NT file
change notification, etc.

ACKNOWLEDGEMENTS

Special thanks to the Samba organization and Christopher R. Hertel for
starting the JCIFS project.