JCIFS Frequently Asked Questions

  1. How do I do NTLM HTTP authentication (a.k.a Single Sign On) for my website?
  2. Does jCIFS support NTLMv2?
  3. Why is java.net.URL throwing unknown protocol: smb Exceptions?
  4. I'm getting these UnknownHostExceptions right from the start. What am I doing wrong?
  5. Why do I get these "Network is unreachable" IOExceptions?
  6. How can I authenticate arbitrary user credentials from an application or web clients against Active Directory?
Q: How do I do NTLM HTTP authentication (a.k.a Single Sign On) for my website?

A: See "Jespa":
Jespa is a complete NTLM implementation in 100% Java that properly implements both the server and client side of NTLMv2, NTLMv1, NTLM2 Session Security and Key Exchange. Of particular interest to users of the old JCIFS SSO Filter, Jespa can properly authenticate NTLMv2 clients just like a Windows server does (using the NetrLogonSamLogon DCERPC call over NETLOGON w/ Secure Channel) and it includes an HTTP SSO Servlet Filter.

Note: Jespa uses JCIFS for DCERPC transport and some basic client side NTLM calculations. Jespa is not Open Source (although it is free for up to 25 users). Please contact IOPLEX Software support if you have any questions regarding Jespa.

Note: The old SSO Filter that used to be included with JCIFS used a "man in the middle" technique that cannot support NTLMv2 and has therefore been removed from the JCIFS package. See the following post for details:


Q: Does jCIFS support NTLMv2?

A: Yes. As of 1.3.0, JCIFS fully supports NTLMv2 and uses it by default.

Note: The NTLM HTTP SSO Filter that used to be included with JCIFS cannot support NTLMv2. See the above question for details.

Q: Why is java.net.URL throwing unknown protocol: smb Exceptions?
Exception in thread "main" java.net.MalformedURLException: unknown protocol: smb
        at java.net.URL.<init>(URL.java:480)
        at java.net.URL.<init>(URL.java:376)
        at java.net.URL.<init>(URL.java:330)
        at jcifs.smb.SmbFile.<init>(SmbFile.java:355)
A: The SMB URL protocol handler is not being successfully installed. In short, the jCIFS jar must be loaded by the System class loader. The problem is reported frequently with servlet containers that load the jCIFS jar using a more restricted class loader (i.e. placing the jar in WEB-INF/lib is not adequate). In this case the solution is to add the jar to the servlet container's CLASSPATH (for Resin this is simply a matter of placing it in the top level lib directory).

More specifically, the SMB URL protocol handler (jcifs.smb.Handler) is used by the java.net.URL class to provide the Java "smb://" URL implementation. There are two possible reasons why this handler is not being recognized.
  1. The current security policy is preventing jCIFS from setting the java.protocol.handler.pkgs system property which is required to install the SMB URL protocol handler. For example, some servlet containers install a security manager or restrictive policy file. In this case, add the jCIFS jar file to the container's CLASSPATH because servlet containers usually associate a policy file with the class files of web applications. Otherwise, the specific (minimum) grant required by jCIFS to successfully install the SMB URL protocol handler is:
    permission java.util.PropertyPermission "java.protocol.handler.pkgs", "read, write";
    If jCIFS is not permitted to write this system property, the SecurityException throw will be caught and a message will be printed to System.err. Alternatively the property can also be set using a VM command line parameter:
    java -Djava.protocol.handler.pkgs=jcifs ...
    This should permit the URL protocol handler to be installed regardless of what security policy is installed (however this isn't recommended as it will override other protocol handlers).
  2. The jCIFS jar file is not in a suitable location. Even if the java.protocol.handler.pkgs property is set successfully, the java.net.URL class must then access the jcifs.smb.Handler class. But if the jCIFS classes are loaded by a different class loader this handler will not be found and again, you will get the "unknown protocol: smb" exception. It is very common for servlet containers to load classes from a class loader other than the System class loader. Like the first scenario, the solution is to add the jCIFS jar file to the container's CLASSPATH and not the WEB-INF/lib directory of the web app.
Q: I'm getting these UnknownHostExceptions right from the start. What am I doing wrong?
$ java List smb://server/share/
Exception in thread "main" java.net.UnknownHostException: SERVER<20>
        at jcifs.netbios.NbtAddress.doNameQuery(NbtAddress.java, Compiled Code)
        at jcifs.netbios.NbtAddress.getByName(NbtAddress.java, Compiled Code)
        at jcifs.smb.SmbFile.<init>(SmbFile.java, Compiled Code)
        at jcifs.smb.SmbFile.<init>(SmbFile.java, Compiled Code)
        at List.main(List.java, Compiled Code)

A: In a nutshell, this is what happens when jCIFS cannot even find the target host.

For jCIFS to access another computer's files and services the target must be running a CIFS server over a NetBIOS LAN. This is exactly the case with 90% of MS Windows networks as CIFS over NetBIOS is MS's native networking setup. In this environment jCIFS should work flawlessly. However the above UnknownHostException is occurring because the name of the target computer cannot be resolved. There could be many reasons why this is happening.

Breakdown of Possible Name Resolution Problems:

In general, if jCIFS is producing unwarranted UnknownHostExceptions, you will need to find out a little more about your network. Be sure to read the Setting Client Properties section from the API Documentation and pay close attention to the jcifs.netbios.wins property. Connecting to Windows machines on the local subnet should work even without setting the WINS property. To connect to a machine on another subnet you can use the IP address of the host (eg. smb:// or set the jcifs.netbios.wins property and use NetBIOS server names. Below are some diagnostics that might help.


Personally I much prefer to take a packet capture when trying to diagnose networking issues. See Obtaining a Network Packet Capture for instructions on how to do that.

Otherwise, first check to see if your local hostname reverse-resolves properly. On UNIX you should look at your /etc/hosts file to make sure it's not mapped to Otherwise just try pinging yourself. The below shows a problem. It should really be resolving to the real IP.
[miallen@nano jcifs]$ ping nano
PING nano ( from : 56(84) bytes of data.    // INCORRECT
64 bytes from nano ( icmp_seq=0 ttl=255 time=0.1 ms
[miallen@bogus jcifs]$ ping bogus
PING bogus.research.ml.com ( from : 56(84) bytes of data. // Real IP is CORRECT
64 bytes from bogus.research.ml.com ( icmp_seq=1 ttl=255 time=0.090 ms
There are many ways to test the machines on your network for the necessary NetBIOS name services. If you have a Windows machine available you can use nbtstat and ipconfig. On Linux and UNIX you can use ifconfig and nmblookup (nmblookup is from the Samba package). More specifically try:
C:\> ipconfig
C:\> ipconfig /all
to confirm your IP address(e.g. and then do:
C:\> nbtstat -A
You should get the netbios hostname of the machine as well as some other useful information. You can now do this on other hosts as well provided you know their IP addresses. If this is working and the necessary properties are set correctly jCIFS should work flawlessly.

The Samba suite has a similar tool that you can use on Linux and UNIX. Again, first verify your IP address with:
$ /sbin/ifconfig
$ nmblookup -A
If any of the above fails you need to look closer at your network settings or have a discussion with your network administrator. But if you determine that the NetBIOS service is in fact listening on the targets of interest you can use the net command on Windows, smbclient on Linux/UNIX, or jCIFS to test connecting to services:
C:\> net use * \\servername\share
or on UNIX with
$ smbclient -L //servername
$ smbclient //servername/share
$ smbclient //servername/share -W research
                            // -W required for domain auth
If the above works the below List example (in the examples directory) should work as well. Try it with -Djcifs.util.loglevel=10 to see detailed log messages.
$ java -Djcifs.util.loglevel=10 List smb://server/share/
Q: Why do I get these "Network is unreachable" IOExceptions?
java.io.IOException: Network is unreachable
at java.net.PlainDatagramSocketImpl.send(Native Method)
at java.net.DatagramSocket.send(DatagramSocket.java, Compiled Code)
at jcifs.netbios.NameServiceClient.send(NameServiceClient.java, Compiled Code)
A: Most likely you need to set the broadcast address that jCIFS should use to broadcast name query requests. The Java Language does not provide a way to extract this information from a host so we simply try to use ''. This will work with most network configurations, however this will fail under certain conditions producing the above exception.

To set the broadcast address, use the jcifs.netbios.baddr property such as adding jcifs.netbios.baddr= or similar to your properties or use -Djcifs.netbios.baddr= on the commandline. You can determine your proper broadcast address by running the ipconfig command on Windows or /sbin/ifconfig on Unix (Linux at least). See the Setting JCIFS Properties page for details.
C:\> ipconfig
C:\> ipconfig /all
or on Linux:
$ /sbin/ifconfig
Another cause of this is if your host does not have a suitable network interface over which to communicate (e.g. laptops with certain power management facilities can switch the NIC to powersave mode if theres nothing plugged into it).

Q: How can I authenticate arbitrary user credentials from an application or web clients against Active Directory?

A: There are two ways to do this. One is to use the jcifs.smb.Session.logon() method to perform an SMB_COM_SESSION_SETUP_ANDX like:
UniAddress mydomaincontroller = UniAddress.getByName( "" );
NtlmPasswordAuthentication mycreds = new NtlmPasswordAuthentication( "ntdom", "user", "pass" );
try {
    SmbSession.logon( mydomaincontoller, mycreds );
    // SUCCESS
    return true;
} catch( SmbAuthException sae ) {
    return false;
} catch( SmbException se ) {
However, just like using an LDAP "bind" to validate credentials, the above method is a mild abuse of the protocol and can cause issues (e.g. with personal workstation AD security policy). The only way to properly validate NTLM credentials is with a NetrLogonSamLogon DCERPC call with the NETLOGON service. The only 100% Java solution that does that is Jespa.
Last updated Mar 18, 2009
Copyright © 2004 The JCIFS Project
validate this page