Setting up for SSL/TLS
- An SSL/TLS only secure connection. This connection requires that the first communication between the client and the server be the handshake that negotiates the secure communication. From that point on only secure communication can occur on the connection.
- A bimodal connection that supports secure and non-secure communication. The client is expected to begin communication in a non-secure mode. At some time during communication, the client might change to secure communication by sending a StartTLS extended operation after which the handshake to negotiate secure communication occurs followed by secure communication. The client might shut down secure communication causing a StopTLS alert to be sent and the server continues communication in a non-secure mode. At a later time, the client might restart secure communication by sending another StartTLS extended operation followed by the handshake.
Using SSL/TLS protected communications
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.
Creating and using key databases, key rings, or PKCS #11 tokens
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 RDATALIB <ringowner>.<ringname>.LST UACC(NONE)
PERMIT <LDAPSRV>.<ringname>.LST CLASS(RDATALIB) ID(LDAPSRV) ACCESS(READ)
ACCESS(READ)
should be specified if the
server certificate is owned by LDAPSRV
. Otherwise, ACCESS(UPDATE)
should be specified.SETROPTS RACLIST(RDATALIB) REFRESH
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(LDAPSRV) ACCESS(READ)
ACCESS(READ)
should be specified if the
server certificate is owned by LDAPSRV
. Otherwise, ACCESS(UPDATE)
should be specified.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.
NAME
is
the name of the PKCS #11 token).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)
Remember
to refresh RACF after doing
the authorizations.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.
Obtaining a certificate
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.
Enabling SSL/TLS support
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.
- 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.
- 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.
- Defining the FIPS mode that you want the server to run.
- Restart the LDAP server.
Setting up the security options for 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.
The z/OS LDAP server does not support SSL V2 protocol, and disables it from being used. SSL V3, TLS V1.0, TLS V1.1, and TLS V1.2 protocols are supported. The z/OS System SSL defaults and environment variables control which of these supported protocols are enabled or disabled. 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 and TLS V1.2 protocols are disabled by default. To enable TLS V1.1 protocol, set the environment variable GSK_PROTOCOL_TLSV1_1 to "ON". Similarly, to enable TLS V1.2 protocol, set the environment variable GSK_PROTOCOL_TLSV1_2 to "ON".
- C028 - 256-bit AES encryption with SHA-384 message authentication and ephemeral ECDH key exchange that is signed with an RSA certificate
- C027 - 128-bit AES encryption with SHA-256 message authentication and ephemeral ECDH key exchange that is signed with an RSA certificate
sslCipherSpecs GSK_V3_CIPHER_SPECS_EXPANDED
GSK_V3_CIPHER_SPECS_EXPANDED=C028C27
In some cases, other z/OS System SSL environment variables might define the SSL cipher specifications, such as GSK_SUITE_B_PROFILE described below. See Environment variables used by the LDAP server for more information on how to specify environment variables for the LDAP server.
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.
- listen
- sslAuth
- sslCertificate
- sslCipherSpecs
- sslFipsState
- sslKeyRingFile
- sslKeyRingFilePW
- sslKeyRingPWStashFile
- sslMapCertificate
- The replKeyRingFile and replKeyRingPW options are no longer necessary or recognized by the LDAP server. These options should be removed from the configuration file.
- The security, port, and securePort options are deprecated by the listen option. For more information, see the listen option.
- For secure only communication, specify one or more listen options for secure communications in the following format:
ldaps://[IP_address | hostname | INADDR_ANY | in6addr_any][:portNumber]
- For bimodal (non-secure/secure) communication, specify one or
more listen options for non-secure communications in the following
format:
ldap://[IP_address | hostname | INADDR_ANY | in6addr_any][:portNumber]
The sslKeyRingFile option specifies the name of the key
database, the RACF key ring,
or the PKCS #11 token that is 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 sslFipsState option indicates whether the LDAP server runs in FIPS mode during secure communication. Turning this option on specifies that the SSL connection between the LDAP server and the LDAP client is required to meet the FIPS 140-2 and SP800-131A criteria. In order to meet the FIPS 140-2 and SP800-131A criteria, when executing the FIPS mode, it is more restrictive with respect to cryptographic algorithms, protocols and key sizes that can be supported.
- OFF
- FIPS mode is off.
- LEVEL1
- Utilizes 80 bit security strength for all operations.
- LEVEL2
- Utilizes 112 bit security strength when generating new keys, digital signatures and RSA
encryption.Note:
LEVEL2
permits 80 bit security strength when performing digital signature verification and RSA decryption when processing previously protected information. - LEVEL3
- Enforces FIPS mode to SP800-131A. A security strength with a size of 112 bit or higher is acceptable for all operations, however, 80 bit is not allowed for any operation.
LEVEL1
through
LEVEL3
algorithm support.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 configuration option can be specified in "bit-mask" form to directly define the cipher specifications that are accepted from clients when using SSL/TLS secure connections. The "bit-mask" form is discouraged, as this method is limited in its support and provided solely for compatibility with earlier versions before z/OS V2R1. 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, as described earlier in this section.
Cipher | Decimal value | Hexadecimal value | SSL value | Description |
---|---|---|---|---|
ALL | 4294967295 | xFFFFFFFF | All cipher suites | |
ANY | 4294967295 | xFFFFFFFF | All cipher suites | |
DES_SHA_EXPORT | 512 | x00000200 | 09 | 56-bit DES encryption with SHA-1 message authentication and RSA key exchange |
DH_DSS_AES_128_SHA | 1048576 | x00100000 | 30 | 128-bit AES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSS certificate |
DH_DSS_AES_256_SHA | 65536 | x00010000 | 36 | 256-bit AES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSS certificate |
DH_DSS_DES_SHA | 128 | x00000080 | 0C | 56-bit DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSS certificate |
DH_DSS_TRIPLE_DES_SHA | 8 | x00000008 | 0D | 168-bit 3DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSS certificate |
DH_RSA_AES_128_SHA | 2097152 | x00200000 | 31 | 128-bit AES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with an RSA certificate |
DH_RSA_AES_256_SHA | 131072 | x00020000 | 37 | 256-bit AES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with an RSA certificate |
DH_RSA_DES_SHA | 64 | x00000040 | 0F | 56-bit DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with an RSA certificate |
DH_RSA_TRIPLE_DES_SHA | 4 | x00000004 | 10 | 168-bit 3DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with an RSA certificate |
DHE_DSS_AES_128_SHA | 4194304 | x00400000 | 32 | 128-bit AES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with a DSS certificate |
DHE_DSS_AES_256_SHA | 262144 | x00040000 | 38 | 256-bit AES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with a DSS certificate |
DHE_DSS_DES_SHA | 32 | x00000020 | 12 | 56-bit DES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with a DSS certificate |
DHE_DSS_TRIPLE_DES_SHA | 2 | x00000002 | 13 | 168-bit 3DES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with a DSS certificate |
DHE_RSA_AES_128_SHA | 8388608 | x00800000 | 33 | 128-bit AES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate |
DHE_RSA_AES_256_SHA | 524288 | x00080000 | 39 | 256-bit AES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate |
DHE_RSA_DES_SHA | 16 | x00000010 | 15 | 56-bit DES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate |
DHE_RSA_TRIPLE_DES_SHA | 1 | x00000001 | 16 | 168-bit 3DES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate |
RC2_MD5_EXPORT | 4096 | x00001000 | 06 | 40-bit RC2 encryption with MD5 message authentication and RSA key exchange |
RC4_MD5_EXPORT | 8192 | x00002000 | 03 | 40-bit RC4 encryption with MD5 message authentication and RSA key exchange |
RC4_MD5_US | 2048 | x00000800 | 04 | 128-bit RC4 encryption with MD5 message authentication and RSA key exchange |
RC4_SHA_US | 1024 | x00000400 | 05 | 128-bit RC4 encryption with SHA-1 message authentication and RSA key exchange |
RSA_AES_128_SHA | 16384 | x00004000 | 2F | 128-bit AES encryption with SHA-1 message authentication and RSA key exchange |
RSA_AES_256_SHA | 32768 | x00008000 | 35 | 256-bit AES encryption with SHA-1 message authentication and RSA key exchange |
TRIPLE_DES_SHA_US | 256 | x00000100 | 0A | 168-bit 3DES encryption with SHA-1 message authentication and RSA key exchange |
Setting up an LDAP client
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.
Using LDAP client APIs to access LDAP using SSL/TLS
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.
Support of certificate bind
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.