LDAP Publisher/LDAP Search Publisher

LDAP Naming 

The recommended method of choosing a naming suffix is the one described in RFC2247 that maps a DNS domain to a DN. If my DNS domain is bigcorp.com it will map to the DN "dc=bigcorp,dc=com". The top node in my LDAP directory will then be "dc=bigcorp,dc=com". For more information and to understand LDAP naming, we recommend the book Understanding and Deploying LDAP Directory Services.

The dc component support is mandated by all of the X.509 RFCs now. For example, if I have this directory:

dc=bigcorp,dc=com
    |
    +-dc=fi
    |
    |
    +-dc=se
        |
        +-cn=Mike Jackson 

The most understandable method is taking the subject name in forward order, like: cn=Mike Jackson,dc=se,dc=bigcorp,dc=com

If the DN is ordered like this it should be published to the correct object in the tree.

If the DN is ordered reverse, like: dc=bigcorp,dc=com,dc=se,cn=Mike Jackson EJBCA will reorder it incorrectly to forward order, so the publishing will be wrong.

Thus, use forward order like this: 'cn=Mike Jackson,dc=se,dc=bigcorp,dc=com' if using the dc model or 'cn=Mike Jackson,o=bigcorp,c=se' if using the o,c model.

Making unique LDAP DNs is the next challenge. If you are in a small organization having the CN will probably work fine, but in a larger organization there are probably several people with the same name. Somehow the names must be made unique, and one way is to introduce numbers, initials etc in the CN. Another way that we recommend is to use uid in the LDAP DN instead. LDAP DNs will then look like "uid=tomas,dc=bigcorp,dc=com". Uid is the username, normally used for login etc, and you probably already have some procedure to create unique usernames already.

LDAP Basics 

If you are not used to X.500 style naming, the LDAP structure of branches and leaf nodes may seem unusual. You can't just drop an object anywhere you like; You need to create the framework to support it. Sort of like if you wanted to put entries in /etc/hosts if the directory /etc did not exist.

First you mkdir /etc, then you create the file. Then you start putting things in the file. The difference with LDAP and x.500 is that instead of paths separate by slashes, you have paths separated by commas and '=' signs.

For example, if you want to make an object "cn=ldaphost,ou=hosts,dc=yourdom,dc=com", you first have to make sure "dc=yourdom,dc=com" exists. Then make sure "ou=hosts,dc=yourdom,dc=com" exists. THEN you can try "cn=ldaphost,ou=hosts,dc=yourdom,dc=com"

EJBCA does not create branches in LDAP. You have to put them there with other means before you start publishing.

Using LDAP 

In Firefox you can for example enter a URL like: ldap://ip-address-of-ldap-server:389/cn=Tomas Gustavsson,dc=se,dc=bigcorp,dc=com and it will fetch an address book entry with the information about the user, including the certificate.

The LDAP url format is described in RFC2255.

To use LDAP top fetch user certificates and use them for encrypting email there seems to be a requirement to use SSL connection to the LDAP server (Account Options > Compositions & Addressing > Edit directories > Edit > Use Secure Connection), see also below how to configure OpenLDAP for SSL.

When fetching certificates from LDAP with Firefox, for example with URL: ldap://ldap-server-host/dc=bigcorp,dc=com??sub?(cn=MyName)?(objectclass=*), the CA certificate must be installed in the Windows truststore, not only in Firefox's, to enable a checkbox at the fetched certificate.

To use SSL against an LDAP server with MS Outlook you must make sure the CN in the LDAP servers certificate is the same as the hostname. An example of adding a user for the LDAP server with the CLI interface is:

bin/ejbca.sh ra addendentity ldap password "C=SE,O=Foo,CN=ldap.foo.se" MyCA 1 PEM SERVER

where ldap.foo.se is the hostname of the LDAP server that Outlook should use.

The CA certificate must also be imported into Windows properly.

Configure LDAP Publishers 

A Publisher is a session bean that implements the IPublishSession interface and is used to store certificates and CRLs for entities. EJBCA have support for endless number of publishers simply by defining publishers in the Admin GUI. The user of EJBCA can implement own publishers, but EJBCA already comes with a publisher for LDAP.

EJBCA uses a notion of base DN to publish to different LDAP structures. The DN used in the certificate can be different from the LDAP structure.

Configuring EJBCA 

To configure the publisher for LDAP:

1. Select Admin GUI > Edit Publishers.
2. Add a new publisher by specifying a name, edit the publisher and specify the necessary fields.

The following lists generic parameters to the LDAP Publisher:

Setting up Certificate Profiles 

To allow publishing in LDAP, you must create an EJBCA custom Certificate profile.

To publish in LDAP, you must create a Certificate profile in EJBCA that publishes to LDAP. If the publisher for LDAP is configured according to Configuring EJBCA above, there will be a section for Publishers available when creating/editing a certificate profile (with Edit Certificate Profiles).

Choose this, and then when adding end-entities, make sure they use the new certificate profile and voila, the certs will be published.

Different LDAP Publishers 

LDAP Publisher

The regular LDAP Publisher works by searching the DN in LDAP.

When EJCA creates an object to publish a certificate to LDAP it firsts builds the DN from the baseDN and 'LDAP location fields for cert DN'. It checks if the entry exists in the LDAP and either creates or modifies the entry.

Example: The certificate DN is "CN=Tomas Gustavsson,O=Foo,C=SE", the BaseDN in the publisher is "DC=primekey,DC=se" and the CN is selected in "LDAP location fields from cert DN". The resulting DN that EJBCA will search for in the LDAP and create if it does not already exist is "CN=Tomas Gustavsson,DC=primekey,DC=se".

Using this publisher, if you have multiple trees in your LDAP (for example "ou=foo,dc=primekey,dc=se" and "ou=bar,dc=primekey,dc=se") you can either:

1. Include both CN and OU in 'LDAP location fields from cert DN' and have your cert DNs like "CN=Tomas,OU=foo,O=MyOrg,C=SE.
2. Use different publishers for ou=foo and ou=bar and issue certificates for the different OUs with different certificate profiles.

LDAP Search Publisher

The LDAP Search Publisher works by searching the LDAP for existing entries using a user defined search filter. If no entries exist in the LDAP when searching for an entry, one is created just like in the regular LDAP Publisher.

The search filter is defined in the following fields under LDAP search settings:

• Suffix base DN of LDAP Search - the base for your search filter.
• LDAP filter of the search - your LDAP filter.

If you build your search filter on DN components, you also have to select those components as LDAP location fields.

The best example of such a search filter is if base is "dc=primekey,dc=se" and filter is "uid=$USERNAME". The search done by EJBCA will be equal to the search:ldapsearch -x -b "dc=primekey,dc=se" "(uid=$USERNAME)"

$USERNAME is replaced by the EJBCA username of the user that has had a new certificate just generated. Other variables apart from $USERNAME is $EMAIL, $UID, $CN, $O, $OU and $C where these values are taken from the certificate DN.

When a certificate is generated for say user "ldap" EJBCA will perform the search:
ldapsearch -x -b "dc=primekey,dc=se" "(uid=ldap)" 

The certificate generated for LDAP will be published in the object returned by the search. This is very useful if you want to publish certificates to an LDAP directory where your users already exists such as an email directory. The DN in the LDAP does not have to match the DN in the certificates at all.

If more than one entry matches the search, the first returned search result will be used.

What EJBCA stores/creates/modifies 

Apart from the DN in the entry, a number of attributes are also stored. Some are required by schema, some are optional. EJBCA find attributes in the certificate, if it is an OU (organizational unit) in the certificate EJBCA uses that to populate the OU attribute in the LDAP entry.

When updating an entry that already exists EJBCA uses replace on the existing attributes, so if an email attributes already exists and EJBCA finds an email address in the certificate, the email attribute in LDAP is replaced with the email address from the certificate.

Attributes are only replaced/updated if the flag Modify Existing Users in the Publisher is active. The certificate attribute is always updated though. Attributes that are part of the DN, i.e. that reflects the location of the entry in LDAP is not modified, since this is usually not allowed. 

The attributes that EJBCA creates or replaces are:

• cn (common name)
• l (locality)
• ou (organizational unit)
• sn (surname)
• gn (givenname)
• st (state)
• o (organization)
• uid (user id)
• initials
• title
• serialnumber - If we have selected to use the SN (serialNUmber DN field) in Ldap Location fields, we will also add it as an attribute.

Publish CA Certificates

Even if only CRLs are published to LDAP, the CRL issuer must still be published by EJBCA before any CRLs can be published. If you attempt to publish a CRL without publishing the CRL issuer first, the LDAP server will complain about a missing cACertificate attribute and the publisher will fail.

You can publish the CRL issuer manually by editing the CA (CRL issuer) in EJBCA. Make sure the LDAP publisher is selected in the list of publishers, and then click on Republish CA Certificates in the CA Life Cycle section.

Configure OpenLDAP 

The objectclass inetOrgPerson is used by default to store certificates.

Example:

dn: cn=Mike Jackson,ou=people,dc=company,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Mike Jackson
sn: Jackson
userCertificate;binary::

CAs are published in the form: 

dn: cn=ejbca,dc=jackson,dc=net
objectClass: top
objectClass: applicationProcess
objectClass: certificationAuthority
cn: ejbca
cACertificate;binary:
certificateRevocationList;binary:
authorityRevocationList;binary:

To configure OpenLDAP (version 2.2.5) to include the inetOrgPerson, add the following lines to slapd.conf. This is already the default in recent releases:

include /etc/ldap/schema/cosine.schema
include /etc/ldap/schema/inetorgperson.schema

Add the top object by creating an LDIF file (org.ldif):

dn: o=AnaTom,c=SE
objectclass: dcObject
objectclass: organization
o: AnaTom
dc: AnaTom 
dn: cn=Admin,o=AnaTom,c=SE
objectclass: organizationalRole
cn: Admin

And using the command:

ldapadd -x -D "cn=Admin,o=AnaTom,c=SE" -W -f org.ldif

Check what you have in the LDAP by:

ldapsearch -x -b 'o=AnaTom,c=SE' '(objectclass=*)'

Configure SSL 

Create a user in EJBCA (this example is for adding a user with the cli interface, adding a user with the admin-GUI works just as fine). In the mail EJBCA directory type (use simply 'ra' on windows):

bin/ejbca.sh ra addendentity ldap foo123 "C=SE,O=Foo,CN=ldap" null ManagementCA null 1 PEM SERVER
bin/ejbca.sh ra setclearpwd ldap foo123

Where foo123 is the ldap users password, C=SE... is the users DN and ManagementCA is the name you chose for your CA. The user type is end-user (1), keystore type is PEM, and if using the admin-GUI check use batch).

Batch generate the PEM keystore:

bin/ejbca.sh batch

Copy the resulting files p12/pem/ldap.pem, p12/pem/ldap-CA.pem and p12/pem/ldap-Key.pem to your LDAP server. In this example the slapd.conf is located in /etc/ldap so we copy the files to that directory. Protect these files so they are only readable by the LDAP server.

Add the following to your slapd.conf:

# Use SSL
TLSCipherSuite HIGH:MEDIUM:+SSLv3
TLSCertificateFile /etc/ldap/ldap.pem
TLSCertificateKeyFile /etc/ldap/ldap-Key.pem
TLSCACertificateFile /etc/ldap/ldap-CA.pem 

Restart slapd: 

./slapd -h "ldap:/// ldaps:///"

and check that it is running with ps -ef|grep slapd. 

On SuSE, if using the built-in OpenLDAP you have to enable ldaps in /etc/sysconfig/openldap:

OPENLDAP_START_LDAPS="yes"

and then run:

SuSEconfig

and then:

rcldap start

Configure your LDAP publisher in EJBCA to use SSL by checking the checkbox TLS Connection, the port should change to port 636.

Note! The CA certificate of the (root)CA used to sign the LDAP server certificate must be present in the java trust cert store ($JAVA_HOME/jre/lib/security/cacerts). Otherwise you will have to add it using something like: First get the CA cert:

bin/ejbca.sh ca getcacert MyCA myca.der -der

Then add it to the java trust store:

keytool -import -trustcacert -alias MyCA -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -file myca.der

You have to re-start JBoss after adding anything to the java trust store.

For more information on configuring OpenLDAP on Solaris, refer to bolthole.com

Sample Ubuntu installation 

- sudo apt-get install slapd ldap-utils
- sudo dpkg-reconfigure slapd
  
Configure slapd with your domain and admin password (primekey.com in this case).
- sudo /etc/init.d/slapd restart
- 'ps -ef|grep slap' 
  should show a slapd running
- ldapsearch -x -b 'dc=primekey,dc=se' '(objectclass=*)'
  
To look at the results
- slapcat -l backup.ldif
  
Make backup
- slapadd -l backup.ldif
- /etc/init.d/slapd restart
  
Restore backup 

Run the following command to add new LDAP nodes:

- ldapadd -x -D "cn=admin,dc=PrimeKey,dc=com" -W -f primekey.ldif
  where primekey.ldif is:

dn: dc=PrimeKey,dc=com
dc: PrimeKey
objectclass: dcObject
objectclass: organization
o: PrimeKey Solutions AB
description: Parent Object for PrimeKey LDAP Directory

dn: ou=Standard,dc=PrimeKey,dc=com
ou: Standard
objectClass: top
objectClass: organizationalUnit
description: Parent Object for all Standard Certificates

dn: ou=High,dc=PrimeKey,dc=com
ou: High
objectClass: top
objectClass: organizationalUnit
description: Parent Object for all High Certificates 

OpenDJ 

OpenDJ is a modern, standards compliant, java based, LDAP server that is easy to set up and use. It also comes with GUI tools to manage and query.

Installing OpenDJ 

This example uses OpenDJ 2.5.0 as an example, but other versions should work similarly.

• unzip OpenDJ-2.5.0-Xpress1.zipthe Control Panel
• cd OpenDJ-2.5.0-Xpress1
• ./setup
  • This launches graphical setup, you can run setup --cli to install without GUI.
  • Use default Root User DN: cn=Directory Manager
  • Directory Base DN: dc=example,dc=com)
  • If you want to be able to run OpenDJ on the same server as JBoss/EJBCA, choose another port for management, i.e. 5555 instead of 4444.
• You can end by starting Launch Control Panel, or you can start it later with bin/control-panel.

An EJBCA publisher for a default installation is then configured with:

• Base DN: dc=example,dc=com
• Administrator: cn=Directory Manager

The graphical LDAP browser is accessible from the Control Panel > Manage Entries. You can start/stop OpenDJ from within the Control Panel or with bin/start-ds and stop-ds.

Management tasks such as creating new attributes and object types easy to do in the Control Panel GUI.

OpenDJ listens to port 1389 by default, but it also occupies other ports stopping it from running on the same server as JBoss. If you want to change the management port (default 4444) after installation you can edit confif/config.ldif and config/tools.properties.

Configure SSL/TLS 

For information on configuring SSL/TLS with OpenDJ, refer to OpenDJ documentation.

If you run setup using the command line (--cli) you will be prompted with TLS questions, having the possibility to set up TLS directly.

Custom Schemas 

See doc/ldapschema for files with custom schemas and attribute types to add to your LDAP schema.

Certificate Serial Number 

This is an attribute and a schema extension to allow storage of certificate serial number in the inetOrgPerson LDAP object, for end user entries. This is done by adding an extension to inetOrgPerson called inetOrgPersonWithCertSerno with a new optional attribute called certificateSerialNumber.

Once you have installed the new schema in the LDAP server you use it by configuring the LDAP publisher with:

• User Object Class: top;person;organizationalPerson;inetOrgPerson;inetOrgPersonWithCertSerno

instead of the befault value:

• User Object Class: top;person;organizationalPerson;inetOrgPerson

The certificateSerialNumber attribute will then automatically be added/modified when publishing to LDAP.

Extra Device Schema 

To store certificates for devices (e.g. routers, toasters etc) in LDAP it is no really suitable standard object class. inetOrgPerson requires surnames etc, and the device objectclass does not include a certificate attribute.

Mike Jackson has kindly contributed additional objects that extend the standard device class with a certificate attribute. The ejbcaDevice uses object ids from PrimeKey Solutions AB.

Installation 

For the Netscape/SUN servers, on UNIX, copy the 85ejbca.ldif file into:

/usr/netscape/servers/slapd-hostname/config/schema/

and restart the LDAP server.

For OpenLDAP, copy the ejbca.schema file into, e.g.:

/etc/ldap/schema/

and edit slapd.conf to add the following line:

include /etc/ldap/schema/ejbca.schema

then restart the server.