Updating to multiple IKE and IPsec algorithms

Understanding update behavior in the API

The API automatically synchronizes singular and array-based algorithm properties. This behavior applies not only to API updates, but also when you update policies from the CLI or Terraform. Review the following behavior and restrictions before updating your policies.

IKE version compatibility

Array-based algorithm properties are supported only with IKEv2. If you use IKEv1, you can configure only one algorithm for each category.

• Use IKEv2 with array-based properties:

   {
      "ike_version": 2,
      "authentication_algorithms": ["sha512", "sha256"],
      "encryption_algorithms": ["aes256", "aes128"]
   }

• Use IKEv1 with only one algorithm per category:

   {
      "ike_version": 1,
      "authentication_algorithms": ["sha256"],
      "encryption_algorithm": ["aes128"],
      "dh_groups:[14]"
   }

IKEv1 supports only one algorithm per category. VPN connections that use IKEv1 don't support array-based IKE or IPsec algorithm properties. Use IKEv2 whenever possible.

Automatic synchronization

When you update array-based properties (authentication_algorithms, encryption_algorithms, dh_groups, pfs_groups), the corresponding singular properties (authentication_algorithm, encryption_algorithm, dh_group, pfs) are updated automatically. Similarly, updating singular properties automatically updates the related array-based properties. For examples, see:

• IKE policy update examples
• IPsec policy update examples

Read-only indicators

When multiple algorithms are configured with array-based properties, the singular properties (authentication_algorithm, encryption_algorithm) return read-only indicator values in API responses.

For example:

• authentication_algorithm returns "multiple"
• encryption_algorithm returns "multiple"
• dh_group returns 65535

These values are returned only in responses and can't be submitted in a PATCH request.

   {
      "authentication_algorithms": ["sha256", "sha384", "sha512"],
      "authentication_algorithm": "multiple",
      "dh_groups": [14, 15, 16],
      "dh_group": 65535,
      "encryption_algorithms": ["aes128", "aes256"],
      "encryption_algorithm": "multiple"
   }

When a single algorithm algorithm is configured in an array-based property, the singular property returns the configured value instead of the read-only indicator values.

   {
      "authentication_algorithms": ["sha256"],
      "authentication_algorithm": "sha256",
      "dh_groups": [14],
      "dh_group": 14,
      "encryption_algorithms": ["aes128"],
      "encryption_algorithm": "aes128"
   }

Property mixing restriction

Do not mix singular and array-based properties for the same algorithm category in a single request. Choose one approach per request.

• Correct example: This example includes the algorithm properties for IKE, where only array-based properties are used for all categories:

   curl -X PATCH "$vpc_api_endpoint/v1/ike_policies/$ike_policy_id?version=$api_version&generation=2" \
      -H "Authorization: $iam_token" \
      -d '{
        "authentication_algorithms": ["sha256", "sha384", "sha512"],
        "dh_groups": [14, 15, 16],
        "encryption_algorithms": ["aes128", "aes256"]
      }'

• Incorrect example: This example includes the algorithm properties for IKE, where both singular and array-based properties are mixed for the same category:

   curl -X PATCH "$vpc_api_endpoint/v1/ike_policies/$ike_policy_id?version=$api_version&generation=2" \
      -H "Authorization: $iam_token" \
      -d '{
        "authentication_algorithm": "sha512",
        "authentication_algorithms": ["sha256", "sha384", "sha512"],
        "dh_groups": [14, 15, 16],
        "encryption_algorithms": ["aes128", "aes256"]
      }'

GCM algorithm requirements and restrictions

If the encryption_algorithms property contains GCM-based algorithms (aes128gcm16, aes192gcm16, or aes256gcm16), the authentication_algorithms property must be set to ["disabled"].

• Correct example: Shows IPsec algorithm properties when the encryption_algorithms array includes GCM-based algorithms and authentication_algorithms is set to ["disabled"]:

   curl -X PATCH "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=$api_version&generation=2" \
      -H "Authorization: $iam_token" \
      -d '{
        "authentication_algorithms": ["disabled"],
        "encryption_algorithms": ["aes256gcm16", "aes192gcm16"],
        "pfs_groups": ["group_14", "group_15", "group_16"]
      }'

• Incorrect example: Shows algorithm properties for IPsec where the encryption_algorithms array includes GCM-based algorithms, whereas authentication_algorithms is not set to ["disabled"]:

   curl -X PATCH "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=$api_version&generation=2" \
      -H "Authorization: $iam_token" \
      -d '{
        "authentication_algorithms": ["sha256"],
        "encryption_algorithms": ["aes256gcm16", "aes192gcm16"],
        "pfs_groups": ["group_14", "group_15", "group_16"]
      }'

GCM algorithms provide encryption and built-in authentication as part of a single operation. Do not configure separate authentication algorithms such as sha256 or sha512 with GCM encryption algorithms.

When you change encryption_algorithms from GCM to non-GCM encryption, you must also update authentication_algorithms from ["disabled"] to multiple algorithm values.

• Correct example: Updates both the encryption_algorithms and authentication_algorithms properties:

   curl -X PATCH "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=$api_version&generation=2" \
      -H "Authorization: $iam_token" \
      -d '{
        "authentication_algorithms": ["sha512", "sha256"],
        "encryption_algorithms": ["aes256", "aes128"],
        "pfs_groups": ["group_14", "group_15", "group_16"]
      }'

• Incorrect example: Shows a case where only the encryption_algorithms property is updated with non-GCM algorithms (aes128, aes192, aes256):

   curl -X PATCH "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=$api_version&generation=2" \
      -H "Authorization: $iam_token" \
      -d '{
        "authentication_algorithms": ["disabled"],
        "encryption_algorithms": ["aes256", "aes128"],
        "pfs_groups": ["group_14", "group_15", "group_16"]
      }'

When both GCM and non-GCM encryption algorithms are specified in encryption_algorithms, the proposal priority order is determined by the type of the first listed algorithm.

• If the first algorithm is GCM, all GCM algorithms are proposed first, followed by non-GCM algorithms (while preserving order within each group).

• Example: Shows a case which groups and orders algorithms based on the first selected algorithm (GCM first):

   curl -X PATCH "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=$api_version&generation=2" \
      -H "Authorization: $iam_token" \
      -d '{
        "encryption_algorithms": ["aes128gcm16", "aes256", "aes128", "aes192gcm16"],
        "authentication_algorithms": ["sha512, sha256"],
        "pfs_groups": ["group_14", "group_15", "group_16"]
      }'

Final proposal order: aes128gcm16, aes192gcm16, aes256, aes128

• If the first algorithm is non-GCM, all non-GCM algorithms are proposed first, followed by GCM algorithms. If the peer gateway does not support them, the negotiation proceeds with the GCM algorithms in the provided order.

• Example: Shows a case which groups and orders algorithms based on the first selected algorithm (non-GCM first):

   curl -X PATCH "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=$api_version&generation=2" \
      -H "Authorization: $iam_token" \
      -d '{
        "encryption_algorithms": ["aes256", "aes128", "aes128gcm16", "aes192gcm16"],
        "authentication_algorithms": ["sha512, sha256"],
        "pfs_groups": ["group_14", "group_15", "group_16"]
      }'

Final proposal order: aes256, aes128, aes128gcm16, aes192gcm16

• If GCM and non-GCM algorithms are mixed, the type of the first algorithm determines overall proposal priority.

• Example: Because the first algorithm is a GCM algorithm, all GCM algorithms are proposed before the non-GCM algorithms in the same order:

   curl -X PATCH "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=$api_version&generation=2" \
      -H "Authorization: $iam_token" \
      -d '{
        "encryption_algorithms": ["aes128gcm16", "aes256", "aes128", "aes192gcm16"],
        "authentication_algorithms": ["sha512, sha256"],
        "pfs_groups": ["group_14", "group_15", "group_16"]
      }'

Final proposal order: aes128gcm16, aes192gcm16, aes256, aes128

Mixing GCM and non-GCM algorithms can lead to configuration conflicts and different negotiation behavior depending on the peer.

Algorithm validation rules

Ensure that all algorithm values in your request are valid, unique, and not empty. Use only supported algorithm names, avoid duplicates, and provide at least one value in each array. Invalid, duplicate, or empty entries can result in a validation error.

• Correct example: Updates the algorithm values, where supported algorithms and values are used for all categories:

   {
      "authentication_algorithms": ["sha512", "sha256"],
      "dh_groups": [14, 15],
      "encryption_algorithms": ["aes256", "aes192", "aes128"]
   }

• Incorrect example: Updates the algorithm values, where duplicate values are used in the same algorithm category:

   {
      "authentication_algorithms": ["sha512", "sha256"],
      "dh_groups": [14, 15],
      "encryption_algorithms": ["aes256", "aes256", "aes128"]
   }