\documentclass{ictlab}

% Copyright (c) 2003 by Nick Urbanik <nicku(at)nicku.org>.
% This material may be distributed only subject to the terms and
% conditions set forth in the Open Publication License, v1.0 or later
% (the latest version is presently available at
% http://www.opencontent.org/openpub/).

\RCS $Revision: 1.1 $

\usepackage{verbatim,alltt,key,xr,biganswerbox}
\usepackage[hang,bf,nooneline]{caption2}
\ifx\pdftexversion\undefined \else
  \usepackage[pdfpagemode=None,pdfauthor={Nick Urbanik}]{hyperref}
\fi

\externaldocument[ld-]{../../lectures/ldap/ldap-slides}
\externaldocument[lp-]{../../lectures/perl-ldap/perl-ldap}

\newcommand*{\labTitle}{Perl Net::LDAP}
\providecommand*{\SNMP}{\acro{SNMP}\xspace}
\providecommand*{\MIB}{\acro{MIB}\xspace}
\providecommand*{\ID}{\acro{ID}\xspace}
\providecommand*{\OID}{\acro{OID}\xspace}
\providecommand*{\USM}{\acro{USM}\xspace}
\providecommand*{\VACM}{\acro{VACM}\xspace}
\renewcommand{\floatpagefraction}{0.75} % default is .5, to increase
% density.
\renewcommand*{\bottomfraction}{0.6} % default is 0.3
\renewcommand*{\topfraction}{0.85} % default is 0.7
\renewcommand*{\textfraction}{0.1} % default is 0.2


\begin{document}

\section{Aims}
\label{sec:aims}

The main aims of the activities today are:
\begin{itemize}
\item To understand how to write a Perl program to perform directory
  searches;
\item To understand how to write a Perl program to perform modify
  operations on a directory.
\end{itemize}



\section{Background}
\label{sec:background}

In slide~\S\ref{lp-sld:authentication} from the Perl \LDAP slides, and
also from slide~\S\ref{ld-sld:bind-operation} in the \LDAP lecture notes,
you can see that a \emph{simple bind} requires:
\begin{itemize}
\item A distinguished name, and
\item a password.
\end{itemize}
However, when a application authenticates a user, we usually send a
\emph{username} and password, not a \DN and password.  To work with
applications in the way you might expect, the authentication operation
is a two-stage process:
\begin{itemize}
\item First we perform an anonymous bind and a search for the \DN that
  matches the given username
\item We then perform the simple bind operation using that \DN the
  given password.
\end{itemize}
This tutorial involves writing software to perform this two-stage
process.

It is poor practice to hard code passwords into software.  There are a
number of ways of avoiding this; one way involves putting the password
into a file that is protected from access by any other users.

Here is some example code that you could use to read the password from
a file \path{/tmp/password.txt}:
\begin{verbatim}
use constant PASSWORD_FILE => '/tmp/password.txt';
sub read_password() {
    open PW, "<", PASSWORD_FILE
        or die "unable to open ", PASSWORD_FILE, ": $!";
    my $pass = <PW>;
    close PW;
    chomp $pass;
    return $pass;
}
\end{verbatim}
Here is a bind example using this function:
\begin{verbatim}
$r = $ldap->bind( $dn, password => read_password );
\end{verbatim}

\newlength{\BW}
\setlength{\BW}{50mm}


\section{Procedure}
\label{sec:procedure}
Refer to the lecture notes about \texttt{Net::LDAP} while doing this
activity.  Refer also to the many manuals for \texttt{Net::LDAP}
including \texttt{perldoc~Net::LDAP::Examples}.  You may choose either
our local \ICT server \path{ldap.tyict.vtc.edu.hk} or the \VTC \LDAP
server \path{ldap.vtc.edu.hk}; it's up to you.

\begin{enumerate}
\item You should have already configured \CPAN.  If not, refer to the
  handout on Net::SNMP.
\item Install \texttt{Net::LDAP} using \CPAN, as described in the
  notes, with:
\begin{alltt}
cpan> install Net::LDAP
\end{alltt}
\item Write a program to take your username as a parameter, and which
  reads your password stored in a file in the \texttt{/tmp} directory
  (note: make the file containing your password have access mode 600,
  and delete it when you have finished your activities today).  The
  program then does the following:
  \begin{itemize}
  \item Performs a search for your entry to obtain the \DN for your
    entry;
  \item Uses this \DN to perform a simple bind to the directory;
  \item Prints the \texttt{userPassword} attribute for your entry.
  \end{itemize}
  \begin{explanation}
    Note that is is \emph{not} a good idea to store your password on
    your networked home directory.  Instead, store it on your local
    hard disk in the \texttt{/tmp} directory and make it readable only
    by your account.  Be sure to delete this file from your hard disk
    before you leave the laboratory today.
  \end{explanation}
\item Copy this program to a new name, and change it to:
  \begin{itemize}
  \item Modify the description in your entry to text read from
    standard input or from a file given on the command line.
  \item The program should display your new entry attributes.
  \end{itemize}
\end{enumerate}

\end{document}