Creating an IPsec policy

Creating an IPsec policy in the console

To create an IPsec policy in the console, follow these steps:

1. From the VPNs for VPC list page, select Site-to-site gateways > IPsec policies.

2. Click Create and specify the following information:

   • Location - Select a region for this IPsec policy.
   • Name - Enter a name for the IPsec policy.
   • Resource group - Select the resource group for this IPsec policy.
   • Encryption - Select the encryption algorithm to use for Phase 2. By default, the lowest-strength algorithm is selected. You can select multiple values for each field and reorder them by priority. The VPN gateway negotiates with the peer gateway to select the best mutually supported algorithm.
   • Authentication - Select the authentication algorithm to use for Phase 2. By default, the lowest-strength algorithm is selected. You can select multiple authentication algorithms and reorder them by priority.
   • Perfect Forward Secrecy - Enable this option to perform a new Diffie-Hellman exchange during each Phase 2 rekey so that if a key is compromised, previously encrypted traffic remains secure.
   • Diffie-Hellman group (if PFS is enabled) - Select the DH group to use for Phase 2 key exchange. By default, the lowest DH group is selected. You can select multiple DH groups and reorder them by priority.
   • Key lifetime - Select the lifetime, in seconds, for the Phase 2 tunnel.

3. Click Create.

4. From the VPN connection details page, set the IPsec policies field to use the wanted IPsec policy.

   To ensure successful IKE/IPsec negotiation, configure both peers with at least one matching algorithm in each category (authentication, encryption, and PF groups). Aligning these settings across peers helps avoid connection failures.

Creating an IPsec policy from the CLI

Before you begin, set up your CLI environment.

To create an IPsec policy from the CLI, enter the following command:

ibmcloud is ipsec-policy-create IPSEC_POLICY_NAME AUTHENTICATION_ALGORITHMS ENCRYPTION_ALGORITHMS PFSGS [--key-lifetime KEY_LIFETIME] [--resource-group-id RESOURCE_GROUP_ID | --resource-group-name RESOURCE_GROUP_NAME] [--output JSON] [-q, --quiet]

Where:

• IPSEC_POLICY_NAME - The name of the IPsec policy.
• AUTHENTICATION_ALGORITHMS - The authentication algorithms. Must be disabled only if ENCRYPTION_ALGORITHMS contains combined-mode algorithms (aes128gcm16, aes192gcm16, aes256gcm16). One of: disabled, sha256, sha384, sha512, or a comma-separated list of authentication algorithms (sha384,sha256,sha512). The order of the algorithms determines their priority during negotiation.
• ENCRYPTION_ALGORITHMS - The encryption algorithms. One of: aes128, aes128gcm16, aes192, aes192gcm16, aes256, aes256gcm16, or a comma-separated list of encryption algorithms (aes128,aes192,aes256). The order of the algorithms determines their priority during negotiation.
• PFSGS - Perfect Forward Secrecy Groups. One of: disabled, group_14, group_15, group_16, group_17, group_18, group_19, group_20, group_21, group_22, group_23, group_24, group_31, or a comma-separated list of PFS groups (group_14,group_15,group_16). The order of the groups determines their priority during negotiation.
• --key-lifetime value - The key lifetime in seconds. Maximum: 86400, Minimum: 1800. The default value is 3600.
• --resource-group-id value - The ID of the resource group. This option is mutually exclusive with --resource-group-name.
• --resource-group-name value - The name of the resource group. This option is mutually exclusive with --resource-group-id.
• --output value - Specify output in JSON format.
• -q, --quiet - Suppress verbose output.

md5 and sha1 authentication algorithms, group_2 and group_5 DH groups, and the triple_des encryption algorithm were deprecated on 20 September 2022 and are no longer supported in the console.

The AUTHENTICATION_ALGORITHMS must be disabled if and only if ENCRYPTION_ALGORITHMS is aes128gcm16, aes192gcm16, or aes256gcm16.

Updating an IPsec policy from the CLI

Before you begin, set up your CLI environment.

To update an IPsec policy from the CLI, enter the following command:

ibmcloud is ipsec-policy-update IPSEC_POLICY [--name NEW_NAME] [--authentication-algorithms AUTHENTICATION_ALGORITHMS] [--pfsgs PFSGS] [--encryption-algorithms ENCRYPTION_ALGORITHMS] [--authentication-algorithm AUTHENTICATION_ALGORITHM] [--pfs disabled | group_14 | group_15 | group_16 | group_17 | group_18 | group_19 | group_20 | group_21 | group_22 | group_23 | group_24 | group_31] [--encryption-algorithm aes128 | aes128gcm16 | aes192 | aes192gcm16 | aes256 | aes256gcm16] [--key-lifetime KEY_LIFETIME] [--output JSON] [-q, --quiet]

Where:

• --name - The name of the IPsec policy.

• --authentication-algorithms - A comma-separated list of authentication algorithms (recommended). The order of the algorithms determines their priority during negotiation.

• --authentication-algorithm - The authentication algorithm (deprecated). Must be disabled only if --encryption_algorithm is aes128gcm16, aes192gcm16, or aes256gcm16. One of: disabled, sha256, sha384, sha512

• --encryption-algorithms - A comma-separated list of encryption algorithms (recommended). The order of the algorithms determines their priority during negotiation.

• --encryption-algorithm - The encryption algorithm (deprecated). One of: aes128, aes128gcm16, aes192, aes192gcm16, aes256, aes256gcm16.

• --pfsgs - A comma-separated list of Perfect Forward Secrecy groups. The order of the groups determines their priority during negotiation.

• --pfs - The Perfect Forward Secrecy group (deprecated). One of: disabled, group_14, group_15, group_16, group_17, group_18, group_19, group_20, group_21, group_22, group_23, group_24, group_31.

  Do not mix singular and array-based properties for the same algorithm category in a single command.

Creating an IPsec policy with the API

The singular properties authentication_algorithm, dh_group, encryption_algorithm, and pfs for IPsec negotiation are deprecated. Use the array-based properties to create IPsec policy. To know more about the singular and array-based algorithm properties for IPsec policy when using the API, see Updating to multiple IKE and IPsec algorithms.

To create an IPsec policy with multiple algorithms by using the array-based properties (recommended), follow these steps:

1. Set up your API environment with the right variables.

2. Store any additional variables to be used in the API commands, for example:

   ResourceGroupId - Find the resource group ID by using the get resource groups command and then populate the variable:

    export ResourceGroupId=<your_resourcegroup_id>
   

3. Create the IPsec policy:

      curl -X POST "$vpc_api_endpoint/v1/ipsec_policies?version=$api_version&generation=2" \
        -H "Authorization: Bearer $iam_token" \
        -d '{
           "name": "my-new-ipsec-policy",
           "authentication_algorithms": ["sha256", "sha512"],
           "encryption_algorithms": ["aes128", "aes256"],
           "pfs_groups": ["group_14", "group_15", "group_16", "group_17", "group_18"],
           "resource_group": {
             "id": "'$ResourceGroupId'"
           }
         }'
   

Create an IPsec policy with encryption_algorithms set to GCM-based algorithms and authentication_algorithms set to disabled:

   curl -X POST "$vpc_api_endpoint/v1/ipsec_policies?version=$api_version&generation=2" \
   -H "Authorization: Bearer $iam_token" \
   -d '{
      "name": "gcm-ipsec-policy",
      "encryption_algorithms": ["aes128gcm16","aes192gcm16","aes256gcm16"],
      "authentication_algorithms": ["disabled"],
      "pfs_groups": ["group_14","group_15","group_16","group_17","group_18"],
      "resource_group": {
        "id": "'$ResourceGroupId'"
      }
    }'

The authentication_algorithms property must be set to disabled if and only if the encryption_algorithms list contains any GCM-based algorithms (aes128gcm16, aes192gcm16, or aes256gcm16). GCM algorithms provide both encryption and built-in data integrity (authentication) as part of a single operation, so a separate authentication algorithm (such as sha256 or sha512) must not be specified.

To create an IPsec policy with the API by using singular properties (deprecated), follow these steps:

1. Set up your API environment with the right variables.

2. Store any additional variables to be used in the API commands, for example:

   ResourceGroupId - Find the resource group ID by using the get resource groups command and then populate the variable:

    export ResourceGroupId=<your_resourcegroup_id>
   

3. Create the IPsec policy:

      curl -X POST "$vpc_api_endpoint/v1/ipsec_policies?version=$api_version&generation=2" \
        -H "Authorization: Bearer $iam_token" \
        -d '{
           "name": "my-new-ipsec-policy",
           "authentication_algorithm": "sha256",
           "encryption_algorithm": "aes128",
           "pfs": "group_14",
           "resource_group": {
             "id": "'$ResourceGroupId'"
           }
         }'
   

Updating an IPsec policy with the API

To update an IPsec policy with the API by using the array-based properties (recommended), follow these steps:

1. Set up your API environment with the right variables.

2. Store any additional variables to be used in the API commands, for example:

   ResourceGroupId - Find the resource group ID by using the get resource groups command and then populate the variable:

   export ResourceGroupId=<your_resourcegroup_id>
   

3. Update the IPsec policy:

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

To update an IPsec policy with the API by using singular properties (deprecated), follow these steps:

You can update IPsec policies by using either deprecated singular properties or array-based properties. Both forms are accepted, but you must not mix singular and array-based properties for the same algorithm category in a single request.

1. Set up your API environment with the right variables.

2. Store any additional variables to be used in the API commands, for example:

   ResourceGroupId - Find the resource group ID by using the get resource groups command and then populate the variable:

   export ResourceGroupId=<your_resourcegroup_id>
   

3. Update the IPsec policy:

      curl -X PATCH "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=$api_version&generation=2" \
        -H "Authorization: Bearer $iam_token" \
        -d '{
            "name": "my-updated-ipsec-policy",
            "authentication_algorithm": "sha512",
            "encryption_algorithm": "aes256",
              "pfs": "group_18",
         }'
   

To view the complete set of APIs for site-to-site VPN gateways, see the VPC API reference.