SSL/TLS information for LDAP client utilities

The user ID under which the LDAP client runs must be authorized by RACF to use RACF key rings. To restrict access to key rings, two methods are available: global profile checking and ring-specific profile checking.

• Ring-specific profile checking, which has precedence over global profile checking, uses a resource with one of the following formats to provide access control to a specific key ring. To authorize the LDAP client using ring-specific profile checking, you can use the RACF commands in the following example (where userid is the user ID associated with the LDAP client utility):

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

  For more details about name restrictions and other considerations for using ring-specific profile checking, see the description of RACF authorization in the R_datalib interface section in z/OS Security Server RACF Callable Services.
• Global profile checking uses the IRR.DIGTCERT.LISTRING resource in the FACILITY class and applies to all key rings. To authorize the LDAP client using global profile checking, you can use the RACF commands in the following example (where userid is the user ID associated with the LDAP client utility).

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

Remember to refresh the RACF FACILITY class after doing the authorization:

    SETROPTS RACLIST(FACILITY) REFRESH

The user ID associated with the LDAP client must be authorized by RACF to use the PKCS #11 token. To authorize the LDAP client, 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 associated with the LDAP client 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

After the PKCS #11 token is set up and authorized, specify the PKCS #11 token for the -K keyFile option using the following format:

-K *TOKEN*/NAME

Also, do not specify the -P keyFilePW option when using a PKCS #11 token.

If SSL initialization fails, an error message like the following is returned:

ldap_ssl_client_init failed! rc == 113, failureReasonCode == 2
reason text: SSL initialization failed

The failureReasonCode indicates the cause of the SSL failure and is mapped from the return code of various SSL functions. See Table 1 for these values. The failure reason code and SSL return code mappings and #defines are documented in file /usr/include/ldapssl.h.

TLS V1.1, TLS V1.2, and TLS V1.3 protocols are disabled by default. To enable these protocol levels or to override the default cipher specifications, the z/OS System SSL environment variables can be used.

• Set GSK_PROTOCOL_TLSV1_1 "ON" to enable TLS V1.1 protocol.
• Set GSK_PROTOCOL_TLSV1_2 "ON" to enable TLS V1.2 protocol.
• Set GSK_PROTOCOL_TLSV1_3 "ON" to enable TLS V1.3 protocol.
• Choose the appropriate cipher format. Only one set of cipher suite specifications (2-byte or 4-byte) is applicable, depending on the setting of the LDAP_SSL_CIPHER_FORMAT environment variable.
  • If the default 2-byte cipher suites are sufficient, you can allow the settings to default. If you want to override the cipher suite specifications, and all can be specified as 2-byte cipher suite values, you can set GSK_V3_CIPHER_SPECS to override the default cipher specifications, specifying the set of 2-byte values you want. You can also set the LDAP_SSL_CIPHER_FORMAT environment variable to CHAR2, or do not set it.
  • If you require any cipher suites that can only be specified as a 4-byte value, you must set GSK_V3_CIPHER_SPECS_EXPANDED to override the default cipher specifications, specifying the set of 4-byte values you want. You must also set the LDAP_SSL_CIPHER_FORMAT environment variable to CHAR4.
• To enable TLS V1.3 protocol, you need to set the environment variable GSK_TLS_SIG_ALG_PAIRS for signature algorithm pair specification. You also must set the environment variable GSK_CLIENT_TLS_KEY_SHARES for key share option on LDAP client side. For more information about the GSK_CLIENT_TLS_KEY_SHARES environment variable, see Environment variables in z/OS Cryptographic Services System SSL Programming.
• Set GSK_SUITE_B_PROFILE to the value you want to apply Suite B-compliant options for your SSL connection. See z/OS Cryptographic Services System SSL Programming for more information. Enabling Suite B by using this environment variable causes the settings of the other environment variables to be ignored, which includes the LDAP_SSL_CIPHER_FORMAT.