Added additional crypt parameter configuration

Author: phax

phase4-lib/src/main/java/com/helger/phase4/crypto/AS4CryptParams.java

@@ -56,6 +56,13 @@ public class AS4CryptParams implements ICloneable <AS4CryptParams>
   public static final ICryptoSessionKeyProvider DEFAULT_SESSION_KEY_PROVIDER = ICryptoSessionKeyProvider.INSTANCE_RANDOM_AES_128;
   public static final boolean DEFAULT_ENCRYPT_SYMMETRIC_SESSION_KEY = true;
 
+  /**
+   * HKDF PRF algorithm URI for HMAC-SHA256, as required by eDelivery AS4 2.0
+   *
+   * @since 4.4.0
+   */
+  public static final String HKDF_PRF_HMAC_SHA256 = WSS4JConstants.HMAC_SHA256;
+
   private static final Logger LOGGER = Phase4LoggerFactory.getLogger (AS4CryptParams.class);
 
   // The key identifier type to use
@@ -68,6 +75,14 @@ public class AS4CryptParams implements ICloneable <AS4CryptParams>
   private String m_sMGFAlgorithm = DEFAULT_MGF_ALGORITHM;
   // The digest algorithm to use with the RSA-OAEP key transport algorithm
   private String m_sDigestAlgorithm = DEFAULT_DIGEST_ALGORITHM;
+  // Key agreement method (e.g. X25519, X448, ECDH-ES) - null means no key
+  // agreement (use key transport instead)
+  private ECryptoKeyAgreementMethod m_eKeyAgreementMethod;
+  // Key derivation function (e.g. HKDF, ConcatKDF) - only used with key
+  // agreement
+  private ECryptoKeyDerivationMethod m_eKeyDerivationMethod;
+  // Key wrap algorithm (e.g. AES-128 KeyWrap) - only used with key agreement
+  private ECryptoKeyWrapAlgorithm m_eKeyWrapAlgorithm;
   // The explicit certificate to use - has precedence over the alias
   private X509Certificate m_aCert;
   // The alias into the WSS4J crypto config
@@ -220,6 +235,121 @@ public final AS4CryptParams setDigestAlgorithm (@NonNull @Nonempty final String
     return this;
   }
 
+  /**
+   * @return The key agreement method to use. May be <code>null</code>, in which case key transport
+   *         (e.g. RSA-OAEP) is used instead of key agreement.
+   * @since 4.4.0
+   */
+  @Nullable
+  public final ECryptoKeyAgreementMethod getKeyAgreementMethod ()
+  {
+    return m_eKeyAgreementMethod;
+  }
+
+  /**
+   * @return <code>true</code> if a key agreement method is set, <code>false</code> if not.
+   * @since 4.4.0
+   */
+  public final boolean hasKeyAgreementMethod ()
+  {
+    return m_eKeyAgreementMethod != null;
+  }
+
+  /**
+   * Set the key agreement method to use. When set, the encryption will use key agreement (e.g.
+   * ECDH-ES, X25519) instead of key transport (e.g. RSA-OAEP). If set to <code>null</code>, key
+   * transport is used.
+   *
+   * @param eKeyAgreementMethod
+   *        The key agreement method. May be <code>null</code>.
+   * @return this for chaining
+   * @since 4.4.0
+   */
+  @NonNull
+  public final AS4CryptParams setKeyAgreementMethod (@Nullable final ECryptoKeyAgreementMethod eKeyAgreementMethod)
+  {
+    m_eKeyAgreementMethod = eKeyAgreementMethod;
+    return this;
+  }
+
+  /**
+   * @return The key derivation function to use with key agreement. May be <code>null</code>.
+   * @since 4.4.0
+   */
+  @Nullable
+  public final ECryptoKeyDerivationMethod getKeyDerivationMethod ()
+  {
+    return m_eKeyDerivationMethod;
+  }
+
+  /**
+   * Set the key derivation function to use with key agreement (e.g. HKDF, ConcatKDF).
+   *
+   * @param eKeyDerivationMethod
+   *        The key derivation method. May be <code>null</code>.
+   * @return this for chaining
+   * @since 4.4.0
+   */
+  @NonNull
+  public final AS4CryptParams setKeyDerivationMethod (@Nullable final ECryptoKeyDerivationMethod eKeyDerivationMethod)
+  {
+    m_eKeyDerivationMethod = eKeyDerivationMethod;
+    return this;
+  }
+
+  /**
+   * @return The key wrap algorithm to use with key agreement. May be <code>null</code>.
+   * @since 4.4.0
+   */
+  @Nullable
+  public final ECryptoKeyWrapAlgorithm getKeyWrapAlgorithm ()
+  {
+    return m_eKeyWrapAlgorithm;
+  }
+
+  /**
+   * Set the key wrap algorithm to use with key agreement (e.g. AES-128 KeyWrap).
+   *
+   * @param eKeyWrapAlgorithm
+   *        The key wrap algorithm. May be <code>null</code>.
+   * @return this for chaining
+   * @since 4.4.0
+   */
+  @NonNull
+  public final AS4CryptParams setKeyWrapAlgorithm (@Nullable final ECryptoKeyWrapAlgorithm eKeyWrapAlgorithm)
+  {
+    m_eKeyWrapAlgorithm = eKeyWrapAlgorithm;
+    return this;
+  }
+
+  /**
+   * Convenience method to set all parameters required for eDelivery AS4 2.0 EdDSA/X25519 key
+   * agreement: X25519 key agreement, HKDF key derivation, AES-128 key wrap.
+   *
+   * @return this for chaining
+   * @since 4.4.0
+   */
+  @NonNull
+  public final AS4CryptParams setEDelivery2KeyAgreementX25519 ()
+  {
+    return setKeyAgreementMethod (ECryptoKeyAgreementMethod.X25519).setKeyDerivationMethod (ECryptoKeyDerivationMethod.HKDF)
+                                                                   .setKeyWrapAlgorithm (ECryptoKeyWrapAlgorithm.AES_128);
+  }
+
+  /**
+   * Convenience method to set all parameters required for eDelivery AS4 2.0 ECDSA/ECDH-ES key
+   * agreement: ECDH-ES key agreement, HKDF key derivation, AES-128 key wrap.
+   *
+   * @return this for chaining
+   * @since 4.4.0
+   */
+  @NonNull
+  public final AS4CryptParams setEDelivery2KeyAgreementECDHES ()
+  {
+    return setKeyAgreementMethod (ECryptoKeyAgreementMethod.ECDH_ES).setKeyDerivationMethod (ECryptoKeyDerivationMethod.HKDF)
+                                                                    .setKeyWrapAlgorithm (ECryptoKeyWrapAlgorithm.AES_128);
+  }
+
   /**
    * @return The currently set X509 certificate. May be <code>null</code>.
    */
@@ -462,6 +592,9 @@ public void cloneTo (@NonNull final AS4CryptParams aTarget)
            .setKeyEncAlgorithm (m_eKeyEncAlgorithm)
            .setMGFAlgorithm (m_sMGFAlgorithm)
            .setDigestAlgorithm (m_sDigestAlgorithm)
+           .setKeyAgreementMethod (m_eKeyAgreementMethod)
+           .setKeyDerivationMethod (m_eKeyDerivationMethod)
+           .setKeyWrapAlgorithm (m_eKeyWrapAlgorithm)
            .setCertificate (m_aCert)
            .setAlias (m_sAlias)
            .setSessionKeyProvider (m_aSessionKeyProvider)
@@ -488,6 +621,9 @@ public String toString ()
                                        .append ("KeyEncAlgorithm", m_eKeyEncAlgorithm)
                                        .append ("MGFAlgorithm", m_sMGFAlgorithm)
                                        .append ("DigestAlgorithm", m_sDigestAlgorithm)
+                                       .appendIfNotNull ("KeyAgreementMethod", m_eKeyAgreementMethod)
+                                       .appendIfNotNull ("KeyDerivationMethod", m_eKeyDerivationMethod)
+                                       .appendIfNotNull ("KeyWrapAlgorithm", m_eKeyWrapAlgorithm)
                                        .append ("Certificate", m_aCert)
                                        .append ("Alias", m_sAlias)
                                        .append ("SessionKeyProvider", m_aSessionKeyProvider)

phase4-lib/src/main/java/com/helger/phase4/crypto/AS4CryptoFactoryConfiguration.java

@@ -38,11 +38,10 @@
 import com.helger.security.keystore.LoadedKeyStore;
 
 /**
- * phase4 crypto factory settings based on {@link IConfig}. The configuration
- * elements are solely taken from the global configuration and not from
- * arbitrary files. Multiple different crypto factory configurations can be
- * handled uses different configuration property prefixes. This class only
- * supports {@link Merlin} as the crypto implementation.
+ * phase4 crypto factory settings based on {@link IConfig}. The configuration elements are solely
+ * taken from the global configuration and not from arbitrary files. Multiple different crypto
+ * factory configurations can be handled uses different configuration property prefixes. This class
+ * only supports {@link Merlin} as the crypto implementation.
  *
  * @author Philip Helger
  * @since 3.0.0
@@ -53,9 +52,8 @@ public class AS4CryptoFactoryConfiguration extends AS4CryptoFactoryInMemoryKeySt
   private static final Logger LOGGER = Phase4LoggerFactory.getLogger (AS4CryptoFactoryConfiguration.class);
 
   /**
-   * @return The default instance, created by reading the default properties
-   *         from the configuration sources (application.properties, environment
-   *         variables and Java system properties).
+   * @return The default instance, created by reading the default properties from the configuration
+   *         sources (application.properties, environment variables and Java system properties).
    * @throws Phase4RuntimeException
    *         if one of the mandatory configuration parameters is not present.
    */
@@ -68,8 +66,8 @@ public static AS4CryptoFactoryConfiguration getDefaultInstance () throws Phase4R
   }
 
   /**
-   * Same as {@link #getDefaultInstance()} just that it returns
-   * <code>null</code> instead of throwing a RuntimeException.
+   * Same as {@link #getDefaultInstance()} just that it returns <code>null</code> instead of
+   * throwing a RuntimeException.
    *
    * @return <code>null</code> in case of error.
    */
@@ -93,8 +91,8 @@ public static AS4CryptoFactoryConfiguration getDefaultInstanceOrNull ()
   private final ITrustStoreDescriptor m_aTrustStorDesc;
 
   /**
-   * This constructor takes the configuration object and uses the default prefix
-   * for backwards compatibility. This is kind of the default constructor.
+   * This constructor takes the configuration object and uses the default prefix for backwards
+   * compatibility. This is kind of the default constructor.
    *
    * @param aConfig
    *        The configuration object to be used. May not be <code>null</code>.
@@ -175,14 +173,14 @@ private static ITrustStoreDescriptor _loadTrustStore (@NonNull final IConfigWith
   }
 
   /**
-   * This constructor takes the configuration object and uses the provided
-   * configuration prefix. This is kind of the default constructor.
+   * This constructor takes the configuration object and uses the provided configuration prefix.
+   * This is kind of the default constructor.
    *
    * @param aConfig
    *        The configuration object to be used. May not be <code>null</code>.
    * @param sConfigPrefix
-   *        The configuration prefix to be used. May neither be
-   *        <code>null</code> nor empty and must end with a dot ('.').
+   *        The configuration prefix to be used. May neither be <code>null</code> nor empty and must
+   *        end with a dot ('.').
    * @throws Phase4RuntimeException
    *         If loading the key store configuration from configuration fails.
    */
@@ -194,14 +192,14 @@ public AS4CryptoFactoryConfiguration (@NonNull final IConfigWithFallback aConfig
   }
 
   /**
-   * This constructor takes the configuration object and uses the provided
-   * configuration prefix. This is kind of the default constructor.
+   * This constructor takes the configuration object and uses the provided configuration prefix.
+   * This is kind of the default constructor.
    *
    * @param aConfig
    *        The configuration object to be used. May not be <code>null</code>.
    * @param sConfigPrefix
-   *        The configuration prefix to be used. May neither be
-   *        <code>null</code> nor empty and must end with a dot ('.').
+   *        The configuration prefix to be used. May neither be <code>null</code> nor empty and must
+   *        end with a dot ('.').
    * @param bLogError
    *        <code>true</code> if errors should be logged if loading fails.
    * @throws Phase4RuntimeException
@@ -220,8 +218,8 @@ public AS4CryptoFactoryConfiguration (@NonNull final IConfigWithFallback aConfig
    * @param aKeyStoreDesc
    *        The key store descriptor. May not be <code>null</code>.
    * @param aTrustStoreDesc
-   *        The trust store descriptor. May be <code>null</code> in which case
-   *        the global JRE CA certs list will be used.
+   *        The trust store descriptor. May be <code>null</code> in which case the global JRE CA
+   *        certs list will be used.
    */
   private AS4CryptoFactoryConfiguration (@NonNull final IKeyStoreAndKeyDescriptor aKeyStoreDesc,
                                          @Nullable final ITrustStoreDescriptor aTrustStoreDesc)
@@ -241,8 +239,7 @@ public IKeyStoreAndKeyDescriptor getKeyStoreDescriptor ()
   }
 
   /**
-   * @return The descriptor used to load the trust store. Never
-   *         <code>null</code>.
+   * @return The descriptor used to load the trust store. Never <code>null</code>.
    */
   @NonNull
   public ITrustStoreDescriptor getTrustStoreDescriptor ()

phase4-lib/src/main/java/com/helger/phase4/crypto/ECryptoKeyAgreementMethod.java

@@ -0,0 +1,69 @@
+/*
+ * Copyright (C) 2015-2026 Philip Helger (www.helger.com)
+ * philip[at]helger[dot]com
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.helger.phase4.crypto;
+
+import org.apache.wss4j.common.WSS4JConstants;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
+import com.helger.annotation.Nonempty;
+import com.helger.base.id.IHasID;
+import com.helger.base.lang.EnumHelper;
+
+/**
+ * Enumeration of key agreement methods for XML Encryption. Key agreement is an alternative to key
+ * transport (e.g. RSA-OAEP) where both parties contribute to deriving a shared secret.
+ *
+ * @author Philip Helger
+ * @since 4.4.0
+ */
+public enum ECryptoKeyAgreementMethod implements IHasID <String>
+{
+  /** ECDH-ES key agreement (generic, for EC keys on standard curves like secp256r1) */
+  ECDH_ES (WSS4JConstants.AGREEMENT_METHOD_ECDH_ES),
+  /** X25519 key agreement (Curve25519, eDelivery AS4 2.0 Common Usage Profile) */
+  X25519 (WSS4JConstants.AGREEMENT_METHOD_X25519),
+  /** X448 key agreement (Curve448) */
+  X448 (WSS4JConstants.AGREEMENT_METHOD_X448);
+
+  private final String m_sID;
+
+  ECryptoKeyAgreementMethod (@NonNull @Nonempty final String sID)
+  {
+    m_sID = sID;
+  }
+
+  @NonNull
+  @Nonempty
+  public String getID ()
+  {
+    return m_sID;
+  }
+
+  @Nullable
+  public static ECryptoKeyAgreementMethod getFromIDOrNull (@Nullable final String sID)
+  {
+    return EnumHelper.getFromIDOrNull (ECryptoKeyAgreementMethod.class, sID);
+  }
+
+  @Nullable
+  public static ECryptoKeyAgreementMethod getFromIDOrDefault (@Nullable final String sID,
+                                                              @Nullable final ECryptoKeyAgreementMethod eDefault)
+  {
+    return EnumHelper.getFromIDOrDefault (ECryptoKeyAgreementMethod.class, sID, eDefault);
+  }
+}