LDAP Backend Module

Authorise the issuing of a certificate, and store the certificate issued against an LDAP directory.

What does it do?

Based on configuration providing the details of an LDAP server, the issuing of the certificate can be authorised in advance, and the resulting issued certificate can be stored in an LDAP directory.

When storing the certificate, all modifications to the directory are applied in a single transaction.

Module Integration

The mod_ca_ldap module is a backend module and will not do anything useful until mod_ca_ldap has been combined with one or more frontend modules listed below. The mod_ca_ldap module uses the following hooks, and suitable frontend modules must be configured to implement each protocol as needed.

All backend modules run within a standard Apache httpd request, and standard httpd functionality applies in all cases.

Request Authorization Hook

This optional hook allows you to verify the parameters included with the certificate sign request, such as the challenge password. If left unconfigured, all certificate requests will be accepted.

This module provides the following implementations of this hook.

LDAP Request Authorization Verifies authorization against an LDAP directory.

This hook is called by the following frontend modules.

mod_csr Generate and issue certificates in response to an X509 certificate request.
mod_pkcs12 Generate public/private key pairs and and issue certificates in response to a application/x-www-form-urlencoded form request.
mod_scep Generate and issue certificates using the SCEP protocol.
mod_spkac Generate and issue certificates using the SPKAC protocol.

Certificate Storage Hook

This optional hook allows the newly generated certificate to be stored locally or in a database or directory. If left unconfigured, no local copy of the certificate will be stored.

This module provides the following implementations of this hook.

LDAP Certificate Storage Stores a generated certificate in an LDAP directory.

This hook is called by the following frontend modules.

mod_csr Generate and issue certificates in response to an X509 certificate request.
mod_pkcs12 Generate public/private key pairs and and issue certificates in response to a application/x-www-form-urlencoded form request.
mod_scep Generate and issue certificates using the SCEP protocol.
mod_spkac Generate and issue certificates using the SPKAC protocol.

Examples

Verification Example

The simplest case: verify the issuing of the certificate. The certificate request is expected to contain a challenge password, and we will attempt to bind to the directory as the mapped user and challenge password.


# backend configuration:
<IfModule mod_ca_simple.c>
  # sign with this certificate...
  CASimpleCertificate /etc/pki/tls/ca-cert.pem
  # ...and private key
  CASimpleKey /etc/pki/tls/ca-key.pem
  # use system clock as the time source
  CASimpleTime on
  # assign a random serial number
  CASimpleSerialRandom on
</IfModule>
<IfModule mod_ca_ldap.c>
  # bind to this directory
  CALdapUrl ${LDAP_BASEURL}?cn?sub?(objectclass=simpleSecurityObject)
  CALdapBindDN "${LDAP_BINDDN}"
  CALdapBindPassword ${LDAP_BINDPW}
  # map the LDAP attribute 'cn' to the 'CN' element
  # in the certificate subject when searching
  CALdapSubject cn CN
</IfModule>

# frontend configuration:
<IfModule mod_csr.c>
  <Location /csr>
    SetHandler csr
    # use subject from the certificate sign request unmodified
    CsrSubjectRequest *
  </Location>
</IfModule>

Storage Example

The storage case: verify the issuing of the certificate, and store the result in the directory.


# backend configuration:
<IfModule mod_ca_simple.c>
  # sign with this certificate...
  CASimpleCertificate /etc/pki/tls/ca-cert.pem
  # ...and private key
  CASimpleKey /etc/pki/tls/ca-key.pem
  # use system clock as the time source
  CASimpleTime on
  # assign a random serial number
  CASimpleSerialRandom on
</IfModule>
<IfModule mod_ca_ldap.c>
  # bind to this directory
  CALdapUrl ${LDAP_BASEURL}?cn?sub?(objectclass=simpleSecurityObject)
  CALdapBindDN "${LDAP_BINDDN}"
  CALdapBindPassword ${LDAP_BINDPW}
  # map the LDAP attribute 'cn' to the 'CN' element
  # in the certificate subject when searching
  CALdapSubject cn CN
  # if the certificate was issued, remove the password
  CALdapPasswordAttribute userPassword
  # if the certificate was issued, remove the objectclass
  CALdapPasswordObjectClass simpleSecurityObject
  # if the certificate was issued, store it in the following attribute
  CALdapCertAttribute userCertificate
  # if the certificate was issued, add the following objectclass
  CALdapCertObjectClass pkiUser
</IfModule>

# frontend configuration:
<IfModule mod_csr.c>
  <Location /csr>
    SetHandler csr
    # use subject from the certificate sign request unmodified
    CsrSubjectRequest *
  </Location>
</IfModule>

Hook Implementation Reference

The following backend hook implementations are provided by this module.

LDAP Request Authorization

Verifies authorization against an LDAP directory.

This optional hook implementaation allows you to verify the parameters included with the certificate sign request, such as the challengePassword. If left unconfigured, all certificate requests will be accepted.

The CALdapUrl and CALdapSubject or CALdapSubjectAltName directives enable verification.

Once the subject or subject alternate request has been used to map the certificate to an entry in the directory, and if a challengePassword has been included with the certificate, this hook implementation will try to bind to the directory as that mapped object, and if this succeeds the request is authorized.

LDAP Certificate Storage

Stores a generated certificate in an LDAP directory.

This optional hook implementation extends and depends on the LDAP Request Authorization hook implementation above.

If an LDAP object was found and verified above, the certificate will be stored in the directory in that object in an attribute specified by the CALdapCertAttribute directive. If an objectclass needs to be added, this is done with the CALdapCertObjectClass directive.

If it is required that the challengePassword be used just once, the challengePassword can be removed by specifying the CALdapPasswordAttribute directive. Similarly, if an objectclass needs to be removed, the objectclass can be specified using the CALdapPasswordObjectClass directive.

It is also possible to store the CertificateExactAssertion as described by RFC 4523 in the same object in an attribute specified by the CALdapPathAttribute directive. If an objectclass needs to be added, this is done with the CALdapPathObjectClass directive.

All of the above modifications to the directory are performed within the same LDAP modification, and are performed as a single transaction.

Directive Reference

CALdapUrl Directive

Description Set to a RFC 2255 compliant URL to define the LDAP connection.
Syntax CALdapUrl url
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_ldap
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to a RFC 2255 compliant URL to define the LDAP connection.

The URL is of the form ldap://host[:port]/basedn[?attrib[?scope[?filter]]].

  • host is the name of the LDAP server. Use a space separated list of hosts to specify redundant servers.
  • port is optional, and specifies the port to connect to.
  • basedn specifies the base DN to start searches from.
  • attrib specifies what attribute to search for in the directory.
  • scope is the scope of the search, and can be either sub or one. If not provided, the default is sub.
  • filter is a filter to use in the search. If not provided, defaults to (objectClass=*)

CALdapBindDN Directive

Description DN to use to bind to LDAP server. If not provided, will do an anonymous bind.
Syntax CALdapBindDN string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_ldap
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

DN to use to bind to LDAP server. If not provided, will do an anonymous bind.

CALdapBindPassword Directive

Description Password to use to bind to LDAP server. If not provided, will do an anonymous bind.
Syntax CALdapBindPassword string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_ldap
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Password to use to bind to LDAP server. If not provided, will do an anonymous bind.

CALdapSubject Directive

Description Mapping from LDAP attribute to certificate subject element.
Syntax CALdapSubject string string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_ldap
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Mapping from LDAP attribute to certificate subject element.

The first parameter is the LDAP attribute to be embedded in the search filter.

The second parameter is the name or OID of the element in the subject to be embedded as the value in the search filter.

CALdapSubjectAltName Directive

Description Mapping from LDAP attribute to certificate subject alternate name element.
Syntax CALdapSubjectAltName string string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_ldap
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Mapping from LDAP attribute to certificate subject alternate name element.

The first parameter is the LDAP attribute to be embedded in the search filter.

The second parameter is the name or OID of the element in the subject alternate name to be embedded as the value in the search filter.

CALdapTimeout Directive

Description Specify the LDAP bind/search timeout in seconds.
Syntax CALdapTimeout integer
Default CALdapTimeout 60
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_ldap
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Specify the LDAP bind/search timeout in seconds. Set to zero for no limit.

CALdapCertAttribute Directive

Description If specified, the certificate is stored in this attribute.
Syntax CALdapCertAttribute string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_ldap
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

If specified, the certificate is stored in this attribute.

CALdapCertObjectClass Directive

Description If specified, the objectclass is added to the directory on storage.
Syntax CALdapCertObjectClass string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_ldap
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

If specified, the objectclass is added to the directory on storage.

CALdapPasswordAttribute Directive

Description If specified, remove the password in this attribute on storage.
Syntax CALdapPasswordAttribute string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_ldap
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

If specified, remove the password in this attribute on storage at the same time as we store the certificate.

This allows the challengePassword to be treated as a one time password which will disappear when the certificate is issued.

CALdapPasswordObjectClass Directive

Description If specified, remove the objectclass along with the password on storage.
Syntax CALdapPasswordObjectClass string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_ldap
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

If specified, remove the objectclass along with the password on storage at the same time as we store the certificate.

This allows the challengePassword to be treated as a one time password which will disappear when the certificate is issued.

CALdapPathAttribute Directive

Description If specified, place the certificate path in this attribute on storage.
Syntax CALdapPasswordObjectClass string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_ldap
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

If specified, place the certificate path in this attribute at the same time as we store the certificate.

The certificate path is stored as an CertificateExactAssertion as described by RFC 4523.

CALdapPathObjectClass Directive

Description If specified, add the objectclass along with the path on storage.
Syntax CALdapPathObjectClass string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_ldap
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

If specified, add the objectclass along with the path at the same time as we store the certificate.