The Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols use public-key infrastructure (PKI) algorithms to establish and maintain an encrypted communications path between a client and server. In z/OS®, the ability to set up and communicate over SSL/TLS protected communication links is provided by the LDAP server with a set of services provided in z/OS (the z/OS Cryptographic Services System SSL set of services).

In order for the LDAP client to communicate with an LDAP server over an SSL/TLS-protected TCP/IP socket connection, the LDAP server must transmit a certificate to the LDAP client and, optionally, the client can transmit its certificate to the LDAP server. The LDAP client and server must verify that the certificates they received are valid. After the LDAP client and server have determined the validity of the certificates provided to them, SSL/TLS-protected communication occurs between the LDAP client and server.

The LDAP client and server verify that the certificates sent to them by using public-key digital signatures. The LDAP client and server take the certificates and compare the digital signature in the certificates with a signature that it computes based on having the public-key of the signer of the certificate. In order to do this, the LDAP client and server must have the public-key of the signer of the certificates. The LDAP client and server obtain this by reading a file that contains these public-keys. This file is called a key database.

A key database, RACF® key ring, or PKCS #11 token contains the public-keys that are associated with signers of certificates. These public-keys are, in reality, contained in certificates themselves. Therefore, verifying that one certificate requires the use of a different certificate, the signers certificate. In this fashion, a chain of certificates is established, with one certificate being verified by using another certificate and that certificate being verified by yet another certificate, and so on. A certificate, and its associated public key, can be defined as a root certificate. A root certificate is self-signed, meaning that the public-key contained in the certificate is used to sign the certificate. Using a root certificate implies that the user trusts the root certificate.

The key databases, RACF key rings, or PKCS #11 tokens used by the LDAP client and server must contain enough certificates in order to verify the certificates sent by the LDAP client and server during the start of the SSL/TLS connection. If either certificate is self-signed, then that certificate must be stored in the others key database. If the certificates are signed by some other certificate signer, then the signers certificate and any certificates that this certificate depends upon must be stored in the key databases. The key databases, RACF key rings, or PKCS #11 tokens used by the LDAP client and server must also contain the certificates that are transmitted to each other during the startup of the SSL/TLS-protected communications.

The LDAP client and server use the System SSL functions provided in z/OS to set up SSL/TLS protected communications. The System SSL capability requires a key database, RACF key ring, or PKCS #11 token to be set up before SSL/TLS protected communications can begin.

The key database is a password protected file stored in the file system. This file is created and managed using a utility program provided with System SSL called gskkyman. See z/OS Cryptographic Services System SSL Programming for more information about the gskkyman utility. The key database file that is created must be accessible by the LDAP server.

The key ring is maintained by RACF. This object is created and managed using the RACF Digital Certificate command, RACDCERT. Directions for using the RACDCERT command can be found in z/OS Security Server RACF Command Language Reference.

RDEFINE FACILITY IRR.DIGTCERT.LIST UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(LDAPSRV) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(LDAPSRV) ACCESS(CONTROL)

SETROPTS RACLIST(FACILITY) REFRESH

PKCS #11 tokens are stored and protected by ICSF. The gskkyman utility or the RACDCERT command can be used to create or modify PKCS #11 tokens. ICSF uses the CRYPTOZ SAF class to determine if the issuer of the gskkyman utility or the RACDCERT command is permitted to perform the operation against a z/OS PKCS #11 token. See z/OS Cryptographic Services System SSL Programming for more information about the gskkyman utility and z/OS Security Server RACF Command Language Reference for more information about the RACDCERT command.

SETROPTS CLASSACT(CRYPTOZ)
RDEFINE CRYPTOZ USER.NAME UACC(NONE)
RDEFINE CRYPTOZ SO.NAME UACC(NONE)
PERMIT USER.NAME CLASS(CRYPTOZ) ID(LDAPSRV) ACCESS(READ)
PERMIT SO.NAME CLASS(CRYPTOZ) ID(LDAPSRV) ACCESS(READ)

SETROPTS RACLIST(CRYPTOZ) REFRESH 

For testing purposes, the LDAP server can use a self-signed certificate. In this case, the certificate of the LDAP server must also be stored in the key database, RACF key ring, or PKCS #11 token of the LDAP client in order for SSL/TLS protected LDAP communications to work between the client and server.

If the SSL certificate that the LDAP server is going to use is not marked as the default certificate in the key database, RACF key ring, or the PKCS #11 token then the sslCertificate server configuration option must be specified in order to determine which SSL certificate to use.

The LDAP server or client can obtain a certificate by contacting a certificate authority (CA) and requesting a certificate. Utilities to formulate a certificate request are provided by System SSL, gskkyman, and RACF, RACDCERT. This certificate request is typically passed to the CA with an electronic mail message or by an HTML form which is filled out using a web browser. When the CA verifies the information for the LDAP client or server, a certificate is returned to the requester, typically by an electronic mail message. The contents of the mail message are used to define the certificate in the key database, RACF key ring, or PKCS #11 token.

The following high-level steps are required to enable SSL/TLS support for LDAP. These steps assume that the LDAP server and z/OS Cryptographic Services System SSL are installed and configured. The data sets containing the LDAP and SSL code must be APF-authorized and available to the LDAP server.

1. Generate the LDAP server private key and server certificate and mark it as the default in the key database, RACF key ring, or PKCS #11 token or use its label on the sslCertificate option in the LDAP server configuration file.
2. Configure the LDAP server to the security options you want that are related to SSL/TLS secure communications. See Setting up the security options for the LDAP server for more information, that includes:
   • Defining the acceptable SSL and TLS protocol levels.
   • Defining the acceptable cipher specifications.
   • Defining the secure sockets and bimodal sockets the server uses to listen for inbound client requests.
   • Defining the type of authentication wanted.
   • Defining the server certificate to be used, and where it is located.
3. Restart the LDAP server.

Several options that are related to the LDAP server SSL/TLS secure communications can be controlled by environment variables that are used by z/OS System SSL. The accepted protocol levels, the cipher suites, and suite B profile are all configured by using environment variables.

By default, the z/OS LDAP server disables SSL V2 protocol and enables SSL V3.0 and TLS V1.0 protocol levels. TLS V1.1 and TLS V1.2 protocol levels are controlled by the z/OS System SSL defaults and environment variables. By default, these two protocols are disabled. To enable TLS V1.1 protocol, you must set the environment variable GSK_PROTOCOL_TLSV1_1 to "ON". Similarly, to enable TLS V1.2 protocol, you must set the environment variable GSK_PROTOCOL_TLSV1_2 to "ON".

The z/OS LDAP server provides the sslCipherSpecs configuration option for specifying the accepted cipher suites that are used in SSL/TLS secure connections. However, this configuration option is limited in its support, and is provided only for compatibility with earlier versions. During the SSL handshake that occurs when a secure connection is established, z/OS system SSL uses the list of acceptable cipher specifications that are provided by the LDAP server to determine preference. When the sslCipherSpecs configuration option is used to specify the acceptable cipher suites, the order of preference is defined by the z/OS LDAP server and matches the default order that is documented by z/OS System SSL. The sslCipherSpecs specification as a bit-mask does not readily accommodate the many available cipher suites that are provided with TLS V1.1 and TLS 1.2 protocols, nor does it provide the capability of altering the default preference order.

If the only cipher specifications required are listed in Table 1, and the default order of preference is acceptable, then the sslCipherSpecs configuration option may be used to list the cipher suites you want. Otherwise, you must specify "sslCipherSpecs GSK_V3_CIPHER_SPECS_EXPANDED" in your z/OS LDAP server configuration file. With this setting, the cipher suites that are accepted come from the defaults as defined by z/OS System SSL, including those specified in the environment variable GSK_V3_CIPHER_SPECS_EXPANDED. Set the environment variable GSK_V3_CIPHER_SPECS_EXPANDED to the 4-character cipher suites you want, in order of preference.

To restrict the SSL/TLS secure connections that are used by the z/OS LDAP server to the Suite B Profile, you must set the GSK_SUITE_B_PROFILE environment variable to the appropriate setting. See z/OS Cryptographic Services System SSL Programming for more information. If the Suite B profile is enabled, this controls the acceptable SSL/TLS protocol levels and cipher suites, overriding the other settings that are mentioned above.

The sslKeyRingFile option specifies the name of the key database, the RACF key ring, or the PKCS #11 token used by the LDAP server. This key database, RACF key ring, or PKCS #11 token is also used for SSL/TLS protected replication. Because the replicating server might be acting as both a replica server and an LDAP server, the replica server's certificate (or CA certificate) must be contained in the replicating server's key database file, RACF key ring, or PKCS #11 token. When using a PKCS #11 token, the sslKeyRingFile configuration option must be set such as this (where NAME is the name of the PKCS #11 token): *TOKEN*/NAME

A key database requires a password. The password may be specified on the sslKeyRingFilePW option or the name of a password stash file may be specified on the sslKeyRingPWStashFile option in the LDAP server configuration file. Use of a stash file provides a method of specifying a password in a form that cannot be easily read by a human. The gskkyman utility provides a function to create the key database password stash file.

When a RACF key ring or PKCS #11 token is used instead of a key database, the sslKeyRingFilePW and sslKeyRingPWStashFile cannot be specified in the configuration file.

The LDAP server is configured to provide server and, optionally, client authentication. The sslAuth option controls this setting.

When using server authentication, by setting the sslAuth server configuration option to serverAuth, the LDAP server must have a digital certificate (based on the X.509 standard). This digital certificate is used to authenticate the LDAP server to the LDAP client application. The LDAP server supplies the client with the LDAP servers X.509 certificate during the initial SSL handshake. If the client validates the servers certificate, then a secure, encrypted communication channel is established between the LDAP server and the LDAP client application.

In addition, if the LDAP server is configured to use server and client authentication, by setting the sslAuth server configuration option to serverClientAuth, and the client sends a digital certificate on the initial SSL handshake, it must be validated by the LDAP server before the secure encrypted communication channel is established between them. The certificate is used to establish the bind identity of the client. This identity is also affected by the sslMapCertificate configuration option. See Support of certificate bind for more information.

The sslMapCertificate option specifies whether the server maps a certificate used in a SASL EXTERNAL bind to the RACF user that is associated with the certificate.

The sslCertificate option indicates the label of the server certificate that is to be used. This option is needed if the default certificate has not been set in the key database, RACF key ring, or PKCS #11 token or if a certificate other than the default certificate is what you want.

The sslCipherSpecs option defines the cipher specifications that are accepted from clients. This option is discouraged and provided only for compatibility with an earlier version. It supports only a portion of the cipher suites available in z/OS System SSL, contains no 4-character cipher suites, and provides no order of preference. The preferred approach is to specify "sslCipherSpecs GSK_V3_CIPHER_SPECS_EXPANDED" and use the environment variable GSK_V3_CIPHER_SPECS_EXPANDED to define the list of 4-character cipher specifications, in order of preference.

If the cipher specifications you want are included in Table 1, and if the order of preference matches the default order that is provided by z/OS System SSL, then the sslCipherSpecs option may be used with any of the values described.

If sslCipherSpecs is omitted from the server configuration file, all cipher specifications that are listed in Table 1 are used.

Depending upon the level of System SSL support, the list of acceptable cipher specifications might be lowered because certain specifications might not be supported by System SSL for that level of the product. Table 1 lists the LDAP sslCipherSpecs mask values that are accepted by the sslCipherSpecs option, and the related decimal, hexadecimal, and keyword values. It also lists the System SSL cipher number.

As with the LDAP server, the LDAP client that wants to use SSL/TLS protected communication needs access to a key database, RACF key ring, or PKCS #11 token. If the LDAP server you are going to contact is using a self-signed certificate (as is done frequently while testing SSL/TLS protected communications between an LDAP client and server), then the self-signed certificate of the LDAP server must be stored into the LDAP client's key database, RACF key ring, or PKCS #11 token.

If the LDAP server you are going to contact is using a certificate which is signed by a certificate authority (CA), you must ensure that the certificate for the CA is contained in the key database, RACF key ring, or PKCS #11 token. Use whatever is provided by the CA for obtaining the CA certificate. The certificate should be obtainable in a format that is acceptable to the gskkyman utility or RACDCERT command.

If the LDAP server is configured for server and client authentication and the client wants client authentication to occur, then the LDAP client must obtain its own certificate from a CA and store it in the client's own key database, RACF key ring, or PKCS #11 token and mark it as the default.

After the key database file, RACF key ring, or PKCS #11 token is created and contains the appropriate certificates, then the LDAP client is ready to perform SSL/TLS protected communications with an LDAP server. The LDAP client utilities (for example, ldapsearch) can be used to communicate securely with the LDAP server using a secure only connection. The utilities are explained in z/OS IBM Tivoli Directory Server Client Programming for z/OS.

The ldap_ssl_client_init() and ldap_ssl_init() APIs can be used to start a secure only connection to an LDAP server. A description of these APIs can be found in z/OS IBM Tivoli Directory Server Client Programming for z/OS.

The SASL bind mechanism of EXTERNAL is supported by the LDAP server. This means that the authentication on the bind is performed using the data obtained during the SSL/TLS client authentication that was performed on the SSL/TLS handshake with the client.

To use SASL EXTERNAL bind, the following steps must occur:

• The LDAP server must be configured and started with sslAuth set to serverClientAuth so that the server can authenticate the client.
• The client connects to the LDAP server and performs the SSL/TLS handshake. The handshake sends the client certificate to the LDAP server.
• The client performs a SASL bind with the mechanism of EXTERNAL.

At this point, the LDAP server considers the bind DN of the client for authorization purposes to be the clients DN as transmitted in the clients certificate on the handshake. The name specified in the BIND request must match the subject name in the client certificate or must be null.

The RACF RACDCERT command is used to associate a certificate with a RACF user ID. If check, add, or replace is specified on the sslMapCertificate configuration option, the LDAP server determines if the client certificate used during an EXTERNAL bind is associated with a RACF user ID, therefore, adds that RACF user ID to the bind information kept for this client.

After an EXTERNAL bind, the client can access LDBM, CDBM, TDBM, and GDBM backends based on the bind DN and the groups it belongs to. If the sslMapCertificate option is set to keep the associated RACF user ID in the bind information, the client can perform SDBM operations to access RACF data, under the context of the RACF user ID.

See z/OS Security Server RACF Security Administrator's Guide for more information about associating a certificate with a RACF user ID.