Merge pull request #605 from shapeblue/vpn-cust-gw

Add settings to mark cryptographic algorithms in vpn customer gateways as excluded or obsolete

Author: harikrishna-patnala

source/adminguide/networking/site_to_site_vpn.rst

@@ -64,7 +64,7 @@ Creating and Updating a VPN Customer Gateway
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. note::
-   A VPN customer gateway can be connected to only one VPN gateway at a time.
+   A VPN Customer Gateway can be connected to only one VPN gateway at a time.
 
 To add a VPN Customer Gateway:
 
@@ -80,7 +80,7 @@ To add a VPN Customer Gateway:
 
    Provide the following information:
 
-   -  **Name**: A unique name for the VPN customer gateway you create.
+   -  **Name**: A unique name for the VPN Customer Gateway you create.
 
    -  **Gateway**: The IP address for the remote gateway.
 
@@ -115,13 +115,19 @@ To add a VPN Customer Gateway:
          confirming that the remote gateway has a matching Preshared Key.
 
    -  **IKE Hash**: The IKE hash for phase-1. The supported hash
-      algorithms are SHA1 and MD5.
+      algorithms are SHA1, SHA256, SHA384 and SHA512 and MD5.
+
+   -  **IKE Version**: The IKE Version to use between ike (autoselect), ikev1, or ikev2.
+      Connections marked with 'ike' will use 'ikev2' when initiating,
+      but accept any protocol version when responding. Defaults to 'ike'.
 
    -  **IKE DH**: A public-key cryptography protocol which allows two
       parties to establish a shared secret over an insecure
       communications channel. The 1536-bit Diffie-Hellman group is used
       within IKE to establish session keys. The supported options are
-      None, Group-5 (1536-bit) and Group-2 (1024-bit).
+      None, Group-2 (1024-bit), Group-5 (1536-bit), Group-14 (2048-bit),
+      Group-15 (3072-bit), Group-16 (4096-bit), Group-17 (6144-bit) and
+      Group-18 (8192-bit).
 
    -  **ESP Encryption**: Encapsulating Security Payload (ESP) algorithm
       within phase-2. The supported encryption algorithms are AES128,
@@ -134,18 +140,19 @@ To add a VPN Customer Gateway:
          extracted from the Diffie-Hellman key exchange in phase-1, to
          provide session keys to use in protecting the VPN data flow.
 
-   -  **ESP Hash**: Encapsulating Security Payload (ESP) hash for
-      phase-2. Supported hash algorithms are SHA1 and MD5.
+   -  **ESP Hash**: Encapsulating Security Payload (ESP) hash for phase-2.
+      Supported hash algorithms are SHA1, SHA256, SHA384 and SHA512 and MD5.
 
    -  **Perfect Forward Secrecy**: Perfect Forward Secrecy (or PFS) is
       the property that ensures that a session key derived from a set of
       long-term public and private keys will not be compromised. This
       property enforces a new Diffie-Hellman key exchange. It provides
       the keying material that has greater key material life and thereby
       greater resistance to cryptographic attacks. The available options
-      are None, Group-5 (1536-bit) and Group-2 (1024-bit). The security
-      of the key exchanges increase as the DH groups grow larger, as
-      does the time of the exchanges.
+      are None, Group-2 (1024-bit), Group-5 (1536-bit), Group-14 (2048-bit),
+      Group-15 (3072-bit), Group-16 (4096-bit), Group-17 (6144-bit) and
+      Group-18 (8192-bit). The security of the key exchanges increase as
+      the DH groups grow larger, as does the time of the exchanges.
 
       .. note::
          When PFS is turned on, for every negotiation of a new phase-2 SA
@@ -172,27 +179,137 @@ To add a VPN Customer Gateway:
    -  **Force UDP Encapsulation of ESP Packets**: Force Encapsulation for
       NAT traversal
 
+   .. note::
+      If the administrator has configured excluded cryptographic
+      parameters, those options will not appear in the form. If obsolete
+      parameters are configured, those options will be displayed with a
+      warning message indicating they are obsolete and should be avoided.
+
 #. Click OK.
 
 
+Configuring Excluded and Obsolete VPN Customer Gateway Parameters
+''''''''''''''''''''''''''''''''''''''''''''''''
+
+CloudStack provides administrators with configuration settings to enforce
+modern security standards by marking certain cryptographic algorithms and
+parameters as excluded or obsolete for VPN Customer Gateway creation.
+
+**Excluded Parameters:**
+
+These parameters are completely hidden from users and cannot be used
+while creating or updating VPN Customer Gateways:
+
+-  **vpn.customer.gateway.excluded.encryption.algorithms**: Comma-separated
+   list of encryption algorithms to exclude. Applies to both phases.
+
+-  **vpn.customer.gateway.excluded.hashing.algorithms**: Comma-separated
+   list of hashing algorithms to exclude. Applies to both phases.
+
+-  **vpn.customer.gateway.excluded.ike.versions**: Comma-separated list of
+   IKE versions to exclude.
+
+-  **vpn.customer.gateway.excluded.dh.group**: Comma-separated list of
+   Diffie-Hellman groups to exclude. Applies to both phases.
+
+**Obsolete Parameters:**
+
+These parameters are shown with a warning message, allowing existing
+deployments to continue functioning while encouraging migration to more
+secure alternatives:
+
+-  **vpn.customer.gateway.obsolete.encryption.algorithms**: Comma-separated
+   list of encryption algorithms marked as obsolete. Applies to both phases.
+
+-  **vpn.customer.gateway.obsolete.hashing.algorithms**: Comma-separated
+   list of hashing algorithms marked as obsolete. Applies to phases.
+
+-  **vpn.customer.gateway.obsolete.ike.versions**: Comma-separated list of
+   IKE versions marked as obsolete.
+
+-  **vpn.customer.gateway.obsolete.dh.group**: Comma-separated list of
+   Diffie-Hellman groups marked as obsolete. Applies to both phases.
+
+**Behavior:**
+
+-  **Excluded parameters**: Not shown in the Create and Update VPN Customer
+   Gateway forms. Users cannot select these options for new gateways.
+
+-  **Obsolete parameters**: Shown with a warning message in the Create and
+   Update forms, indicating they are deprecated and should be avoided.
+
+-  **Existing gateways**: If a VPN Customer Gateway already uses excluded or
+   obsolete parameters:
+
+   -  A warning icon is displayed next to the gateway name with a message
+      prompting users to change the obsolete or excluded parameters.
+
+   -  The Update VPN Customer Gateway form displays the setting with a
+      warning message encouraging users to change it to a more secure
+      alternative.
+
+-  The ``listVpnCustomerGateways`` API response includes two new fields:
+
+   -  **obsoleteparameters**: List of all obsolete parameters used by the gateway
+
+   -  **excludedparameters**: List of all excluded parameters used by the gateway
+
+-  The ``listCapabilities`` API response includes a new field containing
+   the list of excluded and obsolete VPN Customer Gateway parameters, but
+   only if these configuration settings are configured by the operator.
+
+**Events and Alerts:**
+
+There is a thread that run periodically to check for VPN Customer Gateways which
+are using excluded or obsolete cryptographic parameters.The interval at which this thread
+runs is configurable using the setting **vpn.customer.gateway.obsolete.check.interval**.
+The unit is in hours and the default value is 0 which means it is disabled by default.
+
+Each time the thread runs, it generates Events for each VPN Customer Gateway which is
+using excluded or obsolete parameters.
+It also generates Alerts to the Administrator about the number of VPN Customer Gateways
+that are using excluded and/or obsolete parameters.
+
+**Configuration Scope:**
+
+The obsolete and excluded settings support Domain-level configuration.
+When set at Domain level, the values override global settings for that specific Domain only.
+
+- Global Settings: Apply to all Domains without specific overrides
+
+- Domain Settings: Override global settings for that specific Domain only
+
+Note: Domain settings do not cascade to child Domains. Each child Domain must be configured individually,
+or it will inherit from global settings (not from its parent Domain).
+
+To reset a Domain-specific override, navigate to Domains → [Domain Name] → Settings and reset the value.
+This will cause the Domain to fall back to global settings
+
 Updating and Removing a VPN Customer Gateway
 ''''''''''''''''''''''''''''''''''''''''''''
 
 You can update a customer gateway either with no VPN connection, or
 related VPN connection is in error state.
 
+.. note::
+   If a VPN Customer Gateway is using excluded or obsolete cryptographic
+   parameters (as configured by your CloudStack operator), a warning icon
+   will be displayed next to the gateway name. When editing such a gateway,
+   the Update form will display warnings for any obsolete or excluded
+   parameters, encouraging you to change them to more secure alternatives.
+
 #. Log in to the CloudStack UI as an administrator or end user.
 
 #. In the left navigation, choose Network.
 
 #. In the Select view, select VPN Customer Gateway.
 
-#. Select the VPN customer gateway you want to work with.
+#. Select the VPN Customer Gateway you want to work with.
 
 #. To modify the required parameters, click the Edit VPN Customer
    Gateway button |vpn-edit-icon.png|
 
-#. To remove the VPN customer gateway, click the Delete VPN Customer
+#. To remove the VPN Customer Gateway, click the Delete VPN Customer
    Gateway button |delete.png|
 
 #. Click OK.
@@ -364,7 +481,7 @@ This feature is supported on all the hypervisors.
    For more information, see `"Creating a VPN gateway
    for the VPC" <#creating-a-vpn-gateway-for-the-vpc>`_.
 
-#. Create VPN customer gateway for both the VPCs.
+#. Create VPN Customer Gateway for both the VPCs.
 
    For more information, see `"Creating and Updating
    a VPN Customer Gateway" <#creating-and-updating-a-vpn-customer-gateway>`_.
@@ -464,6 +581,6 @@ Restarting and Removing a VPN Connection
 .. |reset-vpn.png| image:: /_static/images/reset-vpn.png
    :alt: button to reset a VPN connection
 .. |delete.png| image:: /_static/images/delete-button.png
-   :alt: button to remove a VPN customer gateway.
+   :alt: button to remove a VPN Customer Gateway.
 .. |vpn-edit-icon.png| image:: /_static/images/edit-icon.png
    :alt: button to edit.