IBM Support

How to Customize Java Security Configuration Properties for JDKs on the IBM i OS

Troubleshooting


Problem

This document describes the best practice for customizing some common Java security properties with the JDKs on the IBM i OS. These properties are needed so a Java Virtual Machine (JVM) can load security settings that have been customized for your application.

Environment

Java Development Kit (Classic and IBM Technology for Java VM) on IBM i OS

Resolving The Problem

  • At IBM i 7.1, only the "IBM Technology for Java VM" is available. If you are at this OS level, proceed to the "Read First!" section.

At IBM i 5.4 and 6.1, you have a couple of different JVM options (the "Classic JVM" and the "IBM Technology for Java VM (IT4J)"). The directories containing the Java security configuration files are different between the two different JVM types, so you will need to figure out which JVM is in use with your job before you proceed. The easiest way to find this is by displaying the job log for the JVM job you want to customize.

====================================================================
For example, if the job is called JVMAPP1, you would do the following from the command line:

1. Issue the WRKJOB JVMAPP1 command and press Enter.
2. Choose option 1 to select the active job.
3. Choose option 10 to display the job log.
4. Press F10 to see all messages.

The joblog will show the following:

Java Virtual Machine is IBM Technology for Java. PID(xxxx)

Where xxxx is the process ID.

OR

Java Virtual Machine is Classic.

Please refer to the appropriate section based on your JVM type.
====================================================================

READ FIRST!

Files that reside in the /QIBM/ProdData/* and /QOpenSys/QIBM/ProdData/* directory structures are "owned" by IBM. These system directories are used for Licensed Program Product (LPP) data. As a result, they will be updated/overlaid when Java PTFs are applied. This means it is very risky for clients/third parties to rely on changes/customizations made to any files in the /QIBM/ProdData/* or /QOpenSys/QIBM/ProdData/* directories because a PTF may overlay any changes/customizations.

The Java LPP on the IBM i provides default files for the security configuration. The default security configuration files include the java.security, java.policy and cacerts files which are located in the /QIBM/ProdData/Java400/jdkxx/lib/security/ and /QOpenSys/QIBM/ProdData/JavaVM/jdkxx/xxbit/jre/lib/security/ directories. It is recommended that you copy these files to another directory outside of the LPP system directories when making customizations. The following properties may be used so the JVM can find and use these customized configuration files. Using these custom properties will insulate your Java applications from changes made to the global Java system LPP security configuration files when applying PTFs.

IBM Technology for Java VM & Classic JVM

The master java.security file is located in the following directories. You will want to check this file first to ensure the properties "policy.allowSystemProperty=true" and "security.overridePropertiesFile=true" are both set to true if you want to customize the locations of the java.policy and java.security files.

Classic JVM
/QIBM/ProdData/Java400/jdkxx/lib/security/

IBM Technology for Java
/QOpenSys/QIBM/ProdData/JavaVM/jdkxx/xxbit/jre/lib/security/

Ensure the master java.security file contains the following: NOTE: These are the default values in the master java.security file.

# whether or not we allow an extra policy to be passed on the command line
# with -Djava.security.policy=somefile. Comment out this line to disable
# this feature.
policy.allowSystemProperty=true

# Determines whether this properties file can be appended to
# or overridden on the command line via -Djava.security.properties
#
security.overridePropertiesFile=true


Custom Properties

=========================================
java.security file

To append to the file:
java.security.properties=<path to security file>
  • For example:
    java.security.properties=/home/java.security

To replace the file:
java.security.properties==<path to security file>
  • For example:
    java.security.properties==/home/java.security
==========================================
java.policy file

java.security.policy=<path to policy file>
  • For example:
    java.security.policy=/home/java.policy
==========================================
jurisdictionPolicyDir

NOTE: This property is used to implement the JCE Unlimited Strength Policy Files for use with AES_256 cipher suites. Refer to the IBM SDK Policy Files link for more information.

com.ibm.security.jurisdictionPolicyDir=<path to unrestricted jurisdiction policy files>
  • For example:
    com.ibm.security.jurisdictionPolicyDir=/policyfiles/unrestricted
==========================================
SSL TrustStore

javax.net.ssl.trustStore=<path to trust store>
  • For example:
    javax.net.ssl.trustStore=/home/cacerts
==========================================
SSL KeyStore

javax.net.ssl.keyStore=<path to key store>
  • For example:
    javax.net.ssl.keyStore=/home/cacerts
=======================================================

There are a variety of ways to specify these properties when the JVM is started.
1. On the Java command:
java -Djavax.net.ssl.trustStore=<path to trust store> ProgramName
2. Add the properties to the SystemDefault.properties file:
javax.net.ssl.trustStore=<path to trust store>

NOTE: The SystemDefault.properties file can be set globally for all JVMs (/QIBM/UserData/Java400/SystemDefault.properties) or for a specific JVM job user in the user's home directory specified on the user profile object (/home/jvmuser/SystemDefault.properties). The SystemDefault.properties file must have a CCSID of 819 or 1252 in order for it to be read correctly.
3. For a WebSphere Application Server Profile, the normal security configuration files cannot be overridden using the above Java properties. These files are already copied into your application server's profile root. You would use these files to make your customizations. For example:

See the following directories in WAS V6.1 and later for the "default" profile/server:

/qibm/userdata/websphere/appserver/<version>/<edition>/profiles/default/etc/*

/qibm/userdata/websphere/appserver/<version>/<edition>/profiles/default/properties/*

If you are not using the default profile, you would customize the files under your custom profile's ../etc/ and .../properties/ directories.

See the WebSphere application server documentation for further information. Search on "Securing the full profile".

[{"Type":"MASTER","Line of Business":{"code":"LOB57","label":"Power"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000001gHbAAI","label":"Java Development Kit->Java Secure Socket Extension"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"7.1.0;7.2.0;7.3.0;7.4.0"}]

Historical Number

522315206

Document Information

Modified date:
19 January 2022

UID

nas8N1012992