Updating to multiple IKE and IPsec algorithms

Understanding update behavior in the API

The API automatically synchronizes singular and array-based algorithm properties. 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 must configure a single algorithm for each category using singular properties.

• Use IKEv2 with array-based properties:

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

• Use IKEv1 with singular properties:

{
   "ike_version": 1,
   "authentication_algorithm": "sha256",
   "encryption_algorithm": "aes128"
}

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, 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"
}

If only one algorithm is configured in an array-based property, the singular property returns the configured value instead of "multiple".

{
   "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:

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:

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.

Do not mix GCM and non-GCM encryption algorithms in the same policy. Mixing them can create configuration conflicts and negotiation failures.

When authentication_algorithms is set to ["disabled"], you must also update authentication_algorithms when changing from GCM to non-GCM encryption algorithms.

• 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"]
   }'

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"]
}