ch19_04.htm

by Randal L. Schwartz and Tom Phoenix ISBN 0-596-00132-0 Third Edition, published July 2001. (See

<tt class="literal">scope</tt> parameter with one of the following values:
</p>

<dl>
<dt><b><tt class="literal">base</tt> </b></dt>
<dd>
Searches only the base object.</p>
</dd>


<dt><b><tt class="literal">one</tt> </b></dt>
<dd>
Searches the entries immediately below the base object.</p>
</dd>


<dt><b><tt class="literal">sub</tt></b></dt>
<dd>
Searches the whole tree below the base object. This is the default.</p>
</dd>

</dl>
</dd>


<dt><b><tt class="literal">deref</tt> </b></dt>
<dd>
By default, aliases are dereferenced to locate the base object for
the search, but not when searching subordinates of the base object.
This may be changed by specifying a <tt class="literal">deref</tt>
parameter with one of the following values:
</p>

<dl>
<dt><b><tt class="literal">never</tt> </b></dt>
<dd>
Do not dereference aliases in searching or in locating the base
object of the search.
</p>
</dd>


<dt><b><tt class="literal">search</tt> </b></dt>
<dd>
Dereferences aliases in subordinates of the base object in searching,
but not in locating the base object of the search.
</p>
</dd>


<dt><b><tt class="literal">find</tt> </b></dt>
<dd>
Dereferences aliases in locating the base object of the search, but
not when searching subordinates of the base object. This is the
default.
</p>
</dd>


<dt><b><tt class="literal">always</tt> </b></dt>
<dd>
Dereferences aliases both in searching and in locating the base
object of the search.
</p>
</dd>

</dl>
</dd>


<dt><b><tt class="literal">sizelimit</tt> </b></dt>
<dd>
Restricts the maximum number of entries to be returned as a result of
the search. A value of <tt class="literal">0</tt>, which is the default,
means that no restriction is requested. Servers may enforce a maximum
number of entries to return.
</p>
</dd>


<dt><b><tt class="literal">timelimit</tt> </b></dt>
<dd>
Restricts the maximum time (in seconds) allowed for a search. A value
of <tt class="literal">0</tt>, which is the default, means that no
timelimit will be requested.
</p>
</dd>


<dt><b><tt class="literal">typesonly</tt> </b></dt>
<dd>
Indicates whether search results should contain both attribute types
and values, or just attribute types. Setting this parameter to true
causes only attribute types (no values) to be returned. Setting this
field to false causes both attribute types and values to be returned.
This is the default.
</p>
</dd>


<dt><b><tt class="literal">filter</tt> </b></dt>
<dd>
Defines the conditions an entry in the directory must meet in order
for it to be returned by the search. This may be a string or a
<em class="emphasis">Net</em> object. See the Net::LDAP::Filter manpage
for a further description of the filter format.
</p>
</dd>


<dt><b><tt class="literal">attrs</tt> </b></dt>
<dd>
A reference to a list of attributes to be returned for each entry
that matches the search filter.
</p>

<p>If not specified, then the server will return the attributes that are
specified as accessible by default given your bind credentials.
</p>

<p>Certain additional attributes, such as
<tt class="literal">createtimestamp</tt>, and other operational attributes
may also be available for the asking:
</p>


<blockquote><pre class="code">$ldap-&gt;search( ... , attrs =&gt; ['createtimestamp'] , ... );</pre></blockquote>

<p>To retrieve the default attributes and additional ones, use
"*":
</p>


<blockquote><pre class="code">my $base_dn = q[o=my.domain];
$mesg = $ldap-&gt;search(
  base   =&gt; $base_dn,
  scope  =&gt; 'sub',
  filter =&gt; '(|(objectclass=rfc822mailgroup)(sn=Patwardhan))'
);

Net::LDAP::LDIF-&gt;new(\*STDOUT,"w")-&gt;write($mesg-&gt;entries);</pre></blockquote>
</dd>

</dl>
</dd>


<a name="INDEX-2368" /><dt><b><tt class="literal">abandon(</tt><em class="replaceable">id</em> <tt class="literal">[, %</tt><em class="replaceable">options</em> <tt class="literal">] )</tt> </b></dt>
<dd>
Requires that a server abandons a request.
<em class="replaceable"><tt>id</tt></em> may be passed first, or as part of
<tt class="literal">%</tt><em class="replaceable"><tt>options</tt></em>, and may be a
number or a Net::LDAP::Message object that's
returned from a previous method call.
</p>

<blockquote><pre class="code">$mesg = $ldap-&gt;search(@search_args);
$ldap-&gt;abandon($mesg); # This could be written as $mesg-&gt;abandon</pre></blockquote></dd>

<a name="INDEX-2369" /><dt><b><tt class="literal">compare(</tt><em class="replaceable">dn</em><tt class="literal">, %</tt><em class="replaceable">options</em><tt class="literal">)</tt> </b></dt>
<dd>
Performs a comparison on the server. <em class="replaceable"><tt>dn</tt></em> is
the DN on which the comparison will be performed.
<em class="replaceable"><tt>dn</tt></em> may be a string or Net::LDAP::Entry
object.
</p>

<dl>
<dt><b><tt class="literal">attr</tt> </b></dt>
<dd>
The name of the attribute to compare.</p>
</dd>


<dt><b><tt class="literal">value</tt> </b></dt>
<dd>
The value to compare with. </p>

<blockquote><pre class="code">my $dn = q[uid=nvp,ou=People,o=my.domain];
$ldap-&gt;compare($dn,
    attr  =&gt; 'cn',
    value =&gt; 'Nathan Patwardhan'
);</pre></blockquote>
</dd>
</dl>
</dd>



<a name="INDEX-2370" /><dt><b><tt class="literal">start_tls([%</tt><em class="replaceable">options</em><tt class="literal">])</tt> </b></dt>
<dd>
Converts the connection to use Transport Layer Security (TLS), which
provides an encrypted connection, if available. Bear in mind that TLS
is supported only under LDAPv3.
<tt class="literal">%</tt><em class="replaceable"><tt>options</tt></em> is a set of
key/value pairs that describe how to configure the security of the
connection:
</p>

<dl>
<dt><b><tt class="literal">verify</tt> </b></dt>
<dd>
Indicates how to verify the server's certificate.
Its values can be <tt class="literal">none</tt> (the server may provide a
certificate, but it will not be checked&#x2014;this may mean you are
connected to the wrong server), <tt class="literal">optional</tt> (verifies
if the server offers a certificate), or <tt class="literal">require</tt>
(the server must provide a certificate, and it must be valid). If you
set <tt class="literal">verify</tt> to <tt class="literal">optional</tt> or
<tt class="literal">require</tt>, you must also set either
<tt class="literal">cafile</tt> or <tt class="literal">capath</tt>. The most
secure option is <tt class="literal">require</tt>.
</p>
</dd>


<dt><b><tt class="literal">sslversion</tt> </b></dt>
<dd>
Defines the version of the SSL/TLS protocol to use. Defaults to
<tt class="literal">tlsv1</tt>; other possible values are
<tt class="literal">sslv2</tt>, <tt class="literal">sslv3</tt>, and
<tt class="literal">sslv2/3</tt>.
</p>
</dd>


<dt><b><tt class="literal">ciphers</tt> </b></dt>
<dd>
Specifies which subset of cipher suites is permissible for this
connection, using the standard OpenSSL string format. The default
value for ciphers is <tt class="literal">ALL</tt>, which permits all
ciphers, even those that don't encrypt!
</p>
</dd>


<dt><b><tt class="literal">clientcert</tt></b></dt>
<dt><b><tt class="literal">clientkey</tt></b></dt>
<dd>
If you want to use the client to offer a certificate to the server
for SSL authentication (which is not the same as for the LDAP Bind
operation), then set <tt class="literal">clientcert</tt> to the
user's certificate file and <tt class="literal">clientkey</tt> to the user's private
key file. These files must be in PEM format.
</p>
</dd>


<dt><b><tt class="literal">capath</tt></b></dt>
<dt><b><tt class="literal">cafile</tt></b></dt>
<dd>
When verifying the server's certificate, set either
<tt class="literal">capath</tt> to the pathname of the directory containing
CA certificates or <tt class="literal">cafile</tt> to the filename
containing the certificate of the CA who signed the
server's certificate. These certificates must all be
in PEM format.
</p>


<p>The directory in <tt class="literal">capath</tt> must contain certificates
named using the hash value of themselves. To generate these names,
use OpenSSL in Unix, as follows:
</p>


<blockquote><pre class="code">ln -s cacert.pem 'openssl x509 -hash -noout &lt; cacert.pem'.0</pre></blockquote>

<p>(assuming that the certificate of the CA is in
<tt class="literal">cacert.pem</tt>).
</p>
</dd>


<dt><b><tt class="literal">cipher</tt> </b></dt>
<dd>
Returns the cipher mode being used by the connection in the string
format used by OpenSSL.
</p>
</dd>


<dt><b><tt class="literal">certificate</tt> </b></dt>
<dd>
Returns an <tt class="literal">X509_Certificate</tt> object containing the
server's certificate. For example, to get the
subject name (in a peculiar OpenSSL-specific format, different from
RFC 1779 and RFC 2253) from the server's
certificate, do the following:
</p>

<blockquote><pre class="code">print "Subject DN: " . $ldaps-&gt;certificate-&gt;subject_name . "\n";</pre></blockquote>
</dd>
</dl>
</dd>


<a name="INDEX-2371" /><dt><b><tt class="literal">version</tt> </b></dt>
<dd>
Returns the version of the LDAP protocol that is being
used.<a name="INDEX-2372" />
</p>
</dd>

</dl>



<hr width="684" align="left" />
<div class="navbar"><table width="684" border="0"><tr><td align="left" valign="top" width="228"><a href="ch19_03.htm"><img src="../gifs/txtpreva.gif" alt="Previous" border="0" /></a></td><td align="center" valign="top" width="228"><a href="index.htm"><img src="../gifs/txthome.gif" alt="Home" border="0" /></a></td><td align="right" valign="top" width="228"><a href="part8.htm"><img src="../gifs/txtnexta.gif" alt="Next" border="0" /></a></td></tr><tr><td align="left" valign="top" width="228">19.3. Adding an Entry to the Directory with Net::LDAP</td><td align="center" valign="top" width="228"><a href="index/index.htm"><img src="../gifs/index.gif" alt="Book Index" border="0" /></a></td><td align="right" valign="top" width="228">VIII. LWP</td></tr></table></div>
<hr width="684" align="left" />

<img src="../gifs/navbar.gif" usemap="#library-map" border="0" alt="Library Navigation Links" />
<p><p><font size="-1"><a href="copyrght.htm">Copyright &copy; 2002</a> O'Reilly &amp; Associates. All rights reserved.</font></p>

<map name="library-map">
<area shape="rect" coords="1,0,85,94" href="../index.htm"><area shape="rect" coords="86,1,178,103" href="../lwp/index.htm"><area shape="rect" coords="180,0,265,103" href="../lperl/index.htm"><area shape="rect" coords="267,0,353,105" href="../perlnut/index.htm"><area shape="rect" coords="354,1,446,115" href="../prog/index.htm"><area shape="rect" coords="448,0,526,132" href="../tk/index.htm"><area shape="rect" coords="528,1,615,119" href="../cookbook/index.htm"><area shape="rect" coords="617,0,690,135" href="../pxml/index.htm">
</map>

</body></html>