The LDAP Proxy is part of an email encryption architecture designed to facilitate the exchange of encrypted email through the use of X.509 personal certificates. The personal certificates contain public email encryption keys needed by the email sender to encrypt email that only the recipient can decrypt. The LDAP Proxy is given an email address and searches remote LDAP servers for an X.509 public certificate belonging to the person who matches the email address. This certificate is returned to the requester and the public encryption key contained in the certificate is used by the requester's email program to encrypt email to be sent to the owner of the certificate.
The LDAP Proxy can also be used to find and return certificate revocation lists (CRL), CA & signing certificates, and other specific data stored on LDAP database servers.
The LDAP Proxy is part of the Public Key Infrastructure (PKI) based email encryption architecture presented to the Open Group Messaging Forum in 2002 as The Boeing Company Secure Messaging Challange.
Under the PKI scheme, each user has two encryption keys; a public key that allows encryption and a private key which allows decryption. These keys are contained in the user's public and private X.509 user certificates. Anyone who has a copy of a user's public certificate can encrypt email that only the certificate's owner can decrypt using their private certificate. Locating and exchanging the public encryption keys has been considered a bottleneck to the PKI email encryption approach. The LDAP Proxy is designed to facilitate the location and exchange of these public certificates.
The LDAP Proxy is not an LDAP server, though it tends to look like one to the LDAP client utilities that send it search requests. It is designed to find and return X.509 type certificates and Certificate Revocation Lists (CRL) for use in email encryption. Information about multiple LDAP servers is defined in the LDAP Proxy so that users only have to query the LDAP Proxy to find public encryption certificates for people from a variety of companies. Consequently the users do not need to query each company's LDAP server to find the encryption certificate they need.
The LDAP Proxy will process only three types of LDAP search requests:
All other types of LDAP queries are not processed. This allows LDAP Proxies on a company firewall to act as a filter when accessing LDAP database servers within the firewall. The Proxy finds and returns specific data but denies access to the rest of the data in the LDAP database.
By default, the LDAP Proxy listens on the standard LDAP port (389) for LDAP queries. These queries can be made from any type of LDAP client but will typically come from an addressbook client or email program. An example of the LDAP Proxy in operation is the Boeing Company's LDAP Proxy Service located at dir.boeing.com port 389, and its Web Interface located at URL http://www.boeing.com/companyoffices/doingbiz/ldap_proxy/get_cert.html.
LDAP Requests for public encryption certificates must have a search filter containing a valid email address. The email address is used by the LDAP Proxy to search a locally maintained list of LDAP servers (See "LDAP Server Lists" below). These servers provide employee information for the companies and organizations that own the server. If the LDAP Proxy finds an LDAP server in the list that services the requested email address, an LDAP query is made to that server using the email address as a search key. If employee information is available for that email address, the LDAP Proxy collects the common name of the employee and their public certificate (if available) and returns these items to the original requester. Once the requester's email program has the public certificate, it can send encrypted email to the owner of that certificate.
The Boeing LDAP Proxy --------------------- ----------- ----------- | Boeing | | Boeing | | ldap | | ldap | | clients | | servers | ----------- ---------- ----------- ^ | Boeing | ^ | | Admin | | | ^ ---------- ^ | | | | | | email | user name | email | user name addr | email addr | addr | email addr | | public cert | | public cert V | | | | | | | V | ---------------------------------------|---------- | | | LDAP_PROXY V | | | | ---------------- | | | | | Cert & LDAP | | | | | | server lists | | | | | ---------------- | | | | | | | | | V | | V | -------------- email addr -------------- | V \ | | |--------------->| | | / <---->| OpenLDAP | | getcert |<----> / | | |<---------------| | | \ ^ | -------------- user name -------------- | ^ | | email addr | | | | public cert | | | | | | | -------------------------------------------------- | | | | | ========|===================Boeing firewall======================|============ | | | | ^ ^ | | | | | user name email | user name email | email addr addr | email addr addr | public cert | | public cert | | V | | V | | | V V -------------- -------------- | non-Boeing | | non-Boeing | | ldap | | ldap | | clients | | servers | -------------- --------------
Requests for CRLs and CA/signing certificates must contain two pieces of information: the data attribute name (for example, "CertificateRevocationList" or "cACertificate"), and a BaseDN (Distinquished Name) which defines the location of the data on the LDAP server. An example of a BaseDN is ou=netscape,ou=certservers,o=Boeing,c=US. The BaseDN and the attribute name are compared with BaseDNs and attribute names listed in the locally maintained LDAP server list (See "LDAP Server Lists" below). If a match is found, an LDAP search request is send by the LDAP Proxy to the matched LDAP server specifying the BaseDN as the location of the attribute on that server and the attribute name as the name of the data we are looking for. The Proxy will fetch one or more CRLs or certificates from the LDAP server and return them to the requesting client.
The current version of ldap_proxy is 4.2.
and is made up of:
OpenLDAP 2.1.30
( http://www.openldap.org/ )
getcert 4.2
The LDAP Proxy software is made up of two components. The OpenLDAP "slapd" daemon is used as the LDAP front-end process and a locally written facility called "getcert" is used as a back-end process to slapd. The front-end process listens on LDAP port 389 and establishes LDAP sessions with remote LDAP clients. When the front-end receives an LDAP query from the remote client, the LDAP search parameters are handed to the back-end process getcert. Getcert then matches the search criteria with entries in the LDAP server lists and queries the appropriate remote LDAP servers for the requested data. Search results are handed back to the slapd front-end process which sends the data to the remote LDAP client and terminates the LDAP session.
The ldap_proxy has been tested on Sun Solaris 8, 9 & 10, RedHat Linux 8 & 9, Fedora Core 3, 4 & 5, and SuSE Linux 9 servers. In theory, it can be compiled and run on any UNIX system that is capable of running OpenLDAP. Instructions for building the LDAP Proxy from source code are included with the LDAP Proxy source code distribution which is available for download from SourceForge.net.
The LDAP Proxy uses a three number version notation to identify the release version. The major version is the left hand number and is incremented only after the source code has undergone a major revision or major rewrite. The middle number is the minor version number and is incremented when new functionality or features are added to the code base. The right hand number is the patch level and is incremented whenever changes are made to the code base but no new functionality is added. If no patches or other changes are made to the code since the minor version was released, no patch level number is listed (i.e., version 2.5 rather than 2.5.0).
The LDAP Proxy uses two locally maintained lists of LDAP servers to define the access information to the servers and the type of data available from that server. At least one of these lists must be available to the Proxy. The full path names to these files are defined in the slapd configuration file (see "Configuration File" below).
The certificate server list is called "certificate_server_list.txt"
and lists information about each LDAP server that can be accessed to
fetch individual pubic encryption certificates. It is an ascii text
file which is read into memory when the Proxy is started. Each
server entry in the list is made up of either seven or nine lines
with one server option per line. Each server entry is separated by
a blank line.
The server options are as follows:
The first seven options are always required and define an LDAP server that allows anonymous access. The last two options are required if the LDAP server requires access authentication.
Example server list entry:
boeing.com | |
directory.boeing.com | |
389 | |
ou=People,o=Boeing,c=US | |
boeingStableAddress | |
boeingDisplayName | |
userCertificate | |
boeingAppCn=ldap_app,ou=apps,o=Boeing,c=US | |
bind_password |
Email Domain Parsing
The ldap_proxy searches the list from the top down using the email
domain name of the input email filter as the search key. The email
domain will be scanned from left to right and each sub-domain of the
email address will be searched until a match is found or only one
email domain (containing a single ".") remains.
For example, if the email filter contains the email address
"Joe.User@dept_32.richmond.virginia.planecorp.com"
the Proxy would make up to four comparisons of each entry in the
server list searching for a match with one of the following email
domains:
If no match is found with the current server entry, the Proxy moves on to the next server entry in the list and begins the four comparisons again. In this way we would find departmental LDAP servers in the list before we found company-wide LDAP servers.
Server Fail-Over and Redundancy
LDAP servers that serve the same email domain can be defined in the
server list. If the LDAP Proxy does not find a public certificate
for the specified email address on one server, it will continue
searching the server list for the next server that serves the desired
email domain. For example, If a company has both primary and backup
LDAP servers, both can be listed in the server list so that the backup
server will be queried by the LDAP Proxy if the primary server goes
off line. Another example would be the splitting of user data among
several servers. The LDAP Proxy would query each in turn until a
valid certificate was found. The local admin controls the order the
Proxy queries the servers by the order they are listed in the server
list.
Server Wildcarding
If the email domain field in the server list entry is a single "*"
character, the server list entry will match any email address.
The server defined by this wildcarded server list entry will always
be searched for the email address specified in the LDAP query, unless
a usable certificate was found on a server defined by a preceeding
server list entry. This is used to define one or more "catch-all"
LDAP servers as the last entries in the server list.
The LDAP server list is called "ldap_server_list.txt" and is an
ascii text file which is read into memory when the Proxy is started.
Each server entry in the list is made up of either five or seven
lines with one server option per line. Each server entry is
separated by a blank line.
The server options are as follows:
The first five options are always required and define an LDAP server that allows anonymous access. The last two options are required if the LDAP server requires access authentication.
Example server list entry:
CN=The Boeing Company Class 2 Certificate Authority,O=Boeing,C=US | |
pkiserver.boeing.com | |
389 | |
certificateRevocationList | |
none | |
boeingCn=ldapaccess,ou=applications,o=Boeing,c=US | |
bind_password |
For each incoming LDAP search request, the LDAP Proxy will compare the request's attributes and search DN with the entries in the LDAP Server List (if it exists). If a match is found with both the DN and one of the attribute names specified in the search request, the Proxy will request the attribute value from the matching server. If no attribute value is returned from that server, the Proxy will continuing searching the LDAP server list and querying matching servers until an attribute value is found or the end of the server list is reached.
If the attribute name in the fourth line of the server list entry is set to the keyword "all", all data from an LDAP entry can be returned. This keyword matches all attribute names for the entry pointed to by the BaseDN.
BaseDN and attribute name comparisons are done character by character and so the entries specified in the LDAP request and listed in the server list must be identical. However, the search is not case-sensitive so upper and lower case differences will not affect the comparisons.
In addition to the two LDAP server lists described above, the Proxy uses a configuration file called slapd.conf to initialize itself on startup. The Proxy installation will include a slapd.conf file with default values specified. Descriptions of each option are included in the slapd.conf file. The configuration options are as follows:
ucdata-path /usr/local/apps/ldap_proxy_4.1/share/openldap/ucdata Path to unicode support data used by slapd front end process. include /usr/local/apps/ldap_proxy_4.1/etc/openldap/schema/core.schema include /usr/local/apps/ldap_proxy_4.1/etc/openldap/schema/cosine.schema include /usr/local/apps/ldap_proxy_4.1/etc/openldap/schema/inetorgperson.schema These include files define the default LDAP database schema. Only attributes listed in the schema files included with these include statements can be returned by the LDAP Proxy. pidfile /usr/local/apps/ldap_proxy_4.1/var/slapd.pid This is where the Proxy will store the Process ID of the front-end process when ldap_proxy is started. argsfile /usr/local/apps/ldap_proxy_4.1/var/slapd.args This is where the Proxy will store the command line entry that was used to start slapd. loglevel 1024 Specifies the default type of debugging information from the front-end "slapd" process. This option has no effect on logging done by the "getcert" back-end process which is controlled by the "debugging" option (See "Logging" below). allow bind_v2 Allow access by LDAP clients that speak only LDAP version 2. idletimeout 600 Specify the number of seconds to wait before forcibly closing an idle client connection. An idletimeout of 0 disables this feature. database getcert Name of the back-end process. All options listed after this database option refer to the getcert process. readonly off Specifies read-only access to ldap_proxy back-end process. It is set to "off" so that ldap_proxy can be commanded to re-read the serverlist file while the Proxy is running. [The ability to re-read the serverlist while the Proxy is running is currently disabled.] lastmod off Set to "off" so that OpenLDAP does not attempt to maintain database maintenance fields (there is no database in the Proxy). access to * by anonymous read stop This defines access controls for the LDAP Proxy. In this case, anyone can query the Proxy. suffix "" Specifies the suffix of the database DN that can be passed to the back-end process. The null string allows the servicing of requests using any base DN (or no base DN). ######################################################## # The following options have default values which will # # be used if the option is not defined in slapd.conf. # ######################################################## debugging 0 The "debugging" option sets the debugging message level of the backend getcert process. When greater than zero, debugging messages from the backend process are logged via syslog to the LDAP Proxy log. To select debugging messages from several levels, you can add the levels. For example, to get high-level, low-level, and memory management messages logged together, specify "7" (level 1 + level 2 + level 4). Debugging levels greater than "1" are not likely to be useful except during software development. Debugging levels: 0 = No debugging messages are logged. 1 = General high-level debugging messages. 2 = Additional low-level debugging messages. 4 = Dynamic memory management messages. 8 = Messages from data parsing routines. [WARNING: Level 8 debugging will significantly degrade proxy performance.] [Default: 0] certificate_serverlist /usr/local/apps/ldap_proxy_4.1/libexec/certificate_server_list.txt "certificate_serverlist" is the full path name of the certificate_server_list file. This file lists all the LDAP servers that we can query for public X.509 certificates. [Default: NULL] ldap_serverlist /usr/local/apps/ldap_proxy_4.1/libexec/ldap_server_list.txt "ldap_serverlist" is the full path name of the ldap_server_list file. If this file exists and is not empty, the LDAP Proxy will be able to fetch CRL lists and CA/signing certificates. [Default: NULL] certificate_check 2 "certificate_check" determines how much checking the LDAP Proxy will do on the X.509 public encryption certificates it finds on the remote LDAP servers. Valid options are: 0 = No certificate checking. Certificates are not examined and are sent the the requesting client just as they are found. 1 = Each certificate is decoded to confirm that it is a readable X.509 certificate. 2 = Each certificate is decoded and must meet the following criteria before being sent to the requesting client: a) The certificate is rejected if it is not readable and identifiable as an X.509 certificate. b) The certificate validity dates are checked and the certificate is rejected if found to be expired or premature. c) The email address supplied by the client is compared with any email addresses defined in the certificate. If email addresses are defined in the certificate but none match the client specified email address, the certificate is rejected. [Default: 2] search_timeout 30 "search_timeout" sets the maximum number of seconds that the Proxy will wait for a response to its LDAP search request from a remote LDAP server or LDAP Proxy. A value of "0" seconds means no timeout limit (i.e., wait forever). [Default: 30 seconds]. certificatetype 0 "certificatetype" limits the Proxy to returning only one version of X.509 certificate. This option is ignored if the "certificate_check" option is set to skip certificate decoding. 0 = Return any version of certificate 1 = Return only version 1 certificates 2 = Return only version 2 certificates 3 = Return only version 3 certificates [Default: 0] limit_return_codes yes "limit_return_codes" controls the type of return codes the LDAP Proxy can return to the LDAP client. The LDAP Proxy communicates with LDAP clients by means of LDAP Return Codes. By default, the Proxy will return either LDAP_SUCCESS (0) or LDAP_OPERATIONS_ERROR (1) on completion of an LDAP request. If limit_return_codes is set to "no", the Proxy will return codes selected from an expanded set of LDAP Return Codes (see the list of possible return codes in the LDAP Proxy documentation [ldap_proxy_release_notes.html]). The use of expanded return codes allow more descriptive status messages during development and debugging. However, some client programs have problems interpreting return codes they do not understand or expect. [Default: no] search_all_servers no "search_all_servers" determines whether the LDAP proxy will search all LDAP servers listed in the certificate_server_lists.txt file for encryption certificates that can be used with the email address specified in the LDAP search request. The default behavior of the Proxy is to return only the certificates found at the first LDAP server that contains usable certificates for the specified email address. Setting "search_all_servers" to "yes" tells the LDAP proxy to keep searching for more certificates even if it has already found some usable certificates. All certificates found are returned. [Default: no] cert_issuer_accept cert_issuer_reject The "cert_issuer_accept" and "cert_issuer_reject" options allow you to select which Issuing Certificate Authorities you are willing, or unwilling, to deliver certificates for. The string values defined by these options are searched for within the "Issuer" section of the user certificates the Proxy retrieves from remote LDAP certificate servers. If any of the values defined here are found in the Issuer description, the certificate is either passed along to the requestor, or not, based on whether the which of the "cert_issuer_" options you are using. You can use as many of these options as you wish, each on a separate line. But NOTE: You can only specify all "cert_issuer_accept" options or all "cert_issuer_reject" options. You *CANNOT* mix the two types of options together. The string values are searched in a case-insensitive manner, but otherwise must match exactly part or all of the Issuing Certificate Authority description. Each string value should be surrounded by quotes. If you are defining "cert_issuer_accept" values, the Proxy will only deliver certificates that contain at least one of the cert_issuer_accept values in its Issuer section. If you are defining "cert_issuer_reject" values, the Proxy not deliver any certificates that contain any of the values defined here. These options are ignored if "the certificate_check" option is set to "0" as this disables certificate decoding. Examples: cert_issuer_accept "C=US, ST=Washington" - or - cert_issuer_reject "O=Operation Testing" cert_issuer_reject "self signed" [Default: NULL] normalize_common_name no The CN (CommonName) value returned with the certificates may be in the form "Last, First". Since this value will become part of the DN value returned to the LDAP client, OpenLDAP will have the comma replaced by "\2C" so that it is not mistaken for a comma delimiter in the DN string. However, some LDAP clients aren't smart enough to understand what "\2C" means. So we give the proxy admin the choice of having the CN rewritten to remove the comma. That should catch "Last, First" names and rewrite them as "First Last". If there is more than one comma in the CN, we don't know what kind of data is being represented in the CN and don't try to rewrite it. Setting "normalize_common_name" to "yes" will tell the LDAP Proxy to always rewrite CN values that contain a single comma. [Default: no] enforce_keyusage The "enforce_keyusage" option allows you to limit which certificates the LDAP Proxy returns based on the keyUsage flags set in the certificate. The optional key usage certificate extension defines the intended purpose of the key contained in the certificate. The LDAP Proxy can enforce any combination of the following nine key usage flags: digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, decipherOnly Each enforce_keyusage flag must be specified on a separate line. The key usage flags must be spelled as listed above but are case-insensitive. For example, to require that certificates contain both keyEncipherment and dataEncipherment flags before being delivered by the LDAP Proxy, use the following config options: enforce_keyusage keyEncipherment enforce_keyusage dataEncipherment When enforce_keyusage flags are specified, the LDAP Proxy will reject any certificate that does not have *all* of the key usage flags specified in the proxy config file with "enforce_keyusage" options. Note that the key usage is optional in X.509 certificates. If you specify any enforce_keyusage options and the certificate being examined does not contain keyUsage flags, it will be rejected. Also, if the "certificate_check" option (see above) is set to "0", the certificate is not read and no "enforce_keyusage" checking is done. [Default: NULL] #################################################### # The following options are used to fine-tune data # # structures within the LDAP Proxy. You probably # # do not want to mess around with them. # #################################################### max_queries 64 "max_queries" determines the size of the in-memory pending_queries table. This table keeps track of all the queries currently being processed by the Proxy. It is used to detect and deal with Proxy query infinite loops and denial of service attacks. Setting this too high wastes system resources. Setting it too low causes query rejections. The default value should be sufficient for typical Proxy configurations, though in extreme cases busy systems could need a larger table while a mostly idle system could use a smaller table. [Default: 64] max_results_cache 128 "max_results_cache" determines the size of an in-memory cache used for short-term storage of certificate search results from completed LDAP SEARCH queries. Microsoft's Outlook email client sends multiple LDAP commands for each single search. The client does not actually accept the bulk of the search results until they are send in response to the last LDAP query in the sequence. So we are forced to save all search results until we can determine if the next search request will meet the criteria. If so, we must send the results again from the cache. [Default: 128] max_results_life 30 "max_results_life" determines how long (in seconds) a cached search result will be held in the max_results_cache. Each time the proxy receives a new search query, it removes any cached search results that have been in the max_results_cache longer than max_results_life seconds. [Default: 30] max_certificates 128 "max_certificates" is the maximum number of certificates that the LDAP Proxy will return per search query. [Default: 128] #--------------------------------------------------------------------------
The following sections outline the details for installing the LDAP proxy using the following steps:
The LDAP Proxy software is distributed for Sun Solaris and Linux systems as a tarball named something like ldap_proxy_4.1.tar.gz. Move the tarball to the directory you wish to install ldap_proxy into. Uncompress the tarball via:
gunzip ldap_proxy_4.1.tar.gz
and extract the directory tree via:
tar xvf ldap_proxy_4.1.tar
You can now delete the tar file.
Once ldap_proxy has been installed, you must configure several files:
Modify the "PROXYHOME" line in these scripts to point to the directory that the Proxy has been installed in.
See the Configuration File section above for a description of the conf file entries. At a minimum you will need to modify the "ucdata-path", "include", "pidfile", "argsfile", "certificate_serverlist", and "ldap_serverlist" entries to reflect the full path to these files. The remaining options in the configuration file have default values which will be sufficient for most LDAP Proxy uses.
Enter LDAP server information for each remote LDAP certificate server or LDAP Proxy that this instance of ldap_proxy will be able to access (see "LDAP Server Lists" above). The default server list file that is installed via the LDAP Proxy install file will already some entries that can serve as examples.
Enter LDAP server information for each remote LDAP CRL server this instance of ldap_proxy will be able to access. (see "LDAP Server Lists" above). The default server list file that is installed via the LDAP Proxy install file will already some entries that can serve as examples.
Specify a log file for the LDAP Proxy via the syslog facility
by adding a line like the following to /etc/syslog.conf
[NOTE: The two fields must be separated by tab characters,
not spaces.]
local4.info;local4.debug /usr/local/logs/ldap_proxy.log
Then force the syslog daemon to reread the syslog.conf file via:
kill -1 PID
Where "PID" is the process ID of syslogd. More information about logging options is available below under: Logging.
If you have been running a version 3 LDAP Proxy and are now installing a version 4 LDAP proxy, you will need to move the server entries listed in your crl_server_list.txt file to the new ldap_server_list.txt file located in ldap_proxy_4.1/libexec/. The crl_server_list.txt file is no longer used.
There are two differences between version 3 entries and version 4 entries in the ldap_server_list.txt file. The fouth line of each entry used to be the CRL list attribute name. In version 4 this can be the attribute name for any single attribute in the LDAP entry pointed to by the BaseDN entry in the first line. In addition, it is now possible to return all core attributes from an LDAP entry by specifying "all" as the attribute name.
The second difference between the versions is the addition of a new, and as yet unimplemented, option in line five of the ldap_server_list.txt file entry. This will be a keyword to describe the type of data represented by the attribute name in line four. This will allow data verification. But for now, put "none" in line five of each entry. This moves the "bind dn" and "bind password" entries to lines 6 and 7.
ulimit -a
The LDAP Proxy startup script uses the following ulimit command to increase the number of file descriptors available to the Proxy:
ulimit -n 1024
Main Menu->System Settings->Security Level
local4.info;local4.debug -/usr/local/logs/ldap_proxy.log
Without this option, LDAP Proxy messages will be logged synchronously which can seriously degrade Proxy performance, especially when debugging messages are enabled in the slapd.conf file. To determine if your Linux implementation uses this option, check the syslog.conf(5) man page or look for entries in the /etc/syslog.conf file that are using this option.
By default, the LDAP Proxy listens on port 389 for incoming queries. Port 389 is the standard LDAP port and is known to LDAP clients as the default port. However, the proxy can be configured to listen on any port. This is done by use of the "-h" option to the slapd startup command (see below). If the LDAP Proxy is configured to run on any port less than 1024 (including port 389) it must be started and run under the "root" userid. If the proxy is run on a port number higher than 1024, any user can start and run the proxy. However, all LDAP clients that send queries to the proxy must specify the new port number in the LDAP request.
Start the Proxy via:
ldap_proxy_4.1/bin/start_ldap_proxy
Ldap_proxy process can also be started directly via:
ldap_proxy_4.1/libexec/slapd
This command and the startup script launches the slapd daemon in
the background.
slapd supports a number of command-line options as detailed in the
slapd(8) manual page. Below are a few of them:
-d | <debug level of front-end slapd process> (See "Logging" below). If this option is specified, slapd will run in the foreground and front-end debugging information will display to the screen as slapd runs. |
-f | <filename> This option specifies a different slapd.conf file than the default in ldap_proxy_4.1/etc/openldap/slapd.conf. |
-h | <URLlist> This option can be used to run the LDAP Proxy on a port other than the default LDAP port 389. For example, to run the Proxy on port 390, start slapd via:
ldap_proxy_4.1/libexec/slapd -h "ldap://0.0.0.0:390/"
|
-l | <syslog-local-user> Use this to specify a different log file for the Proxy to log to. The syslog-local-user value can be LOCAL0, LOCAL1, and so on, up to LOCAL7. The default value is LOCAL4. Use use the syslog-local-user value selected here when defining the log file name in /etc/syslog.conf: local6.info;local6.debug /usr/local/logs/ldap_proxy_alt.log |
Sending a HUP signal to the slapd process will allow the Proxy to
conclude any current LDAP session and shut down cleanly.
Stop the Proxy via:
ldap_proxy_4.1/bin/stop_ldap_proxy
You can also shut down the Proxy process directly if you know the process ID of the "slapd" process:
kill -1 PID
Where "PID" is the process ID of slapd.
On Linux systems, each ldap_proxy thread runs as a separate process. So there will be several slapd processes running at any one time. To bring down the ldap_proxy, it is only necessary to kill the process whose parent process is number "1".
There are three types of logging performed by the LDAP Proxy:
Only informational message logging is required for normal LDAP Proxy operations.
You must define in the /etc/syslog.conf file the log file(s) to be used by the LDAP Proxy(s) you intend to run on the system. By default the Proxy will use the "LOCAL4" syslog log facility to identify the log file in syslog.conf. You can override this default by using the "-l" option of the slapd command (See "Starting the Proxy" above for more details). You can specify LOCAL0, LOCAL1, and so on through LOCAL7 with the "-l" option.
Specify a log file for ldap_proxy via the syslog facility by
adding a line like the following to /etc/syslog.conf
[NOTE: The two fields must be separated by tab characters,
not spaces.]
local4.info;local4.debug /usr/local/logs/ldap_proxy.log
Then force the syslog daemon to reread the syslog.conf file via:
kill -1 PID
Where "PID" is the process ID of syslogd. Syslogd must reread the syslog.conf file whenever the log file is moved or renamed, even if it is renamed to the same name (i.e., log file rotation).
Debugging messages produced by the getcert back-end process can be configured using the "debugging" option in the slapd.conf configuration file. When greater than zero, debugging messages from the backend process are logged via syslog to the LDAP Proxy log. To select debugging messages from several levels, you can add the levels. For example, to get high-level, low-level, and memory management messages logged together, specify "debug 7" (level 1 + level 2 + level 4). Debugging levels greater than "3" are not likely to be useful except during Proxy software development.
0 | No debugging messages are produced. |
1 | General high-level debugging messages. |
2 | Additional low-level debugging messages, including full copies of all certificates returned to the requester. |
4 | Dynamic memory management debugging messages. |
8 | Messages from the certificate and data parsing routines.
[WARNING: This level can significantly degrade Proxy performance.] |
The OpenLDAP slapd front-end process handles LDAP session and protocol handling. The level of debugging messages is specified with the "loglevel" variable in the slapd.conf file, but can be overridden via the "-d" option of the slapd command when slapd is started. When using "-d" the messages are displayed on the console monitor rather than the log file.
ldap_proxy_4.1/libexec/slapd -d NUM
where "NUM" is a debugging level from the following list:
-1 | Enable all debugging levels |
0 | No debugging |
1 | trace function calls |
2 | debug packet handling |
4 | heavy trace debugging |
8 | connection management |
16 | packets sent & received |
32 | search filter processing |
64 | configuration file processing |
128 | access control list processing |
256 | stats log connections/operations/results |
512 | stats log entries sent |
1024 | print communications with shell backends |
2048 | print entry parsing debugging |
The debugging level numbers can be added together to log multiple levels. The "-d" option produces messages from the front-end slapd process only and is likely to be useful only in debugging OpenLDAP function.
The LDAP Proxy will display error messages during start up to the terminal
that is running the "start_ldap_proxy" script. Once the Proxy has started
successfully, status and error messages will be logged in the LDAP Proxy
log by the syslog process (See "Logging" above). More detailed status and
error messages will be logged in the Proxy log when the "debugging" option
is enabled in the slapd.conf configuration file (See "Configuration File"
above).
All informational and error messages passed by the Proxy to LDAP clients
must be in the form of LDAP return codes rather than text messages.
Consequently, each LDAP client program will display messages based on
its own interpretation of the LDAP return codes it receives.
By default, the LDAP Proxy will return only two LDAP Return Codes: LDAP_SUCCESS (0) or LDAP_OPERATIONS_ERROR (1). However, for development and debugging purposes, the list of possible return codes generated by the Proxy can be expanded via the "limit_return_codes" option in the slapd.conf configuration file. The use of expanded return codes can confuse some LDAP client programs that are not expecting them or do not understand them.
Return Code Name | limit_return_codes | Description | |
---|---|---|---|
yes | no | ||
LDAP_SUCCESS | 0 | 0 | No errors were encountered by the Proxy. However, this does not necessarily imply that any valid certificates or data were found. |
LDAP_OPERATIONS_ERROR | 1 | 1 | The Proxy experienced problems while trying to process LDAP search results. |
LDAP_NO_SUCH_ATTRIBUTE | 0 | 16 | Entries were found on at least one of the LDAP servers listed in the Proxy's server list that match the email address given to the Proxy, but no valid certificates were found in those entries. |
LDAP_INVALID_SYNTAX | 1 | 21 | One of the entries in the Proxy's LDAP server list is malformed. |
LDAP_NO_SUCH_OBJECT | 0 | 32 | No entry was found on any of the LDAP servers listed in the server list that match the email address given to the Proxy. |
LDAP_BUSY | 1 | 51 | The query was rejected because the Proxy is currently processing the maximum number of queries it is configured for (as defined by the "max_queries" slapd.conf configuration option). |
LDAP_UNAVAILABLE | 1 | 52 | Either a certificate request is being rejected because no certificate server list file was defined on the LDAP Proxy, or a search request is being rejected because no LDAP server list file was defined. |
LDAP_LOOP_DETECT | 1 | 54 | The query was rejected because the Proxy was already processing an identical query from the same client address. |
LDAP_RESULTS_TOO_LARGE | 1 | 70 | The Proxy could not allocate enough memory on the Proxy server to process search results. |
LDAP_TIMEOUT | 1 | 85 | A search request was sent by the LDAP Proxy to a remote LDAP server, but no search results were returned within the configured timeout period (default: thirty seconds). |
LDAP_FILTER_ERROR | 1 | 87 | The search filter containing the email address that was provided by the LDAP client was invalid. Usually caused by a missing or malformed email address or a syntax error in the search string. |
A useful tool for testing the LDAP Proxy or an LDAP server is the ldapsearch utility included in the LDAP Proxy installation. For example, to fetch a user's public certificate execute the following:
ldap_proxy_4.1/bin/ldapsearch -h <LDAPserver> -p <ldap_port> -b <base_dn> "(mail=first.i.last@email_domain)"
The values for <LDAPserver>, <ldap_port>, and <base_dn> can be read from the certificate_server_list.txt file.
To fetch a CRL, execute the following:
ldap_proxy_4.1/bin/ldapsearch -h <LDAPserver> -p <ldap_port> -b <base_dn> "(objectClass=*)" certificateRevocationList
The values for <LDAPserver>, <ldap_port>, and <base_dn> can be read from the ldap_server_list.txt file.
To fetch all core data from an LDAP entry, execute the following:
ldap_proxy_4.1/bin/ldapsearch -h <CRLserver> -p <ldap_port> -b <base_dn> "(objectClass=*)"
The values for <CRLserver>, <ldap_port>, and <base_dn> can be read from the ldap_server_list.txt file. However, the entry in the ldap_server_list.txt file that matches the <base_dn> must have "all" listed as the attribute name (line 4).
The following examples use the Boeing LDAP Proxy to demonstrate the three types of queries the LDAP Proxy is designed to respond to:
ldap_proxy_4.1/bin/ldapsearch -h dir.boeing.com -p 389 '(mail=wen.fang@boeing.com)'
This query returns Wen Fang's public encryption certificate.
ldap_proxy_4.1/bin/ldapsearch -h dir.boeing.com -p 389 -b 'CN=The Boeing Company Class 2 Certificate Authority,OU=netscape,OU=certservers,O=Boeing,C=US' certificateRevocationList
This query returns a Certificate Revocation List from the Boeing Class 2 Certificate Authority.
ldap_proxy_4.1/bin/ldapsearch -h dir.boeing.com -p 389 -b 'CN=Boeing PCA Med Hardware,OU=certservers,O=Boeing,C=US' '(objectClass=*)'
This query returns all data found in the Boeing Class 3 Medium Assurance Hardware LDAP entry.
You can run more than one LDAP Proxy on the system at a time. Each instance must be assigned a unique LDAP port number and each instance should be assigned its own log file. To add a new instance of the LDAP Proxy on a system already running one or more Proxies, do the following:
Install the new Proxy using the instructions above under "Installation" and "Configuration". You may need to change the name of the directory name this instance is installed under so that it doesn't conflict with other Proxies already installed on the system. For example, to install a new instance of LDAP Proxy 4.2 in the same directory that contains other instances of the 4.2 Proxy:
mkdir temp
cd temp
tar xf ldap_proxy_4.1.tar
mv ldap_proxy_4.1 ../ldap_proxy_4.1_port395
rm ldap_proxy_4.1.tar
cd ..
rmdir temp
Edit the ldap_proxy_4.1_port395/bin/start_ldap_proxy script by adding configuration options to the "slapd" line. For example, to run the new Proxy on LDAP port 395 and using a new log file, enter the "slapd" line to look like this:
$PROXYHOME/libexec/slapd -h "ldap://0.0.0.0:395/" -l LOCAL5
Add the following line to /etc/syslog.conf to define a unique log file for use by this LDAP Proxy instance. Use the LOCAL value you selected above with the "-l" slapd option:
local5.info;local5.debug /usr/local/logs/ldap_proxy_395.log
[NOTE: The two fields must be separated by tab characters, not spaces.]
Tell syslogd to reread its configuration file via:
kill -1 <PID>
Where
Change the PROXYHOME line at the top of the start and stop scripts in the bin directory so that it points to the directory into which you have installed this version of the proxy.
You can now start and stop this instance of the LDAP Proxy using the scripts in bin directory.
If the LDAP Proxy has problems, the ldap_proxy.log file will be the most useful tool for identifying the source of the error. Debugging messages from the Proxy's back-end should pinpoint the error. Set the "debugging" option in the slapd.conf file to "3" to gather as much useful data as possible. The Proxy will log messages with the "[error]" tag if it recognizes the problem as an error. Check for these messages first.
If the problem is not obvious, sent a copy of the log file to the LDAP Proxy Development Team (email addresses below). If the log file is large, it can be compressed before being emailed using utilities like gzip, zip, compress, bzip2, etc. Include also a copy of the X.509 certificate if it appears that the Proxy is having trouble interpreting it. You can use the ldapsearch utility (see above) to download a base64 encoded copy of the certificate.
A web interface to the LDAP Proxy is available on the Boeing web site. This web page will allow certificate lookups to be made through a web server. The web interface is made up of a web page and a corresponding CGI program. The web page allows the user to specify the email address of the person you want the public certificate(s) for, and the type of certificate (i.e., the certificate issuer). The web page will invoke the CGI program which will perform the LDAP search using the Boeing LDAP Proxy.
This interface has two primary advantages over client-based LDAP queries. First, it allows access to the LDAP Proxy through firewalls that may be blocking LDAP ports which would prevent the user from doing email client-based LDAP queries to that Proxy. This assumes, of course, that the firewall is not also blocking the HTTP port (80). Secondly, the web interface will (hopefully) provide an easier means of getting public X.509 certificates imported into various email clients.
The web interface is currently configured to help load certificates into the Mozilla, Firefox, and Internet Explorer web browsers and the Entrust Address Book. Once the certificates are loaded into Mozilla, the built-in Mozilla Communicator email client has access to the certificates for use in email encryption and digital signing. Also, the Outlook email client has access to the public certificates once they are loaded into Internet Explorer. Once user certificates are loaded into any of the web browsers, they can be exported and then imported into the Thunderbird email client.
Alternatively, an option is available to have the certificate(s) returned by the web interface displayed to the browser window. This allows the user to cut-and-paste each certificate to a file that can then be stored in PKI client using the client's certificate import procedure.
A sourcecode kit is used to distribute the open-source LDAP Proxy Web Interface to those who wish to build their own web interface. In addition to the source code kit, building the web interface will require additional open-source software: OpenLDAP, GNUTLS, libgcrypt, and libgpg-error.
ldap.proxy@boeing.com - Development Team Mailbox