Configuration

The primary configuration file for phase4 is called application.properties but you can also use the legacy name phase4.properties. For historic reasons, settings in phase4.properties has higher precedence, but application.properties has smarter ways to resolve it and is therefore preferred. It contains both the phase4 specific configuration items as well as the WSS4J ones (see https://ws.apache.org/wss4j/config.html). The resolution of the configuration properties is not bound to the configuration file - system properties and environment variables can also be used. See https://github.com/phax/ph-commons/wiki/ph-config for details. Upon resolution of configuration values, Java system properties have the highest priority (400), before environment variables (300), the file phase4.properties (203), the file private-application.json (195), the file private-application.properties (190), the file application.json (185), the file application.properties (180) and finally the file reference.properties (1).

Note: programmatic access to the configuration is solely achieved via class com.helger.phase4.config.AS4Configuration.

WSS4J properties

Note: the descriptions and the default values are taken from WSS4J.

• org.apache.wss4j.crypto.provider (unused since v3.0.0): WSS4J specific provider used to create Crypto instances. Defaults to org.apache.wss4j.common.crypto.Merlin.

• org.apache.wss4j.crypto.merlin.keystore.type: the keystore type. Usually one of JKS or PKCS12. Defaults to java.security.KeyStore.getDefaultType().

• org.apache.wss4j.crypto.merlin.keystore.file: the path to the keystore. Can be an entry in the class path, a URL or an absolute file path.

• org.apache.wss4j.crypto.merlin.keystore.password: the password to the whole keystore.

• org.apache.wss4j.crypto.merlin.keystore.alias: the alias of the key to be used inside the keystore. Hint case sensitivity may be important here.

• org.apache.wss4j.crypto.merlin.keystore.private.password: the password to access the key only. May be different from the keystore password.

• org.apache.wss4j.crypto.merlin.load.cacerts (unused since v3.0.0): Whether or not to load the CA certificates in ${java.home}/lib/security/cacerts (default is false).

• org.apache.wss4j.crypto.merlin.truststore.provider (unused since v3.0.0): The provider used to load truststores. By default it’s the same as the keystore provider. Set to an empty value to force use of the JRE’s default provider.

• org.apache.wss4j.crypto.merlin.truststore.type: The truststore type. Usually one of JKS or PKCS12. Defaults to java.security.KeyStore.getDefaultType().

• org.apache.wss4j.crypto.merlin.truststore.file: The location of the truststore. Can be an entry in the class path, a URL or an absolute file path.

• org.apache.wss4j.crypto.merlin.truststore.password: The truststore password. Defaults to changeit.

Note: for Peppol users the key store must contain the AccessPoint private key and the truststore must contain the Peppol truststore.

Multi profile key store and trust store configuration

This works with version 3.0.0-beta2 and onwards only.

Multiple key stores may be configured below a selectable configuration prefix (the below example uses 'dummy'), followed by constant sub-properties:

• dummy.keystore.type: the keystore type. Usually one of JKS or PKCS12.
• dummy.keystore.file: the path to the keystore. Can be an entry in the class path, a URL or an absolute file path.
• dummy.keystore.password: the password to the whole keystore.
• dummy.keystore.alias: the alias of the key to be used inside the keystore. Hint case sensitivity may be important here.
• dummy.keystore.private.password: the password to access the key only. May be different from the keystore password.

Multiple trust stores may be configured below a selectable configuration prefix (the below example uses 'dummy'), followed by constant sub-properties:

• dummy.truststore.type: The truststore type. Usually one of JKS or PKCS12.
• dummy.truststore.file: The location of the truststore. Can be an entry in the class path, a URL or an absolute file path.
• dummy.truststore.password: The truststore password.

Note: For the default key store and trust store, the configuration prefix is automatically org.apache.wss4j.crypto.merlin

Note: To use multiple key stores and trust stores, you need to provide the respective configuration prefix to the constructor of AS4CryptoFactoryConfiguration

phase4 properties

The properties have the following meaning

• global.debug: enable or disable the global debugging mode in the system. It is recommended to have this always set to false except you are developing with the components. Valid values are true and false.

• global.production: enable or disable the global production mode in the system. It is recommended to have this set to true when running an instance in a production like environment to improve performance and limit internal checks. Valid values are true and false.

• global.nostartupinfo: disable the logging of certain internals upon server startup when set to true. Valid values are true and false.

• global.datapath: the writable directory where the server stores data. It is recommended to be an absolute path (starting with /). The default value is the relative directory conf.

• phase4.manager.inmemory: if this property is set to true than phase4 will not create persistent data for PModes ands other domain objects. The default value is true.

• phase4.wss4j.syncsecurity: if this property is set to true all signing, encryption, signature verification and decryption is linearized in an artificial lock. This should help working around the https://issues.apache.org/jira/browse/WSS-660 bug if one Java runtime needs to contain multiple instances of phase4. Note: this flag is still experimental. Note: this is only a work-around if only phase4 based applications run in the same Java runtime - if other WSS4J applications (like e.g. Oxalis) are also run, this switch does not solve the issue. Defaults to false.

• phase4.default.profile (before 3.0.0-beta2: phase4.profile): a specific AS4 profile ID to be used, if none was configured. This property should not be set in a multi-profile environment to avoid unwanted side effects.

• phase4.incoming.duplicatedisposal.minutes: the number of minutes a message is kept for duplication check. After that time, the same message can be retrieved again. Valid values are integer numbers ≥ 0. The default value is 10.

• phase4.dump.path: the base path where dumps of incoming and outgoing files should be created, if the respective dumpers are activated. The default value is phase4-dumps relative to the current working directory.

• phase4.endpoint.address: the public URL of this AS4 server to send responses to. This value is optional. This value is checked by the underlying profile.

  • In the case of Peppol and CEF, this value needs to have the https protocol (except the global debug mode is enabled in which case the http protocol is also allowed)
  • In the case of ENTSOG this value needs to be http or https

• phase4.errormsg.include.stacktraces (since v2.7.5): by setting this value to false stack traces will not be included in AS4 Error Messages. The default is true for backwards compatibility reason