Penango LDAP Lookup Configuration Guide

Configuring Penango’s Automatic LDAP-Based Certificate Directory Lookup

Table of Contents

§ 1 Introduction
§ 2 LDAP Lookup Preferences
§ 2.1 compose.ldap.urls
§ 2.1.1 Examples of compose.ldap.urls
§ 2.2 compose.ldap.useAD
§ 2.3 compose.ldap.useDefaultConfigs
§ 2.4 compose.ldap.useDiscovery
§ 3 Testing LDAP Lookup in Penango

§ 1 Introduction

The Penango Webmail Client ("Penango") uses a patent-pending certificate lookup method, Automatic LDAP-Based Certificate Directory Lookup, which quickly and asynchronously finds and validates certificates. As soon as the user types an e-mail address into the to, cc, or bcc fields (and indicates completion of the typing by moving the cursor to another field in the compose window), Penango begins a parallelized search for the recipients’ certificates. Automatic LDAP-Based Certificate Directory Lookup allows users to send encrypted e-mail messages without first having to receive the recipients’ certificates via a signed e-mail; as a result, it facilitates secure e-mail communication among users within a single enterprise and across different organizations.

To search for certificates, Penango searches the following LDAP sources: user-specific configurations, Active Directory, pre-configured LDAP configurations on domains, and DNS-based methods (SRV records, and well-known names). If Penango reports that the message still cannot be encrypted, it may be due to at least two factors: (1) the certificates were not discovered by the LDAP-based search; (2) the certificates are not valid.

Return to table of contents.

§ 2 LDAP Lookup Preferences

Penango uses four different preferences to control how sources produce LDAP Service Records (LSRs):
compose.ldap.urls
compose.ldap.useAD
compose.ldap.useDefaultConfigs
compose.ldap.useDiscovery

All LSRs are parameterized by domain. “Parameterized by domain” means that the preference can have different values depending on the domain name of the recipient’s e-mail address during lookup. For example, useDiscovery can be set explicitly to true for “example.cn”, to false for “example.cl”, and to true in general. When the e-mail address “foo@example.cl” is entered, discovery will not be attempted, but when the e-mail address “foo@example.eu” is entered, discovery will be attempted (because the general preference is used when the domain-specific preference is not specified).

For Firefox, users may view and edit the preferences by going to about:config in Firefox. For Internet Explorer, users may view and edit the preferences by opening the Windows Registry and creating the following preferences as needed, or editing them if they already exist:
HKEY_CURRENT_USER\Software\Penango\Client
HKEY_LOCAL_MACHINE\SOFTWARE\Penango\Client

Then, within the Client key, create a new String Value or DWORD Value (depending on the preference; see preference descriptions below) with the appropriate name, such as compose.ldap.urls or compose.ldap.useAD.

Note: In Firefox, all configuration entries must be prefixed with extensions.penango.client; for example:
extensions.penango.client.compose.ldap.urls?domain:"company.com"

Return to table of contents.

§ 2.1 compose.ldap.urls

The value of the preference compose.ldap.urls is a list of LDAP URLs, delimited by angle brackets (“<>”). The Penango LDAP subsystem will query the LDAP URLs in sequence, in preference to any other discovered LDAP Service Record (LSR). The format complies with Internet standards RFC 4516, “LDAP: Uniform Resource Locator”, and RFC 3986, “URI: Generic Syntax”. Because the LDAP URL specification (RFC 4516) does not specify how to include a bind name and password in the LDAP URI, the format is extended in Penango Automatic LDAP-Based Certificate Directory Lookup based on the generic syntax of URIs (RFC 3986).

Each LDAP URL must be separated by angle brackets (“<>”) and must start with the left angle bracket (“<”). For each of the provided URLs, an LSR is built and added to the list of queries. The URLs will be queried in the order that they appear; if contacting the first URL fails, then the second will be queried. This process proceeds until a successful search is performed or the list of configurations is exhausted.

The specification can be on a per-domain basis; for example, for the domain “company.com,” the preference in Firefox would be extensions.penango.client.compose.ldap.urls?domain:"company.com", while the preference in Internet Explorer would be as follows:
HKEY_CURRENT_USER\Software\Penango\Client\domain:"company.com"\compose.ldap.urls
When configuring Penango for Internet Explorer in the Windows Registry, compose.ldap.urls should be a String Value (REG_SZ).

Return to table of contents.

§ 2.1.1 Examples of compose.ldap.urls

1. Generic format (Note: name is actually a distinguished name, e.g. cn=John Doe): compose.ldap.urls = <ldap://cn=John%20Doe:password@hostname:port/basedn>

2. Example for ldap.penango.com, port 389, no username, no password, and basedn = dc=penango,dc=com: compose.ldap.urls = <ldap://ldap.penango.com:389/dc=penango,dc=com>

3. Example for ldap.penango.com, port 389, name "cn=test", password "testpwd", and basedn = "o=Penango,c=US":
compose.ldap.urls = <ldap://cn=test:testpwd@ldap.penango.com/o=Penango,c=US>

4. Example for multiple configurations, where the first connection is attempted with LDAP over SSL/TLS (defaults to port 636), and the second connection is attempted with plain LDAP on non-standard port 399:
compose.ldap.urls = <ldaps://cn=test:testpwd@ldap.penango.com/o=Penango,c=US> <ldap://ldap.penango.com:399/dc=penango,dc=com>

5. Example of configuration restricted to @company.com e-mail addresses only:
First, change the base configuration entry from compose.ldap.urls to compose.ldap.urls?domain:"company.com"
Then the configuartion is as follows:
compose.ldap.urls?domain:"company.com" = <ldap://cn=testme:password@ldap.company.com/dc=company,dc=com>

Note: In Firefox, all configuration entries must be prefixed with "extensions.penango.client"; accordingly, the above example should be entered as follows:
extensions.penango.client.compose.ldap.urls?domain:"company.com" = <ldap://cn=testme:password@ldap.company.com/dc=company,dc=com>

Return to table of contents

§ 2.2 compose.ldap.useAD

The preference compose.ldap.useAD is a Boolean that by default is set to true. When set to true, this preference enables querying of the local Active Directory server (if available). This preference is useful only for systems that are joined in a Windows domain; OpenLDAP-based systems will replace null with localhost. On Windows, Active Directory querying will attempt to log in with LDAP_AUTH_NEGOTIATE, which translates to GSS-SPNEGOauthentication with Winldap using the current Windows user’s logon credentials.

When configuring Penango for Internet Explorer in the Windows Registry, compose.ldap.useAD should be a DWORD.

Return to table of contents

§ 2.3 compose.ldap.useDefaultConfigs

The preference compose.ldap.useDefaultConfigs is a Boolean that by default is set to true. When set to true, this preference enables the LDAP configurations embedded by default in Penango. In particular, Penango will look for a match of the domains of the recipients as listed in the file generic/ldap-configs.js. If Penango finds one or more matching LDAP Service Records (LSRs), it will query those servers as well.

When configuring Penango for Internet Explorer in the Windows Registry, compose.ldap.useDefaultConfigs should be a DWORD value.

Return to table of contents

§ 2.4 compose.ldap.useDiscovery

The preference compose.ldap.useDiscovery is a Boolean that by default is set to true. When set to true, Penango will try to automatically discover server configurations for each of the domains of the recipients. The approach is twofold:

  1. DNS SRV record lookup. Penango is capable of querying the DNS and asking for DNS SRV records associated with a particular domain; if the DNS query returns valid records, Penango will query the returned hostnames in sequence.
  2. Well-Known Names. Penango will try to discover the LDAP server by adding the prefix “ldap” to the domain of the e-mail address; for example, if the recipient is jane@company.com, Penango will try to connect to ldap.company.com.
When configuring Penango for Internet Explorer in the Windows Registry, compose.ldap.useDiscovery should be a DWORD Value.

Return to table of contents

§ 3 Testing LDAP Lookup in Penango

Users can test LDAP lookup in Penango in Firefox by using the following steps:

  1. Install the Console² add-on to Firefox: https://addons.mozilla.org/en-us/firefox/addon/console²/
  2. If Penango is not installed yet, install it from https://www.penango.com/.
  3. Clear the “People” certificate store: Restart Firefox, and go to Firefox > Tools > Certificate Manager, then select the “People” tab. Delete the certificates of any recipients to whom you might want to send an encrypted e-mail message for testing purposes—for example, jane@company.com. Deleting the certificates is needed because if the recipients’ certificates are found in the local store, and they are valid, Penango will not try to contact the LDAP servers, as doing so is not needed.
  4. Test A – Send encrypted e-mail to info@penango.com
    a. Open Firefox, then open the Error Console (Firefox > Tools > Web Developer > Error Console). Clear the "People" certificate store as explained above.
    b. Log into your Gmail or Google Apps account, then click “Compose.”
    c. Clear the Error Console by going to the Error Console and clicking “Clear.”
    d. Within the Error Console, please ensure that only the following buttons and tabs are enabled: Errors, Warnings, Messages, JS, Chrome, Content, Resource.
    e. In the Compose window’s “To:” field, type in info@penango.com.
    f. Click on the “lock” icon to try to encrypt the e-mail message.
    g. At this point, Penango should start looking for info@penango.com’s certificate from Penango Inc.’s LDAP server. Penango should be able to find the certificate within a few seconds or less, and the Penango infobar should appear with a green color and inform you that only info@penango.com and you will be able to read the body of the message. Check the Error Console for messages regarding the activities; if Penango is unable to find info@penango.com’s certificate, please copy the text in the Error Console and paste the text in an e-mail to support.ticket@penango.com.
  5. Test B – Send encrypted e-mail to someone within your company or organization
    a. This is practically the same test as Test B, but uses an e-mail address from your company or organization; specifically, this test uses an e-mail address that you know has its certificate installed in company’s LDAP server. For purposes of this configuration guide, we’ll refer to that e-mail address as someone@company.com.
    b. Open Firefox, then open the Error Console (Firefox > Tools > Web Developer > Error Console). Clear the "People" certificate store as explained above.
    c. Log into your Gmail or Google Apps account, then click “Compose.”
    d. Clear the Error Console by going to the Error Console and clicking “Clear.”
    e. Within the Error Console, please ensure that only the following buttons and tabs are enabled: Errors, Warnings, Messages, JS, Chrome, Content, Resource.
    f. In the Compose window’s “To:” field, type in that person’s e-mail address (e.g., someone@company.com).
    g. Click on the “lock” icon to try to encrypt the e-mail message.
    h. At this point, Penango should start looking for the person’s certificate from the company’s LDAP server. Penango should be able to find the certificate within a few seconds or less, and the Penango infobar should appear with a green color and inform you that only the person and you will be able to read the body of the message. Check the Error Console for messages regarding the activities; if Penango is unable to find that person’s certificate, please copy the text in the Error Console and paste the text in an e-mail to support.ticket@penango.com.
  6. Return to table of contents