OpenCA provides an LDAP interface for users to download certificates from a central repository. This interface can be utilised by browser address books and specialised LDAP clients.
Before the OpenCA Online components can write certificates and CRLs to the directory you must have an LDAP compliant directory installed and available to the online components (this can be on the same or different machine). One example of an appropriate directory is the OpenLDAP project.
A full description of the configuration of your LDAP directory is outside the scope of this document. Important points to note are:
Ensure that the following schemas are included (probably in the slapd.conf file):
core.schema
cosine.schema
inetorgperson.schema
openca.schema
Ensure the directory is started with the appropriate suffix (e.g. o=myorg,c=gb).
Ensure the rootdn is specified.
Ensure the root password is specified.
Three configuration files must be configured for the online
components to make use of the LDAP directory to store certificates;
OPENCADIR/etc/servers/node.conf
,
OPENCADIR/etc/servers/ldap.conf
and
OPENCADIR/etc/ldap.xml
.
Usually it is enough to set the
correct options in ldap.xml
or in
config.xml
.
The configuration is splitted into two parts - a OpenCA related
part and a LDAP related part. The OpenCA related part consists
only of four options - the LDAP activation, automatic LDAP
updates during imports and distinguished name manipulations for
CA objects like CA certificates and CRLs. These options can be
configured in the interface configurations in
OPENCADIR/etc/servers/
.
Supported options in interface configurations
If you set this option to "yes" then the LDAP code will be activated.
This option will be used by the node interface. If the value is yes then the LDAP server will be updated automatically during imports of certificates, CRRs or CRLs.
Some users want to store the CRL in a special node of the LDAP server which is not identical with the issuer of the CRL. This can be happen if the user specifies a special CRL Distribution Point (CDP) which differs from the subject of the CA certificate. Here you can specify this special distinguished name. Please remember that OpenCA is today not able to add this node automatically if it is not present.
Some users want to store the CA certificate in a not standard conform node which means that there is perhaps an already existent directory which conflicts with the PKI structure. Here they can add the distinguished name of this special node. This node can be automatically added by OpenCA.
The LDAP related part of the configuration can be found in
OPENCADIR/etc/ldap.xml
. This central
configuration file avoids double configurations which can
produce many errors and confusion because you are sure that
you changed it but you only did it for one interface. The
isolated configration allows better names for the
configuration options too.
This is the hostname of your LDAP server.
This is the port where your LDAP server listens.
This is the suffix (OpenLDAP terminology) of your LDAP server. You can add here several suffixes if your LDAP server supports this feature (e.g. OpenLDAP v2). Every suffix must be placed in a seperate dn tag. The suffix tag is the bracket for all those suffixes.
The bind DN of the user which OpenCA uses to add data to the server.
The passphrase for OpenCA's ldap account.
OpenCA supports LDAP v2 and v3. The default is v2 because all servers can support v2. Several new distributions especially of Linux deactivates the LDAP v2 support. So if your OpenCA LDAP code completely fails check first the protocol versions of OpenCA and your LDAP server.
Some other options like ldaptls and ldapsasl require LDAP v3. So be really careful which protocol you use. If your LDAP server supports protocol version 3 then please use it. It avoids a lot of trouble.
Use no or yes to deactivate or activate TLS. Please remember that this option only works with LDAP v3.
Use no or yes to deactivate or activate SASL. Please remember that this option only works with LDAP v3. We use CRAM-MD5 for passphrase hashing.
OpenCA supports the possibility to exclude roles from certificate publishing. This can be useful for security reason and be required by privacy laws. If you have such a special role simply add it to to this options.
As long as the option updateLDAPautomatic
is set to
yes
the online components will attempt to upload
certificates to the directory after an import. Before this can
happen the directory must be initialised and the appropriate
structure must be implemented. In this version of OpenCA this
initialization is done automatically.
The common situation in large directory projects is a big schema
and at the end a small request for certificate integration. This
is usually no problem if OpenCA has to create and add
certificates to an existent and filled LDAP server. OpenCA gets
a problem if you want that OpenCA initialize this LDAP server
and should create all missing nodes in the directory tree. If
this is the case then you must integrate your schema
specification into OpenCA's ldap configuration. You can find
this schema specification in ldpa.xml
. The
path to the schema specification is
openca/ldap/schema
.
First you have to understand the general design of OpenCA's LDAP schema support. We have a very pragmatical idea of directory trees because it is not possible to handle all full featured ideas. We simply use the least significant attribute to select an appropriate schema definition for a distinguished name. Do you want to know what this mean? If you have a RFC 2253 conform distinguished name then you take the RDN on the left side. The used attribute type is used to detect the appropriate schema.
Before you can select a schema with the atribute type you must
know what you want to create for a node in the directory tree.
If the used distinguished name is the complete subject of a
certificate then you must select the schema specification from
the XML path openca/ldap/schema/certificate
.
Otherwise you you have to use
openca/ldap/schema/default
. If you need to
store a CA certificate then you must specify the schema in
openca/ldap/schema/ca
.
Every RDN entry in the described sections specifies the characteristics for one attributetype. This include things like required (must) or optional (may) attributes and used objectclasses (structural and auxiliary). If you have for example a new attributetype uid_special and a new class MY_CLASS then your RDN section for certificates with this attributetype as last one should looks like this.
OpenCA's schema definition is perhaps not so flexible as you need but we are open for new ideas. Be free to mail us your ideas. If they are not too proprietary then perhaps we can integrate them :)