Menu
▾
▴
[perl-ldap-checkins] CVS: ldap/lib/Net LDAP.pod,1.29,1.30 LDAPS.pm,1.15,1.16 LDAPI.pm,1.3,1.4
|
From: Chris R. <chr...@us...> - 2003-05-22 09:24:27
|
Update of /cvsroot/perl-ldap/ldap/lib/Net
In directory sc8-pr-cvs1:/tmp/cvs-serv7386/lib/Net
Modified Files:
LDAP.pod LDAPS.pm LDAPI.pm
Log Message:
Moved guts of LDAP[SI] doc into LDAP.pod
Index: LDAP.pod
===================================================================
RCS file: /cvsroot/perl-ldap/ldap/lib/Net/LDAP.pod,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -d -r1.29 -r1.30
--- LDAP.pod 9 May 2003 18:19:54 -0000 1.29
+++ LDAP.pod 22 May 2003 09:24:23 -0000 1.30
@@ -62,7 +62,7 @@
C<HOST> may be a host name or an IP number. TCP port may be specified
after the host name followed by a colon (such as localhost:10389). The
-default TCP port is 389.
+default TCP port for LDAP is 389.
You can also specify a URI, such as 'ldaps://127.0.0.1:666' or
'ldapi://%2fvar%2flib%2fldap_sock'. Note that '%2f's in the LDAPI
@@ -140,9 +140,9 @@
=item version
-Set the protocol version being used (default is LDAPv2). This is
-useful if you want to avoid sending a bind operation and therefore
-have to use LDAPv3.
+Set the protocol version being used (default is LDAPv3). This is
+useful if you want to talk to an old server and therefore have to use
+LDAPv2.
=back
@@ -150,6 +150,14 @@
$ldap = Net::LDAP->new('remote.host', async => 1);
+LDAPS connections have some extra valid options, see the
+L<start_tls|start_tls> method for details. Note the default value for
+'sslversion' for LDAPS is 'sslv2/3', and the default port for LDAPS
+is 636.
+
+For LDAPI connections, HOST is actually the location of a UNIX domain
+socket to connect to. The default location is '/var/lib/ldapi'.
+
=back
=head1 METHODS
@@ -726,10 +734,14 @@
=item start_tls ( [ OPTIONS ] )
-Calling this method will convert the connection to using Transport
-Layer Security (TLS), which potentially provides an encrypted
-connection. This is I<only> possible if the connection is using
-LDAPv3. OPTIONS is a number of key-value pairs which describe how to
+Calling this method will convert the existing connection to using
+Transport Layer Security (TLS), which provides an encrypted
+connection. This is I<only> possible if the connection uses LDAPv3,
+and requires that the server advertizes support for
+LDAP_EXTENSION_START_TLS. Use
+L<Net::LDAP::RootDSE/supported_extension> to check this.
+
+OPTIONS is a number of key-value pairs which describe how to
configure the security of the connection:
=over 4
Index: LDAPS.pm
===================================================================
RCS file: /cvsroot/perl-ldap/ldap/lib/Net/LDAPS.pm,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -d -r1.15 -r1.16
--- LDAPS.pm 8 May 2003 19:46:23 -0000 1.15
+++ LDAPS.pm 22 May 2003 09:24:24 -0000 1.16
@@ -31,23 +31,24 @@
verify => 'require',
capath => '/usr/local/cacerts/');
-=head1 DESCRIPTION
+ # alternate way
+ use Net::LDAP;
-Communicate using the LDAP protocol to a directory server using a
-potentially encrypted (SSL) network connection.
+ $ldaps = new Net::LDAP('ldaps://myhost.example.com:10000',
+ verify => 'require',
+ capath => '/usr/local/cacerts/');
-This class is a subclass of Net::LDAP so all the normal Net::LDAP
-methods can be used with a Net::LDAPS object; see the documentation
-for Net::LDAP to find out how to query a directory server using the
-LDAP protocol.
+=head1 DESCRIPTION
-Note that the use of LDAPS is not recommended, because it is not
-described by any IETF documents. Instead, you should consider using
-LDAPv3 with the TLS extension defined in RFC 2830. This will give you
-the same functionality as LDAPS, but using recognized standards.
-Unfortunately servers may support LDAPS but not the TLS extension. See
+Communicate using the LDAP protocol to a directory server using an
+encrypted (SSL) network connection. This mechanism is non-standard but
+widely supported; consider using LDAPv3 with the standard TLS
+extension if possible (many servers do not support it yet.) See
L<Net::LDAP/start_tls>.
+All the normal C<Net::LDAP> methods can be used with a C<Net::LDAPS>
+object; see L<Net::LDAP> for details.
+
=head1 CONSTRUCTOR
=over 4
@@ -55,98 +56,7 @@
=item new ( HOST [, OPTIONS ] )
Create a new connection. HOST is the hostname to contact. OPTIONS is a
-number of key/value pairs - additional keys to those understood by
-Net::LDAP::new are:
-
-=over 4
-
-=item verify
-
-How to verify the server's certificate, either 'none' (the server may
-provide a certificate but it will not be checked - this may mean you
-are be connected to the wrong server), 'optional' (verify if the
-server offers a certificate), or 'require' (the server must provide a
-certificate, and it must be valid.) If you set verify to optional or
-require, you must also set either cafile or capath. The most secure
-option is 'require'.
-
-=item sslversion
-
-This defines the version of the SSL/TLS protocol to use. Defaults to
-'sslv2/3', other possible values are 'sslv2', 'sslv3', and 'tlsv1'.
-
-=item ciphers
-
-Specify which subset of cipher suites are permissible for this
-connection, using the standard OpenSSL string format. The default
-value for ciphers is 'ALL', which permits all ciphers, even those that
-don't encrypt!
-
-=item clientcert
-
-=item clientkey
-
-=item keydecrypt
-
-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 clientcert to the user's certificate file, and
-clientkey to the user's private key file. These files B<must> be in
-PEM format.
-
-If the private key is encrypted (highly recommended!) then set
-keydecrypt to a reference to a subroutine that returns the decrypting
-key. For example:
-
- $ldaps = new Net::LDAPS('myhost.example.com',
- port => '636',
- verify => 'require',
- clientcert => 'mycert.pem',
- clientkey => 'mykey.pem',
- keydecrypt => sub { 'secret'; },
- capath => '/usr/local/cacerts/');
-
-=item capath
-
-=item cafile
-
-When verifying the server's certificate, either set capath to the
-pathname of the directory containing CA certificates, or set cafile to
-the filename containing the certificate of the CA who signed the
-server's certificate. These certificates B<must> all be in PEM format.
-
-The directory in 'capath' must contain certificates named using the
-hash value of the certificates' subject names. To generate these
-names, use OpenSSL like this in Unix:
-
- ln -s cacert.pem `openssl x509 -hash -noout < cacert.pem`.0
-
-(assuming that the certificate of the CA is in cacert.pem.)
-
-=back
-
-=back
-
-=head1 ADDITIONAL METHODS
-
-=over 4
-
-=item cipher
-
-Returns the cipher mode being used by the connection, in the string
-format used by OpenSSL.
-
-=item certificate
-
-Returns an X509_Certificate object containing the server's
-certificate. See the IO::Socket::SSL documentation for information
-about this class.
-
-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 this:
-
- print "Subject DN: " . $ldaps->certificate->subject_name . "\n";
+number of key/value pairs. See L<Net::LDAP/new> for details.
=back
Index: LDAPI.pm
===================================================================
RCS file: /cvsroot/perl-ldap/ldap/lib/Net/LDAPI.pm,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- LDAPI.pm 8 May 2003 19:46:23 -0000 1.3
+++ LDAPI.pm 22 May 2003 09:24:24 -0000 1.4
@@ -26,17 +26,21 @@
use Net::LDAPI;
- $ldaps = new Net::LDAPI('/var/lib/ldapi');
+ $ldapi = new Net::LDAPI('/var/lib/ldapi');
+
+ # alternate way
+ use Net::LDAP;
+
+ $ldapi = new Net::LDAP('ldapi://');
=head1 DESCRIPTION
-Communicate using the LDAP protocol to a directory server using a
-UNIX domain socket.
+Communicate using the LDAP protocol to a directory server using a UNIX
+domain socket. This mechanism is non-standard, UNIX-specific and not
+widely supported.
-This class is a subclass of Net::LDAP so all the normal Net::LDAP
-methods can be used with a Net::LDAPI object; see the documentation
-for Net::LDAP to find out how to query a directory server using the
-LDAP protocol.
+All the normal C<Net::LDAP> methods can be used with a C<Net::LDAPI>
+object; see L<Net::LDAP> for details.
=head1 CONSTRUCTOR
@@ -44,9 +48,9 @@
=item new ( [SOCKPATH] )
-Create a new connection. SOCKPATH can optionally be specified, to specify
-the location of the UNIX domain socket to connect to. By default, the
-domain socket path is '/var/lib/ldapi'. This is OpenLDAP-specific.
+Create a new connection. SOCKPATH can optionally be specified, to
+specify the location of the UNIX domain socket to connect to. See
+L<Net::LDAP/new> for details.
=back
|
