OpenSSL 3.0: Apache HTTP Server setup with the IBMCA provider

Edit online

In the presented usage scenario, you learn how to configure the software of the Apache HTTP Server in order to use OpenSSL which is configured to exploit the IBMCA provider.

Preparing the environment

  1. Install the IBMCA provider. See Installing IBMCA for details about how to install or build the IBMCA provider. Assume you plan to run the Apache HTTP Server on an IBM z15® or LinuxONE III or later machine generation.
  2. Run the following command:
    $ dnf install httpd

IBMCA provider configuration

Follow the instructions in Configuring OpenSSL to use the IBMCA provider to enable the IBMCA provider system-wide.

Here is an excerpt from the OpenSSL configuration file. The settings added or changed are marked in bold.

Note: There is nothing specific for the Apache HTTP Server in this configuration, just regular IBMCA provider configuration.

[openssl_init]
providers = provider_sect
alg_section = evp_properties
# Load default TLS policy configuration
ssl_conf = ssl_module

# Uncomment the sections that start with ## below to enable the legacy provider.
# Loading the legacy provider enables support for the following algorithms:
# Hashing Algorithms / Message Digests: MD2, MD4, MDC2, WHIRLPOOL, RIPEMD160
# Symmetric Ciphers: Blowfish, CAST, DES, IDEA, RC2, RC4,RC5, SEED
# Key Derivation Function (KDF): PBKDF1
# In general it is not recommended to use the above mentioned algorithms for
# security critical operations, as they are cryptographically weak or vulnerable
# to side-channel attacks and as such have been deprecated.

[provider_sect]
default = default_sect
ibmca_provider = ibmca_sect
##legacy = legacy_sect

[default_sect]
activate = 1
fips = no

[ibmca_sect]
identity = ibmca
module = ibmca-provider.so
activate = 1
algorithms = RSA,DH

##[legacy_sect]
##activate = 1

[evp_properties]
default_properties = ?provider=ibmca

Use the command openssl list -providers to check that the IBMCA provider is available:

# openssl list -providers
Providers:
  default
    name: OpenSSL Default Provider
    version: 3.0.1
    status: active
  ibmca
    name: ibmca
    version: 1.1.0
    status: active

Configure the Apache HTTP Server

The Apache HTTP Server configuration is in /etc/httpd/conf/httpd.conf and the SSL/TLS configuration is in /etc/httpd/conf.d/ssl.conf. Locations may differ between distributions.

Information about a generic HTTP server configuration can be found in the man pages of httpd (Hypertext Transfer Protocol daemon), man httpd and man httpd.conf, and is not covered in this publication. Also, information about securely configuring TLS and HTTPS with the HTTP server is also not covered in this publication.

Usually the following steps need to be taken in /etc/httpd/conf.d/ssl.conf to configure the use of TLS (HTTPS) with the Apache HTTP Server. For details about how to perform these steps, refer to the HTTPD documentation:

  1. Enable the Apache HTTP Server to listen on port 443 (https): Listen 443 https
  2. Configure SSL for the virtual host context: <VirtualHost_default_:443>
  3. Enable the SSL engine of the HPTTPD server (note that here the term ‘engine’ does not relate to OpenSSL engines, but describe the HTTP internal SSL routines that are part of the httpd): SSLEngine on
  4. Select the SSL cipher suites to use/allow: SSLCipherSuite PROFILE=SYSTEM
  5. Generate a private key for the server. This can be an RSA or an ECC key. You can achieve this, for example, by using the openssl command line tool.
  6. Generate a certificate for the server. For production use, this should be signed by a trusted Certificate Authority (CA), but for testing purposes it can also be a self-signed certificate.
  7. Specify the private key in ssl.conf: SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
  8. Specify the certificate in ssl.conf: SSLCertificateFile /etc/pki/tls/certs/localhost.crt
  9. Configure further SSL options as required.

The default configuration (at least starting with Red Hat Enterprise Linux 9) already contains all required settings, but uses test keys and certificates that should not be used for a production system.

Note: There is nothing specific for IBMCA in the HTTPD configuration files. Because the IBMCA provider has been configured system-wide in the OpenSSL configuration file, it is automatically used by HTTPD whenever cryptographic operations are performed by HTTPD via OpenSSL.

Starting and stopping the Apache HTTP Server

Use the apachectl command to start or stop the HTTPD server. See the apachectl man page for details (man apachectl):

  1. Start HTTPD: apachectl start
  2. Stop HTTPD: apachectl stop

Alternatively you can use the systemctl command to start and stop the HTTPD server:

  1. systemctl start httpd.service
  2. systemctl stop httpd.service

Testing if IBMCA is used by HTTPD

Use the curl command line tool to connect via HTTPS to the HTTPD server and get the default page. The –insecure option may be required if the server used a self-signed certificate. You can alternatively use any other tool (for example, wget or your web browser) to retrieve a web page from the HTTP server. Just make sure you use HTTPS, so that cryptographic operations are being used. 

curl https://localhost --verbose [--insecure]

Use the icastats tool to check if counters for RSA are increasing with each page retrieval. Dependent on the private key type of HTTPD (RSA or ECC), the signature algorithm of the certificates used by the server, and the selected cipher suites for the TLS connection, the RSA counters may increase with every connection if RSA is used.

icastats counts cryptographic operations per user. Make sure to display the counters for the user who runs the HTTPD server, for example by using icastats --user <user-name>. See also icastats - Show use of libica functions.

Use cpacfstats for counting CPACF activity in OpenSSL.