1.3 Authentication and Security

This section contains an overview of authentication and security in the LDAP Libraries for C. This section provides the information you need to set up SSL security, effectively authenticate servers and clients, examine certificates, and securely transport information across your network.

1.3.1 Setting Up SSL Security

The LDAP Libraries for C are independent of Novell client software, and they perform their own authentication. For SSL authentication to work, the LDAP server must have a certificate to use with SSL, and the LDAP libraries must be configured to trust the LDAP server's certificate. Thus, the following two components must be set up to use SSL:

Additionally, to use Client-Based Certificate Authentication (CBCA, sometimes referred to as mutual authentication), you must have a client certificate. See the following for additional information:

LDAP Server

In eDirectory 8 and higher, the LDAP server is installed and started automatically with eDirectory. The LDAP server is set up to service anonymous binds by default.

To enable secure connections over SSL, the LDAP server must be set up with a digital certificate from a Certificate Authority.

The steps for setting up SSL on the LDAP server are slightly different for each release of eDirectory. For specific information, see one of the following:

Server Certificate

The LDAP libraries perform SSL server authentication using SSL certificates.

To export an eDirectory server certificate use ConsoleOne. For step-by-step instructions for this procedure, see the Novell Certificate Server Documentation.

For details on using this certificate see SSL Certificates.

Client Certificate

The LDAP Libraries for C perform SSL client authentication using SSL certificates.

To export a client certificate, use ConsoleOne. For step-by-step instructions for this procedure see Novell Certificate Server Documentation.

HINT:When exporting a client certificate using ConsoleOne, you can place the client private key and certificate in the same file, then secure this file with a password. This password helps prevent unauthorized use of this file.

For details on using this certificate see the Client-Based Certificate Authentication and the SASL External sections in Authentication.

1.3.2 Authentication

The LDAP Libraries for C provide two methods for authentication: Simple Bind and Simple Authentication Security Layer (SASL). Simple Bind enables you to authenticate using a distinguished name and password, whereas SASL defines a standard method to support any number of different authentication mechanisms.

Simple Bind

Simple bind enables you to authenticate to an LDAP server using a distinguished name and password. Simple bind can be used with or without SSL security, and with or without client-based certificate authentication (CBCA).

Simple Bind Without SSL

In order to use simple bind without SSL, eDirectory must be configured to accept clear text passwords:

Allow Clear Text Paswords Configuration in ConsoleOne

WARNING:Enabling eDirectory to accept clear text passwords means that any password you send in clear text is not encrypted as it is transported. Clear text passwords should not be used outside of a secure environment.

For an example, see bind.c. For information on client certificates, see Client Certificate.

Simple Bind With SSL

To use simple bind with SSL, the session is initialized using ldapssl_init (instead of ldap_init), which returns an SSL-enabled context handle to your application. calling ldap_simple_bind with this handle encrypts your bind call using SSL.

For an example using simple bind with SSL, see sslbind.c.

Client-Based Certificate Authentication

Optionally, the LDAP client can present an SSL certificate during authentication, and eDirectory can be configured to require this. This feature is called client-based certificate authentication (CBCA, sometimes referred to as mutual authentication), and can be enabled on the LDAP server object using ConsoleOne:

CBCA Configuration in ConsoleOne

To use CBCA, specify a client private key and a client certificate by calling the ldapssl_set_client_private_key and the ldapssl_set_client_cert functions. Once you have specified a private key and certificate, call ldap_simple_bind to perform the bind.

For an example using client based certificate authentication with simple bind, see mutual.c.

Simple Authentication Security Layer

Simple Authentication Security Layer (SASL) is a standard way for adding authentication support to connection-based protocols.

SASL is used by LDAP to provide modular authentication by defining a standard method for a client and server to use common or custom mechanisms for authentication. Several SASL mechanisms are currently defined by IETF RFCs and Internet drafts.

Although generic SASL support is provided by the ldap_sasl_bind function, the LDAP Libraries for C have been enhanced to simplify using many SASL mechanisms.

NOTE:Support for SASL was added in eDirectory 8.7. To determine which SASL mechanisms are supported by any LDAP server query the rootDSE.

SASL is defined in RFC 2222. The following SASL mechanisms are currently supported by eDirectory 8.7:

Digest MD5

Digest MD5 uses a hash algorithm to encrypt and ensure the integrity of transferred data without using SSL. During Digest MD5 authentication, the client sends a request to the sever, to which the server responds with a digest-challenge (unique data that is verified by the client). The client then sends a response to the server with digest information and login credentials. If the server successfully verifies the response the user is authenticated.

Digest MD5 is defined in RFC 2831.

To use Digest MD5, call the ldap_bind_digest_md5_start function. Once that call completes successfully, call the ldap_bind_md5_finish function specifying your login credentials.

Optionally, before calling the ldap_bind_md5_finish function, you can call ldap_get_digest_md5_realms to retrieve the MD5 realms. In eDirectory, there is only one realm returned which is the tree to which you sent the bind request.

For an example, see md5bind.c.

NOTE:To use SASL Digest MD5 you do not need to call the ldap_sasl_bind function directly.

Mechanism-specific dependencies:

  • The simplePassword attribute must have been set for the user attempting authentication. To set a simplePassword, use the Novell Import Convert Export utility or the simplePassword snap-in for ConsoleOne.

External

SASL External is used in conjunction with the client-based certificate authentication (CBCA) feature of eDirectory. This enables you to require any client attempting a connection to your sever to present an SSL certificate for verification. With this mechanism, the client and server exchange SSL certificates and each determine whether or not to accept the connection.

When using CBCA, instead of passing credentials, the client can use the SASL External mechanism to authenticate to the server based on the information in the SSL certificate.

To use SASL external, specify a client private key and a client certificate by calling the ldapssl_set_client_private_key and the ldapssl_set_client_cert functions. Once you have specified a private key and certificate, call ldap_sasl_bind specifying EXTERNAL as the mechanism parameter to perform the bind.

For an example, see saslExternal.c.

Mechanism-specific dependencies:

  • Client-based certificate authentication must be enabled and required by eDirectory (see LDAP Server).

Novell Modular Authentication Services

Novell Modular Authentication Services (NMAS) provides the ability for developers to add various login and authentication methods to their applications. Possible methods include face recognition, fingerprints, voice recognition, signature, iris recognition, tokens, and smart cards as well as standard passwords. The NMAS SASL mechanism enables you to use these methods to bind to eDirectory using the LDAP protocol.

To use the SASL NMAS mechanism, call ldap_bind_nmas_s specifying the requested NMAS sequence and clearance.

NOTE:To use SASL NMAS authentication you do not need to call the ldap_sasl_bind function directly.

Mechanism-specific dependencies:

  • Microsoft Windows (NMAS functionality is limited to Windows)

  • The NMAS library, nmas.dll, which is included with the LDAP Libraries for C. For additional information on NMAS see Novell Modular Authentication Service.

GSSAPI

The SASL-GSSAPI mechanism enables you to authenticate to eDirectory through LDAP using a Kerberos ticket and you are not required to enter the eDirectory user password. The Kerberos ticket should be obtained by authenticating to a Kerberos server.

This feature is primarily useful for LDAP application users in environments that already has a Kerberos infrastructure in place. Therefore, these users should be able to authenticate to the LDAP server without providing a separate LDAP user password.

To facilitate this, eDirectory introduces the SASL-GSSAPI mechanism.

The current implementation of SASL-GSSAPI is compliant with RFC 2222 (http://www.ietf.org/rfc/rfc2222.txt?number=2222) and supports only Kerberos v5 as the authentication mechanism.

Mechanism-specific dependencies:

  • We assume that SASL-GSSAPI is already installed on your machine. If not, you might want to download and install SASL-GSSAPI.

  • On Windows, SSPI is used for Kerberos authentication

1.3.3 SSL Certificates

The LDAP Libraries for C can be configured to handle server SSL certificates in one of three ways:

  • Add trusted certificates. Your application individually adds each trusted server certificate and does not accept any other certificates. This is the most secure way to handle SSL certificates and is the default mode.

  • Interactive verification. Your application provides a callback mechanism that is called when non-trusted certificates are encountered. This method provides functions to determine the characteristics of the certificate so your application can decide whether or not to trust the certificate.

Add Trusted Certificates

If your application is designed to work with a known set of LDAP servers, the most secure way to handle SSL certificates is to individually add each server certificate.

Only trusted certificates are accepted in this mode unless you specify a callback function using interactive verification, in which case your callback function is called to handle the certificate. This is the default mode for SSL certificate verification.

To add trusted certificates, use the ldapssl_add_trusted_cert function to add each certificate from a DER or Base64 encoded file. For instruction on exporting encoded certificates using ConsoleOne see Setting Up SSL Security.

Interactive Server Verification

The LDAP libraries for C provide an interactive mechanism to handle SSL certificates, called Interactive SSL.

Interactive SSL is used in conjunction with the add trusted certificates mode to provide a callback function when an un-trusted certificate is encountered. If a certificate is not found in the list of trusted certificates, your callback function is called to review the certificate. Your callback function can then choose to accept or reject the certificate.

Interactive server verification mode is set by calling the ldap_ssl_set_verify_callback function and specifying a callback function. If no callback function is specified, certificates are handled as described in Add Trusted Certificates.

For an example of a complete certificate callback routine, see sslbindi.c.

Creating a Certificate Callback Function

To create your own certificate callback function you need to do the following three things:

  1. Before coding, determine your criteria for accepting or rejecting certificates based on the certificate status, issuer, subject, and validity period.

  2. In your code, retrieve the certificate status and other certificate information and determine if the certificate meets your acceptance criteria.

  3. Return either LDAPSSL_CERT_ACCEPT (to accept the certificate) or LDAPSSL_CERT_REJECT (to reject the certificate).

Certificate Status

The SSL certificate status codes are defined in Section 6.12, SSL Certificate Status Codes. The status code indicates the reason your callback function was called. For example, the certificate might be un-trusted, contain an invalid date, or a formatting error.

The certificate status is retrieved by calling ldapssl_get_cert_attribute specifying LDAPSSL_CERT_GET_STATUS as the attribute ID you would like returned.

Of the sixteen status codes, only three indicate a valid certificate: LDAPSSL_CERT_STATUS_ERR_CERT_UNTRUSTED, LDAPSSL_CERT_STATUS_ERR_DEPTH_ZERO_SELF_SIGNED_CERT, and LDAPSSL_CERT_STATUS_ERR_SELF_SIGNED_CERT_IN_CHAIN. The first status simply means that this certificate is not trusted, and the other two indicate a self-signed certificate.

All other status codes indicate a problem with the certificate, such as an invalid date or a format error. In most cases you will reject invalid certificates, though you can find out more about the certificate and decide based on other factors.

Other Certificate Information

The ldapssl_get_cert_attribute function can also retrieve the certificate issuer (LDAPSSL_CERT_ATTR_ISSUER), the certificate subject (LDAPSSL_CERT_ATTR_SUBJECT), and the certificate validity period (LDAPSSL_CERT_ATTR_VALIDITY_PERIOD) to help you determine whether or not to accept the certificate. For example, you might want to check the issuer and validity period on all un-trusted certificates before accepting them.

Accept or Reject the Certificate

Once you have determined whether or not the certificate meets your criteria for acceptance your callback function returns either LDAPSSL_CERT_ACCEPT to accept the certificate or LDAPSSL_CERT_REJECT to reject the certificate.

Helper Functions

In addition to ldapssl_get_cert_attribute, the LDAP Libraries for C provide other functions to help you handle SSL certificates, outlined below:

  • ldapssl_get_cert enables you to place the certificate in a buffer encoded in DER or Base64 format. You can then pass this buffer directly to ldapssl_add_trusted_cert to add this certificate to the list of trusted certificates.

  • ldapssl_add_trusted_cert enables you to add a certificate to a list of trusted certificates. The certificate will remain trusted for the duration of the session.

  • ldapssl_get_verify_mode returns the current server verification mode.

Accept Any Certificate

This function will be deprecated in the future C LDAP SDK releases. For this release, the LDAPSSL_VERIFY_NONE option will not be supported in both ldapssl_set_verify_mode and ldapssl_get_verify_mode.

1.3.4 Transport Layer Security

When you perform SSL authentication, SSL security is used to encrypt data transfers for the duration of the session.

HINT:Transport Layer Security (TLS) is the open-standards equivalent of SSL. When the IETF standardized SSL, this standardized security layer was named TLS.

Because of the overhead of encryption, there are times when a client might want to disable SSL security and send information un-encrypted. Additionally, you might want to perform a clear text or non-SSL SASL authentication, then enable SSL security to transfer a piece of sensitive information.

The LDAP Libraries for C provide startTLS and stopTLS functions to enable and disable TLS.

For an example of starting and stopping TLS see starttls.c.

1.3.5 Recommendations

We recommend you do the following for maximizing the security:

  • Do a simple bind over encrypted channel.

  • Do not accept any certificates without validation.

  • Do a check for the SSL authentication failure. As LDAP Libraries for C does not check this, but your application should do it.

  • Do set the cipher to high.