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 (IBM Technology for Java VM) on IBM i OS

Resolving The Problem

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

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.
 
JDK70, JDK80
/QOpenSys/QIBM/ProdData/JavaVM/jdkxx/xxbit/jre/lib/security/
JDK11, JDK17
/QOpenSys/QIBM/ProdData/JavaVM/jdk11/64bit/conf/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":"LOB68","label":"Power HW"},"Business Unit":{"code":"BU070","label":"IBM Infrastructure"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000001gHbAAI","label":"Java Development Kit-\u003EJava 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:
17 June 2024

UID

nas8N1012992

Page Feedback