howto-ldap.txt

JAVA做的J2EE下CA认证系统 基于EJB开发

LDAP Naming
===========

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.

Therefore...
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.

An example image of an LDAP structure can be seen in HOWTO-LDAP-tree.png.

LDAP BASICS
===========
LDAP has an unusual structure, if you are not used to X.500 style naming. 
Things are either branches, or leaf nodes. 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.

CONFIGURE LDAP PUBLISHERS
=========================

Consider also checking INSTALL-guide.txt in the source package.

A good free LDAP server can be found at http://www.openldap.org/

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:
Choose 'Edit Publishers' in the admin-GUI.
Add a new publisher with a name you define yourself. Edit the publisher and fill 
in all the neccesary fields.

Parameters to LDAP Publisher:

- 'Hostname' is the host where the LDAP server is located.

- 'Port' is the port on which the LDAP server listens, default non-SSL is 389.

- 'Login DN' is the DN of a user on the LDAP server with permissions to add and
update enties.

- 'Login Password' is the password for the user above.

- 'User Object Class' is the objectclass for the LDAP entries for users, where user
certificates are published. The entry is hierarchical separated by ';' to build 
a structure like:
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
This objectclass must allow the attribute 'userCertificate;binary'. 
Default 'top;person;organizationalPerson;inetOrgPerson'

- 'CA Object Class' is the objectclass for the LDAP entries for CAs, where CA
certificates and CRLs are published. The entry is hierarchical separated by ';' 
to build a structure. This objectclass must allow the attributes
'cACertificate;binary', 'certificateRevocationList;binary' and 'authorityRevocationList;binary'.
Default 'top;applicationProcess;certificationAuthority'

- 'User Certificate Attribute' is the attribute name, in the userObjectClass, for the users 
certificate. Default 'userCertificate;binary'

- 'CA Certificate Attribute' is the attribute name, in the cAObjectClass, for the CAs 
certificate. Default 'cACertificate;binary'

- 'CRL Attribute' is the attribute name, in the cAObjectClass, for CRLs (user CRLs) 
publisher by the CA. Default 'certificateRevocationList;binary'

- 'ARL Attribute' is the attribute name, in the cAObjectClass, for ARLs (CA CRLs) 
publisher by the CA. Default 'authorityRevocationList;binary' 
(note that pure ARLs are not implemented yet in EJBCA)

- 'LDAP location fields from cert DN'
When configuring the LDAP publisher the BaseDN will be used as the base for the DN published in LDAP,
and it will be appended to the LDAP location fields selected to be used.
example: If the user DN in EJBCA is "cn=tomas gustavsson, uid=tomasg, O=PrimeKey Solutions AB, C=SE"
and the BaseDN is "dc=PrimeKey,dc=SE" and the selected LDAP location fields are "CN". 
The LDAP DN used for publishing will be "cn=tomas gustavsson, dc=PrimeKey, dc=SE", and the "uid=tomasg" 
will be added as an attribute in LDAP. The certificate stored under "cn=tomas gustavsson, dc=PrimeKey, dc=SE"
will have the subjectDN "cn=tomas gustavsson, uid=tomasg, O=PrimeKey Solutions AB, C=SE".


Setting up certificate profiles
-------------------------------
You MUST make a custom certificate profile to publish to LDAP!

To publish in LDAP you must create a Certificate profile in EJBCA that publishes 
to LDAP. If the above is configured, 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.

Publishing to AD
----------------
When configuring Active Directory LDAP, Bind DN for the users are usually, 
cn=<user>,cn=Users,dc=<domain-component>,dc=<domain-component>. 
For example: cn=Philip Vendil,cn=Users,dc=primekey,dc=se for the domain primekey.se

If your DN is like "cn=Ejbca1,0=MyOrg,c=SE" and your base DN is like
"DC=Security,DC=Software,DC=MyOrg".
The publisher for AD should have base DN like
"cn=Users,dc=Security,dc=Software,dc=MyOrg"

For Login DN you should use the full ldap name, for example:
"CN=Administrator,C=Users,dc=primekey,dc=se"

In order to connect to AD though SSL you should issue a LDAP SSL P12
to the domain controller. Accoring to:
http://support.microsoft.com/default.aspx?scid=kb;en-us;321051&sd=tech

The same certificate is used for both the AD an global catalouge.
Remember to add the CA certificate to the machine stores trusted root certificates.

Custom publishers
-----------------
If your setup makes it very complex to configure multiple certificate profiles 
and multiple publishers you might consider writing a custom publisher that 
handles things directly according to you demands.
Look in the directory src/java/se/anatom/ejbca/ca/publishers for more information 
about writing your own solution. There is an empty custom publisher called 
DummyCustomPublisher.java that can be extended.


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

The LDAP url format is described in rfc2255: http://www.ietf.org/rfc/rfc2255.txt

Examples of using LDAP with Netscape/Mozilla:
http://www.umdnj.edu/istweb/pki/pki_files/secure_email_ns7.html

To use LDAP top fetch user certificates and use them for encrypting email there seems to be a 
reuirement 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.

Note: When fetching certificates from LDAP with Mozilla for example with URL:
ldap://<ldap-server-host>/dc=bigcorp,dc=com??sub?(cn=MyName)?(objectclass=*)
To get a checkbox at the fetched certificate, the CA certificate must be installed in the Windows truststore,
not only in Mozillas.

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:
./ra.sh adduser ldap password "C=SE,O=Foo,CN=ldap.foo.se" null MyCA null 1 PEM
where ldap.foo.se is the hostname of the LDAP server that Outlook shoudl use.

The CA certificate must also be imported into Windows properly.


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' you must 
add the following lines to slapd.conf:

include         /usr/local/etc/openldap/schema/cosine.schema
include         /usr/local/etc/openldap/schema/inetorgperson.schema

Don't forget to 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:
/usr/local/bin/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 adduser ldap foo123 "C=SE,O=Foo,CN=ldap" null AdminCA1 null 1 PEM
bin/ejbca.sh ra setclearpwd ldap foo123 
Where foo123 is the ldap users password, C=SE... is the users DN and AdminCA1 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 /usr/local/etc/openldap so we copy the 
files to that directory. Protect theses files so they are only readable by the LDAP server.

Add the following to your slapd.conf:
# Use SSL
TLSCipherSuite HIGH:MEDIUM:+SSLv3
TLSCertificateFile /usr/local/etc/openldap/ldap.pem
TLSCertificateKeyFile /usr/local/etc/openldap/ldap-Key.pem
TLSCACertificateFile /usr/local/etc/openldap/ldap-CA.pem

Restart slapd:
./slapd -h "ldap:/// ldaps:///"
and check thats it is running with 'ps -ef|grep slapd'.

On SuSE, if using the builting 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 'Use SSL', the port
shold 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). If you use the defualt CA created when  
ejbca was installed this is alread included. Otherwise you will have to add it using something like:
First get the CA cert:
bin/ejbca.sh ca getrootcert MyCA -der
Then add it to the java trust store:
keytool -import -trustcacert -alias MyCA -keystore $JAVA_HOME/jre/lib/security/cacerts -password changeit

A guide for configuring OpenLDAP on Solaris can be found at:
http://www.bolthole.com/solaris/LDAP.html

Configuring extra device schema
===============================

To store certificates for devices (e.g. routers, toasters etc) in LDAP there is
no really suitable standard object class. inetOrgPerson requires surnames etc, and 
the device objectclass does not include a certifictae 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.:

/usr/local/etc/openldap/schema/

and edit slapd.conf to add the following line:

include /usr/local/etc/openldap/schema/ejbca.schema

then restart the server.