The following information was provided to us courtesy of the IBM testing team, who tested the functionality of apache with mod_ssl on SUSE LINUX Enterprise Server 9 for S/390 and zSeries. It thus refers to testing only from a certain point, and the z90crypt part is of course specific to S/390 and zSeries. ------------------------------------------------------------------- Installation and Configuration of S/390 HW Crypto on SUSE Linux Enterprise Server 9 for S/390 and zSeries: 1) Installation of the driver packages openCryptoki and libica The driver packages are installed during base install in the default selection. If you installed only minimal system or deinstalled the packages, install them now. If the installation source is accessible, you can do it with a single command: 31bit: yast sw_single openCryptoki openCryptoki-32bit 64bit: yast sw_single openCryptoki openCryptoki-32bit openCryptoki-64bit This will automatically install the necessary libica packages as well if they are not installed yet. 2) Loading the z90crypt driver: systemctl start z90crypt to load z90crypt systemctl stop z90crypt to unload z90crypt this command will be available only after installation of the crypto driver packages. To load the driver automatically at every system boot, integrate it with the other boot scripts issuing systemctl enable z90crypt 3) Checking if the z90crypt hardware driver can be accessed Run this command: openssl speed rsa1024 -engine ibmca -elapsed If you get 'can't use that engine', as the first line of output of the command look for the successive line and check: - if running "rcz90crypt restart" gives no error message - the output of command "dmesg" for error messages from the driver - the hardware is indeed available to this instance 4) Installation and Setup of mod_ssl and apache a) ensure that mod_ssl and apache are installed during base install. If the installation source is accessible, the command yast sw_single mod_ssl will install apache and mod_ssl if they are not installed yet. b) to activate the apache ssl support do the following: if you did not use yast to install the packages, you have to run manually: SuSEconfig --module apache edit /etc/sysconfig/apache: change HTTPD_START_TIMEOUT=2 to 20 change HTTPD_SEC_MOD_SSL=no to yes edit httpd.conf in /etc/httpd: in section 2: check that the ServerName and ServerMail in the ServerAdmin section is ok. in section 3: set inside the ServerName to host name add on section : SSLCryptoDevice ibmca run: SuSEconfig --module apache 5) Crypto configuration of apache/mod_ssl: a) create a certificate (Snake Oil) for the TEST --- THIS CERTIFICATE IS NOT SECURE FOR PRODUCTION USE! IT IS FOR TESTING PURPOSES ONLY! GET A PROPER CERTIFICATE FROM A CERTIFICATION AUTHORITY FOR PRODUCTION USE. go to: cd /usr/share/doc/packages/mod_ssl run: ./certificate.sh see following questions will come up. Give shown answers and use the pass phrase: der3gbe:/usr/share/doc/packages/mod_ssl # ./certificate.sh SSL Certificate Generation Utility (mkcert.sh) Copyright (c) 1998 Ralf S. Engelschall, All Rights Reserved. Generating test certificate signed by Snake Oil CA [TEST] WARNING: Do not use this for real-life/production systems STEP 0: Decide the signature algorithm used for certificate The generated X.509 CA certificate can contain either RSA or DSA based ingredients. Select the one you want to use. Signature Algorithm ((R)SA or (D)SA) [R]:R STEP 1: Generating RSA private key (1024 bit) [server.key] 123006 semi-random bytes loaded Generating RSA private key, 1024 bit long modulus ..++++++ .................++++++ e is 65537 (0x10001) STEP 2: Generating X.509 certificate signing request [server.csr] Using configuration from .mkcert.cfg You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- 1. Country Name (2 letter code) [XY]:DE 2. State or Province Name (full name) [Snake Desert]: 3. Locality Name (eg, city) [Snake Town]: 4. Organization Name (eg, company) [Snake Oil, Ltd]: 5. Organizational Unit Name (eg, section) [Webserver Team]: 6. Common Name (eg, FQDN) [www.snakeoil.dom]: 7. Email Address (eg, name@FQDN) [www@snakeoil.dom]: STEP 3: Generating X.509 certificate signed by Snake Oil CA [server.crt] Certificate Version (1 or 3) [3]:3 Signature ok subject=/C=DE/ST=Snake Desert/L=Snake Town/O=Snake Oil, Ltd/OU=Webserver Team/CN=www.snakeoil.dom/Email=www@snakeoil.dom Getting CA Private Key Verify: matching certificate & key modulus read RSA key Verify: matching certificate signature /etc/httpd/ssl.crt/server.crt: /C=XY/ST=Snake Desert/L=Snake Town/O=Snake Oil, Ltd/OU=Certificate Authority/CN=Snake Oil CA/Email=ca@snakeoil.dom error 10 at 1 depth lookup:certificate has expired OK STEP 4: Enrypting RSA private key with a pass phrase for security [server.key] The contents of the server.key file (the generated private key) has to be kept secret. So we strongly recommend you to encrypt the server.key file with a Triple-DES cipher and a Pass Phrase. Encrypt the private key now? [Y/n]: Y read RSA key writing RSA key Enter PEM pass phrase: <=== crypto Verifying password - Enter PEM pass phrase: <=== crypto Fine, you're using an encrypted RSA private key. RESULT: Server Certification Files o conf/ssl.key/server.key The PEM-encoded RSA private key file which you configure with the 'SSLCertificateKeyFile' directive (automatically done when you install via APACI). KEEP THIS FILE PRIVATE! o conf/ssl.crt/server.crt The PEM-encoded X.509 certificate file which you configure with the 'SSLCertificateFile' directive (automatically done when you install via APACI). o conf/ssl.csr/server.csr The PEM-encoded X.509 certificate signing request file which you can send to an official Certificate Authority (CA) in order to request a real server certificate (signed by this CA instead of our demonstration-only Snake Oil CA) which later can replace the conf/ssl.crt/server.crt file. WARNING: Do not use this for real-life/production systems der3gbe:/usr/share/doc/packages/mod_ssl # 6) Start Apache with SSL a) start with pass phrase (Changes done to apache modul described in item c)). run: rcapache start dev3fe01:~ # rcapache start Starting httpd [ PERL PHP4 Python SSL ]Apache/1.3.26 mod_ssl/2.8.10 (Pass Phrase Dialog) Some of your private key files are encrypted for security reasons. In order to read them you have to provide us with the pass phrases. Server dev3fe01.boeblingen.de.ibm.com:443 (RSA) Enter pass phrase: crypto Ok: Pass Phrase Dialog successful. done b) start without pass phrase when using apache without ssl-support remark: You need to change the apache modul (see item c)). Set the HTTPD_SEC_MOD_SSL=no. run: rcapache start 7) Check that ibmca is used and apache is working with http and https: a) On a browser enter http:// or https:// b) with netstat or netstat -a on the apache server machine you can see if https is used. c) in the log /var/log/httpd/ssl_engine_log you can see if the ibmca engine is started or not. d) during siege test you can see with cat /proc/driver/z90crypt if and what crypto HW is used e) you can check a http connection with telnet http. Then enter get / http/1.0 and you should get back some stuff after pressing enter twice. f) You can check if openssl works with the ibmca engine a) Therefore you must create certificates: cd /usr/share/ssl/misc run: ./CA.sh -newcert dev3fe01:/usr/share/ssl/misc # ./CA.sh -newcert Using configuration from /etc/ssl/openssl.cnf Generating a 1024 bit RSA private key ......................++++++ .++++++ writing new private key to 'newreq.pem' Enter PEM pass phrase: <== geheim Verifying password - Enter PEM pass phrase: <== geheim Verify failure Enter PEM pass phrase: Verifying password - Enter PEM pass phrase: phrase is too short, needs to be at least 4 chars Enter PEM pass phrase: Verifying password - Enter PEM pass phrase: ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]: <== press enter State or Province Name (full name) [Some-State]: <== press enter Locality Name (eg, city) []: <== press enter Organization Name (eg, company) [Internet Widgits Pty Ltd]: <== press enter Organizational Unit Name (eg, section) []: <== press enter Common Name (eg, YOUR name) []: <== press enter Email Address []: <== press enter Certificate (and private key) is in newreq.pem run: ./CA.sh -newca dev3fe02:/usr/share/ssl/misc # ./CA.sh -newca CA certificate filename (or enter to create) newreq.pem dev3fe02: b) Use openssl as a Web-browser and use https connection: openssl s_client \ -connect :443 -state -debug The machine were you start the client is working as your 'browser' connecting to the webserver. You can start commands from the client like get / http/1.0 . c) Use openssl as a Web-server and use https connection: openssl s_server \ -accept 443 -www -engine ibmca -cert newreq.pem The machine is working like a small webserver with full openssl functionality. You can start your browser to this machine and a lot of info will be sent. dev3fe01:/usr/share/ssl/misc # openssl s_server -accept 443 -www -cert newreq.pem -engine ibmca engine "ibmca" set. Using default temp DH parameters Enter PEM pass phrase: <== geheim ACCEPT -------------------------------------------------------------------