SSL/TLS information for LDAP client 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 LDAP client utilities without the -Z parameter and calling the secure port on an LDAP server (in other words, a non-secure call to a secure port) is not supported. Also, a secure call to a non-secure port is not supported.

FIPS mode can be specified for SSL/TLS protected connections by using the -x parameter. When FIPS mode is enabled, it is more restrictive in regards to cryptogrpahic algorithms, protocols, and key sized that are supported. When executing in FIPS mode, only the TLS V1.0, TLS V1.1, and TLS V1.2 protocols are supported. The specification of SSL V2 and SSL V3 are not supported. For more information about using FIPS mode in System SSL, see z/OS Cryptographic Services System SSL Programming.

SSL/TLS encrypts the key database file therefore either the key database password or a stash file must be specified on the -P 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 and restricting access to them

Alternately, LDAP supports the use of a RACF® key ring. See Certificate/Key management 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 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

Guideline: Global profile checking applies to all key rings. Ring-specific profile checking applies to a specific key ring. Ring-specific checking has precedence over global profile checking. The method that is chosen must work with the methods of permitting and securing access to other key rings being used on your system. Because of the wide scope of coverage that global profile checking provides, ring-specific profile checking is typically the more appropriate method to use.

After the RACF key ring is set up and authorized, specify the RACF key ring name for the -K keyFile option and do not specify the -P keyFilePW option.

Using PKCS #11 tokens

The LDAP client supports the use of PKCS #11 tokens. 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. For information about using the gskkyman utility, see z/OS Cryptographic Services System SSL Programming. For information about using the RACDCERT command, see z/OS Security Server RACF Command Language Reference.

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.

SSL initialization failure

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.
Table 1. SSL failure reason codes.

list of SSL failure reason codes with three columns: Failure reason code, SSL return code, and Failure reason code description
Failure reason code SSL return code Failure reason code description
-1 402 No ciphers matched the server and client lists of acceptable ciphers
-2 403 No client certificate is to be used
-6 405 The certificate type is not supported
-10 406 I/O error communicating with peer application
-11 410 Incorrectly-formatted message received from peer application
-12 411 Message verification failed
-13 412 SSL protocol or certificate type is not supported
-14 413 Certificate signature is not correct for a certificate received from the peer
-15 414 Certificate is not valid
-16 415 Peer application has violated the SSL protocol
-17 416 Not authorized to access key database or SAF keyring
-18 417 Self-signed certificate cannot be validated
-20 4 Insufficient storage is available
-21 5 The environment or connection is not in the open state
-22 420 Socket closed by peer
-41 422 V3 cipher is not valid
-99 12 or any other unmapped SSL reason code Unrecognized error
-1000 none Failed loading SSL DLL
-1001 none Failed locating SSL function
1 102 Keyring I/O error
2 202 Keyring open error
4 408 Keyring password is incorrect
12 6, 407 Keyfile label is not valid or certificate is not trusted
106 106 Key database file is corrupted
109 109 Key database or SAF key ring does not contain any valid CA certificates
201 201 Key database password or stash filename not set
203 203 Unable to generate temporary RSA key
204 204 Key database password is expired
301 301 Close failed
302 302 Connection has an active write
401 401 Validity time period for the certificate has expired
427 427 Unable to access the LDAP directory
428 428 The client key did not contain a private key
431 431 Certificate has been revoked
432 432 Session renegotiation is not allowed
433 433 Key exceeds allowable export size
434 434 Certificate key is not compatible with the negotiated cipher suite
435 435 Missing CA certificate
436 436 CRL cannot be processed
437 437 A close notification alert has been sent for the connection
438 438 Internal error reported by remote partner
439 439 Unknown alert received from remote partner
500 500 TDES key parts are not unique
501 501 The buffer size is negative or zero
502 502 Operation would block
503 503 Read would be blocked
504 504 Write would be blocked
505 505 Record overflow
508 508 Key size is smaller than the minimum
602 602 Function identifier is not valid
701 701 Attribute ID is not valid
702 702 Attribute length is not valid
703 703 Attribute enumeration value is not valid
705 705 Attribute value is not valid
706 706 Attribute parameter value is not valid
10001 1 Environment or SSL handle not valid
10003 3 Internal SSL error
10007 7 No certificate received from partner
10008 8 Certificate validation error
10009 9 Error processing cryptography
10010 10 Error validating ASN.1 fields in certificate
10011 11 Error connecting to LDAP server
10103 103 The database is not a key database
53817447 53817447 The power-on known answer tests failed
53817451 53817451 The System SSL FIPS mode state cannot be changed to FIPS mode because it is not in FIPS mode
53817452 53817452 The request to execute in FIPS mode has failed because the Cryptographic Services Security Level 3 FMID is not installed so that the required System SSL DLLs could not be loaded
53817482 53817482 The power-on known answer tests failed. Either ISCF is not available or FIPS mode is disabled.
53817525 53817525 The System SSL FIPS mode LEVEL state cannot be changed to another FIPS mode LEVEL

Using environment variables to control SSL/TLS settings

The z/OS LDAP client utilities do not support SSL V2 protocol, and disable it from being used. SSL V3, TLS V1.0, TLS V1.1, TLS V1.2, Start of changeand TLS V1.3End of change protocols are supported. The z/OS System SSL defaults and environment variables control which of these supported protocols are enabled or disabled, and which cipher specifications apply. For example, the environment variable GSK_PROTOCOL_SSLV3 can be set to "ON" to enable SSL V3 protocol, or "OFF" to disable SSL V3 protocol. The environment variable GSK_PROTOCOL_TLSV1 can be set to "ON" to enable TLS V1.0 protocol, or "OFF" to disable TLS V1.0 protocol.

TLS V1.1, TLS V1.2, Start of changeand TLS V1.3End of change 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.
  • Start of changeSet GSK_PROTOCOL_TLSV1_3 "ON" to enable TLS V1.3 protocol.End of change
  • 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.
  • Start of changeTo 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.End of change
  • 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.