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, JDK21
/QOpenSys/QIBM/ProdData/JavaVM/jdkxx/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/TLS TrustStore

javax.net.ssl.trustStore=<path to trust store>
  • For example:
    javax.net.ssl.trustStore=/home/cacerts
==========================================
SSL/TLS 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 IBM WebSphere Application Server v8.5, v8.0, v7.0, and v6.1 profiles, 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 v8.5, v8.0, v7.0, and v6.1 for your custom profile/server:

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

For WAS v8.5 profiles, refer to this document.
How To Enable the TLSv1.3 & TLSv1.2 Protocols for a WebSphere Application Server v8.5 and v9.0 Profile on IBM i OS

See Securing Application and their environment documentation for more information.

[{"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":"All Versions"}]

Historical Number

522315206

Document Information

More support for:
IBM i

Component:
Java Development Kit->Java Secure Socket Extension

Software version:
All Versions

Operating system(s):
IBM i

Document number:
634649

Modified date:
07 May 2025

UID

nas8N1012992

Manage My Notification Subscriptions