Provide feedback on the IBM HTTP Server forum on IBM developerWorks.
Note: Cryptographic Hardware topics are largely covered here.
See pkcs12.html
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.
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).
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.
Not directly, but WAS can create and manage the key store used by IHS, and it will provide 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:
*** 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.
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.
GSKit trace on the server reports "No matching alg for certificate". If the backend is IHS, it reports SSL0224E. See errorlog.html#SSL0266E
No, IHS always uses the servers preference (acts like 'SSLHonorcipherorder on');
IHS supports and sends TLS_FALLBACK_SCSV by default after PI52299 (8.5.5.9, 8.0.0.13) on distributed platforms.
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.
No, the Dual-EC DRBG algorithm has never been implemented by IHS.
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
SSLAttributeSet proxy:439 0 ENUM
gsk7capicmd/gskcapicmd
can create certificates with 4096 bit keys
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.
IHS 8.0.0.6/8.5.0.2 and later support ECDHE ciphers and keys. These ciphers provide PFS, but must be manually enabled through the SSLCipherSpec directive. After PI81589 (8.5.5.12, 8.0.0.14) these are enabled and preferred by default on distributed platforms.
Related note: In 8.5.5.5 and later, IHS can simultaneously use 1 RSA and 1 ECDSA certificate, selecting the appropriate one based on information in the TLS client hello. This is configured by providing two certificate labels to the SSLServerCert directive. The order influences the selection.
Below are a few example configurations for enabling ECDHE. Note that the SSLCipherSpec
directives must be placed at the same level as
SSLEnable
, e.g. in the same virtualhost.
#Allow ECDHE-RSA ciphers, but do not prefer them SSLCipherSpec TLSv12 +TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 SSLCipherSpec TLSv12 +TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 SSLCipherSpec TLSv12 +TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 SSLCipherSpec TLSv12 +TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
#Prefer ECDHE-RSA ciphers SSLCipherSpec ALL NONE SSLCipherSpec TLSv12 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 SSLCipherSpec TLSv12 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 SSLCipherSpec TLSv12 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 SSLCipherSpec TLSv12 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 SSLCipherSpec ALL TLS_RSA_WITH_AES_128_GCM_SHA256 SSLCipherSpec ALL TLS_RSA_WITH_AES_256_GCM_SHA384 SSLCipherSpec ALL TLS_RSA_WITH_AES_128_CBC_SHA256 SSLCipherSpec ALL TLS_RSA_WITH_AES_256_CBC_SHA256 SSLCipherSpec ALL TLS_RSA_WITH_AES_128_CBC_SHA SSLCipherSpec ALL TLS_RSA_WITH_AES_256_CBC_SHA SSLCipherSpec ALL SSL_RSA_WITH_3DES_EDE_CBC_SHA
#Require ECDHE-RSA ciphers - not recommended, many clients still # do not support ECDHE SSLProtocolDisable SSLv2 SSLv3 TLSv10 TLSv11 SSLCipherSpec ALL NONE SSLCipherSpec TLSv12 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 SSLCipherSpec TLSv12 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 SSLCipherSpec TLSv12 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 SSLCipherSpec TLSv12 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
Note that the ECDHE ciphers in the examples above are only a subset of the ones IHS supports. For the full list, refer to the infocenter.
In Version 9 and later, ECDHE is enabled by default and preferred over RSA. Example config changes follow:
# Disable ECDHE in V9 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
# Prefer RSA in V9 # 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
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.
Specifying any SSLv3/TLSv1 ciphers as illustrated in the performance guide will disable support for the NULL/Plaintext ciphers, provided you don't explicitly enumerate the following ciphers:
SSL_RSA_WITH_NULL_SHA (30) SSL_RSA_WITH_NULL_MD5 (31) SSL_NULL_WITH_NULL_NULL (32)Note: The following releases disable NULL ciphers by default:
SSLv2 can be re-enabled by specifying any SSLv2 ciphers with SSLCipherSpec
. Don't do this.
SSLv2 can be re-enabled by specifying 'SSLProtocolEnable SSLv2'
. Don't do this.
'SSLProtocolDisable SSLv2'
is specifiedSSLCipherSpec
and no SSLv2 ciphers are specified with SSLCipherSpec
SSLv2 cipher long and numeric names can be viewed here.
SSLProtocolDisable
is supported in 6.0.2.13, 6.1.0.2, 7.0.0.0 and later.
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.
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
.
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:
openssl s_client -connect ihshostname:443 -ssl2 openssl s_client -connect ihshostname:443 -ssl3 openssl s_client -connect ihshostname:443 -tls1
curl -vk -2 https://ihshostname curl -vk -3 https://ihshostname # -1 tests for TLSv1 curl -vk -1 https://ihshostnameFor more information see: How can I disable support for SSLv2?
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.
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.
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.
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.
No.
No.
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, legacy can be enabled |
IHS 8.0.0.0 | RFC5746 supported, signaled, and accepted by default. Legacy can be enabled |
IHS 8.0.0.1 and later | RFC5746 renegotiation supported, signaled but not accepted by default. Legacy can be enabled |
If you update GSKit to an RFC5746 renegotiation aware level (7.0.4.38 or later) without updating to an IHS aware of RFC5746 renegotiation, RFC5746 renegotiation is enabled.
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 |
IHS 7.0 and earlier do not support TLS compression.
IHS 8.0.0.0 through 8.0.0.4 and later does support TLS compression, but it can be disabled by adding the following
directive in the same context as SSLEnable
SSLAttributeSet 445 1
IHS 8.0.0.5, 8.5.0.1, and later support TLS compression but it is disabled by default. Use SSLCompression directive to re-enable (distributed only)
Only in V8R0 and later with PM80235. The only supported curves are secp256r1, secp384r1, and secp521r1 (RFC4492 names).
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.
SHA-2 based SSL ciphers are supported and used by default in IHS 8.0 and later. They're not supported in older releases.
IHS 7 and all later fixpacks and releases supports SHA-2 certificates at runtime and in one or more included certificate management tools.
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.
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.
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.
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.
6.1 and earlier:
An alternative shorthand for the recommended config above is SSLFIPSEnable with no SSLCipherSpec at all
7.0:
An alternative shorthand for the recommended config above is SSLFIPSEnable with no SSLCipherSpec at all
8.0 and later:
These releases have had "reasonable defaults" since their inception. The defaults are only used in the absence of SSLCipherSpec, but SSLCipherSpec can be used relative to the defaults by using the "-" symbol to remove ciphers.
Remove RC4 until PI34229 can be applied (Removed from defaults in PI34229, see http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=ihs-dist&topic=rihs_ciphspec)
SSLCipherSpec ALL -SSL_RSA_WITH_RC4_128_SHA -SSL_RSA_WITH_RC4_128_MD5
Other significant recommended SSL APARs:
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.
The consensus is to disable SSLv3 as the problem cannot be corrected in SSLv3
This requires corrective maintenance if your server is affected (PI31516 for IHS)
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:
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.
History:
20150203: The example that previously accompanied this FAQ is now hidden. If you want to view it for historical reasons, view the source of this page
In IHS 8.0 and later:
If there is a question of how your configuration customizations are ultimately combined, you can run apachectl -t -DDUMP_SSL_CONFIG to see the effective values after processing the configuration. 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),S SL_RSA_WITH_RC4_128_SHA(35),SSL_RSA_WITH_RC4_128_MD5(34),SSL_RSA_WIT H_3DES_EDE_CBC_SHA(3A) Ciphers for TLSv10: (defaults) TLS_RSA_WITH_AES_128_CBC_SHA(2F),TLS_RSA_WITH_AES_256_CBC_SHA(35b),S SL_RSA_WITH_RC4_128_SHA(35),SSL_RSA_WITH_RC4_128_MD5(34),SSL_RSA_WIT H_3DES_EDE_CBC_SHA(3A) Ciphers for TLSv11: (defaults) TLS_RSA_WITH_AES_128_CBC_SHA(2F),TLS_RSA_WITH_AES_256_CBC_SHA(35b),S SL_RSA_WITH_RC4_128_SHA(35),SSL_RSA_WITH_RC4_128_MD5(34),SSL_RSA_WIT H_3DES_EDE_CBC_SHA(3A) 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_S HA256(3D),TLS_RSA_WITH_AES_128_CBC_SHA(2F),TLS_RSA_WITH_AES_256_CBC _SHA(35b),SSL_RSA_WITH_3DES_EDE_CBC_SHA(3A) (Note: we report SSLv2 as enabled with zero available ciphers as an implementation quirk)
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/
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.
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] </VirtualHost>
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.
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.
The validity period of the cached SSL session is not reset when an SSL session is reused. In 8.5.5.9 (but not later fixpacks) the time is reset when an SSL session is reused.
This cannot be easily accomplished because there is no support for telling the web browser to "try again with a client certificate." This also will not work with TLS 1.3 as SSL renegotiation is prohibited. 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.
SSLClientAuth optional
in your virtual host
RewriteEngine on RewriteCond %{ENV:SSL_CLIENT_CERTBODYLEN} ^$ RewriteCond %{REQUEST_URI} !^/error/ RewriteRule /secure/ /certrequired.html [PT]
/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.
(See this question for why we exclude error documents from the rule.)
SSLClientAuthRequire
<VirtualHost *:443> 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] ...
IHS cannot choose a certificate or ciphers based on name-based virtual host configuration. This technote describes the configuration requirements:
Why?
A TLS extension has been defined in RFC 3546 which allows selection of the virtual host during the handshake, avoiding this dependence on IP addresses. In the coming years we'll see browsers which are able to support this TLS extension, but it will be a very long time before an customers could rely on that because older browsers would be unable to participate.
If you have a certificate that applies to all of your name-based vhosts,
and you don't require any separate SSL configuration across the set of
name-based vhosts, you can just fully configure SSL in the first one then
configure just SSLEnable
in all the subsequent ones.
Note: It is the IP address/port combination which must be unique. You could support multiple SSL-enabled virtual hosts on the same IP address if they differ in port number, but that would require that clients specify the port number in https URLs for all but one of the SSL-enabled virtual hosts. |
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.
Unfortunately, the restrictions configured with SSLCipherBan
,
SSLCipherRequire
, and SSLVersion
do not influence the
actual SSL handshake and are only checked later on during request processing.
No SSL renegotiation is triggered by these directives, and instead the
configured 403 error response is issued at the application level. This 403
response may be difficult to distinguish from 403 errors triggered by other
authorization or access control directives.
As an example of why SSLVersion
is difficult to implement, if you use
SSLVersion SSLv3
(or SSLv2) and a browser connects with a
"stronger" protocol, not only do they get a generic 403 response but the user
would have to take some action to disable the stronger/preferred SSL
protocols in their browser to be able to reconnect. Using SSLVersion TLSv1
,
which requires the latest SSL protocol, sends clients without TLSv1 support a generic
403 response. This 403 response can be customized with the
ErrorDocument
directive but it is not distinguishable from other
access control errors in the same context.
Because of the limitations of SSLCipherBan, SSLCipherRequire, and SSLVersion, using mod_rewrite to analyze the SSL environment variables (HTTPS_CIPHER, SSL_PROTOCOL_VERSION, HTTPS_KEYSIZE) is much more flexible.
SSLCipherSpec
and
SSLProtocolDisable
influence the SSL handshake itself, and as a
consequence are only available in a per-vhost basis. While it's normally safe
to limit cipher support to "128-bit or
higher ciphers" or to disable SSLv2, we do not recommend restricting access
much further than this with SSLCipherSpec
and
SSLProtocolDisable
. Instead, use mod_rewrite as illustrated above
to enforce more restrictive access control; otherwise IHS and the browser may
not be able to negotiate a secure channel and users may not see a descriptive
error message from their browser.
This is an alternative to shutting out very old clients that might not be able to negotiate a strong cipher.
SSLCipherSpec
RewriteEngine On RewriteCond %{ENV:HTTPS_KEYSIZE} !^(128|168|256)$ RewriteCond %{REQUEST_URI} !^/error/ RewriteRule ^/secret3/ /128_or_higher.html
RewriteEngine On RewriteCond %{ENV:HTTPS_KEYSIZE} !^(128|168|256)$ [OR] RewriteCond %{ENV:SSL_PROTOCOL_VERSION} ^SSLV2$ RewriteCond %{REQUEST_URI} !^/error/ RewriteRule .* /low_grade_encryption.html
(See this question for why we exclude error documents from the rule.)
Instead of using mod_ibm_ssl SSLCipherSpec directives to allow only SSLv3 and TLSv1 ciphers, use mod_rewrite to recognize when SSLv2 is used, and redirect the request to a document explaining the restriction.
Example:
RewriteEngine On RewriteCond %{ENV:SSL_PROTOCOL_VERSION} ^SSLV2$ RewriteCond %{REQUEST_URI} !^/error/ RewriteRule .* /low_grade_encryption.html
RewriteEngine On RewriteCond %{ENV:HTTPS_CIPHER} !AES RewriteCond %{REQUEST_URI} !^/error/ RewriteRule ^/secret1/ /AES_only.html RewriteCond %{ENV:HTTPS_CIPHER} MD5 RewriteCond %{REQUEST_URI} !^/error/ RewriteRule ^/secret2/ /no_md5.html
(See this question for why we exclude error documents from the rule.)
SSLRequireSSL
directive?The SSLRequireSSL
directive is not supported with any
level of IHS. IHS uses a different SSL implementation than available
for Apache 1.3 or Apache 2.0.
Instead of using the SSLRequireSSL
directive to
specify that certain files or directories can only be served over SSL,
a customer can achieve the same result in different manner, by denying
access to the file or directory in the non-SSL configuration. In
following example, files under URI /onlyssl
can only be
served over SSL:
... # /onlyssl can't be served by default <Location /onlyssl> Order Allow,Deny Deny from all </Location> ... <VirtualHost *:443> SSLEnable ... # put this config for /onlyssl inside all SSL-enabled # VirtualHost containers <Location /onlyssl> Order Allow,Deny Allow from all </Location> </VirtualHost> ...
%{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.
Example:
LogFormat "%h %l %u %t \"%r\" %>s %b %{HTTPS_CIPHER}e" common CustomLog logs/access_log common
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.
The key size can be logged with the %{HTTPS_KEYSIZE}e
format string. See the section on SSL environment variables in the
IBM HTTP Server InfoCenter for information about other SSL environment
variables which can be logged. See the documentation for the
LogFormat and CustomLog directives for more information about format
strings in general.
A manual way to check this is to use Wireshark on the client system and start a packet trace capture. Then load the web page with your choice of web browser. Then stop the capture in Wireshark and look for the Server "Hello" response. This will appear in the packet window like this:
1.750088 server-ip-address client-ip-address TLS Server Hello, Certificate, [Unreassembled Packet]
Select that packet, then look for the "Handshake Protocol" information in the next window:
Handshake Protocol: Server Hello Handshake Type: Server Hello (2) Length: 70 Version: TLS 1.0 (0x0301) Random.gmt_unix_time: Apr 8, 2005 14:15:33.00000000 Random.bytes Session ID Length: 32 Session ID (32 bytes) Cipher Suite: TLS_RSA_WITH_RC4_128_MD5 (0x0004) Compression Method: null (0)
Check the display of the cipher suite.
Consult the Wireshark documentation for further information about using that tool.
If you have the openssl command-line client (not part of IHS, but distributed at www.openssl.org), that can display the cipher used as well, for an SSL session established by that command-line client.
To see which cipher is selected for the request, run openssl s_client -connect IPADDR:PORT and look for this part of the output:
New, TLSv1/SSLv3, Cipher is AES256-SHA
The symbolic names for the ciphers as displayed by openssl are are not the same symbolic names used by IHS. Here are the openssl names for common ciphers used with IHS:
IHS name | OpenSSL name |
TLS_RSA_WITH_AES_256_CBC_SHA | AES256-SHA |
TLS_RSA_WITH_AES_128_CBC_SHA | AES128-SHA |
SSL_RSA_WITH_RC4_128_SHA | RC4-SHA |
SSL_RSA_WITH_RC4_128_MD5 | RC4-MD5 |
TLS_RSA_EXPORT1024_WITH_RC4_56_SHA | EXP1024-DES-CBC-SHA |
TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA | EXP1024-RC4-SHA |
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 | EXP-RC2-CBC-MD5 |
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 | EXP-RC2-CBC-MD5 |
SSL_RSA_EXPORT_WITH_RC4_40_MD5 | EXP-RC4-MD5 |
The openssl client supports many ciphers which are not supported by IHS.
openssl will hold the connection open until you interrupt it with the EOF character (usually <Ctrl>D on Unix systems).
You can restrict the openssl client to a particular cipher to see if IHS supports it, using the -cipher CIPHERNAME option.
Consult the OpenSSL documentation for further information about using the openssl command-line tool.
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.
All example configurations should be placed inside a VirtualHost container with
<VirtualHost ...> SSLEnable SSLClientAuth required RewriteEngine on <VirtualHost>
RewriteCond %{ENV:SSL_CLIENT_O} !^IBM$ RewriteCond %{REQUEST_URI} !^/error/ # match any incoming URL RewriteRule ^ /IBM_org_required.html
RewriteCond %{ENV:SSL_CLIENT_O} !^IBM$ RewriteCond %{REQUEST_URI} !^/error/ # match URls beginning with /ibm_only RewriteRule ^/ibm_only /IBM_org_required.html
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
RewriteCond %{ENV:SSL_CLIENT_O} !^IBM$ [OR] RewriteCond %{ENV:SSL_CLIENT_OU} ^Tivoli$ RewriteCond %{REQUEST_URI} !^/error/ RewriteRule /secret/ /IBM_or_Tivoli_required.html
RewriteCond %{ENV:SSL_CLIENT_O} !^IBM$ [OR] RewriteCond %{ENV:SSL_CLIENT_OU} ^Tivoli$ RewriteCond %{REQUEST_URI} !^/error/ RewriteRule /secret/ - [F]
(See this question for why we exclude error documents from the rule.)
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.
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.
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.
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
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
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.
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.
No manual setup is required.
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.
Only IHS v8 and later, and only with the gskcapicmd
command
line utility. See the -eku
option.
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.
As of July 2010, here's how things look:
You can observe this happening with SSLTrace
SSL handshake initiated [x:3360 -> y:443] [20:52:35.000704700] SSL read begin bytes [5] timeout [300000000] SSL read end bytes [5] err [0] to [0] eof [0] ^ start of new SSL record SSL read begin bytes [65] timeout [300000000] SSL read end bytes [65] err [0] to [0] eof [0] ^ client hello SSL write begin bytes [16389] timeout [300000000] SSL write end bytes [16389] err [0] to [0] ^ maximum size of SSL record in first write of handshake SSL write begin bytes [485] timeout [300000000] SSL write end bytes [485] err [0] to [0] ^ immediate subsequent write for remainder
Complicating the issue at this time, Wireshark also seems to have a bug understanding these long messages, so looking at a packet trace in Wireshark might suggest that the message itself is incorrect. (https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=3303). However, GSKit support has carefully examined traces in this situation and verified that IHS and GSKit are sending the correct messages, according to the RFC.
Some possible remediations:
SSLAttributeSet 457 0
which
suppresses providing any CA certificates to the client with client auth enabled. Most clients will still
offer to send a certificate even when the CA list is not included.
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.
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:
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
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.
Supported algorithms
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 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.
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 7.0.3.27.
Here is the gskcapicmd manual for IHS 8.0 and later
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).
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):
# 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):
# 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.