IBM HTTP Server V5.3 for z/OS: Part 4: Basic configuration

Various capabilities in IBM HTTP Server V5.3 for z/OS® are available in IBM HTTP Server, but implemented differently. Learn about key differences in the basic configuration of the two web servers.

The part and chapters correspond to the part and chapters in publication number SC34-4826-09 of the z/OS HTTP Server Planning, Install, and Using guide for IBM HTTP Server V5.3 for z/OS.

The following topics apply to chapter 7:

The following topics apply to chapter 8:

The following topics apply to chapter 9:


How to serve files

IBM HTTP Server can serve static files or run CGI script files. These files can be in default directories or directories that you specify. We can use various directives to serve these files. Use the Directory section to group the directives together and specify that they apply to a particular directory.

Static files are in the install_root/htdocs directory by default. We can specify an alternative directory on the Alias directive to map the alternative directory to a web address prefix. Then, we can create or copy a Directory section and have it point to the alternative directory. For example, we can copy the Directory directive that specifies the install_root/htdocs default directory and change from the default directory to the install_root/static directory.

CGI scripts run from the install_root/cgi-bin/ directory by default. We can specify an alternative directory on the ScriptAlias directive to map the alternative directory to a web address prefix. Then, we can create or copy a Directory section and have it point to the alternative directory. For example, we can copy the Directory directive that specifies the install_root/cgi-bin/ default directory and change from the default directory to the install_root/cgi2 directory.

For more information about the directives, read the Apache HTTP Server documentation.


How to serve directory listings

Because the DirectoryIndex directive is set to index.html in the default httpd.conf file, IBM HTTP Server serves the directory index file of index.html for directory requests. We can set the DirectoryIndex directive to other files for IBM HTTP Server to serve. We can also add the Options directive with the Indexes argument to a new or existing Directory section so that the web server returns information for that directory. If you include a + in front of the Indexes argument, then the Directory section inherits arguments that are set on other Options directives. If neither of the DirectoryIndex and Options directives is set, the web server returns a 403 error.

For more information about the directives, read the Apache HTTP Server documentation.


How to configure the server

We can administer IBM HTTP Server only by updating the EBCDIC configuration files.

The default IBM HTTP Server configuration file is install_root/conf/httpd.conf. To review or recover the shipped defaults, we can find them in the install_root/conf/httpd.conf.default file.


Files to back up

Periodically back up the following files:

  • The configuration file, which by default is the install_root/conf/httpd.conf file

  • The environment variable file, which is the install_root/bin/envvars file

  • Secure Sockets Layer (SSL) files, such as the following files:

    • Key database files, which have a kdb extension

    • Stash files, which have an sth extension

    • Request database files, which have an rdb extension

    • Certificate revocation list files, which have a crl extension

    • Certificate files, which have an arm extension

  • Output from commands like the install_root/bin/htpasswd command, which we can use for access control

  • Hand-edited group lists

  • Any content that is served in HTTP requests, such as HTML files, images, Java™ scripts, cascading style sheets, and CGI scripts


Encryption support

The US government and governments outside the US regulate products that are used for encryption and prohibit their export unless their key size is strictly limited. As the US government updates their export laws and governments outside the US update their import rules, the supported key lengths and cipher specifications can change.

The IBM HTTP Server supports the SSL ciphers that are listed in the SSL cipher specifications topic.


Hardware encryption

We can use hardware encryption to improve the performance of SSL sessions between the client and the server. By far, the biggest gain in performance for the web server is in the SSL handshake. The handshake uses asymmetric keys and functions. The web server uses RSA technology to implement the asymmetric capability. When you implement SSL without hardware encryption, the asymmetric functions are much slower than symmetric functions. So when you implement hardware encryption with the web server, make sure that you set up your asymmetric Master Keys properly. Use the Integrated Cryptographic Services Facility (ICSF) software so that we can take advantage of the performance boost. The asymmetric Master Keys are not the same as the RSA keys of the web server.

Data Encryption Standard (DES) cipher specifications and Triple-DES cipher specifications use symmetric keys in to handle data transmission. Data transmission might or might not be faster in hardware. Whether data transmission is faster in hardware or software depends on the size of the data stream. SSL should be sending relatively small streams of data, usually 4K bytes, or less. Smaller streams of data tend to be faster in software. Mid-range streams can be faster in hardware or software. Very large streams are faster in hardware.

When you implement hardware encryption, keep in mind these points:

  • The web server uses RSA technology for the SSL handshake. The handshake is an asymmetric capability and uses RSA public-private key pairs. We can generate RSA keys in software or hardware.

  • If you generate the RSA keys in software, we can use RACF® commands or the gskkyman utility.

  • Define RACF commands to permit user IDs and the web server ID to profiles in the CSFSERV general resource class. The CSFSERV general resource class controls the use of ICSF software.

For information about how to implement hardware encryption, read the appropriate manuals. For example, read the z/OS Processor Resource/Systems Management Planning Guide on the IBM support portal.. Additionally, you can read the z/OS Cryptographic Services ICSF Administrator's Guide and the z/OS Cryptographic Services ICSF System Programmer's Guide, which are available on the z/OS Internet Library.


How to check whether hardware encryption is used for web server encryption

ICSF is the software interface to the cryptographic hardware. Use this checklist to determine if your web server is working with hardware encryption.

  • Verify that user IDs and the web server ID have access to ICSF.

  • Check that the ICSF started task is active.

  • Do one or both of the following tasks through the ICSF TSO panels to ensure that ICSF is working properly:

    • Check that ICSF has PKA Master Keys defined.

    • Generate a PKA Master Key successfully.


Checklist for setting up a secure server

To enable Transport Layer Security (TLS), use the SSL virtual host example in the conf/httpd.conf.default file. The example contains elements that are required to enable TLS, including a Listen directive, the SSLEnable directive, and a mod_ibm_ssl module.

IBM HTTP Server uses CMS SSL keystore files, which have a kdb extension. We can use the gskkyman utility or the RACF RACDCERT command to create and administer a keystore file. Attention: Do not share these keystore files between z/OS and distributed platforms.


How to change the default order of the encryption levels that the web server uses

We can use the SSLCipherSpec directive to control order of the encryption levels. IBM HTTP Server always enforces the order of preference. Read about the SSLCipherSpec directive in the topic on SSL directives.


How to set up protection for server resources

The following steps are in the z/OS HTTP Server Planning, Install, and Using guide for IBM HTTP Server V5.3 for z/OS. The information that is associated with each step is information that is needed to do the step in IBM HTTP Server.

  • Step 1. Activate protection on the server.

    You have nothing to do for this step because IBM HTTP Server by default loads the common modules that limit access to resources

  • Step 2. Specify which requests you want the server to accept.

    Use configuration sections to enclose protection-related configuration directives. Read about configuration sections in the Apache HTTP Server documentation.

    For resources in the hierarchical file system (HFS), use the <Directory> and <DirectoryMatch> directives to enclose protection directives. For other resources that are not in the HFS, such as those resources that plug-ins serve, use the <Location> and <LocationMatch> directives.

  • Step 3. Decide which protection options to use.IBM HTTP Server offers a number of different protection mechanisms from which we can choose:

    • Host-based access control via the mod_authz_host module. The mod_authz_host module permits or denies individual IP addresses or subnets.

    • Various modules interoperate to provide user ID and password authentication. These capabilities include HTTP basic authentication for files databases, and LDAP; HTTP digest authentication; and SSL client certificate authentication.

    • Various modules interoperate to provide authorization. These capabilities include groups, Lightweight Directory Access Protocol (LDAP), and SSL client certificates.

    The server processes requests by first checking host-based access control. Then, it checks authentication and access control. If the Satisfy directive is set to any, the request only must meet either host-based access control or authorization requirements. Any match of a Require authorization directive allows access. However, granting access based on the match of multiple Require directives is not possible. CAUTION:We can use the <Limit> and <LimitExcept> directives to constrain protection methods to individual HTTP request methods, but carefully test this approach.

  • Step 4. Create protection setups.

    We can check IBM HTTP Server passwords against user and group password files. However, if you want to check IBM HTTP Server passwords against the local system, then specify the AuthBasicProvider SAF directive. We can optionally change the SAF user ID under which a request is served by specifying the SAFRunAs directive.

    To request SSL client authentication on a virtual host basis, then specify the SSLCLientAuth required directive. Use the SSLClientAuthRequire directive to specify attribute values, or groups of attribute values, that must be validated against a client certificate before the server allows access to the protected resource.

    Use the following examples to guide you in creating your protection setups:

    • Control access to resources by using the Order, allow, and deny directives:
      Alias /my-app /opt/my-app/htdocs
      
      <Directory /opt/my-app/htdocs>
         # Allow requests that match the allow directives. Then, deny requests that match the deny directives. 
         # Then, deny requests that do not match the allow or deny directives.
         Order allow,deny
         # Allow access only to those users from the local host.
         Allow from 127.0.0.1
      </Directory>

    • Control access to resources by using the order, allow, and deny directives. Additionally, use basic authentication so that a user provides a user ID and password to access the resources. Specify the file that contains the user IDs and passwords.
      <Directory /opt/my-app/htdocs/members-only>
           Order allow,deny
           Allow from 127.0.0.1
           # Add HTTP basic authentication.
           AuthType Basic
           AuthBasicProvider file
           AuthName "Login with your example.com user ID."
           # Use the htpasswd utility in the <install_root>/bin/htpasswd file to maintain the passwords.
           # Store the userid and password file in a directory other than the one that it is protecting.
           AuthUserFile /opt/my-app/users.passwd
           Require valid-user
        </Directory>

    • Allow only the user ID of administrator to access the resources.
      <Directory /opt/my-app/htdocs/admin>
           ...
           Require user administrator
        </Directory>

    • Allow only the user group of admins to access the resources. Specify the file that contains the user groups.
      <Directory /opt/my-app/htdocs/admin>
           ...
           # text file with multiple group-name: member1 member2... lines
           # Store the group file in a directory other than the one that it is protecting.
           AuthzGroupFile /auth/groups
           Require group admins
        </Directory>

    • Allow the local host to access resources as if it is an administrator.
        <Directory /opt/my-app/htdocs/admin>
           ...
           Require group admins
           Satisfy any
           Order allow,deny
           Allow from 127.0.0.1
        </Directory>

  • Step 5. Limit access to individual files.

    We can limit the files that a user accesses by nesting the <Files> directive or the <FilesMatch> directive inside of the <Directory> directive or the <DirectoryMatch> directive.


Rules for specifying user names, group names, and address templates

We cannot allow access based on a combination of a user name and an address, such as bob@192.168.1.1 and steve@192.168.2.2, without writing your own Apache module for authorization.


Use of group files in protection setups

A group file in IBM HTTP Server is only a mapping from a group name to a list of users. It cannot have nested definitions or include address specifications.


Access Control List files

IBM HTTP Server does not have access control list files. We can use .htaccess files to limit access to resources. However, avoid using .htaccess files if we can update the httpd.conf file because using .htaccess files slows down your server. As an alternative, include directives in a <Directory> directive and put all the directives in the httpd.conf file.


Related