
      Important notes and instructions for building NTLM authentication
                          based on libdsm for DACS


Notes
-----

o This is a fork of the official libdsm-0.2.7 distribution.

  Please use the latest official libdsm distribution if you need to use libdsm
  functionality outside of DACS.
    https://videolabs.github.io/libdsm/

o For licensing, see the COPYING file included in this directory.

  The official libdsm distribution's license (i.e., the GNU LESSER GENERAL
  PUBLIC LICENSE) applies to this modified version.
  Licensing of this libdsm code is identical to that of videolabs's official
  distribution (12-Jul-2016):
    liBDSM is released under LGPLv2.1 (or later)
  DACS licensing DOES NOT APPLY to this modified libdsm code.

o Some files included in the official libdsm distribution (or generated when
  building it) that are not required for use by DACS have been removed or
  hidden in an attempt to present a minimal distribution.  Files not having
  a DSS copyright notice and revision identifier are (probably) unmodified
  from the original distribution.

o Code and configuration for platforms not supported by DACS (e.g., MS Windows
  and Android) has been removed from the original code base as it will never
  be needed by DACS and would therefore never be maintained or tested.

o Code in this distribution that is not required for NTLM authentication is
  unlikely to have been tested and may be removed in a future release.

o There is currently no intent to track or incorporate changes made
  to the official libdsm distribution, or maintain API compatibility.

o There is no plan to distribute this version outside of the DACS
  distribution, although anyone is free to do so subject to the
  licensing terms (see COPYING).

o Since this libdsm implementation contains modifications of the official
  release, bugs etc. found in this code are not the responsibility of the
  maintainers of the official libdsm distribution and should not be reported
  to them.  To report a problem, see:
    https://dacs.dss.ca/support.html
  

Building
--------

The build procedure for the library is only partially incorporated
into the DACS build.  The configuration steps detailed here must be completed
manually.  The DACS Makefile will ask the libdsm Makefile to do a
'make install'.  Everything will be built and installed under this directory,
where the DACS build expects it to be.  No system files will be installed
or touched.


A. Unpack the DACS libdsm archive and cd to its root directory.

B. If not included in the archive, or if for some reason you choose to use a
   different version, obtain these third-party packages required by libdsm
   and unpack them in this directory:

   1) libtasn1 (currently tested with version 4.13)
      https://www.gnu.org/software/libtasn1/

   2) libiconv (currently tested with version 1.15)
      https://www.gnu.org/software/libiconv/

C. Although GNU Libtasn1 may already be installed on your system, at present
you must build it here, in its own subdirectory, then create a symbolic
link to it:

% rm -f libtasn1
% ln -s libtasn1-4.13 libtasn1
% cd libtasn1
% mv install install.help  || echo Ignore this error message
% ./configure --prefix=$cwd/install
% make install
% cd ..

D. Although libiconv ("man 3 iconv") may already be installed on your system,
at present you must build it here, in its own subdirectory, then create a
symbolic link to it:

% rm -f libiconv
% ln -s libiconv-1.15 libiconv
% cd libiconv
% mv install install.help  || echo Ignore this error message
% ./configure --prefix=$cwd/install --enable-static --disable-nls --enable-fast-install
% make install
% cd ..

NOTE:
If the build fails with the error message:
   gcc: error: 0": No such file or directory
edit preload/Makefile and change
   -DPACKAGE_STRING=\"libiconv\ 0\"
to
   -DPACKAGE_STRING=\"libiconv-0\"
And try 'make install' again.

E. Configure this version of libdsm:

% sh ./config.nice

F. Build and install it in its build directory (under "./install").

% make install

This will build the library and test/demo program ("ntlmauth", which uses
libtasn1, libiconv, and libdsm).
The approximate directory structure is:

   dacs-1.4.X / src / libdsm / src
                             / include
                             / install
                               / bin
                                 / ntlmauth
                               / include
                               / lib
                             / libiconv
                               / install
                                 / bin
                                 / include
                                 / lib
                             / libtasn1
                               / install
                                 / bin
                                 / include
                                 / lib


Testing using ntlmauth
----------------------

ntlmauth tries to validate a username/password pair against a
specified NTLM server.

Run:

% ./ntlmauth
% ./ntlmauth -s some-ntlm-server-host -u some-username -pw some-password


Flags:
-h: show help
-q: quiet (suppress normal output)
-v: verbose (always emit normal output)
-s server: NTLM server domain name or IP address (required: SAMBA_SERVER)
-u username: try to validate this NTLM account
-pw passwd: validate passwd against the username (password will be visible)
-d domain: validate using this domain (optional: SAMBA_DOMAIN)
-port #: use only this SMB server port (optional: SAMBA_PORT)
-w workgroup: validate using this workgroup (probably not required)

The program prompts for a password if it is not provided on the command line.
The port number is optional; probably only 445 and 139 are sensible and
the default is try both of those ports.  Explicitly specifying port zero
is equivalent to the default behaviour.  Using the port number known to be
correct may be more efficient since an incorrect port number won't be tried.

The exit code is 0 if authentication succeeded, 1 otherwise.

Links:

https://github.com/naxos/SMBClient
http://videolabs.github.io/libdsm/

===============================================================================
Copyright (c) 2003-2018
Distributed Systems Software.  All rights reserved.
$Id: README 2996 2018-01-29 18:04:51Z brachman $
