Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update secure-communications.md #8165

Merged
merged 3 commits into from
Nov 27, 2024
Merged

Update secure-communications.md #8165

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
707f9fe
Update secure-communications.md
veenaraja Nov 22, 2024
e42adfc
Apply suggestions from code review
cloudjumpercat Nov 25, 2024
616fc72
Apply suggestions from code review
cloudjumpercat Nov 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 28 additions & 9 deletions app/konnect/gateway-manager/data-plane-nodes/secure-communications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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.

## 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 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:

Expand All @@ -20,9 +18,30 @@ 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.
## Generate certificates in {{site.konnect_short_name}}
{{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.
Loading