# FAQ: SSL Note: Cryptographic Hardware topics are largely covered [here](cryptohw.html). ## Certificate and certificate management FAQS ### Certificate and certificate management musgather / common problems See [gather_certificate_doc.htm](gather_certificate_doc.html) ### PKCS12 with IBM HTTP Server See [pkcs12.html](pkcs12.html) ### How can I summarize expiry info of many certificates? Future levels of IHS V8R0 and later, with GSKit 8.0.50.11 or later, will support `bin/gskcapicmd -cert -list -expiry` which will summarize the expiration of each personal certificate. ### How can I avoid putting the keystore password on the command line? While it does not appear in the usage, `bin/gskcapicmd` and `bin/gsk7capicmd` support a `-stashed` parameter in lieue of the password. This works at least with PM85211 and later (7.0.4.45, 8.0.14.27). ### Why doesn\'t an imported personal certificate show up with \"trust\" status? The tooling is in error, because trust status is never applicable to personal certificates (certificates with a private key). GSKit v8 will not show trust status on any personal certificates. ### Can IHS monitor certificate expiration? IHS 9.0 has rudimentary support for reporting soon-to-expire certificates ~at startup~. This reporting is to the error_log only. Information is available [here](https://publib.boulder.ibm.com/httpserv/manual24/mod/mod_ibm_ssl.html#sslcheckcertificateexpiration) Better monitoring is available Indirectly, when WAS manages the key store used by IHS. WAS provides monitoring of certificates and automatic renewal of self-signed certificates. To use this support, create an SSL-enabled virtual host from the WAS Admin console. You will have to propagate the updated keystore once after you create it, and subsequently when it is updated. There is a button to propagate the keystore in the console under \'Servers \> webserver1 \> Web server virtual hosts \> 1.2.3.4:443\' More information on certificate monitoring in WebSphere is available [here](http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-dist&topic=tsec_sslconfcertexpmon) By default, expiration info is written to the deployment managers SystemOut.log: ```text *** CERTIFICATES THAT ARE EXPIRED OR BEYOND THE EXPIRATION THRESHOLD AND HAVE BEEN REPLACED ***; CWPKI0645I: Personal certificate alias "selfSigned" in KeyStore "webserver1((cell):ndcell:(node):node1:(server):webserver1)" was REPLACED. ... *** CERTIFICATES THAT ARE EXPIRED OR BEYOND THE EXPIRATION THRESHOLD THAT CANNOT BE REPLACED BY THE SERVER ***; CWPKI0643I: Personal certificate alias "not-self-signed" in KeyStore "webserver1((cell):ndcell:(node):node1:(server):webserver1)" will expire on Aug 2, 2019. ``` ### Is some action required before January 2014 if 1024 bit certificates are in use? The nearly universal recommendation is to stop using 1024-bit RSA certificates. The NIST originally *recommended* a transition from 1024-bit by January 2011, and now recommends the same by January 2014. Many certificate authorities no longer issue 1024-bit certificates, and some go as far as to say that existing 1024-bit certificates will be revoked and/or otherwise not be acepted by browsers before January 2014. Consult your certificate authority of choice for more details on revocation/renewal. It\'s impossible to anticpiate when clients will begin warning about, or outright rejecting, 1024-bit certificates. There is however no good reason to stay on relatively weak keys. SSL Proxy FAQs ---------------------------------------- ### SSLProxyEngine failure IHS 8.0 and later proxy to any TLS1.2-enabled server (incl IHS 8.0 and later) with a legacy certificate may fai. GSKit trace on the server reports \"No matching alg for certificate\". If the backend is IHS, it reports SSL0224E. See [errorlog.html\#SSL0266E](errorlog.html#SSL0266E) ## SSL Protocol FAQs ### Does IHS support FFDHE ciphers or key exchange No, FFDHE key exchange nor ciphers are not supported. IHS supports only RSA and ECDHE key exchange. TLS 1.3 requires clients to support ECDHE key exchange. ### Is IHS affected by ROBOT? ROBOT is a vulnerability in implementations of RSA key exhcange in SSL. It was disclosed in 2018 and quickly fixed by affected implementations. IHS 8.5 and 9.0 were never affected. Unfortunately, some scare-mongering SSL scanners will report that any configuration that uses RSA key exchange based ciphers is "vulnerable to ROBOT". Disabling RSA key exchange ciphers is considered low risk for compatibility, but not zero-risk. Note: RSA ciphers are disabled by default on most systems by PH51473. To silence reports of ROBOT vulnerabilities in IHS, do all the following: 1. Remove `SSLCipherSpec` directives that explicitly enable RSA key exchange ciphers. 2. In fix packs 8.5.5.19-8.5.5.23 and 9.0.5.7-9.0.5.14 add `SSLCipherSpec ALL -RSA` to each virtual host with `SSLEnable` 3. In fix packs prior to 8.5.5.19 and 9.0.5.7, a lengthy recipe is here: [ECDHE/RSA Cipher Configurations](#ECDHE_CONFIG) ### TLS1.3-specific issues - Configurations with `SSLFIPSEnable` and 9.0.5.2 are later are likely to fail with `SSL0232W`. Several workarounds are available: - Add `SSLAttributeSet 2006 "GSK_TLS_SUPPORTED_GROUP_ECDHE_SECP256R1, GSK_TLS_SUPPORTED_GROUP_ECDHE_SECP384R1" BUFF` after each use of `SSLFIPSEnable`. - Disable TLSv1.3 with `SSLProtocolDisable` - Comment out `SSLFIPSEnable` - PH21804 issues - In 9.0.5.2 and 9.0.5.3 handshakes with ECDSA certificates may fail with `SSL0200E: SSL Handshake Failed: (454)GSK_ERROR_ILLEGAL_PARAMETER.` - In 9.0.5.2 and 9.0.5.3 handshakes may fail with SSL0212E during TLS13 session resumption - 403 errors with TLS client authentication: For clients that enable the post_handshake_auth extension, TLS client authentication does not currently work with TLS13 in IHS. - Java 6 and IE11 cannot handshake with IHS when TLS13 is enabled. IE11 uses an "SSLv2 Client Hello" which is not supported in IHS while TLsv13 is enabled. - [SSL0230I with legacy clients](ssl_questions#SSL0230I) - z/Linux can fail with SSL0209E before PH39992 (9.0.5.10) - On z/OS, some certificates may fail with SSL0283E or SSL0212E under TLSv1.3, see - DSA or DH keys - RSA keys less than 2048 bits long - If the certificate to be used for the TLS connection is of type RSA with its private key stored in the PKDS and was created or added to the RACF database prior to z/OS V2R4, the certificate will not be usable for TLS 1.3 connections. The RSA key needs to be protected using the ECC master key. ### Is there an equivalent of mod\_ssl\'s SSLHonorcipherorder? No, IHS always uses the servers preference acts like `SSLHonorcipherorder on` ### Does IHS support TLS\_FALLBACK\_SCSV? IHS supports and sends TLS\_FALLBACK\_SCSV by default after PI52299 (8.5.5.9, 8.0.0.13) on distributed platforms. ### Does IHS allow user configurable DHE parameters? No, IHS only supports DHE with Elliptic Curve, and for EC in IHS GSKit only allows the use of the NIST Prime Elliptic Curves P256, P384 and P521. No user selectable parameters are allowed. GSKit selects a Curve to be Greater than or Equal to the CipherSuite Strength e.g. for a TLS\_ECDHE\_ECDSA\_WITH\_SHA256 CipherSuite curve P256 or higher can be used and for TLS\_ECDHE\_ECDSA\_WITH\_SHA384 curve P384 or higher can be used. ### Does IHS use RSA\'s Dual Elliptic Curve Deterministic Random Bit Generation (DRBG) ? No, the Dual-EC DRBG algorithm has never been implemented by IHS. ### Can I prevent IHS from sending the root certificate in the handshake? With GSKit 7.0.4.37 / 8.0.14.12 or later, this setting in IHS will disable sending the root certificate. This is needed by some older android clients. PM66218 or later has the necessary GSKit. `SSLAttributeSet 462 1` ### Can I prevent SSLProxyEngine from using an \"SSLv2 compatible hello/open\"? In 8.0 and later on distributed only: `SSLAttributeSet proxy:439 0 ENUM` ### Can the SSL proxy protocols be limited or changed? The proxy supports all protocols unless they\'re disabled with SSLProtocolDisable. The set cannot be controlled separately from the supported frontend protocols. - As of the java that accompanies 7.0.0.23, ikeyman can create certificates with a public key sizes up to 4096 bits. - In the level of GSKit bundled with 7.0.0.0 and later, `gsk7capicmd/gskcapicmd` can create certificates with 4096 bit keys - With IBM HTTP Server 8.0 and later, ikeyman, gskcmd, and gskcapicmd can create 4096-bit keys. - mod\_ibm\_ssl can use certificates with public keys up to 4096 bits ### How can I require SHA2 ciphers? By default, IHS 8.0 and later prefers SHA2 over TLS1.2, but will negotiate older ciphers and protocols. To completely block all connections that come in without SHA2 over TLS1.2, replace any `SSLProtocol` or `SSLCipherSpec` cusotmizations with a derivative of the examples below. This configuration should come after existing `SSLEnable` directives. ```apache # SHA2-only, no ECDHE SSLProtocolDisable TLSv10 TLSv11 SSLCipherSpec TLSv12 TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA256 ``` ```apache # SHA2-only w/ ECDHE preferred SSLProtocolDisable TLSv10 TLSv11 SSLCipherSpec TLSV12 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 SSLCipherSpec TLSv12 +TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA256 ``` ### Does IHS support perfect forward secrecy (PFS)? 9.0.0.0/8.5.5.12 and later _support_ ECDHE ciphers which provide perfect forward secrecy (PFS). These ciphers are are enabled and preferred by default on distributed platforms. Ciphers with RSA key exchange, known as "non-PFS" or "static key ciphers" are supported/tolerated i but not preferred. #### V9 / 8.5 post-PI81589 ECDHE cipher manipulation examples

In Version 9 and later, or in 8.5.5 after PI81589, ECDHE is enabled by default and preferred over RSA. You may wish to disable non-PFS ciphers (RSA), prefer RSA over ECDHE, or disable ECDHE. Example config changes follow, choose 1 stanza depending on your requirements. # Example 1: Require ECDHE (PFS)/ disable RSA (non-PFS) ## Remove default RSA key exchange ciphers SSLCipherSpec ALL -9C -9D -3C -3D -2F -35B ## PH30598: In 8.5.5.19/9.0.5.7 and later, you can just use: ## SSLCipherSpec ALL -RSA # Example 2: Disable ECDHE (PFS) including ALL TLSv13. This should only be done if you have some kind of rare # incompatibility or performance issue. SSLCipherSpec ALL 9C 9D 3C 3D 2F 35B # Example 3: Prefer RSA over ECDHE. See caveat about example #2. ## Step 1: Remove the defaults SSLCipherSpec ALL -TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 -TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 -TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 SSLCipherSpec ALL -TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 -TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA -TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA -TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA SSLCipherSpec ALL -TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 -TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 SSLCipherSpec ALL -TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 -TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 SSLCipherSpec ALL -TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA -TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA -TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ## Step 2: Append the same ECDHE ciphers SSLCipherSpec ALL +TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 +TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 +TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 SSLCipherSpec ALL +TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 +TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA +TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA +TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA SSLCipherSpec ALL +TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 +TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 SSLCipherSpec ALL +TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 +TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 SSLCipherSpec ALL +TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA +TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA +TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ### Does IHS support DSA certificates? IHS only supports RSA\_RSA, ECDHE\_RSA, and ECDHE\_ECDSA and no other combinations (such as those including DH or DSA). The Java key management utility, keytool, will create DSA certificates by default, see the JSSE FAQ for more info. ### What restrictions are placed on ikeyman passwords? - Passwords can contain up to 127 (single byte) characters and may not contain an embedded ASCII NUL. If a multi-byte character set is used, the limit is 127 *bytes*. - Versions of ikeyman prior to 7.0.3.25 allow access to KDB files as long as the first N characters of password input match the entire password used when the KDB was created. In other words, a database protected with the password \"test\" can be accessed with a password of \"test123\" (but not \"tes\"). This is irrespective of the level of ikeyman used to create the KDB. - KDB files containing private keys should be treated as highly confidential. ### How can I disable support for NULL / Plaintext ciphers? These have been disabled by default since 6.1.0.0. ### How can I disable support for SSLv2? - In IHS 8.0 and higher, the SSLv2 protocol is disabled by default. SSLv2 can be re-enabled by specifying any SSLv2 ciphers with `SSLCipherSpec`. Don\'t do this. ### Is SSLProtocolDisable negated if a SSLCipherSpec is declared for a cipher within the protocol being disabled? For example: ```apache SSLProtocolDisable SSLv2 SSLCipherSpec ALL 21 ``` The `SSLProtocolDisable` directive supercedes the selecting of the ciphers. It is applied \'after\' cipher selection, so it is not negated by specifying a cipher within the protocol to be disabled. ### How does IHS use the `close_notify` SSL alert? IHS does not initiate a `close_notify` alert during the shutdown of a connection, but will respond to a client\'s `close_notify` with one of its own. This behavior is not configurable. In some non-keepalive cases, IHS cannot respond to a `close_notify` alert because IHS has already shutdown the connection for writing, which will send a FIN to the client. In this case, the client must react to the FIN instead of wait for a response to the `close_notify`. Some non-browser clients (observed with an F5 load balancer) might not close their end of the connection when the FIN is sent from IHS but instead wait for a `close_notify` alert. This can cause an accumulation of sockets in [FIN\_WAIT\_2](ihs_performance.html#FINWAIT2) on the IHS system. No response of any type can be sent after the FIN, so the client should not wait for the `close_notify`. ### How can I test if my server supports a specific SSL protocol? Two common command line tools can help you test which SSL protocols your server is configured to use. ##### openssl If a protocol is enabled, the `openssl s_client` command will wait for input (or Control-D). If the protocol is disabled, openssl will report an exception similiar to the one reproduced below: 21112:error:1407F0E5:SSL routines:SSL2\_WRITE:ssl handshake failure:s2\_pkt.c:428: Examples: ```text openssl s_client -connect ihshostname:443 -ssl2 openssl s_client -connect ihshostname:443 -ssl3 openssl s_client -connect ihshostname:443 -tls1 ``` ##### curl If a protocol is enabled, curl will display the URL as requested. If the protocol is disabled, will report an error message similiar to the one reproduced below: ```text curl: (35) Unknown SSL protocol error in connection to ihshostname:443 ``` Examples: ```text curl -vk -2 https://ihshostname curl -vk -3 https://ihshostname # -1 tests for TLSv1 curl -vk -1 https://ihshostname ``` ### What is the behavior of using \'ALL\' for the protocol\_name argument of the SSLCipherSpec directive? In IHS 8.0 and higher, there is a new multi-argument form of the `SSLCipherSpec` directive which takes a `protocol_name` value as the first argument.\ You can specify the name of an SSL protocol (or \'`ALL`\') as the value of this argument.\ *For more information, refer to the \'SSL Directives\' section of the Information Center documentation for your version of IBM HTTP Server.* Using the new syntax with \'`ALL`\' followed by a single cipher is similar to leaving off \'`ALL`\' and using the legacy syntax. Both of \"`SSLCipherSpec 3A`\" and \"`SSLCipherSpec ALL 3A`\" resets all protocols which 3A supports (SSLV3, TLSV10, TLSv11, TLSv12) to zero ciphers, then adds 3A. For TLSv12, this results in turning off the most advanced ciphers. This is why we are emphasizing the importance of the protocol\_name argument in the V8.0 and higher syntax. ### How do I enable strong encryption on z/OS? Strong encryption (128-bit and above) is available when the \"z/OS Security Level 3\" unpriced optional feature has been installed. Without this feature, IHS is limited to the RSA ciphers listed in Table 1 of the System SSL Programming guide. ### What's required for TLSv1.3 support? IHS 9.0.5.2 or later adds TLSv1.3 support and enables it by default. On z/OS, z/OS 2.4 or later is additionally required. ### Does IHS support TLSv1.1 or later? IHS 7.0 (and earlier) cannot negotiate TLSv1.1 or TLSv1.2 connections. IBM HTTP Server 8.0 and later supports TLSv1.1 and TLSv1.2 whenever SSL is enabled. Prior to PI27904, IHS on z/OS required TLSv1.1 and TLSv1.2 be explicitly enabled. ### Does IHS support TLS Server Name Indication (SNI)? Server Name Indication (SNI) is supported in IHS 9.0 and later. IHS uses SNI for inbound connections only, to map the hostname in the SNI extension to a certificate label. Outbound SSL connections via the WAS Plug-in or mod\_proxy (w/ SSLProxyEngine ON) do not send an SNI extension. For some basic configurations, an SNI extension can be added to outbound mod\_proxy traffic with the following recipe (only example.com varies) ``` SSLProxyEngine ON ProxyPass ... ... SSLAttributeSet proxy:230 example.com BUFFNULL # Or as described below, sometimes ... # SSLAttributeSet proxy:230 my-backend-service.myproj.example.com BUFFNULL ``` Setting the SNI extension to a value other than the incoming Host: header is a violation of a "SHOULD" specification requirement, but there are environments where this is the only feasible option. For example, if the backend connection goes to an HAProxy instance doing TLS Passthrough and selecting a backend based on the SNI hostname, those backends are unlikely to identify themselves with a frontend host like "example.com" and moreso with something esoteric like myservicename.project.example.com. This requires SNI to be set to something that would not be suitable for the Host: header, since it would result in redirects and self-referential links to the backend service name. ### Does IHS support signed OCSP requests? No. ### Does IHS support OCSP Stapling? No. ### Does IHS support SSL Renegotiation? Insecure renegotiation is rejected by default in V8R0 and all later releases. ```text IHS Version Renegotiation behavior IHS 6.1.0.27 / 6.0.2.37 / 7.0.0.7 and earlier legacy renegotiation enabled by default. IHS 6.1.0.29 / 6.0.2.39 / 7.0.0.9 and later legacy renegotiation disabled by default. ``` ### Does IHS support TLS Renegotiation Indication (RFC 5746)? Secure renegotiation is advertised/signaled in V8R0 and all later releases. All maintenance levels except 8.0.0.0 reject any secure reneogtiation request that actually occurs. The signalling/advertising is necessary to protect against the "triple handshake attack" that RFC 5746 secure renegotiation was created to address, even when no intentional renegotiation will occur. ```text IHS Version RFC5746 behavior ------------------------- --------------------------------------------------- IHS 7.0 and earlier Not supported IHS 7.0.0.19 / 6.1.0.41 Supported, signaled but *not* accepted by default IHS 8.0.0.0 Supported, signaled, and accepted by default IHS 8.0.0.1 and later Supported, signaled but *not* accepted by default ``` ### Does IHS support TLS compression / SSL Compression? - IHS 7.0 and earlier do not support TLS compression. - IHS 8.0.0.5, 8.5.0.1, and later fixpacks and releases support TLS compression but it is disabled by default. Use SSLCompression directive to re-enable (distributed only) ### Does IHS support ECC certificates? Only in V8R0 and later with PM80235. The only supported curves are secp256r1, secp384r1, and secp521r1 (RFC4492 names). ### What are the ramifications of using large (2048-bit) RSA keys? When the key size doubles, the CPU overhead of a *full* SSL handshake can increase by 8-12 times. Abbreviated (reused) handshakes are not affected by the change in key size. As SSL *handshakes* (as opposed to block/bulk encryption or other processing overhead) can account for almost none, or almost all, of your overall CPU usage, it is critical to performance tests new certificates which contain larger keypairs under realistic workloads to determine the net change in CPU usage. ### Can IHS use SHA-2 (sha224, sha256, sha384, sha512) digest algorithms? #### SSL Ciphers SHA-2 based SSL ciphers are supported and used by default in IHS 8.0 and later. They\'re not supported in older releases. #### Certificate signature algorithms IHS 7 and all later fixpacks and releases supports SHA-2 certificates at runtime and *in one or more* included certificate management tools. #### Runtime issues - IHS 7.0.0.0 and all later fixpacks and releases can use and/or validate SHA-2 *certificate signatures* at runtime. Beyond obtaining a certificate / certificate chain that uses SHA-2, no further setup or configuration (the `KeyFile` directive in httpd.conf points to the location of the currently configured CMS (\*.kdb) key store). - IBM HTTP Server 8.0.0.0 and all later fixpacks and releases can use SSL *ciphers* that use a SHA-2 based digest, since such ciphers are valid only in TLSv1.2 which is not supported by GSKit 7 used in prior IHS releases. While SHA-2 ciphers are important, they aren\'t related to \"SHA-2 transition\" occuring with browser vendors and the certificate authorities. #### Detailed Certificate management issues - IHS 7.0.0.0 supports command-line SHA-2 management with Ikeyman/gskcmd at any maintenance level. IHS 7.0.0.11 adds command-line SHA-2 management with `gsk7capicmd`. - IHS 8.0.0.0 and all later fixpacks and releases supports SHA-2 certificate management with `gskcapicmd` and Ikeyman/gskcmd at any maintenance level. #### Related information about advanced certificate management functionality: - Support using SHA-2 for certificate includes signing requests (CSR) and self-signed certificates. Note that the algorithm used in the CSR does not directly influence the algorithm used in the resulting certificate chain. - The WebSphere Administration Console certificate management panels can create SHA-2 CSR\'s and self-signed certificates after PM48805 (7.0.0.23, 8.0.0.3, and 8.5.5.0 and later). - Ikeyman versions since 8.0.383 added support for additional elliptic curve signature algorithms: **SHA2WithECDSA** (i.e. SHA256), **SHA3WithECDSA** (i.e. SHA384), and **SHA5WithECDSA** (i.e. SHA512) when creating certificate signing requests or self-signed certificates. Earlier versions of Ikeyman can be updated by updating the Java installed with IHS. Ikeyman 8.0.383 started shipping with Java versions: IBM Java 7.1 sr1, Java 7.0sr7, Java 6.26sr1fp8, Java 6.0sr15fp2. Applying a WASSDK interim fix that contains Java at these versions or newer as appropriate for your version of IHS (example: PI14303 or PI14305) over your IHS installation will update the Java (and Ikeyman) in IHS. ### Do the Triple DES ciphers in IHS use two or three independent keys? Triple DES comes in a 2-key and 3-key form, but the cipher as defined in SSL/TLS is always of the 3-key form (generally assesed at a strength of 112 bits, vs. 80 for 2-key). Why doesn\'t the above paragraph say 168 bit? We\'re not cryptographers, but the effective and actual number of bits in a cryptographic algorithm differ. ### What ciphers does IBM recommend? IBM support cannot make this kind of recommendation tailored to any particular use case or deployment. Beginning in 8.0, IHS defaults evolve throughout the maintenance stream to exclude exceptionally weak ciphers and protocols. These defaults can be augmented with `SSLCipherSpec` and `SSLProtocolDisable`. - SSLv2 was disabled by default in 8.0.0.0 and all future releases. - SSLv3 was disabled by default in 8.0.0.10, 8.5.5.4, and 9.0.0.0 - NULL and export SSL ciphers were disabled by default in 8.0.0.0 and all future releases. - NULL and export SSL ciphers were disabled by default in 8.0.0.0 and all future releases. - RC4 ciphers were disabled by default in 8.0.0.11, 8.5.5.6, and 9.0.0.0 - 3DES ciphers were disabled by default in 8.0.0.15, 8.5.5.13, and 9.0.0.5 For detailed information about cipher available and defaults, consult the `SSL cipher specifications` topic in the corresponding release of the knowledge center. - [9.0](https://www.ibm.com/support/knowledgecenter/en/SSEQTJ_9.0.5/com.ibm.websphere.ihs.doc/ihs/rihs_ciphspec.html) - [8.5](https://www.ibm.com/support/knowledgecenter/en/SSEQTJ_8.5.5/com.ibm.websphere.ihs.doc/ihs/rihs_ciphspec.html) ### Note about older releases Releases prior to 8.0 do not support TLS 1.2 or ECDHE and cannot be recommended for any use. ### z/OS specific notes - Prior to V9, ECDHE\_RSA and GCM/SHA2 RSA ciphers need to be explicitly enabled. They depend on some external ICSF setup. - In 9.0.0.0 and later, these ciphers are enabled automatically if ICSF appears to be available at startup. However this detection may result in a false positive. ### How can I resolve a \"CBC\" vulnerability reported by a security scanner? Simply put, you can\'t even begin to address a generically stated \"CBC\" problem without more specifics (such as a CVE number). If a scanner reports some problem with a \"CBC\" cipher enabled, they could be referring to any one of a number of historic or contemporary issues with different actions required. - CVE-2011-3389 (BEAST) In 2011 and early 2012, the remediation was to enable RC4. Since 2014, the consensus is that RC4 is too weak and browser circumventions for this vulnerability are sufficient. - CVE-2014-3566 (POODLE SSLv3) The consensus is to disable SSLv3 as the problem cannot be corrected in SSLv3 - CVE-2014-8730 (POODLE TLS) This requires corrective maintenance if your server is affected (PI31516 for IHS) - If a scanner reports that IHS *may* be vulnerable to `Golden Poodle` or `Zombie Poodle` solely because it supports CBC ciphers, no maintenance is required as this scanner is not even suggesting it has scanned for vulnerable implementations. The only action required is to evaluate any non-default `SSLCipherSpec` configuration to ensure GCM-based ciphers are preferred over CBC-based ciphers. - At this time, GSKit is not known to be vulnerable to this weakness/attack. - The online scanner at https://www.ssllabs.com/ has the ability to detect vulnerable implementations and does not report GSKit as vulnerable. - IHS already prefers the few non-CBC ciphers available in TLS1.2. - To the extent that any client negotiates CBC ciphers today, which are not vulnerable to these named attacks, their handshakes would fail if CBC ciphers were removed. ### How can I disable CBC ciphers to protect unmaintained clients from BEAST (CVE-2011-3389) or to satisfy my security scanner? We do not recommend taking BEAST countermeasures (disabling CBC ciphers) on the server. When BEAST was first disclosed in 2011, the short-term remediation was disabling all CBC ciphers. In TLS1.0, the highest protocol with broad browser support, all ciphers except for RC4 are CBC ciphers. Fast-forward to 2014, and browsers have long since had BEAST circumventions and RC4 is considered too weak for sites requiring even moderate levels of TLS security. References: - Proposed retroactive RC4 removal from TLS 1.0: https://tools.ietf.org/html/rfc7465 - TLS Best Practices doc from Ivan Ristic / Qualsys SSL labs as of 12/2014 says: > RC4 is weaker than previously thought. You should remove support > for this cipher as soon as possible, but after checking for > potential negative interoperability impact. ### How can I check the end result of my SSL configuration changes to verify what prototcols and ciphers my server will use ? In IHS 8.0 and later *(not available until 8.0.0.12 / 8.5.5.8 via PI47605 for the Windows version of IHS)*: If there is a question of how your configuration customizations are ultimately combined, you can run the following command to see the effective values after processing the configuration: ```apache /path/to/IHS/bin/apachectl -t -DDUMP_SSL_CONFIG {for non-Windows versions) C:\path\to\IHS\bin\apache -t -DDUMP_SSL_CONFIG {for Windows version} Example output of the default configuration + SSLEnable is: SSL server defined at: /home/ihs/2.2/built/conf/httpd.conf:907 Server name: 127.0.1.1:443 SSL enabled: YES FIPS enabled: 0 Keyfile: /home/ihs/IHSJTest/data/ihskeys/key.kdb Protocols enabled: SSLV2,SSLV3,TLSv10,TLSv11,TLSv12 Ciphers for SSLV2: (defaults) Ciphers for SSLV3: (defaults) TLS_RSA_WITH_AES_128_CBC_SHA(2F),TLS_RSA_WITH_AES_256_CBC_SHA(35b),SSL_RSA_WITH_RC4_128_SHA(35),SSL_RSA_WITH_RC4_128_MD5(34) Ciphers for TLSv10: (defaults) TLS_RSA_WITH_AES_128_CBC_SHA(2F),TLS_RSA_WITH_AES_256_CBC_SHA(35b),SSL_RSA_WITH_RC4_128_SHA(35),SSL_RSA_WITH_RC4_128_MD5(34) Ciphers for TLSv11: (defaults) TLS_RSA_WITH_AES_128_CBC_SHA(2F),TLS_RSA_WITH_AES_256_CBC_SHA(35b),SSL_RSA_WITH_RC4_128_SHA(35),SSL_RSA_WITH_RC4_128_MD5(34) Ciphers for TLSv12: (defaults) TLS_RSA_WITH_AES_128_GCM_SHA256(9C),TLS_RSA_WITH_AES_256_GCM_SHA384(9D),TLS_RSA_WITH_AES_128_CBC_SHA256(3C),TLS_RSA_WITH_AES_256_CBC_SHA256(3D),TLS_RSA_WITH_AES_128_CBC_SHA(2F),TLS_RSA_WITH_AES_256_CBC_SHA(35b) (Note: we report SSLv2 as enabled with zero available ciphers as an implementation quirk) ``` ## General SSL FAQs ### Does IHS generate unique session identifiers with a FIPS 140-2 approved random number generator? The only session identifier generated by IHS is an SSL Session ID. It uses a FIPS 140-2 approved random number generator regardless of the setting of `SSLFIPSEnable`. ### How can I implement HTTP Public Key Pinning (HPKP) with IHS? You can manually set the \"Public-Key-Pins\" header with IHS (as with other webservers), but if you\'re following instructions meant for Apache+OpenSSL you\'d have to start by using ikeyman, gskcmd, or gskcapicmd to extract the certificates for which you\'d like to send a PIN. Once you have the certificates saved to a flat file, the openssl command line utility can be used to generate the pin-sha256 value. It\'s imperative that you learn about the meaning and repercussions of HPKP before performing this setup, and that you integrate HPKP changes into your procedure for certificate changes. A sample java program that obtains `pin-sha256` values from an IBM CMS \*.kdb key store is available here: ### Does IHS support HSTS / strict transport security? See [questions.html\#HSTS](questions.html#HSTS) ### Does IHS support AES-NI acceletion? IHS 8.0 and later support AES-NI acceleration when the non-FIPS ICC library in GSKit is used. This can be enabled by setting `export ICC_IGNORE_FIPS=YES` in \$IHSROOT/bin/envvars and doing a full stop and start. AES-NI is implicitly ICC\_IGNORE\_FIPS is not be required after PI09443 (8.0.0.9, 8.5.5.2) which is available as a published interim fix. ### mod\_rewrite: How can I redirect all non-SSL requests to SSL? Here is an example where all requests received on port 80 are redirected to the SSL port. Replace *www.example.com* with the hostname of your server. The new VirtualHost container will automatically apply to any requests received on the specified port (80), and mod\_rewrite will always redirect these requests to the https (SSL) equivalent. ```apache RewriteEngine on RewriteRule ^/(.*) https://%{HTTP_HOST}/$1 [R,L] ``` *Important:* If using HTTP authentication, make sure it is only configured for your SSL virtual host. If it also applies to your port 80 requests, the authentication challenge can pre-empt the rewrite, resulting in userids and passwords being sent over an unencrypted session. It is also recommended that you configure your port 80 virtual host with a different document root etc. from your SSL virtual host. This is to be sure that even if your rewrite fails, sensitive information cannot be served from that virtual host over unencrypted sessions. ### Why can\'t root install GSKit on solaris? See [questions.html\#gskitinstall](questions.html#gskitinstall) ### How many SSL Session IDs can IHS cache? See [SSL Tuning](ihs_performance.html#SIDCACHELIMIT) ### What is the SSL Session ID Cache? Negotiating new SSL sessions can be costly in terms of CPU usage and latency. A previously negotiated SSL session can be be reused by a client, but this requires some state to be saved by the server. Because IHS is multi-process and a new connection can be handled by a different process then where the previous handshake occurred, IHS uses a cross-process session cache (sidd). This replaces the built-in per-process session cache used by GSKit. #### Timeout details The validity period of the cached SSL session _is not_ reset when an SSL session is reused. This is true of both the external session cache (sidd) and the internal GSKit session cache. Note: In 8.5.5.9 (but _not_ later fixpacks) the time _is_ reset when an SSL session is reused. #### Disabling session caching Setting `SSLV3Timeout 0` disables session caching in both the cross-process `sidd` cache and the internal SSL session cache. This can be appended to httpd.conf and need not be copied to each virtual host. #### WAS Plugin The WAS Plugin automatically attempts to reuse SSL sessions with WAS in 8.5.5.4/9.0.0.0 and later. This can be disabled on the Plugin (client) side by setting native environment variable `GSK_V3_SIDCACHE_SIZE` to the value `0`. ### How can I require SSL client certificates (mutual SSL authentication) only on some URLs in a VirtualHost? This cannot be easily accomplished because there is no support for telling the web browser to "try again with a client certificate". The following recipe is one way to simulate this behavior without using an additional virtual host, which would involve redirecting select URLs to the alternate virtual host. 1. Set `SSLClientAuth optional` in your virtual host 2. Use mod\_rewrite to check one of the SSL client certificate environment variables: RewriteEngine on RewriteCond %{ENV:SSL_CLIENT_CERTBODYLEN} ^$ RewriteCond %{REQUEST_URI} !^/error/ RewriteRule /secure/ /certrequired.html [PT] 3. Provide an HTML page (`/certrequired.html` in the previous step) describing what your users need to do get a certificate. Note that users would probably have to close and reopen their web browser before they\'d be able to select a client certificate, which can only happen at the beginning of a new handshake. ### How can I require a specific SSL Client certificate by serial number? - In maintenance levels with PM87247, consider using a certificate fingerprint instead. - In maintenance levels with PM87247, SERIALNUMBER/SN can be used in `SSLClientAuthRequire` - In maintenance levels without PM87247: ```apache SSLEnable SSLCLientAuth REQUIRED_RESET # A more robust serial number based check would also evaluate the issuer details RewriteEngine on RewriteCond %{ENV:SSL_CLIENT_SERIALNUM} !=00:8a:c9:f6:6c:72:95:49:4d RewriteRule ^/secret/ - [F] ... ``` - If you want to provide a custom error page, see the preceding FAQ. ### Why must IP-based virtual hosting be used when multiple SSL virtual hosts are supported? In releases prior to 9.0, IHS cannot choose a certificate or ciphers based on name-based virtual host configuration. In 9.0 and later, IHS can choose an alternate SSL certificate label based on the requested hostname. This technote describes the configuration requirements: [SSL Technote](http://www-1.ibm.com/support/docview.wss?rs=177&uid=swg21045922) ### How can the other SSL access control directives be used to limit access? #### Per-directory SSL access control directives `SSLVersion` allows access control to occur based on the SSL Protocol (SSLv2, SSLv3, TLSv1) the client and server negotiated during the handshake, and can be used in a per-directory context (\, \). `SSLCipherBan` and `SSLCipherRequire` operate in the same fashion as `SSLVersion`, but they look at the individual SSL cipher that was previously negotiated. The restrictions configured with `SSLCipherBan`, `SSLCipherRequire`, and`SSLVersion` do not influence the actual SSL ndshake and are only checked later on during request processing. No renegotiation is triggered by these directives, and instead the configured 403 error response is issued at the application level. This response may be difficult to distinguish from 403 errors triggered other authorization or access control directives. Because of the limitations of SSLCipherBan, SSLCipherRequire, and SSLVersion, [using mod\_rewrite to analyze the [SSL vironment riables](http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/topic/com.ibm.websphere.ihs.doc/info/ihs/ihs/cihs_envvar.html) TTPS\_CIPHER, SSL\_PROTOCOL\_VERSION, HTTPS\_KEYSIZE) is much more exible. #### per-vhost SSL handshake directives `SSLCipherSpec` and `SSLProtocolDisable` influence the SSL handshake self, and as a consequence are only available in a per-vhost basis. ile it's normally safe to limit cipher support to [128-bit or gher ciphers](ihs_performance.html#SSL) or to disable SSLv2, we do t recommend restricting access much further than this with `SLCipherSpec` and `SSLProtocolDisable`. Instead, use mod\_rewrite as lustrated above to enforce more restrictive access control; otherwise S and the browser may not be able to negotiate a secure channel and users may not see a descriptive error message from their browser. : ### How can I display a custom document when a client connects with a weak cipher?] Configure your server to prefer stronger ciphers as described in the [SSL Performance](ihs_performance.html#SSL) section of the [IHS Performance tuning](ihs_performance.html) guide. Append any weak ciphers you wish to support ([list of ciphers](http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.ihs.doc/info/ihs/ihs/rihs_v3ciphspec.html)) using `SSLCipherSpec` Determine the SSL criteria you want to enforce (e.g. keysize, protocol version) and the set of URLs for which it applies. ```apache RewriteEngine On RewriteCond %{ENV:HTTPS_KEYSIZE} !^(128|168|256)$ RewriteCond %{REQUEST_URI} !^/error/ RewriteRule ^/secret3/ /128_or_higher.html ``` ### How can I see which cipher specification was negotiated for a specific request? #### In the access log: Change the LogFormat directive to include the cipher specification as part of the information logged for each request. The format string `%{HTTPS_CIPHER}e` will log the name of the cipher (e.g, `TLS_RSA_WITH_AES_256_CBC_SHA`). Ensure that the LogFormat directive which is changed is for the format used on the CustomLog directive. ```apache LogFormat "%h %l %u %t \"%r\" %\>s %b %{HTTPS_CIPHER}e" common CustomLog logs/access_log common ``` ```text 9.48.108.152 - - [17/Feb/2005:15:37:39 -0500] "GET / HTTP/1.1" 200 1507 SSL_RSA_WITH_RC4_128_SHA 9.48.108.152 - - [17/Feb/2005:15:37:40 -0500] "GET /httpTech.view1.gif HTTP/1.1" 200 1814 SSL_RSA_WITH_RC4_128_SHA 9.48.108.152 - - [17/Feb/2005:15:37:40 -0500] "GET /httpTech.masthead.gif HTTP/1.1" 200 11844 SSL_RSA_WITH_RC4_128_SHA 9.48.108.152 - - [17/Feb/2005:15:37:41 -0500] "GET /httpTech.visit1.gif HTTP/1.1" 200 1457 SSL_RSA_WITH_RC4_128_SHA ``` For non-secure requests, \"-\" will be logged for the cipher specification. #### With Wireshark Wireshark will show the negotiated cipher in the "Server Hello" message. ### How can I perform access control with details from the SSL client certificate? mod\_ibm\_ssl provides a set of access control directives that can be difficult to use (SSLClientAuthRequire, SSLClientAuthGroup). Instead, we recommend using mod\_rewrite to inspect the SSL Client Certificate environment variables for access control. The environment variables available for use in `RewriteCond` directives are listed in the table [here](https://www.ibm.com/support/knowledgecenter/en/SSEQTJ_8.5.5/com.ibm.websphere.ihs.doc/ihs/rihs_clcertenvvar.html). Note that many fields in the client certificate are optional and may be empty. #### Example configurations All example configurations should be placed inside a VirtualHost container with ```apache SSLEnable SSLClientAuth required RewriteEngine on ``` #### Examples - Restrict access to entire Virtual Host based on \'Organization\' field ```apache RewriteCond %{ENV:SSL_CLIENT_O} !^IBM$ RewriteCond %{REQUEST_URI} !^/error/ # match any incoming URL RewriteRule ^ /IBM_org_required.html ``` - Restrict access to a URI pattern based on \'Organization\' field ```apache RewriteCond %{ENV:SSL_CLIENT_O} !^IBM$ RewriteCond %{REQUEST_URI} !^/error/ # match URls beginning with /ibm_only RewriteRule ^/ibm_only /IBM_org_required.html ``` - Restrict access to a URI pattern based on a multiple certificate fields ```apache RewriteCond %{ENV:SSL_CLIENT_O} !^IBM$ RewriteCond %{REQUEST_URI} !^/error/ # Note: AND between RewriteCond's is implicit RewriteCond %{ENV:SSL_CLIENT_OU} ^Tivoli$ RewriteRule ^/secret/ /IBM_and_Tivoli_required.html ``` - Restrict access to a URI pattern based on any one of multiple certificate fields ```apache RewriteCond %{ENV:SSL_CLIENT_O} !^IBM$ [OR] RewriteCond %{ENV:SSL_CLIENT_OU} ^Tivoli$ RewriteCond %{REQUEST_URI} !^/error/ RewriteRule /secret/ /IBM_or_Tivoli_required.html ``` - Instead of redirecting to a descriptive page, a HTTP Forbidden (403) response can be returned. ```apache RewriteCond %{ENV:SSL_CLIENT_O} !^IBM$ [OR] RewriteCond %{ENV:SSL_CLIENT_OU} ^Tivoli$ RewriteCond %{REQUEST_URI} !^/error/ RewriteRule /secret/ - [F] ``` To identify the fields of interest in your users' certificates, a test environment can be used that logs client certificate details to the access log. Note: This is 1 very long line followed by a shorter line. ```apache LogFormat "%h SSL_SERVER_C=%{SSL_SERVER_C}e SSL_CLIENT_C=%{SSL_CLIENT_C}e SSL_CLIENT_IC=%{SSL_CLIENT_IC}e SSL_SERVER_CN=%{SSL_SERVER_CN}e SSL_CLIENT_CN=%{SSL_CLIENT_CN}e SSL_CLIENT_ICN=%{SSL_CLIENT_ICN}e SSL_SERVER_DN=%{SSL_SERVER_DN}e SSL_CLIENT_DN=%{SSL_CLIENT_DN}e SSL_CLIENT_IDN=%{SSL_CLIENT_IDN}e SSL_SERVER_EMAIL=%{SSL_SERVER_EMAIL}e SSL_CLIENT_EMAIL=%{SSL_CLIENT_EMAIL}e SSL_CLIENT_IEMAIL=%{SSL_CLIENT_IEMAIL}e SSL_SERVER_L=%{SSL_SERVER_L}e SSL_CLIENT_L=%{SSL_CLIENT_L}e SSL_CLIENT_IL=%{SSL_CLIENT_IL}e SSL_SERVER_O=%{SSL_SERVER_O}e SSL_CLIENT_O=%{SSL_CLIENT_O}e SSL_CLIENT_IO=%{SSL_CLIENT_IO}e SSL_SERVER_OU=%{SSL_SERVER_OU}e SSL_CLIENT_OU=%{SSL_CLIENT_OU}e SSL_CLIENT_IOU=%{SSL_CLIENT_IOU}e SSL_SERVER_ST=%{SSL_SERVER_ST}e SSL_CLIENT_ST=%{SSL_CLIENT_ST}e SSL_CLIENT_IST=%{SSL_CLIENT_IST}e SSL_CLIENT_CERTBODY=%{SSL_CLIENT_CERTBODY}e SSL_CLIENT_CERTBODYLEN=%{SSL_CLIENT_CERTBODYLEN}e SSL_CLIENT_SESSIONID=%{SSL_CLIENT_SESSIONID}e SSL_CLIENT_SERIALNUM=%{SSL_CLIENT_SERIALNUM}e HTTPS=%{HTTPS}e HTTPS_CIPHER=%{HTTPS_CIPHER}e HTTPS_KEYSIZE=%{HTTPS_KEYSIZE}e HTTPS_SECRETKEYSIZE=%{HTTPS_SECRETKEYSIZE}e SSL_PROTOCOL_VERSION=%{SSL_PROTOCOL_VERSION}e %l %u %t \"%r\" %>s %b" client_cert_info CustomLog logs/certinfo.log client_cert_info ``` #### Notes * If users have multiple client certificates, they will have to clear the SSL state of their browser to send a different certificate. * When comparing a non-empty pattern to an "unset" environment variable, mod\_rewrite treats this as non-matching. This is different, but often preferable, behavior than SSLClientAuthRequire/SSLClientAuthGroup. mod\_rewrite directives must be specified in each Virtual Host for which you want them to take effect. ### How do I know if my cryptographic accelerator is working? When SSLPKCSDriver is specified, IHS/GSKit will not fallback to using software-based RSA crypto. For further confirmation, consult the list below. * Collect a GSKit trace that covers at least one SSL handshake. If the following command returns any text, the PKCS11 device was used for RSA operations. ```text strings /tmp/gsktrace_log | grep PKCS11KRYAlgorithmFactory::make_RSAPKCS_DecryptionAlgorithm ``` * If you're using the integrated NCP crypto processors on a Sun Ultrasparc system you can run the following command after before and after an SSL handshake, and you should see the count increase: ```text kstat -n ncp0 -s rsaprivate ``` ### How do I know if OCSP is working? When you connect with a revoked certificate, the SSL handshake should be terminated by IHS before any page is delivered. If LogLevel is set to warn, notice, info, or debug you will see the following messages in the error log when you connect with a revoked certificate: ```text [9fc7468] SSL0234W: SSL Handshake Failed, The certificate sent by the peer has expired or is invalid. [9fc7468] Certificate validation error during handshake, last PKIX/RFC3280 certificate validation error was GSKVAL_ERROR_REVOKED_CERT ``` ### Can I provide a custom error page for SSL handshake failures? IBM HTTP Server 7.0 and earlier: No, if the SSL handshake fails, there is no client-server connection that the server could use to send a custom error page response. The client browser is responsible for notifying the user of the error. IBM HTTP Server 8.0 and later: See the `SSLClientAuthVerify` directive in the infocenter. ### Does IHS support Subject Alternate Names on certificates? If your server certificate includes Subject Alternate Names (SANs), they are part of the certificate and will be passed to SSL clients by any version of IHS. It is up to the client whether it recognizes the SANs and handles them properly, though most modern browsers will. You can generate Certificate Signing Requests (CSRs) with SANs using `gsk7cmd` (command line) or the ikeyman graphical application. Note, though, that the Certificate Authority (CA) is not required to recognize the SAN in your CSR. If the CA ignores it, then the signed certificate will not include the SAN. #### Setup There is some one-time setup necessary in order to be sure you\'re using the latest tools and the SAN options are displayed. ##### IHS v8 and later No manual setup is required. ##### IHS v7 setup - Make sure the file `_IHS_INSTALL_DIR_/java/jre/lib/ext/gskikm.jar` is still in place, which causes Ikeyman v8 to be used #### Generating a CSR with SANs using the command line gsk7cmd tool - Run `gsk7cmd -version` and see what iKeyman version it reports. Verify that the iKeyman version is at least 7.0.4 if using IHS v6.1, or at least 8 if using IHS v7. If not, review the setup instructions for your version of IHS. - Run `bin/gsk7cmd -certreq -create` and review the list of options in the usage output beginning with -san\_\*. The `gsk7capicmd` command-line tool in IHS v6.1 and v7 does not support Subject Alternate Names. #### Generating a CSR with SANs using the graphical ikeyman application - Start `ikeyman` - Invoke `Help/About iKeyman` and verify that the iKeyman version is at least 7.0.4 if using IHS v6.1, or at least 8 if using IHS v7. If not, review the setup instructions for your version of IHS. - Create your certificate request and fill in the fields for the SAN. You can enter more than one value for any of the fields by separating them with commas, e.g. `a.example.com,b.example.com`. ### Does IHS support generating certificate requests with other Extended Key Usage (EKU) fields? Only IHS v8 and later, and only with the `gskcapicmd` command line utility. See the `-eku` option. ### Some browsers fail to handshake with my IHS server, and I am using client certificate authentication and have a lot of certificate authorities in my server key database Some browsers seem to have a bug handling very long SSL server handshake messages. The size of the server\'s SSL handshake message when requesting a client certificate depends on how many CA\'s it has. If it exceeds 16K, the SSL protocol requires it to be split into multiple SSL \"records\", which seems to confuse some browsers. This has only been observed on IE 7 and IE 8, which are now hopelessly out of date. For more information, you can see this KB article: [933430 Clients cannot make connections if you require client certificates on a Web site or if you use IAS in Windows Server 2003](http://support.microsoft.com/kb/933430), though the fix there only increases the limit to a single full SSL record, 16384 bytes. This [blog entry](http://blogs.technet.com/b/askds/archive/2008/10/27/ssl-tls-record-fragmentation-support.aspx) from Jonathan Stephens describes the current problem as well. ### Why are my users seeing my custom SSL error pages when they\'ve connected with a valid SSL connection? If the server configuration is using mod\_rewrite to test characteristics of SSL connections, be sure those rules aren\'t being applied to HTTP error documents. Here\'s what can happen: 1. Browser requests a page that doesn\'t exist, using a valid SSL connection 2. Server redirects the request to an HTTP error document, e.g. /error/HTTP\_NOT\_FOUND.html, to tell the user about the problem 3. mod\_rewrite rules think the connection doesn\'t meet the SSL characteristic required, and redirects again to your custom SSL error page The cause of the problem is that the internal SSL environment variables often tested in mod\_rewrite rules are no longer available after the internal redirect to an HTTP error document. So a test like this fails: ```apache RewriteCond %{ENV:SSL_CLIENT_O} !^Acme$ RewriteRule ^ /Acme_employees_only.html ``` The test is intended to redirect all non-Acme employees to a special page, but it does not find an SSL\_CLIENT\_O variable set to Acme after the internal redirect, so Acme employees who make a typo in a URL end up at a page telling them they\'re not Acme employees. The solution is to not apply the mod\_rewrite rules to error documents. If the error documents\' URLs start with /error/, then the rules above could be fixed like this: ```apache RewriteCond %{ENV:SSL_CLIENT_O} !^Acme$ RewriteCond %{REQUEST_URI} !^/error/ RewriteRule ^ /Acme_employees_only.html ``` ### How can I choose a Signature Algorithm? Some Certificate Authorities (CAs) require that you create your Certificate Signing Request (CSR) with a particular signature algorithm and/or signature algorithm key size. It\'s important to recognize a few things about the chosen CSR algorithm. - The signature algorithm chosen for CSR has no relationship to the signature algorithm used on your issued certificate, which is selected by your certificate authority. - The signature algorithm chosen does indirectly determine what type of private key will be associated with your certificate. Unless you have specific requirements, always choose an RSA based signature algorithm. - Ikeyman and Ikeycmd (gsk7md) v7 in IHS 6.0.2 and later support selecting between MD5 and SHA-1 by creating a \"ikmuser.properties\" in your working directory with a single line containing just: ```text DEFAULT_SIGNATURE_ALGORITHM=SHA1_WITH_RSA ``` Note: SHA-1 is the default in GSKit 7.0.4.27 and later. - Ikeyman and Ikeycmd (gsk7cmd/gskcmd) v8 in IHS 7.0 and later additionally support the SHA-2 family of ciphers directly via the UI (See documentation links below). - gsk7capicmd, the native command-line certificate management tool, supports the SHA-2 family of algorithms in 7.0.4.28 and later, regardless of the IHS release. Refer to the \'[Can IHS use SHA-2 (sha224, sha256, sha384, sha512) digest algorithms? \' section for additional information about using **SHA2** signature algorithms. #### Reference manuals for certificate management tools - Here is the [iKeyman doc](http://download.boulder.ibm.com/ibmdl/pub/software/dw/jdk/security/60/iKeyman.8.User.Guide.pdf) (pdf) for the iKeyman (v8) available in IHS v7 and later. Page 48 documents the signature algorithm options for the command line. If you use the iKeyman graphical interface, some of the algorithm names might be displayed in an abbreviated form, but you can find the full names in the list on that page. - Here is the [iKeyman manual](http://download.boulder.ibm.com/ibmdl/pub/software/dw/jdk/security/50/GSK7c_SSL_IKM_Guide.pdf) (.pdf) for the iKeyman (v7) available in IHS v6.1 (with JDK v5). Make sure you [remove the gskikm.jar file](gather_certificate_doc.html#GSKIKM) first so you\'re using the latest ikeyman. Page 44 documents the signature algorithm options for the command line. Version 7 of iKeyman does not make these options available in the graphical interface, but the signature algorithm can be chosen by editing ikmuser.properties in your working directory (see details above) - Here is the [gsk7capicmd manual](ftp://public.dhe.ibm.com/software/webserver/appserv/library/v61/ihs/GSK7c_CapiCmd_UserGuide.pdf) (.pdf) for the gsk7capicmd available in IHS 6.0.2, 6.1, and 7.0. Search for `-sigalg` for the valid parameters during the `-certreq -create` operation (-sigalg \). Be sure to confirm that `gsk7capicmd -version` (or \/bin/gsk7capicmd -version) reports at least version 7.0.3.27. - Here is the [gskcapicmd manual](ftp://ftp.software.ibm.com/software/webserver/appserv/library/v80/GSK_CapiCmd_UserGuide.pdf) for IHS 8.0 and later ### How can I force CRL data to be retrieved over LDAP v3? IHS 8.0 and later: IHS directive `SSLAttributeSet 314 3 NUMERIC` in the appropriate SSL enabled virtual host. IHS 7.0 and earlier: `export GSK_LDAP_VERSION=3` in the native environment (bin/envvars). ### How can I remove 3DES from the default list of ciphers on z/OS? **Note:** After IBM HTTP Server versions 9.0.0.6, 8.5.5.13, 8.0.0.15, and 7.0.0.45, all 3DES ciphers are disabled by default on all platforms. No further action is required if you are on any release after the aforementioned fixpacks. Before [PI73819](http://www-01.ibm.com/support/docview.wss?uid=swg1PI73819), the advanced syntax to remove specific ciphers is not valid on z/OS. The only way to remove the 3DES cipher from the default list is to respecify all other default ciphers. The ciphers below are the default ciphers as of 2017/01. For IBM HTTP Server 9.0 and above (after PI73819, applies to all platforms): ```pache SSLCipherSpec ALL -SSL_RSA_WITH_3DES_EDE_CBC_SHA -TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA -TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ``` For IBM HTTP Server 9.0 and above (before PI73819, z/OS): ```apache # Enable all default ciphers except the 3DES cipher suite on z/OS for IHS 9.0+. SSLCipherSpec TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 SSLCipherSpec TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 SSLCipherSpec TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 SSLCipherSpec TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 SSLCipherSpec TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA SSLCipherSpec TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA SSLCipherSpec TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 SSLCipherSpec TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 SSLCipherSpec TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 SSLCipherSpec TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 SSLCipherSpec TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA SSLCipherSpec TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA SSLCipherSpec TLS_RSA_WITH_AES_256_GCM_SHA384 SSLCipherSpec TLS_RSA_WITH_AES_128_GCM_SHA256 SSLCipherSpec TLS_RSA_WITH_AES_256_CBC_SHA256 SSLCipherSpec TLS_RSA_WITH_AES_128_CBC_SHA256 SSLCipherSpec TLS_RSA_WITH_AES_256_CBC_SHA SSLCipherSpec TLS_RSA_WITH_AES_128_CBC_SHA ``` For IBM HTTP Server 8.0 and 8.5.5 (z/OS): ```apache # Enable all default ciphers except the 3DES cipher suite on z/OS for IHS 8.0 and 8.5.5. SSLCipherSpec TLS_RSA_WITH_AES_128_CBC_SHA SSLCipherSpec TLS_RSA_WITH_AES_256_CBC_SHA ``` **Note:** The default cipher list for IBM HTTP Server 8.0 and 8.5.5 is limited on z/OS because the other ciphers require access to ICSF. Additionally, ECDSA ciphers are not enabled by default before IBM HTTP Server 9.0. All supported ciphers can still be enabled, including the above defaults used for 9.0. ### How to create a detailed error page when a client's SSL protocol is not supported? With PI91075, an internal environment variable `ssl-version-check-failed` is set to the minimum version of SSL/TLS that the server is able to support. This makes it possible for a dynamic 403 ErrorDocument to produce a detailed error message similar to the following: ``` SSL Protocol 'TLSV1.1' was negotiated, but only TLSV12 is allowed. ``` Example server configuration and SHTML can be found below. #### Example Server Configuration ```apache # Require TLSv1.2 for all location. SSLVersion TLSV12 ErrorDocument 403 "/403.shtml" # Allow all protocols for the SHTML. SSLVersion ALL AddType text/html .shtml AddOutputFilter INCLUDES .shtml Options +IncludesNoExec ``` #### Example 403.shtml (IBM HTTP Server version 9.0 and above) ```html

SSL Protocol 'TLSv1.0' '' was negotiated, but only is allowed.

Normal 403 ``` #### Example 403.shtml (IBM HTTP Server version 8.5.5 and below) ```html

SSL Protocol 'TLSv1.0' '' was negotiated, but only is allowed.

Normal 403 ```