jcifs-0.7.11 from tgz

Thu Jul 10 22:07:09 EDT 2003

Support  for  LMv2  authentication has been added. See the Overview page in
the  API  documentation  regarding  the jcifs.smb.lmCompatibility property.
Some  additonal  "cleanup"  has  also  been performed. One side-effect that
might be noticed is that the default domain/username/password can no longer
be  set  at runtime. Once the client is initialized the default credentials
are  fixed.  Setting  default  credentials are runtime was always an unsafe
operation. Create an NtlmPasswordAuthentication object instead.

Thu Jul  3 20:59:25 EDT 2003

There  have  been  two small bug fixes in the SMB layer; the count field in
the  SMB_COM_WRITE_ANDX  response  was  being ignored. Apparently the count
specified  in the request is always honored or we would have seen plenty of
file corruption by now. Second, the list() and listFiles() did not properly
handle  Transaction  buffering  with  certain  values  for the listSize and
listCount  properties  (if  multipart transaction responses are send). Also
removed  a  few  obnoxious warnings getting logged during file transfers if
Log.WARNINGS is set.

Regarding  NTLM  HTTP Authentication; there have been additions and updates
to  the  documentation  on the NTLM flags, a fix to NtlmSsp to only provide
the  target when requested by the client via the NTLM "request target" flag
(this   is   the   correct  behavior),  and  a  bugfix  to  NtlmSsp  to  do
Base64.encodeBytes(bytes,  false)  instead  of Base64.encodeBytes(bytes) (a
linewrap  in  the  header  can  cause  an  error).  Eric has also excellent
documentation detailing his analysis of the NTLM protocol:

  http://davenport.sourceforge.net/ntlm.html

Thu Jun 12 00:18:05 EDT 2003

It  was  discovered  that if a server responds to the NBT session setup but
not  to  the  SMB_COM_NEGOTIATE  request the client will hang indefinately.
This  is not a likely thing to occur because servers usually respond or not
at  all.  Regardless  it  has  been  fixed.  The  client will timeout after
jcifs.netbios.soTimeout in this situation.

Some tweeking of the NTLM http code has been performed.

Wed May 28 19:09:17 EDT 2003

jcifs-0.7.8 released

A bug in the new ntlm http client code was identified and fixed.

Tue May 27 21:40:58 EDT 2003

jcifs-0.7.7 released

A  deadlock  was  identified  in SmbTransport very similar to the one found
last  year.  A  significant  change  has  been made that greatly simplifies
synchronization in the transport layer. It eliminates this issue as well as
the  extra synchronization introduced to fix the previous problem. It is an
elemental change however so proceed with caution.

Two  new  packages  have  been  introduced.  The  jcifs.ntlmssp package now
contains  all NTLMSSP base code. This code is used by the NtlmHttpFilter as
well  has  the  new  NtlmHttpURLConnection class for transparently enabling
your  HTTP and HTTPS client to negotiate NTLM authentication. The other new
package  is  jcifs.https  which  just  contains  the HTTPS protocol handler
necesary for proper protocol handler registration. Please read the document
entitled  "Using  jCIFS  NTLM  Authentication  for  HTTP  Connections"  for
important details.

To permit SmbFileOutputStream to be used with unusual named pipe modes (see
5/1/03  message)  that  will  be  both  read  and written the open flags in
SmbFileOutputStream have been changed from O_WRONLY to O_RDWR.

The    attrExpiration    period    of    SmbFile    is    now    reset   in
SmbFileOutputStream.write()  to  prevent  jCIFS  from  reporting  incorrect
attributes  values  after  writing  the file. Previously it was possible to
write  to  the file and immediated check the timestamp or file size and get
an old value. This should no longer happen.

The  SmbFileInputStream.skip()  method  has  been implemented in a way that
will  not  result  in  any  IO to the server. Thus it is possible to resume
large downloads from the point of failure for instance.

Wed Apr 16 22:46:07 EDT 2003

jcifs-0.7.6 released

The  isDirectory method has been changed to return false if the target does
not  exist.  Previously  this  would return true which is inconsistent with
java.io.File.

Wed Apr  2 23:56:26 EST 2003

jcifs-0.7.5 released

More  refinement  to  the  NTLM  HTTP authentication code has been applied.
There  is  also  a fix for listing hosts from Windows ME/98/95 local master
browsers.

Wed Mar 26 19:17:24 EST 2003

jcifs-0.7.4 released

Some NtlmHttpFilter issues were reported by several users of Win98 clients.
Eric  has  provided  a  new  NtlmSsp.java  that  works correctly with these
clients.

Wed Feb 12 01:23:02 EST 2003

From    the    beginning   jCIFS   identified   SmbSessions   uniquely   by
domain\username. This meant that once a session was established it could be
shared  by  another  requestor even if they supplied an incorrect password.
This  was  done  for  reasons  that  strangely  enough  had  to do with SMB
chaining.  However  with  the  introduction  of  the http package it is now
common  to  use  jCIFS  to  authenticate  web  clients from a central jCIFS
instance.  This  introduces  a security flaw because there would be a brief
window  of  opportunity after a user logs in during which an impostor could
log  in  as that user with a simple change to their MSIE security settings.
This  problem has been fixed. Another related issue has also been fixed. If
the   NtlmHttpFilter  or  NetworkExplorer  servlet  is  supplied  with  bad
credentials  the  behavior  was to throw an SmbAuthException up through the
container.   Instead   these   classes   will  respond  with  the  standard
Authentication:   NTLM  response  triggering  the  password  dialog  to  be
displayed until correct credentials are displayed.

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.