---
schema_version: "1"
id: 04f19b006371cd09d89b64e73ecd6e17fff9e6a3f6bc4cd2a3755770cf51d697
title: Upgrading and Migrating AS2 Connector to Version 7.x
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/as2-connector/latest/as2-connector-upgrade-migrate.md
canonical_url: https://docs.mulesoft.com/as2-connector/latest/as2-connector-upgrade-migrate
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 56c942d070a5f00c495ed84cb219db369b46486756fe5f958b47341c91174a6a
description: MuleSoft Documentation Site
release: "7.0"
latest: true
---
---
product: AS2 Connector
version: 7.0
is-latest-version: true
---

# Upgrading and Migrating AS2 Connector to Version 7.x

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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

<table><colgroup><col> <col></colgroup><thead><tr><th>From Version</th><th>To Version</th></tr></thead><tbody><tr><td><div><div><p>6.x</p></div></div></td><td><div><div><p>7.x</p></div></div></td></tr></tbody></table>

## 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.

```bash
-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.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Security Mode</th><th>Global Configuration</th><th>Default Name</th><th>Required Library Maven Coordinates</th></tr></thead><tbody><tr><td><p>non-FIPS</p></td><td><p><code>AS2 Connector External Libs - Non FIPS</code></p></td><td><p><code>AS2_Connector_External_Libs___Non_FIPS</code></p></td><td><p>com.mulesoft.connectors:as2-bc-non-fips-impl:3.0.0, org.bouncycastle:bcpkix-jdk18on:1.82, org.bouncycastle:bcprov-jdk18on:1.82</p></td></tr><tr><td><p>FIPS 140-2</p></td><td><p><code>AS2 Connector External Libs - FIPS 140-2</code></p></td><td><p><code>AS2_Connector_External_Libs___FIPS_140_2</code></p></td><td><p>com.mulesoft.connectors:as2-bc1-fips-impl:3.0.0</p></td></tr><tr><td><p>FIPS 140-3</p></td><td><p><code>AS2 Connector External Libs - FIPS 140-3</code></p></td><td><p><code>AS2_Connector_External_Libs___FIPS_140_3</code></p></td><td><p>com.mulesoft.connectors:as2-bc2-fips-impl:3.0.0</p></td></tr></tbody></table>

![Connector configurations that are used for creating Global Elements](/mulesoft/current/en-us/as2-connector/latest/_images/as2-connector-upgrade-global-element-config.png)

## 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:

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

2.  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](/mulesoft/current/en-us/as2-connector/latest/_images/as2-connector-upgrade-non-fips-config.png)

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:

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

4.  Add the required Maven dependencies to the `pom.xml` file. Refer to the
    [AS2 Connector Release Notes](https://docs.mulesoft.com/release-notes/connector/as2-connector-release-notes-mule-4)
    for the compatible versions of the dependencies.

```xml
<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>
```

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

```xml
<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](https://docs.mulesoft.com/mule-runtime/latest/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](/mulesoft/current/en-us/as2-connector/latest/_images/as2-connector-upgrade-fips140-2-config.png)

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.

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

4.  Add the required Maven dependencies to the `pom.xml` file. Refer to the
    [AS2 Connector Release Notes](https://docs.mulesoft.com/release-notes/connector/as2-connector-release-notes-mule-4)
    for the compatible versions of the dependencies.

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

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

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

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

```bash
-Dmule.security.model=fips140-2
```

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

```bash
-Dorg.bouncycastle.fips.approved_only=true
```

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

```bash
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](/mulesoft/current/en-us/as2-connector/latest/_images/as2-connector-upgrade-fips140-3-config.png)

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:

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

4.  Add the required Maven dependencies to the `pom.xml` file. Refer to the
    [AS2 Connector Release Notes](https://docs.mulesoft.com/release-notes/connector/as2-connector-release-notes-mule-4)
    for the compatible versions of the dependencies.

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

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

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

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

```bash
-Dmule.security.model=fips140-3
```

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

```bash
-Dorg.bouncycastle.fips.approved_only=true
```

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

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

> [!NOTE] 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.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Property</th><th>Description</th><th>Values</th><th>Default</th><th>Scope</th></tr></thead><tbody><tr><td><p><code>mule.security.model</code></p></td><td><p>Security mode used by the connector</p></td><td><p><code>fips140-2</code> or <code>fips140-3</code></p></td><td><p><code>non-FIPS</code> (when not set)</p></td><td><p>Mule runtime or JVM</p></td></tr><tr><td><p><code>org.bouncycastle.fips.approved_only</code></p></td><td><p>Restricts BCFIPS to FIPS-approved algorithms only. Required for FIPS compliance when using BCFIPS.</p></td><td><p><code>true</code>, <code>false</code></p></td><td><p><code>false</code></p></td><td><p>JVM-wide</p></td></tr></tbody></table>

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](https://docs.mulesoft.com/mule-runtime/latest/securing) 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](#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](https://docs.mulesoft.com/mule-runtime/latest/securing) 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](#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

- [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors)

- [AS2 Connector Reference](https://docs.mulesoft.com/as2-connector/latest/as2-connector-reference)

- [Salesforce Help](https://help.salesforce.com)