AS4 uses the OASIS WS-Security standard to protect SOAP messages. phase4 delegates all cryptographic operations to the Apache WSS4J library, which implements WS-Security 1.0 and 1.1.Two security operations are applied to AS4 messages:
Operation
Purpose
Direction
Signing
Proves the message was sent by the claimed party and has not been altered
Outbound — sign with your private key; inbound — verify with sender’s certificate
Encryption
Ensures only the intended recipient can read the payload
Outbound — encrypt with receiver’s public key; inbound — decrypt with your private key
Signing and encryption are separate operations. A message can be signed only, encrypted only, both, or neither — depending on the profile and PMode security settings.
IAS4CryptoFactory is the central crypto abstraction in phase4. It provides:
A WSS4J Crypto object for signing and verification operations
Access to the signing key store and private key entry
Access to the trust store for validating inbound signatures
public interface IAS4CryptoFactory { // Returns the WSS4J Crypto instance for the given mode (sign or encrypt) Crypto getCrypto(ECryptoMode eCryptoMode); // Returns the key store backing this factory KeyStore getKeyStore(); // Returns the private key entry (alias + key + certificate chain) KeyStore.PrivateKeyEntry getPrivateKeyEntry(); // Returns the alias used to look up the private key String getKeyAlias(); // Returns the key password for the given alias char[] getKeyPasswordPerAliasCharArray(String sSearchKeyAlias); // Returns the trust store (for validating inbound certificates) KeyStore getTrustStore();}
phase4 ships two ready-to-use implementations:
AS4CryptoFactoryInMemoryKeyStore
Accepts KeyStore objects you load programmatically. Nothing is read from disk at construction time. Use this when you manage key stores in your application.
AS4CryptoFactoryConfiguration
Reads key store path, alias, and password from the global phase4 configuration file (phase4.properties / application.properties). Suitable for file-based deployments.
Use AS4CryptoFactoryInMemoryKeyStore when you load key stores from your application’s classpath, a database, or a secrets manager.
// Load your key store (PKCS12 or JKS)KeyStore keyStore = KeyStore.getInstance("PKCS12");try (InputStream is = getClass().getResourceAsStream("/my-keystore.p12")) { keyStore.load(is, "keystore-password".toCharArray());}// Load your trust store (contains trusted CA certificates)KeyStore trustStore = KeyStore.getInstance("JKS");try (InputStream ts = getClass().getResourceAsStream("/my-truststore.jks")) { trustStore.load(ts, "truststore-password".toCharArray());}// Create the factoryIAS4CryptoFactory cryptoFactory = new AS4CryptoFactoryInMemoryKeyStore( keyStore, "my-key-alias", // alias of the private key entry "key-password".toCharArray(), // password for that key entry trustStore // null to fall back to JRE cacerts);
You can also pass IKeyStoreAndKeyDescriptor and ITrustStoreDescriptor descriptors from the com.helger.security.keystore package if you use the helger security infrastructure:
// Use the built-in defaults (RSA-SHA256 + SHA-256 digest)AS4SigningParams signingParams = AS4SigningParams.createDefault();// Or configure explicitlyAS4SigningParams signingParams = new AS4SigningParams() .setAlgorithmSign(ECryptoAlgorithmSign.RSA_SHA_256) .setAlgorithmSignDigest(ECryptoAlgorithmSignDigest.DIGEST_SHA_256) .setAlgorithmC14N(ECryptoAlgorithmC14N.C14N_ALGORITHM_DEFAULT) .setKeyIdentifierType(ECryptoKeyIdentifierType.BST_DIRECT_REFERENCE);// For Peppol — single certificate BST value type (#X509v3)signingParams.setUseSingleCertificate(true);// Check if signing is enabled (both algorithm and digest must be set)boolean enabled = signingParams.isSigningEnabled();
Call AS4SigningParams.createDefault() to get a pre-configured instance using ECryptoAlgorithmSign.SIGN_ALGORITHM_DEFAULT (RSA_SHA_256) and ECryptoAlgorithmSignDigest.SIGN_DIGEST_ALGORITHM_DEFAULT (DIGEST_SHA_256). This matches the most common AS4 deployments.
// Use the built-in default (AES-128-GCM)AS4CryptParams cryptParams = AS4CryptParams.createDefault();// Or configure explicitly — requires an algorithm plus either an alias or certificateAS4CryptParams cryptParams = new AS4CryptParams() .setAlgorithmCrypt(ECryptoAlgorithmCrypt.AES_128_GCM) .setAlias("receiver-certificate-alias"); // alias in the key/trust store// Alternatively, set the recipient certificate directlyAS4CryptParams cryptParams = new AS4CryptParams() .setAlgorithmCrypt(ECryptoAlgorithmCrypt.AES_128_GCM) .setCertificate(receiverX509Certificate);// Key transport algorithm (used to encrypt the symmetric session key)cryptParams.setKeyEncAlgorithm(ECryptoKeyEncryptionAlgorithm.RSA_OAEP_XENC11);// Check if encryption is enabledboolean enabled = cryptParams.isCryptEnabled(warning -> System.out.println(warning));
The trust store contains the CA certificates used to validate inbound signatures. If you pass null as the trust store to AS4CryptoFactoryInMemoryKeyStore, phase4 falls back to the JRE’s default cacerts trust store.
Network-specific trust stores (such as the Peppol SMP root CA) are not in the JRE cacerts. Always provide an explicit trust store when connecting to closed networks.