From 707f9fe8d9a6233f069c15f28cc03fc2ed0b4070 Mon Sep 17 00:00:00 2001 From: veenaraja <135896097+veenaraja@users.noreply.github.com> Date: Fri, 22 Nov 2024 10:17:11 -0800 Subject: [PATCH 1/3] Update secure-communications.md --- .../data-plane-nodes/secure-communications.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/app/konnect/gateway-manager/data-plane-nodes/secure-communications.md b/app/konnect/gateway-manager/data-plane-nodes/secure-communications.md index a85873487b4a..622b9abd9b90 100644 --- a/app/konnect/gateway-manager/data-plane-nodes/secure-communications.md +++ b/app/konnect/gateway-manager/data-plane-nodes/secure-communications.md @@ -3,14 +3,12 @@ title: Secure Control Plane and Data Plane Communications content_type: how-to --- -{{site.konnect_short_name}} uses a mutual TLS handshake (mTLS) for authentication between data plane and control plane so the actual private key is never transferred on the network, and communication between the control plane and data plane nodes is secure. {{site.konnect_short_name}} supports two modes for handling certificate/key pairs: -* **Pinned mode**: This is the default mode. The same public key is added to the data plane and the control plane, and the control plane uses this public key to authenticate the data plane. Validation of the certificate only happens on the control plane. -* **Public Key Infrastructure (PKI) mode**: This mode uses digital certificates signed by a certificate authority, or a chain of certificate authorities, to authenticate between control plane and data plane. The public key is added to the data plane, while the chain of certificate authority is added to the control plane. Any certificate authority from the chain can be used to authenticate between dataplane and control plane. {{site.konnect_short_name}} validates both the control plane and data plane sides by checking if they are from the same certificate authority, thereby increasing the security of the network and eliminating the risks associated with transporting private keys. This mode is only supported for Control Plane and Control Plane Groups. +{{site.konnect_short_name}} uses a mutual TLS handshake (mTLS) to secure communication between the control plane and data plane nodes. {{site.konnect_short_name}} control planes support data planes authenticating either with a certificate keypair (aka ‘pinned cert’) or use a certificate signed by a CA (aka PKI). +* **Pinned Certificates**: The data planes authenticate to control plane using a shared certificate. For this option, the control plane and data plane nodes are provisioned with the same certificate. The control plane validates that the data planes establish connection using the pinned certificate. +* **Public Key Infrastructure (PKI) Certificates**: The data planes can establish connection using digital certificates signed by a certificate authority (CA). The control plane must be provisioned with the CA certificate. Konnect uses this certificate to build a chain of trust by verifying the certificates presented by the data planes. If there are intermediate authorities issuing the certificates, the data plane nodes must include the intermediate certificates while establishing connection to control plane. -## Set certificate authentication mode -You specify which certificate authentication mode is used at the control plane level. You can select between Pinned mode and PKI mode while creating a control plane, or edit the control plane to select a different mode. - -You need to upload enough of the certificate chain in the control plane so that the control plane can trust the certificate in the dataplane request and authenticate. +## Certificate Chain +You need to upload enough of the certificate chain in the control plane so that the control plane can trust the certificate in the data plane request and authenticate. Consider the following scenarios with this example cert chain: @@ -20,9 +18,11 @@ Consider the following scenarios with this example cert chain: | `cert2` | Intermediary | Issued by Root | | `cert3` | Root | Issued by Root (Self-signed) | -* **Upload only cert1 to the control plane**: This is the Pinned mode. You can include just `cert1` in your data plane request and not include the chain. The control plane doesn’t need to evaluate the issuer because it trusts the cert itself. +* **Upload only cert1 to the control plane**: This is the Pinned certificate. You can include just `cert1` in your data plane request and not include the chain. The control plane doesn’t need to evaluate the issuer because it trusts the cert itself. * **Upload only cert2 to the control plane**: This would mean any cert coming in that has (issuer: intermediary) would be trusted. You can include just `cert1` in your data plane request. The control plane would trust any certificate issued by the intermediary public key. * **Upload only cert3 to the control plane**: This is the typical PKI case. It means any cert signed by the root is trusted. However, since `cert1` is signed by an intermediary and `cert2` is signed by root, you need to include both `cert1` and `cert2` in your data plane request. The control plane would trust the whole chain because `cert2` is issued by `cert3` and `cert1` is issued by `cert2`. -You can generate pinned certificates in {{site.konnect_short_name}} or bring your own pinned and PKI certificates. Data plane certificates generated by {{site.konnect_short_name}} expire every ten years. If you bring your own certificates, make sure to review the expiration date and associated metadata. See [Renew Certificates for a Data Plane Node](/konnect/gateway-manager/data-plane-nodes/renew-certificates/) for more details. +## Konnect Certificate Utility +{{site.konnect_short_name}} offers a helper utility to get started with securing control plane / data plane communications. Using the quick start flow, a certificate keypair is generated. Data planes can establish a connection with this certificate keypair (aka ‘pinned cert’). Alternatively, the Generate Certificates option in the UI generates a CA allowing data planes to connect using a certificate signed by that CA (aka PKI). +Certificates generated by {{site.konnect_short_name}} have a 10 year validity. If you bring your own certificates, make sure to review the expiration date and associated metadata. See Renew Certificates for a Data Plane Node for more details. From e42adfc37e1f530d276e46a15b485bbe160ed360 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Mon, 25 Nov 2024 09:52:30 -0600 Subject: [PATCH 2/3] Apply suggestions from code review --- .../data-plane-nodes/secure-communications.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/app/konnect/gateway-manager/data-plane-nodes/secure-communications.md b/app/konnect/gateway-manager/data-plane-nodes/secure-communications.md index 622b9abd9b90..f6d956a4c489 100644 --- a/app/konnect/gateway-manager/data-plane-nodes/secure-communications.md +++ b/app/konnect/gateway-manager/data-plane-nodes/secure-communications.md @@ -3,12 +3,12 @@ title: Secure Control Plane and Data Plane Communications content_type: how-to --- -{{site.konnect_short_name}} uses a mutual TLS handshake (mTLS) to secure communication between the control plane and data plane nodes. {{site.konnect_short_name}} control planes support data planes authenticating either with a certificate keypair (aka ‘pinned cert’) or use a certificate signed by a CA (aka PKI). -* **Pinned Certificates**: The data planes authenticate to control plane using a shared certificate. For this option, the control plane and data plane nodes are provisioned with the same certificate. The control plane validates that the data planes establish connection using the pinned certificate. -* **Public Key Infrastructure (PKI) Certificates**: The data planes can establish connection using digital certificates signed by a certificate authority (CA). The control plane must be provisioned with the CA certificate. Konnect uses this certificate to build a chain of trust by verifying the certificates presented by the data planes. If there are intermediate authorities issuing the certificates, the data plane nodes must include the intermediate certificates while establishing connection to control plane. +{{site.konnect_short_name}} uses a mutual TLS handshake (mTLS) to secure communication between the control plane and data plane nodes. {{site.konnect_short_name}} control planes support data planes authenticating either with a certificate key pair (a pinned certificate) or a certificate signed by a CA (a PKI certificate). +* **Pinned certificates**: The data planes authenticate to the control plane using a shared certificate. For this option, the control plane and data plane nodes are provisioned with the same certificate. The control plane validates that the data planes established connection using the pinned certificate. +* **Public Key Infrastructure (PKI) certificates**: The data planes can establish connection using digital certificates signed by a certificate authority (CA). The control plane must be provisioned with the CA certificate. {{site.konnect_short_name}} uses this certificate to build a chain of trust by verifying the certificates presented by the data planes. If there are intermediate authorities issuing the certificates, the data plane nodes must include the intermediate certificates while establishing connection to the control plane. -## Certificate Chain -You need to upload enough of the certificate chain in the control plane so that the control plane can trust the certificate in the data plane request and authenticate. +## Certificate chain +You must upload enough of the certificate chain in the control plane so that the control plane can trust the certificate in the data plane request and authenticate. Consider the following scenarios with this example cert chain: @@ -18,11 +18,11 @@ Consider the following scenarios with this example cert chain: | `cert2` | Intermediary | Issued by Root | | `cert3` | Root | Issued by Root (Self-signed) | -* **Upload only cert1 to the control plane**: This is the Pinned certificate. You can include just `cert1` in your data plane request and not include the chain. The control plane doesn’t need to evaluate the issuer because it trusts the cert itself. +* **Upload only cert1 to the control plane**: This is the pinned certificate. You can include just `cert1` in your data plane request and not include the chain. The control plane doesn’t need to evaluate the issuer because it trusts the cert itself. * **Upload only cert2 to the control plane**: This would mean any cert coming in that has (issuer: intermediary) would be trusted. You can include just `cert1` in your data plane request. The control plane would trust any certificate issued by the intermediary public key. * **Upload only cert3 to the control plane**: This is the typical PKI case. It means any cert signed by the root is trusted. However, since `cert1` is signed by an intermediary and `cert2` is signed by root, you need to include both `cert1` and `cert2` in your data plane request. The control plane would trust the whole chain because `cert2` is issued by `cert3` and `cert1` is issued by `cert2`. -## Konnect Certificate Utility +## Generate certificates in {{site.konnect_short_name}} {{site.konnect_short_name}} offers a helper utility to get started with securing control plane / data plane communications. Using the quick start flow, a certificate keypair is generated. Data planes can establish a connection with this certificate keypair (aka ‘pinned cert’). Alternatively, the Generate Certificates option in the UI generates a CA allowing data planes to connect using a certificate signed by that CA (aka PKI). -Certificates generated by {{site.konnect_short_name}} have a 10 year validity. If you bring your own certificates, make sure to review the expiration date and associated metadata. See Renew Certificates for a Data Plane Node for more details. +Certificates generated by {{site.konnect_short_name}} are valid for 10 years. If you bring your own certificates, make sure to review the expiration date and associated metadata. See [Renew Certificates for a Data Plane Node](/konnect/gateway-manager/data-plane-nodes/renew-certificates/) for more details. From 616fc729ee271cd260b9bc00841bb4a38fd4e4d7 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 26 Nov 2024 15:32:46 -0600 Subject: [PATCH 3/3] Apply suggestions from code review --- .../data-plane-nodes/secure-communications.md | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/app/konnect/gateway-manager/data-plane-nodes/secure-communications.md b/app/konnect/gateway-manager/data-plane-nodes/secure-communications.md index f6d956a4c489..75766f3e4fa3 100644 --- a/app/konnect/gateway-manager/data-plane-nodes/secure-communications.md +++ b/app/konnect/gateway-manager/data-plane-nodes/secure-communications.md @@ -23,6 +23,25 @@ Consider the following scenarios with this example cert chain: * **Upload only cert3 to the control plane**: This is the typical PKI case. It means any cert signed by the root is trusted. However, since `cert1` is signed by an intermediary and `cert2` is signed by root, you need to include both `cert1` and `cert2` in your data plane request. The control plane would trust the whole chain because `cert2` is issued by `cert3` and `cert1` is issued by `cert2`. ## Generate certificates in {{site.konnect_short_name}} -{{site.konnect_short_name}} offers a helper utility to get started with securing control plane / data plane communications. Using the quick start flow, a certificate keypair is generated. Data planes can establish a connection with this certificate keypair (aka ‘pinned cert’). Alternatively, the Generate Certificates option in the UI generates a CA allowing data planes to connect using a certificate signed by that CA (aka PKI). +{{site.konnect_short_name}} provides several options to generate or add a certificate for your data plane nodes. + +### Generate a certificate key pair + +When you use the {{site.konnect_short_name}} wizard to create a data plane node, it generates a certificate key pair. Data planes can establish a connection with this certificate key pair (pinned cert). + +1. 1. Navigate to [**Gateway Manager**](https://cloud.konghq.com/gateway-manager/) in {{site.konnect_short_name}}. +1. Click on the control plane you want to create a data plane node for. +1. Click **Data Plane Nodes** in the sidebar. +1. Click **Create a New Data Plane Node**. +1. Follow the instructions in the wizard to create a data plane node and generate the certificate key pair. + +### Generate a CA-signed certificate + +Using the {{site.konnect_short_name}} UI, you can generate a CA certificate, which allows data planes to connect using a certificate signed by that CA (PKI). Alternatively you can upload your own CA using the upload option. + +1. Navigate to [**Gateway Manager**](https://cloud.konghq.com/gateway-manager/) in {{site.konnect_short_name}}. +1. Click on the control plane you want to create a data plane node for. +1. From the Action menu, select **Data Plane Certificates**. +1. Either upload or generate a certificate. Certificates generated by {{site.konnect_short_name}} are valid for 10 years. If you bring your own certificates, make sure to review the expiration date and associated metadata. See [Renew Certificates for a Data Plane Node](/konnect/gateway-manager/data-plane-nodes/renew-certificates/) for more details.