Note: Cryptographic Hardware topics are largely covered here.

Certificate and certificate management FAQS

Certificate and certificate management musgather / common problems

See gather_certificate_doc.htm

PKCS12 with IBM HTTP Server

See pkcs12.html

How can I summarize expiry info of many certificates?

Future levels of IHS V8R0 and later, with IBM Global Security Kit (GSKit) 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 (,

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). IBM Global Security Kit (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

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 >'

More information on certificate monitoring in WebSphere is available here

By default, expiration info is written to the deployment managers SystemOut.log:

    CWPKI0645I: Personal certificate alias "selfSigned" in KeyStore "webserver1((cell):ndcell:(node):node1:(server):webserver1)" was REPLACED.
    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.

IBM Global Security Kit (GSKit) trace on the server reports "No matching alg for certificate". If the backend is IHS, it reports SSL0224E. See 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 and add SSLCipherSpec ALL -RSA to each virtual host with SSLEnable

  3. In fix packs prior to and, a lengthy recipe is here: ECDHE/RSA Cipher Configurations

TLS1.3-specific issues

  • Configurations with SSLFIPSEnable and are later are likely to fail with SSL0232W. Several workarounds are available:


    • Disable TLSv1.3 with SSLProtocolDisable

    • Comment out SSLFIPSEnable

  • PH21804 issues

    • In and handshakes with ECDSA certificates may fail with SSL0200E: SSL Handshake Failed: (454)GSK_ERROR_ILLEGAL_PARAMETER.

    • In and 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.

  • z/Linux can fail with SSL0209E before PH39992 (

  • On z/OS, some certificates may fail with SSL0283E or SSL0212E under TLSv1.3, see https://www.ibm.com/docs/en/zos/2.4.0?topic=protocols-required-updates-enable-tls-v13-protocol-support

    • 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


IHS supports and sends TLS_FALLBACK_SCSV by default after PI52299 (, on distributed platforms.

Does IHS allow user configurable DHE parameters?

No, IHS only supports DHE with Elliptic Curve, and for EC in IHS IBM Global Security Kit (GSKit) only allows the use of the NIST Prime Elliptic Curves P256, P384 and P521. No user selectable parameters are allowed. IBM Global Security Kit (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 IBM Global Security Kit (GSKit) / 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 IBM Global Security Kit (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, ikeyman can create certificates with a public key sizes up to 4096 bits.

  • In the level of IBM Global Security Kit (GSKit) bundled with 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.

    # SHA2-only, no ECDHE
    SSLProtocolDisable TLSv10 TLSv11
    # SHA2-only w/ ECDHE preferred
    SSLProtocolDisable TLSv10 TLSv11

Does IHS support perfect forward secrecy (PFS)? 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 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
    ## Step 2: Append the same ECDHE ciphers

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 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

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:

    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 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.


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:


    openssl s_client -connect ihshostname:443 -ssl2
    openssl s_client -connect ihshostname:443 -ssl3
    openssl s_client -connect ihshostname:443 -tls1


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:

    curl: (35) Unknown SSL protocol error in connection to ihshostname:443


    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 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?


Does IHS support OCSP Stapling?


Does IHS support SSL Renegotiation?

Insecure renegotiation is rejected by default in V8R0 and all later releases.

  IHS Version                                     Renegotiation behavior
  IHS / / and earlier   legacy renegotiation enabled by default.
  IHS / / 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 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.

  IHS Version               RFC5746 behavior
  ------------------------- ---------------------------------------------------
  IHS 7.0 and earlier       Not supported
  IHS /   Supported, signaled but *not* accepted by default
  IHS               Supported, signaled, and accepted by default
  IHS 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,, 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 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 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 IBM Global Security Kit (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 supports command-line SHA-2 management with Ikeyman/gskcmd at any maintenance level. IHS adds command-line SHA-2 management with gsk7capicmd.

  • IHS and all later fixpacks and releases supports SHA-2 certificate management with gskcapicmd and Ikeyman/gskcmd at any maintenance level.

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 and all future releases.

  • SSLv3 was disabled by default in,, and

  • NULL and export SSL ciphers were disabled by default in and all future releases.

  • NULL and export SSL ciphers were disabled by default in and all future releases.

  • RC4 ciphers were disabled by default in,, and

  • 3DES ciphers were disabled by default in,, and

For detailed information about cipher available and defaults, consult the SSL cipher specifications topic in the corresponding release of the knowledge center.

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 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, IBM Global Security Kit (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 IBM Global Security Kit (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.


  • 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 / 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:

      /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:                                                  
    Server name:                                              
    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)                                           
    Ciphers for TLSv10: (defaults)                                          
    Ciphers for TLSv11: (defaults)                                          
    Ciphers for TLSv12: (defaults)                                          

    (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: https://github.com/covener/certutil/

Does IHS support HSTS / strict transport security?

See 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 IBM Global Security Kit (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 (, 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.

    <VirtualHost *:80>
    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 IBM Global Security Kit (GSKit) on solaris?

See questions.html#gskitinstall

How many SSL Session IDs can IHS cache?

See SSL Tuning

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 IBM Global Security Kit (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 IBM Global Security Kit (GSKit) session cache.

Note: In (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 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 %{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:

        <VirtualHost *:443>
          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

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 (<Directory>, <Location>). 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, andSSLVersion 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 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 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 section of the IHS Performance tuning guide. Append any weak ciphers you wish to support (list of ciphers) using SSLCipherSpec Determine the SSL criteria you want to enforce (e.g. keysize, protocol version) and the set of URLs for which it applies.

    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.

  LogFormat "%h %l %u %t \"%r\" %\>s %b %{HTTPS_CIPHER}e" common CustomLog logs/access_log common - - [17/Feb/2005:15:37:39 -0500] "GET / HTTP/1.1" 200 1507 SSL_RSA_WITH_RC4_128_SHA - - [17/Feb/2005:15:37:40 -0500] "GET /httpTech.view1.gif HTTP/1.1" 200 1814 SSL_RSA_WITH_RC4_128_SHA - - [17/Feb/2005:15:37:40 -0500] "GET /httpTech.masthead.gif HTTP/1.1" 200 11844 SSL_RSA_WITH_RC4_128_SHA - - [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. 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

    <VirtualHost ...>
    SSLClientAuth required
    RewriteEngine on


  • Restrict access to entire Virtual Host based on 'Organization' field

        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

        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

        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

        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.

        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.

        CustomLog logs/certinfo.log client_cert_info


  • 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/IBM Global Security Kit (GSKit) will not fallback to using software-based RSA crypto. For further confirmation, consult the list below.

  • Collect a IBM Global Security Kit (GSKit) trace that covers at least one SSL handshake. If the following command returns any text, the PKCS11 device was used for RSA operations.

    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:

    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:

    [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.


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, though the fix there only increases the limit to a single full SSL record, 16384 bytes. This blog entry 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:

    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:

    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:

Note: SHA-1 is the default in IBM Global Security Kit (GSKit) 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 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 (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 (.pdf) for the iKeyman (v7) available in IHS v6.1 (with JDK v5). Make sure you remove the gskikm.jar file 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 (.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 <md5 | sha1 | sha224 | sha256 | sha384 | sha512>). Be sure to confirm that gsk7capicmd -version (or <ihs_root>/bin/gsk7capicmd -version) reports at least version

  • Here is the gskcapicmd manual 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,,, and, 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, 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):


For IBM HTTP Server 9.0 and above (before PI73819, z/OS):

    # Enable all default ciphers except the 3DES cipher suite on z/OS for IHS 9.0+.
    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

For IBM HTTP Server 8.0 and 8.5.5 (z/OS):

    # Enable all default ciphers except the 3DES cipher suite on z/OS for IHS 8.0 and 8.5.5.

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

# Require TLSv1.2 for all location.
<Location />
  SSLVersion TLSV12

ErrorDocument 403 "/403.shtml"

# Allow all protocols for the SHTML.
<Location /403.shtml>
  SSLVersion ALL
  AddType text/html .shtml
  AddOutputFilter INCLUDES .shtml
  Options +IncludesNoExec

Example 403.shtml (IBM HTTP Server version 9.0 and above)

<!--#if expr="%{env:REDIRECT_ssl-version-check-failed} =~ /.+/" -->
SSL Protocol
  <!--#if expr="%{env:SSL_PROTOCOL_VERSION} == 'TLSV1'" -->
  <!--#else -->
      '<!--#echo var="SSL_PROTOCOL_VERSION" -->'
  <!--#endif -->
was negotiated, but only <!--#echo var="REDIRECT_ssl-version-check-failed" --> is allowed.
<!--#else -->
Normal 403
<!--#endif -->

Example 403.shtml (IBM HTTP Server version 8.5.5 and below)

<!--#if expr="${REDIRECT_ssl-version-check-failed} = /.+/" -->
SSL Protocol
  <!--#if expr="${SSL_PROTOCOL_VERSION} == 'TLSV1'" -->
  <!--#else -->
      '<!--#echo var="SSL_PROTOCOL_VERSION" -->'
  <!--#endif -->
was negotiated, but only <!--#echo var="REDIRECT_ssl-version-check-failed" --> is allowed.
<!--#else -->
Normal 403
<!--#endif -->