JCIFS Frequently Asked Questions

How do I do NTLM HTTP authentication (a.k.a Single Sign On) for my website?
Does jCIFS support NTLMv2?
Why is java.net.URL throwing unknown protocol: smb Exceptions?
I'm getting these UnknownHostExceptions right from the start. What am I doing wrong?
Why do I get these "Network is unreachable" IOExceptions?
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":

http://www.ioplex.com/jespa.html

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:

http://lists.samba.org/archive/jcifs/2008-October/008227.html

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.

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).
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:

The name really doesn't exist. The computer name is misspelled or the machine is off. Doah!
The target is on a different subnet and the name service properties are not set correctly. Larger computer networks are divided up into "subnets". In this case a WINS server is required to resolve hostnames (although fully qualified DNS names will work just as well). The jcifs.netbios.wins property must be set to the IP address of the WINS server for your network.
See the Setting Client Properties page for information on how to set jCIFS properties. Also see the Setting Name Resolution Properties page for more detail about resolver properties and what they do. You might also ask your network administrator about what NetBIOS name services are available or check the Network Settings of a nearby MS Windows host for this information.
The target computer is not running a CIFS server. Not all operating systems have CIFS servers running. Generally Windows NT, Windows 95/98/ME/2000/XP, Samba on UNIX, and possibly OS/2 should work fine (although you can run jCIFS from any computer with an adequate version of Java). The best way to confirm that the target is in fact running a CIFS server is to try to "share" a folder on the target machine and access files on it from another machine (see Diagnostics below). Otherwise you may need to configure it to run a CIFS server ( e.g. Samba on Linux) or get third party software (e.g. Thursby Software's Dave for MacOS). Note, Windows 95/98/ME do not have the CIFS server running by default -- you must "Allow others access to my files" under Control Panel > Network Settings first.
You are using the NetBIOS "scope id". This is rarely encountered but you may need to set the jcifs.netbios.scope property. Ask your network administrator if a NetBIOS scope id is being used and look at the Network Settings of nearby machines. It will just be a string like 'CHEM_BLDNG' or 'scope.com' or similar. See the Setting Name Resolution Properties page for more information about scope and other properties that control hostname resolution.
Your hostname is resolving to 127.0.0.1. It is not uncommon on Linux for an /etc/hosts file to map the hostname to 127.0.0.1 such as:
```
127.0.0.1      nano   localhost.localdomain    localhost
```
Taking the host name (e.g. nano) out of the localhost line should solved the problem.
JCIFS is not reading the properties file. If you are using the -Djcifs.properties=<filename.prp> command line option, make sure you spell it correctly or the properties file will silently be ignored, including any important name service properties within it.

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://192.168.1.15/someshare/) or set the jcifs.netbios.wins property and use NetBIOS server names. Below are some diagnostics that might help.

Diagnosis:

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 127.0.0.1. 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 (127.0.0.1) from 127.0.0.1 : 56(84) bytes of data.    // 127.0.0.1 INCORRECT
64 bytes from nano (127.0.0.1): icmp_seq=0 ttl=255 time=0.1 ms
...
[miallen@bogus jcifs]$ ping bogus
PING bogus.research.ml.com (172.32.29.134) from 172.32.29.134 : 56(84) bytes of data. // Real IP is CORRECT
64 bytes from bogus.research.ml.com (172.32.29.134): 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
or
C:\> ipconfig /all
to confirm your IP address(e.g. 192.168.1.15) and then do:
C:\> nbtstat -A 192.168.1.15

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 192.168.1.15

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 '255.255.255.255'. 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=192.168.1.255 or similar to your properties or use -Djcifs.netbios.baddr=192.168.1.255 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( "192.168.1.15" );
NtlmPasswordAuthentication mycreds = new NtlmPasswordAuthentication( "ntdom", "user", "pass" );
try {
    SmbSession.logon( mydomaincontoller, mycreds );
    // SUCCESS
    return true;
} catch( SmbAuthException sae ) {
    // AUTHENTICATION FAILURE
    return false;
} catch( SmbException se ) {
    // NETWORK PROBLEMS?
    se.printStackTrace();
}

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.