Contact Us 1-800-596-4880
  1. Homepage
  2. AS2 Connector (7.0)

  3. Upgrading and Migrating AS2 Connector to Version 6.x

All Connectors

Upgrading and Migrating AS2 Connector to Version 7.x

Upgrade Anypoint Connector for AS2 (AS2 Connector) from version 6.x to 7.x to take advantage of FIPS-compliant cryptographic support and other improvements.

Supported Upgrade Paths

From Version To Version

6.x

7.x

Before You Begin

Before you upgrade to AS2 Connector 7.x, make sure you have:

  • Mule runtime 4.4.0 or later. See the Mule runtime release notes for FIPS support by version.

  • AS2 Connector version 7.0.0 or later.

  • AS2 Support Libraries version 3.0.0 or later.

  • For non-FIPS mode, Bouncy Castle Java Cryptography Extension (JCE) provider designed for JDK 1.8 or higher. This configuration requires the bcprov-jdk18on and bcpkix-jdk18on libraries. Version 1.82 is recommended.

  • For FIPS modes, Bouncy Castle FIPS (BCFIPS) libraries as required by your Mule runtime and security model.

  • For FIPS 140-3, Java 17 or later with FIPS-capable JVM if required by your deployment.

Supported Security Modes

AS2 Connector 7.x supports these security modes, which are controlled by the mule.security.model system property:

  • non-FIPS (default)

    This is the default security mode for Mule applications that don’t require FIPS compliance. AS2 Connector uses the standard cryptographic libraries bcprov-jdk18on and bcpkix-jdk18on, which aren’t FIPS compliant. Don’t set the system property as the default mode.

  • FIPS 140-2 Compliant Mode

    Enable this security mode to configure AS2 Connector to use FIPS 140-2 approved cryptographic providers.

  • FIPS 140-3 Compliant Mode

    Enable this security mode to configure AS2 Connector to use FIPS 140-3 approved cryptographic providers.

If the mule.security.model property begins with fips140-, then AS2 Connector activates FIPS mode and applies the corresponding security controls, as shown in the example.

-Dmule.security.model=fips140-3

Configure External Libraries

Mule applications using AS2 Connector require a Global Element configuration that includes the necessary AS2 support and cryptographic libraries for each security mode. The table shows the global configuration and required libraries for each security mode. Use only one security mode per application.

For FIPS modes, the Mule runtime and BCFIPS requirements apply.

Security Mode Global Configuration Default Name Required Library Maven Coordinates

non-FIPS

AS2 Connector External Libs - Non FIPS

AS2_Connector_External_Libs___Non_FIPS

com.mulesoft.connectors:as2-bc-non-fips-impl:3.0.0, org.bouncycastle:bcpkix-jdk18on:1.82, org.bouncycastle:bcprov-jdk18on:1.82

FIPS 140-2

AS2 Connector External Libs - FIPS 140-2

AS2_Connector_External_Libs___FIPS_140_2

com.mulesoft.connectors:as2-bc1-fips-impl:3.0.0

FIPS 140-3

AS2 Connector External Libs - FIPS 140-3

AS2_Connector_External_Libs___FIPS_140_3

com.mulesoft.connectors:as2-bc2-fips-impl:3.0.0
Connector configurations that are used for creating Global Elements

Upgrade Steps

Follow these steps to upgrade from AS2 Connector 6.x to 7.x. Use the configuration that applies to your selected security mode.

Step 1: Update the Connector Dependency

  1. Update your project’s pom.xml file to use AS2 Connector 7.x:

<dependency>
    <groupId>com.mulesoft.connectors</groupId>
    <artifactId>mule-as2-connector</artifactId>
    <version>7.0.0</version>
    <classifier>mule-plugin</classifier>
</dependency>

  1. Rebuild the project and resolve API or configuration changes reported by the build.

Step 2: Add a Connector Configuration Global Element

Include only one external library global configuration. Follow the global element configuration steps for your selected security mode.

Configure a Global Element for the non-FIPS Security Mode

  1. Add the external library global configuration and don’t set the runtime property. Also, make sure the BouncyCastle jdk18on library version 1.82 is available to add as an external library.

  2. Configure the global element as a Mule app in Anypoint Studio:

    1. In the Package Explorer or Anypoint Studio canvas, open your Mule flow or configuration.

    2. Click Global Elements. Or click Create global element, and then click the plus icon next to Global Elements.

  3. Click Create, and then search for the AS2 or External Libs option and select AS2 Connector External Libs - Non FIPS.

    1. Name the configuration.

    2. Click Configure > Add recommended libraries.

    3. Click OK to include the libraries as dependencies and shared libraries in the Mule application pom.xml file.

  4. Verify that your project has the required dependencies for your selected security mode. Add the dependencies via Maven if they aren’t added automatically.

The Connector Configuration Global Element and the configurations for non-FIPS security mode

To configure the global element manually in XML (Maven or standalone):

  1. Open your main Mule configuration file, such as src/main/mule/ or src/main/resources/.

  2. Add the as2-mule4:external-libs-non-fips-config global element to the Mule configuration file.

  3. Add the AS2 Connector External Libs - Non FIPS global configuration to your Mule configuration file, as shown in the example:

<as2-mule4:external-libs-non-fips-config name="AS2_External_Libs_Non_FIPS" />

  1. Add the required Maven dependencies to the pom.xml file. Refer to the AS2 Connector Release Notes for the compatible versions of the dependencies.

<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcpkix-jdk18on</artifactId>
    <version>${bouncy.castle.jdk18on.version}</version>
</dependency>
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk18on</artifactId>
    <version>${bouncy.castle.jdk18on.version}</version>
</dependency>
<dependency>
    <groupId>com.mulesoft.connectors</groupId>
    <artifactId>as2-bc-non-fips-impl</artifactId>
    <version>${as2.support.library.version}</version>
</dependency>

  1. Update the mule-maven-plugin by including the shared libraries in the build > plugins > plugin section of the pom.xml file.

<configuration>
  <sharedLibraries>
    <sharedLibrary>
      <groupId>com.mulesoft.connectors</groupId>
      <artifactId>as2-bc-non-fips-impl</artifactId>
    </sharedLibrary>
    <sharedLibrary>
      <groupId>org.bouncycastle</groupId>
      <artifactId>bcpkix-jdk18on</artifactId>
    </sharedLibrary>
    <sharedLibrary>
      <groupId>org.bouncycastle</groupId>
      <artifactId>bcprov-jdk18on</artifactId>
    </sharedLibrary>
  </sharedLibraries>
</configuration>

Configure a Global Element for the FIPS 140-2 Security Mode

  1. Add the external library global configuration and set the runtime property. Also, make sure BouncyCastle FIPS (BCFIPS) is available as required by your Mule runtime. Configure BCFIPS in Java Security.

    For FIPS 140-2, follow the FIPS 140-2 Compliance Support documentation.

  2. Configure the global element as a Mule app in Anypoint Studio:

    1. In the Package Explorer or Anypoint Studio canvas, open your Mule flow or configuration.

    2. Click Global Elements. Or click Create global element, and then click the plus icon next to Global Elements.

  3. Click Create, and then search for the AS2 or External Libs option and select AS2 Connector External Libs - FIPS 140-2.

    1. Name the configuration.

    2. Click Configure > Add recommended libraries.

    3. Click OK to include the libraries as dependencies and shared libraries in the Mule application pom.xml file.

  4. Verify that your project has the required dependencies for your selected security mode. Add the dependencies via Maven if they aren’t added automatically.

The Connector Configuration Global Element and the configurations for FIPS 140-2 security mode

To configure the global element manually in XML (Maven or standalone):

  1. Open your main Mule configuration file, such as src/main/mule/ or src/main/resources/.

  2. Add the as2-mule4:external-libs-fips140-2-config global element to the Mule configuration file.

  3. Add the AS2 Connector External Libs - FIPS 140-2 global configuration to your Mule configuration file, as shown in the example.

<as2-mule4:external-libs-fips140-2-config name="AS2_External_Libs_FIPS_140_2" />

  1. Add the required Maven dependencies to the pom.xml file. Refer to the AS2 Connector Release Notes for the compatible versions of the dependencies.

<dependency>
    <groupId>com.mulesoft.connectors</groupId>
    <artifactId>as2-bc1-fips-impl</artifactId>
    <version>${as2.support.library.version}</version>
</dependency>

  1. Update the mule-maven-plugin by including the shared libraries in the build > plugins > plugin section of the pom.xml file.

<configuration>
  <sharedLibraries>
    <sharedLibrary>
      <groupId>com.mulesoft.connectors</groupId>
      <artifactId>as2-bc1-fips-impl</artifactId>
    </sharedLibrary>
  </sharedLibraries>
</configuration>

  1. In JVM or Mule runtime, set the security model to FIPS 140-2.

-Dmule.security.model=fips140-2

  1. Restrict BCFIPS to use only FIPS-approved algorithms.

-Dorg.bouncycastle.fips.approved_only=true

This example shows the Mule runtime startup configuration for FIPS 140-2:

java -Dmule.security.model=fips140-2 \
  -Dorg.bouncycastle.fips.approved_only=true \
  -jar mule-standalone.jar

Configure a Global Element for the FIPS 140-3 Security Mode

  1. Add the external library global configuration and set the runtime property. Also:

    • Make sure BouncyCastle FIPS (BCFIPS) is available as required by your Mule runtime.

    • Configure BCFIPS in Java Security or by following the Mule runtime FIPS documentation for your version.

    • Make sure you have Java 17 or later as required for FIPS 140-3 support in your deployment.

  2. Configure the global element as a Mule app in Anypoint Studio:

    1. In the Package Explorer or Anypoint Studio canvas, open your Mule flow or configuration.

    2. Click Global Elements. Or click Create global element, and then click the plus icon next to Global Elements.

  3. Click Create, and then search for the AS2 or External Libs option and select AS2 Connector External Libs - FIPS 140-3.

    1. Name the configuration.

    2. Click Configure > Add recommended libraries.

    3. Click OK to include the libraries as dependencies and shared libraries in the Mule application pom.xml file.

  4. Verify that your project has the required dependencies for your selected security mode. Add the dependencies via Maven if they aren’t added automatically.

The Connector Configuration Global Element and the configurations for FIPS 140-3 security mode

To configure the global element manually in XML (Maven or standalone):

  1. Open your main Mule configuration file, such as src/main/mule/ or src/main/resources/.

  2. Add the as2-mule4:external-libs-fips140-3-config global element to the Mule configuration file.

  3. Add the AS2 Connector External Libs - FIPS 140-3 global configuration to your Mule configuration file, as shown in the example:

<as2-mule4:external-libs-fips140-3-config name="AS2_External_Libs_FIPS_140_3" />

  1. Add the required Maven dependencies to the pom.xml file. Refer to the AS2 Connector Release Notes for the compatible versions of the dependencies.

<dependency>
    <groupId>com.mulesoft.connectors</groupId>
    <artifactId>as2-bc2-fips-impl</artifactId>
    <version>${as2.support.library.version}</version>
</dependency>

  1. Update the mule-maven-plugin by including the shared libraries in the build > plugins > plugin section of the pom.xml file.

<configuration>
  <sharedLibraries>
    <sharedLibrary>
      <groupId>com.mulesoft.connectors</groupId>
      <artifactId>as2-bc2-fips-impl</artifactId>
    </sharedLibrary>
  </sharedLibraries>
</configuration>

  1. In JVM or Mule runtime, set the security model to FIPS 140-3.

-Dmule.security.model=fips140-3

  1. Restrict BCFIPS to use only FIPS-approved algorithms.

-Dorg.bouncycastle.fips.approved_only=true

This example shows the Mule runtime startup configuration for FIPS 140-3:

java -Dmule.security.model=fips140-3 \
  -Dorg.bouncycastle.fips.approved_only=true \
  -jar mule-standalone.jar

The org.bouncycastle.fips.approved_only property is JVM-wide and must be set in your system or runtime configuration when running in FIPS mode.

If you use BCFIPS in FIPS mode, key and algorithm restrictions apply. Only approved algorithms supported by the BCFIPS provider are allowed.

Step 3: Verify Keystore and Algorithm Compatibility

  1. Verify that keystores and certificates are compatible with your selected security mode. Some FIPS modes require FIPS-approved algorithms.

  2. Review the Mule and BCFIPS documentation for approved algorithms if you use BCFIPS in FIPS mode, since key and algorithm restrictions apply.

Step 4: Verify Connector Usage in Flows

  1. Verify that partner certificates and algorithms are compatible with your selected security mode.

  2. If you use AS2 Connector operations in your flows, verify that the connector configuration also exists in your Mule app.

AS2 Connector Startup Validation

When an AS2 listener, AS2 MDN listener, or Send operation starts, AS2 Connector validates that the external library configuration and runtime settings are correct. Validation fails if the Mule application includes listener, MDN listener, or Send operations that don’t meet these requirements:

  • The application must include one external library. An error occurs if more than one external library is included or if none are included.

  • The mule.security.model system property must match the selected external library configuration:

    • For non-FIPS, mule.security.model must be disabled. If it’s enabled, remove the property.

    • For FIPS 140-2, mule.security.model must be set to fips140-2. If the property is configured incorrectly, a message is logged to correct the setting to -Dmule.security.model=fips140-2.

    • For FIPS 140-3, mule.security.model must be set to fips140-3. If the property is configured incorrectly, a message is logged to correct the setting to -Dmule.security.model=fips140-3.

  • The implementation library for the selected security mode must be on the same classpath. If the library is missing, startup fails. To resolve the issue, review the error log to find the conflicting library and remove it from the classpath.

    Use the implementation library that applies to your security mode:

    • non-FIPS: as2-bc-non-fips-impl

    • FIPS 140-2: as2-bc1-fips-impl

    • FIPS 140-3: as2-bc2-fips-impl

  • AS2 Connector instantiates the cryptographic implementation for the selected security mode at startup. If this fails, for example due to missing or incompatible libraries, an error is logged that includes the security profile and the cause.

Post-Upgrade Steps

  1. Verify that the application starts without errors and that AS2 Connector initializes correctly for your selected security mode.

  2. Test the AS2 listener, MDN listener, and Send operations against your AS2 partners.

  3. Confirm that certificates and algorithms are accepted in FIPS mode if applicable.

  4. Notify partners of URL or port changes if you modified the HTTP Listener configuration.

System Properties Reference

The table details the system-level properties that are required to configure AS2 Connector’s security modes and BCFIPS compliance within the Mule runtime or JVM.

Property Description Values Default Scope

mule.security.model

Security mode used by the connector

fips140-2 or fips140-3

non-FIPS (when not set)

Mule runtime or JVM

org.bouncycastle.fips.approved_only

Restricts BCFIPS to FIPS-approved algorithms only. Required for FIPS compliance when using BCFIPS.

true, false

false

JVM-wide

The org.bouncycastle.fips.approved_only property affects the entire JVM. When the application runs in FIPS mode, the system administrator must configure the property. For more information, see the FIPS 140-2 Compliance Support section on the Security page in the Mule runtime documentation.

Migrate Existing Deployments

AS2 Connector 7.x introduces a Global Connector Configuration and supports configurable security modes including non-FIPS, FIPS 140-2, and FIPS 140-3 via the mule.security.model system property. Follow the Upgrade Steps to make the necessary changes to your Mule app. AS2 Connector’s cryptographic behavior is determined by the global configuration, which provides the required libraries and defines the runtime security model.

Existing 6.x flows remain functional without requiring code changes.

Migrate Deployments from FIPS 140-2 or 140-3 Environments

  1. Verify that BCFIPS and FIPS-related settings are configured correctly for your Mule runtime version. For more information, see the FIPS 140-2 Compliance Support section on the Security page in the Mule runtime documentation.

  2. Set mule.security.model to fips140-2 or fips140-3 as appropriate for your compliance requirements.

  3. Set org.bouncycastle.fips.approved_only to true if required by your runtime for compliance.

  4. Test your configuration in a non-production environment by running your flows with the AS2 listener, MDN listener, and Send operations.

  5. Deploy the application to production and monitor the error log to verify a successful startup and AS2 message exchange.

Troubleshooting

These common error messages and issues indicate configuration or classpath problems that prevent AS2 Connector from operating in the selected security mode. Follow the recommendations to resolve the issues.

  • AS2 Connector requires at least one External Libs configuration

    Add AS2 Connector External Libs - Non FIPS, AS2 Connector External Libs - FIPS 140-2, or AS2 Connector External Libs - FIPS 140-3 to your application. See AS2 Connector Startup Validation.

  • Only one External Libs configuration is allowed per application

    Remove the additional external library configurations so that you only have one.

  • Detected 'as2-bc-non-fips-impl' but system property 'mule.security.model' is …​

    For non-FIPS mode, disable mule.security.model or remove it from the JVM arguments or runtime configuration.

  • Detected 'as2-bc1-fips-impl' but system property …​ Set -Dmule.security.model=fips140-2

    Add -Dmule.security.model=fips140-2 if you’re using AS2 Connector External Libs - FIPS 140-2.

  • Detected 'as2-bc2-fips-impl' but system property …​ Set -Dmule.security.model=fips140-3

    Add -Dmule.security.model=fips140-3 if you’re using AS2 Connector External Libs - FIPS 140-3.

  • External Libs - …​ configuration selected, but '…​' is not on the classpath

    Add the correct implementation dependency for your selected security mode or make sure the external library configuration imports the dependency. If you receive a warning, make sure only the library for your active security mode remains on the classpath by removing any additional AS2 cryptographic implementations.

  • Startup or Crypto Errors in FIPS Mode

    Make sure mule.security.model matches your runtime FIPS setup and that BCFIPS is installed and registered. Set org.bouncycastle.fips.approved_only to true if required.

  • Tests or Flows that Relied on non-FIPS Behavior

    If your application is running with mule.security.model=fips140-2 or fips140-3, some algorithms or key usages are restricted. Align keystores and partner expectations with FIPS-approved algorithms.

  • Caching or Metadata Issues

    If Anypoint Studio or Anypoint Design Center shows a stale configuration, try restarting the IDE or clearing your cache.

Revert the Upgrade

To revert to AS2 Connector 6.x:

  1. Change the mule-as2-connector dependency in your project’s pom.xml file to the desired 6.x version.

  2. Remove the external library global configuration.

  3. Remove the libraries that were added as dependencies and shared libraries from the pom.xml file.

  4. Remove or adjust 7.x system properties, such as mule.security.model, if they aren’t being used by other components.

See Also

Back to top
View on GitHub