SSL/TLS information for LDAP utilities

The contents of a client's key database file is managed with the gskkyman utility. See z/OS Cryptographic Services System SSL Programming for information about the gskkyman utility. The gskkyman utility is used to define the set of trusted certificate authorities (CAs) that are to be trusted by the client. By obtaining certificates from trusted CAs, storing them in the key database file, and marking them as trusted, you can establish a trust relationship with LDAP servers that use certificates issued by one of the CAs that are marked as trusted.

If the LDAP servers accessed by the client use server authentication, it is sufficient to define one or more trusted root certificates in the key database file. With server authentication, the client can be assured that the target LDAP server has been issued a certificate by one of the trusted CAs. In addition, all LDAP transactions that flow over the SSL/TLS connection with the server are encrypted, including the LDAP credentials that are supplied on the ldap_sasl_bind_s() API.

For example, if the LDAP server is using a high-assurance VeriSign certificate, obtain a CA certificate from VeriSign, receive it into your key database file, and mark it as trusted. If the LDAP server is using a self-signed gskkyman server certificate, the administrator of the LDAP server can supply you with a copy of the server's certificate request file. Receive the certificate request file into your key database file and mark it as trusted.

Using the db2pwden or ldapexop utilities without the -Z parameter or the ldapdiff utility without the -sZ or the -cZ parameters and calling the secure port on an LDAP server (in other words, a nonsecure call to a secure port), is not supported. Also, a secure call to a nonsecure port is not supported.

SSL/TLS encrypts the key database file, therefore, either the key database password or a stash file must be specified on the -P keyFilePW parameter. If a stash file is specified, it must be specified in the form file:// followed immediately (no blanks in between) by the file specification of the stash file. See z/OS Cryptographic Services System SSL Programming for information about using the gskkyman utility to create a stash file.

Using RACF key rings

Alternately, LDAP supports the use of a RACF® key ring. See the certificate/key management section in z/OS Cryptographic Services System SSL Programming for instructions on how to migrate a key database to RACF and how to use the RACDCERT command to protect the certificate and key ring.

The user ID under which the LDAP client runs must be authorized by RACF to use RACF key rings. To authorize the LDAP client, you can use the RACF commands in the following example (where userid is the user ID running the LDAP client utility):

RDEFINE RDATALIB <ringowner>.<ringname>.LST UACC(NONE)
PERMIT <userid>.<ringname>.LST CLASS(RDATALIB) ID(userid) ACCESS(READ)

Note: In the previous example, ACCESS(READ) should be specified if the server certificate is owned by userid. Otherwise, ACCESS(UPDATE) should be specified.

Remember to refresh RACF after doing the authorizations.

SETROPTS RACLIST(RDATALIB) REFRESH

RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(userid) ACCESS(READ)

Note: In the previous example, ACCESS(READ) should be specified if the server certificate is owned by userid. Otherwise, ACCESS(UPDATE) should be specified.

Remember to refresh RACF after doing the authorizations.

SETROPTS RACLIST(FACILITY) REFRESH

After the RACF key ring is set up and authorized, specify the RACF key ring name for the -K keyFile, -cK keystore, or -sK keystore options and do not specify the -P keyFilePw, -cP keystorePwd, or -sP keystorePwd options.

Using PKCS #11 tokens

The db2pwden and ldapexop utilities support the use of PKCS #11 tokens. 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.

The user ID that runs the db2pwden or ldapexop utility must be authorized by RACF to use the PKCS #11 token. To authorize the user ID, you can use the RACF commands in the following example (where NAME is the name of the PKCS #11 token and userid is the user ID running the utility).

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

Remember to refresh RACF after doing the authorizations.

SETROPTS RACLIST(CRYPTOZ) REFRESH

Once the PKCS #11 token is set up and authorized, specify the PKCS #11 token for the -K keyFile option in the following manner: -K *TOKEN*/NAME. Also, do not specify the -P keyFilePW option when using a PKCS #11 token.

Using a Java keystore or RACF key ring for ldapdiff

Keys and certificates needed for using SSL with the ldapdiff utility must be stored in either a Java™ keystore file (.jks) or a RACF key ring. If your existing keys and certificates are in a System SSL key database file or a PKCS #11 token, you must migrate them to a keystore file or a RACF key ring. If they are already in a RACF key ring, you can use them as is or can migrate them to a keystore file. To migrate keys and certificates, you must first export them from their source location and then import them into their target location.

You can use the gskkyman utility to export from a key database file or from a PKCS #11 token. You can use the RACDCERT command to export from a RACF key ring or PKCS #11 token.

You can then use the RACDCERT command to import into a RACF key ring or the keytool Java application to import into a Java keystore. Make sure to specify the -storetype JCEKS option when using keytool.

When set up is complete, identify the Java keystore or RACF key ring using the appropriate -sK keystore, -sN keystoreType, -cK keystore, -cN keystoreType, -sT truststore, -st truststoreType, -cT truststore, or -ct truststoreType options when running the ldapdiff utility.

See z/OS Cryptographic Services System SSL Programming for more information about the gskkyman utility and migrating keys and certificates. See z/OS Security Server RACF Command Language Reference for more information about the RACDCERT command. See the keyTool User Guide for SDK for more information about the keytool Java application.