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.
- 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):
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.RDEFINE RDATALIB <ringowner>.<ringname>.LST UACC(NONE) PERMIT <userid>.<ringname>.LST CLASS(RDATALIB) ID(userid) ACCESS(READ)
- 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)
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.
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)
SETROPTS RACLIST(CRYPTOZ) REFRESH
-K *TOKEN*/NAME
Also,
do not specify the -P keyFilePW option when using a
PKCS #11 token.SSL initialization failure
ldap_ssl_client_init failed! rc == 113, failureReasonCode == 2
reason text: SSL initialization failed
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, and TLS V1.3 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.
- 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 theLDAP_SSL_CIPHER_FORMAT
environment variable toCHAR2
, 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 theLDAP_SSL_CIPHER_FORMAT
environment variable toCHAR4
.
- 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
- 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 theGSK_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 theLDAP_SSL_CIPHER_FORMAT
.