ruby-ldapserver 0.3.1

data/COPYING

@@ -0,0 +1,27 @@
+The file 'test/core.schema' is Copyrighted by the OpenLDAP project. See the
+comments in that file for full details.
+
+All other files in this distribution are subject to the following copyright
+notice:
+
+COPYING
+=======
+Copyright (c) 2005 Brian Candler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

data/ChangeLog

@@ -0,0 +1,83 @@
+0.3.1 - 2008-01-16
+* First release as a gem [Brandon Keepers]
+
+RELEASE_0_3
+
+Filters now return nil instead of LDAP::Server::MatchingRule::DefaultMatch
+in the case that there's no schema.
+Minor changes to syntax.rb to support OpenLDAP extensions.
+
+20050722
+
+Change the 'validate' API so it works for updates too.
+Change the 'modify' API so it sends a hash of attr=>[:op,data] which makes
+it easier to determine which entries have been modified.
+Fix modify, add and compare to normalise attribute names using the schema if
+there is one.
+
+20050721
+
+Added a whole loada Schema stuff.
+Moved exceptions under LDAP::ResultError for consistency with ruby-ldap.
+Changed the parsed [filter] format to include a MatchingRule object always
+(even if no schema is present)
+
+20050711
+
+Changed LDAPserver to LDAP::Server and rejigged the repository to match.
+In your code you will have to change:
+  require 'ldapserver/foo'  ->  require 'ldap/server/foo'
+  LDAPserver::bar           ->  LDAP::Server::bar
+
+I have added require 'ldap/server' which pulls in the things a basic server
+will need (minus schema)
+
+20050626
+
+Factored out the SSL stuff into Connection, which should also allow the
+STARTTLS extension to be implemented later
+
+Added a Server class, with methods run_tcpserver and run_prefork.
+
+Created an explicit preforkserver method.
+
+20050625
+
+tcpserver: add ability to drop privileges
+
+examples/rbslapd3.rb: make work if ldapdb.yaml does not exist. Also bind
+explicitly to 0.0.0.0; it seems that TCPSocket doesn't work properly in
+some circumstances without it (FreeBSD 5.4 with IPv6 disabled in kernel)
+
+20050620
+
+RELEASE_0_2
+
+Implemented SSL support in tcpserver, just by copying examples from
+openssl module.
+
+Tweak split_dn so that it should work properly with UTF-8 encoded strings
+
+Added examples/rbslapd3.rb, a preforking LDAP server
+
+Added :listen option to tcpserver to set listen queue size. With the default
+of 5, and 100 children trying to connect, a few connections get dropped.
+
+Added :nodelay option to tcpserver to set TCP_NODELAY socket option. This
+removes 100ms of latency in responses.
+
+Added examples/speedtest.rb
+
+20050619
+
+Modify connection.rb to ensure no memory leak in the event of exceptions
+being raised in operation threads.
+
+Fix examples/rbslapd2.rb SQLPool so that it always puts connections back
+into the pool (using 'ensure' this time :-)
+
+20050618
+
+RELEASE_0_1
+
+20050616

data/Manifest.txt

@@ -0,0 +1,32 @@
+COPYING
+ChangeLog
+Manifest.txt
+README
+Rakefile
+examples/README
+examples/mkcert.rb
+examples/rbslapd1.rb
+examples/rbslapd2.rb
+examples/rbslapd3.rb
+examples/speedtest.rb
+lib/ldap/server.rb
+lib/ldap/server/connection.rb
+lib/ldap/server/filter.rb
+lib/ldap/server/match.rb
+lib/ldap/server/operation.rb
+lib/ldap/server/preforkserver.rb
+lib/ldap/server/result.rb
+lib/ldap/server/schema.rb
+lib/ldap/server/server.rb
+lib/ldap/server/syntax.rb
+lib/ldap/server/tcpserver.rb
+lib/ldap/server/util.rb
+lib/ldap/server/version.rb
+test/core.schema
+test/encoding_test.rb
+test/filter_test.rb
+test/match_test.rb
+test/schema_test.rb
+test/syntax_test.rb
+test/test_helper.rb
+test/util_test.rb

data/README

@@ -0,0 +1,222 @@
+CHANGES FROM VERSION 0.2 TO VERSION 0.3
+---------------------------------------
+
+There have been substantial changes to ruby-ldapserver between version 0.2
+and version 0.3. If you have not been using 0.2, you can skip this section.
+
+Major API changes:
+
+* I have renamed module LDAPServer to module LDAP::Server, This means e.g.
+require 'ldapserver/connection' becomes require 'ldap/server/connection'
+
+* I have moved the result exceptions to be subclasses of LDAP::ResultError,
+for consistency with ruby-ldap, and named under LDAP::ResultError::<name> to
+group them together. Everything else remains under LDAP::Server.
+
+* The format of the parsed 'filter' parameter to Operation#search has
+changed. See filter.rb. In particular, the format of a :substrings filter
+has been changed (simplified).
+
+* The format of the 'modinfo' parameter to Operation#modify has changed. See
+the comment above 'def modify' in operation.rb
+
+* Attribute names are no longer automatically downcased. If you are running
+with a schema, however, then they will be converted into their preferred
+forms. That is, "OBJECTCLASS" will become "objectClass", "CommonName" will
+become "cn", and so on.
+
+Improvements include:
+
+* There is now an explicit object representing a server instance:
+"LDAP::Server". This bundles together the root DSE, the schema (if used),
+the subclass of Operation which you wish to use, and various other
+parameters such as ssl certificate data. It has methods run_tcpserver and
+run_prefork, making it straightforward to start a server. Both support SSL
+on connect. You can do require 'ldap/server' to get all the essential
+libraries for a server.
+
+* LDAP::Server :user and :group settings let you drop privileges after
+binding to port 389.
+
+* Schema support. Can load schemas in OpenLDAP format, publish them via
+LDAP, validate add/modify operations, use them to map attribute names to
+their 'standard' versions (e.g. "commonname" becomes "cn"), and perform
+case-insensitive comparisons where the schema mandates this. See classes
+LDAP::Server::Schema, LDAP::Server::ObjectClass, LDAP::Server::AttributeType,
+LDAP::Server::Syntax, LDAP::Server::MatchingRule, and examples/rbslapd3.rb.
+
+What is it?
+-----------
+
+ruby-ldapserver is a lightweight, pure Ruby skeleton for implementing LDAP
+server applications. It is intended primarily for when you wish to build a
+gateway from LDAP queries into some other protocol or database; it does not
+attempt to be a full implementation of the standard LDAP data model itself
+(although you could build one using this as a frontend)
+
+The Connection class handles incoming connections, decodes ASN1-formatted
+LDAP requests, and creates an Operation object for each request. The
+Operation object further parses the ASN1 request and invokes methods which
+you override to perform useful work. Responses and exceptions are converted
+back into ASN1 and returned to the client. Optionally, a collection of
+objects can be used to implement a Schema (e.g. normalize attribute names,
+validate add and modify operations, perform appropriate matching operations)
+
+Since it's written entirely in Ruby, it benefits from Ruby's threading
+engine.
+
+Target audience
+---------------
+
+Technically-savvy Ruby applications developers; the sort of people who are
+happy to read RFCs and read code to work out what it does :-)
+
+The examples/ directory contains a few minimal LDAP servers which you can
+use as a starting point.
+
+Status
+------
+
+This is an early release. It works for me as an LDAP protocol convertor; the
+Schema stuff has not been heavily tested by me.
+
+Libraries
+---------
+
+ASN1 encoding and decoding is done using the 'openssl' extension, which is
+standard in the Ruby 1.8.2 base distribution. To check you have it, you
+should be able to run `ruby -ropenssl -e puts` with no error.
+
+However, I've found in the past that Linux machines don't always build the
+openssl extension when compiling Ruby from source. With Red Hat 9, the
+solution for me was, when building Ruby itself:
+
+    # export CPPFLAGS="-I/usr/kerberos/include"
+    # export LDFLAGS="-L/usr/kerberos/lib"
+    # ./configure ...etc
+
+If you want to run the test suite then you'll need to install the ruby-ldap
+client library, and if you want to run examples/rbslapd3.rb then you'll need
+the prefork library. Both are available from <http://raa.ruby-lang.org/>.
+
+Protocol implementation
+-----------------------
+
+ruby-ldapserver tries to be a reasonably complete implementation of the
+message decoding and encoding components of LDAP. However, it does not
+synthesise or directly enforce the LDAP data model. It will advertise a
+schema in the root DSE if you configure one, and it provides helper
+functions which allow you to validate add and modify operations against a
+schema; but it's up to you to use them, if you wish. If you're just using
+LDAP as a convenient query interface into some other database, you probably
+don't care about schemas.
+
+If your clients permit it, you can violate the LDAP specification further,
+eliminating some of the gross design flaws of LDAP. For example, you can
+ditch the LDAP idea that a Distinguished Name must consist of
+attr=val,attr=val,attr=val... and use whatever is convenient as a primary
+key (e.g. "val1,val2,val3" or "id,table_name"). The 'add' operation could
+allocate DNs automatically from a sequence. There's no need for the data
+duplication where an LDAP entry must contain the same attr=val pair which is
+also the entry's RDN. Violations of the LDAP spec in this way are at your
+own risk.
+
+Threading issues
+----------------
+
+The core of this library is the LDAP::Server::Connection object which handles
+communication with a single client, and the LDAP::Server::Operation object
+which handles a single request. Because the LDAP protocol allows a client to
+send multiple overlapping requests down the same TCP connection, I start a
+new Ruby thread for each Operation.
+
+If your Operation object deals with any global shared data, then it needs to
+do so in a thread-safe way. If this is new to you then see
+<http://www.rubycentral.com/book/tut_threads.html>
+<http://www.rubygarden.org/ruby?MultiThreading>
+
+For incoming client connections, I have supplied a simple tcpserver method
+which starts a new Ruby thread for each client. This works fine, but in a
+multi-CPU system, all LDAP server operations will be processed on one CPU;
+also with a very large number of concurrent client connections, you may find
+you hit the a max-filedescriptors-per-process limit.
+
+I have also provided a preforking server; see examples/rbslapd3.rb. In this
+case, your connections are handled in separate processes so they cannot
+share data directly in RAM.
+
+If you are using the default threading tcpserver, then beware that a number
+of Ruby extension libraries block the threading interpreter. In particular,
+the client library "ruby-ldap" blocks when waiting for a response from a
+remote server, since it's a wrapper around a C library which is unaware of
+Ruby's threading engine. This can cause your application to 'freeze'
+periodically. Either choose client libraries which play well with threading,
+or make sure each client is handled in a different process.
+
+For example, when talking to a MySQL database, you might want to choose
+"ruby-mysql" (which is a pure Ruby implementation of the MySQL protocol)
+rather than "mysql-ruby" (which is a wrapper around the C API, and blocks
+while waiting for responses from the server)
+
+Even with something like ruby-mysql, beware DNS lookups: resolver libraries
+can block too. There is a pure Ruby resolver replacement in the standard
+library: if you do
+
+    require 'resolv-replace'
+
+this changes TCPSocket and friends to use it instead of the default C
+resolver. Or you could just hard-code IP addresses, or put entries in
+/etc/hosts for the machines you want to contact.
+
+Another threading issue to think about is abandoned and timed-out LDAP
+operations. The Connection object handles these by raising an
+LDAP::Server::Abandon or LDAP::Server::TimeLimitExceeded exception in the
+Operation thread, which you can either ignore or rescue. However, if in
+rescuing it you end up putting (say) a SQL connection back into a pool, you
+should beware that the SQL connection may still be mid-query, so it's
+probably better to discard it and use a fresh one next time.
+
+Performance
+-----------
+
+examples/speedtest.rb is a simple client which forks N processes, and in
+each process opens an LDAP connection, binds, and sends M search requests
+down it.
+
+Using speedtest.rb and rbslapd1.rb, running on the *same* machine
+(single-processor AMD Athlon 2500+) I achieve around 800 searches per second
+with N=1,M=1000 and 300-400 searches per second with N=10,M=100.
+
+To-do list
+----------
+
+- handle and test generation of LDAP referrals properly
+- more cases in test suite: abandon, concurrency, performance tests, error
+  handling
+- extensible match filters
+- extended operations
+  RFC 2830 - Start TLS
+  RFC 3062 - password modify
+  RFC 2839 - whoami
+  RFC 3909 - cancel
+
+References
+----------
+
+- ftp://ftp.isi.edu/in-notes/rfc2251.txt (base protocol)
+- ftp://ftp.isi.edu/in-notes/rfc2252.txt (schema)
+- ftp://ftp.isi.edu/in-notes/rfc2253.txt (DN encoding)
+- http://www.itu.int/ITU-T/studygroups/com17/languages/X.680-0207.pdf
+- http://www.itu.int/ITU-T/studygroups/com10/languages/X.690_1297.pdf
+
+Contact
+-------
+
+You are very welcome to E-mail me with bug reports, patches, comments and
+suggestions for this software. However, please DON'T send me any general
+questions about LDAP, how LDAP works, how to apply LDAP in your particular
+situation, or questions about any other LDAP software. The `ldap@umich.edu`
+mailing list is probably the correct place to ask such questions. See:
+<http://listserver.itd.umich.edu/cgi-bin/lyris.pl?enter=ldap>
+
+Brian Candler <B.Candler@pobox.com>

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rubygems'
+require 'hoe'
+require File.join(File.dirname(__FILE__), 'lib', 'ldap', 'server', 'version')
+
+RDOC_OPTS = ['--quiet', '--title', "ruby-ldapserver",
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+# Generate all the Rake tasks
+hoe = Hoe.new('ruby-ldapserver', ENV['VERSION'] || LDAP::Server::VERSION::STRING) do |p|
+  p.rubyforge_name = 'ruby-ldapserver'
+  p.summary = "A pure-Ruby framework for building LDAP servers"
+  p.description = "ruby-ldapserver is a lightweight, pure-Ruby skeleton for implementing LDAP
+  server applications."
+  p.author = 'Brian Candler'
+  p.email = 'B.Candler@pobox.com'
+  p.url = 'http://rubyforge.org/projects/ruby-ldapserver'
+  p.test_globs = ["test/**/*_test.rb"]
+  p.changes = p.paragraphs_of('ChangeLog', 0..1).join("\n\n")
+end

data/examples/README

@@ -0,0 +1,89 @@
+Using the example programs
+==========================
+
+These servers all listen on port 1389 by default, so that they don't have to
+be run as root.
+
+Example 1: trivial server using RAM hash
+----------------------------------------
+
+$ ruby rbslapd1.rb
+
+In another window:
+
+$ ldapadd -H ldap://127.0.0.1:1389/
+dn: dc=example,dc=com
+cn: Top object
+
+dn: cn=Fred Flintstone,dc=example,dc=com
+cn: Fred Flintstone
+sn: Flintstone
+mail: fred@bedrock.org
+mail: fred.flintstone@bedrock.org
+
+dn: cn=Wilma Flintstone,dc=example,dc=com
+cn: Wilma Flintstone
+mail: wilma@bedrock.org
+^D
+
+Try these queries:
+
+$ ldapsearch -H ldap://127.0.0.1:1389/ -b "" "(objectclass=*)"
+$ ldapsearch -H ldap://127.0.0.1:1389/ -b "dc=example,dc=com" -s base "(objectclass=*)"
+$ ldapsearch -H ldap://127.0.0.1:1389/ -b "dc=example,dc=com" "(mail=fred*)"
+
+If you terminate the server with Ctrl-C, its contents should be written
+to disk as a YAML file.
+
+A fairly complete set of the filter language is implemented. However, this
+simple server works by simply scanning the entire database and applying the
+filter to each entry, so it won't scale to large applications. No validation
+of DN or attributes against any sort of schema is done.
+
+Example 1a: with SSL
+--------------------
+
+In rbslapd1.rb, uncomment
+
+	:ssl_key_file		=> "key.pem",
+	:ssl_cert_file		=> "cert.pem",
+	:ssl_on_connect		=> true,
+
+and run mkcert.rb. Since this is a self-signed certificate, you'll have to
+turn off certificate verification in the client too. For example:
+
+    $ env LDAPTLS_REQCERT="allow" ldapsearch -H ldaps://127.0.0.1:1389/
+
+Making your own CA and installing its certificate in the client, or
+generating a Certificate Signing Request and sending it to a known CA, is
+beyond the scope of this documentation.
+
+Example 2: simple LDAP to SQL mapping
+-------------------------------------
+
+You will need to set up a MySQL database with a table conforming to the
+schema given within the code. Once done, LDAP gives a read-only view of the
+database with only the filter "(uid=<foo>)" supported.
+
+Example 3: preforking server and schema
+---------------------------------------
+
+This functions in the same way as rbslapd1.rb. However, since each query is
+answered in a separate process, the YAML file on disk is used as the master
+repository. Update operations re-write this file each time.
+
+Also, the schema is read from file 'core.schema'. Attempting to insert the
+above entries will fail, due to schema violations. Insert a valid entry,
+e.g.
+
+dn: cn=Fred Flintstone,dc=example,dc=com
+objectClass: organizationalPerson
+cn: Fred Flintstone
+sn: Flintstone
+telephoneNumber: +1 555 1234
+telephoneNumber: +1 555 5432
+
+Schema validation takes place for the attribute values and that attributes
+are allowed/required by the objectclass(es); however, the DN itself is not
+validated, nor any checks made that the RDN is present as an attribute
+(since this is one of the more stupid parts of the LDAP/X500 data model)