Generate Certificates and associate them with SNIs (#363)

* rebase and conflicts and things * generate and test cert * Apply suggestions from code review Co-authored-by: lena-larionova <[email protected]> * feedback * fix * remove konnect specific * test and cleanup * use key icon for cert prereq * fix typo --------- Co-authored-by: lena-larionova <[email protected]> Co-authored-by: lena-larionova <[email protected]>
Kong · Feb 1, 2025 · 9ad1826 · 9ad1826
1 parent 6e65abb
commit 9ad1826
Show file tree

Hide file tree

Showing 5 changed files with 283 additions and 9 deletions.
diff --git a/app/_how-tos/associate-certificate-with-sni.md b/app/_how-tos/associate-certificate-with-sni.md
@@ -0,0 +1,96 @@
+---
+title: Associate a Certificate with an SNI
+content_type: how_to
+related_resources:
+  - text: Secure your API with TLS using SNIs
+    url: /how-to/secure-api-with-tls/
+  - text: Proxy TLS traffic
+    url: /how-to/proxy-tls-passthrough-traffic-using-sni/
+
+products:
+    - gateway
+
+works_on:
+    - on-prem
+    - konnect
+
+entities: 
+  - certificate
+  - sni
+  - route
+  - service
+
+tldr:
+    q: How do you associate a Certificate with an SNI and make sure it works?
+    a: |
+      After creating a Certificate entity in {{site.base_gateway}}, 
+      you can associate it to an SNI and use `openssl` to verify that {{site.base_gateway}} returns the expected certificate for the SNI. 
+
+tools:
+    - deck
+
+prereqs:
+  inline:
+    - title: Create an SSL certificate
+      include_content: prereqs/certificate
+      icon_url: /assets/icons/key.svg
+    - title: Configure environment variables
+      content: |
+        Set the `SNI_NAME` as an environment variable. 
+        This is the name of the [SNI](/gateway/entities/sni/) that you intend to associate the Certificate to.
+
+        For example: 
+        ```sh
+        export SNI_NAME=my.sni.example.com
+        ```
+    
+
+cleanup:
+  inline:
+    - title: Clean up Konnect environment
+      include_content: cleanup/platform/konnect
+      icon_url: /assets/icons/gateway.svg
+    - title: Destroy the {{site.base_gateway}} container
+      include_content: cleanup/products/gateway
+      icon_url: /assets/icons/gateway.svg
+
+min_version:
+    gateway: '3.4'
+
+tags:
+  - ssl
+  - certificates
+---
+
+
+## 1. Associate your certificate with an SNI
+
+Associate the Certificate you created as a [prerequisite](#prerequisites) with an SNI. 
+If the SNI doesn't exist, this request creates a new one:
+
+{% control_plane_request %}
+url: certificates/$CERT_ID/snis
+method: POST
+headers:
+  - 'Accept: application/json'
+  - 'Content-Type: application/json'
+body:
+  name: $SNI_NAME
+{% endcontrol_plane_request %}
+
+## 2. Validate the certificate
+
+Using `openssl`, open a connection with {{site.base_gateway}} and check that {{site.base_gateway}} returns the correct certificate for the SNI:
+
+```sh
+echo "" | openssl s_client \
+  -connect 127.0.0.1 \
+  -port 8443 \
+  -servername $SNI_NAME 2>/dev/null \
+  | openssl x509 -text -noout | head -10
+```
+
+The response will contain the certificate you created and attached to the SNI in the first step, along with the `CN` and any other information you used when creating the certificate. 
+Because TLS passthrough is not enabled, {{site.base_gateway}} is returning its own Certificate. 
+
+For instructions on configuring TLS passthrough, review the how-to guide on [Proxying TLS traffic](/how-to/proxy-tls-passthrough-traffic-using-sni/).
diff --git a/app/_how-tos/proxy-tls-passthrough-traffic-using-sni.md b/app/_how-tos/proxy-tls-passthrough-traffic-using-sni.md
@@ -1,10 +1,11 @@
 ---
-title: Proxy TLS passthrough traffic using an SNI in {{site.base_gateway}}
+title: Proxy TLS passthrough traffic
 content_type: how_to
 related_resources:
   - text: SNI entity
     url: /gateway/entities/snis
 
+
 products:
     - gateway
 
@@ -24,6 +25,13 @@ tldr:
 tools:
     - deck
 
+prereqs:
+  entities:
+      services:
+        - example-service
+      routes:
+        - example-route
+
 cleanup:
   inline:
     - title: Clean up Konnect environment
@@ -37,10 +45,5 @@ min_version:
     gateway: '3.4'
 ---
 
-@todo
-
-<!--content notes:
-- Based on this section: https://docs.konghq.com/gateway/latest/how-kong-works/routing-traffic/#proxy-tls-passthrough-traffic
-- Add certificate and SNI prereqs
-
--->
+@TODO
+{{site.base_gateway}} can proxy TLS requests using the client's TLS SNI extension as a forwarding mechanism. This allows a TLS request to be accepted without needing to decrypt it. 
diff --git a/app/_how-tos/secure-api-with-tls.md b/app/_how-tos/secure-api-with-tls.md
@@ -0,0 +1,92 @@
+---
+title: Secure your API with TLS using SNIs
+content_type: how_to
+related_resources:
+  - text: SNI entity
+    url: /gateway/entities/snis/
+  - text: Certificates
+    url: /gateway/entities/certificate/
+
+
+products:
+    - gateway
+tier: enterprise
+
+works_on:
+    - on-prem
+
+entities: 
+  - certificate
+  - sni
+  - route
+  - service
+
+tldr:
+    q: How do I set up {{site.base_gateway}} with TLS?
+    a: By creating an SSL [Certificate](/gateway/entities/certificate), and associating it with an [SNI](/gateway/entities/sni), you can force {{site.base_gateway}} to handle encrypted traffic.
+tools:
+    - deck
+
+prereqs:
+  inline:
+    - title: Certificate
+      include_content: prereqs/certificate
+      icon_url: /assets/icons/file.svg
+    - title: Configure environment variables
+      content: |
+        Set the following variables: 
+        * `CERT_ID`: The UUID set when you associated a Certificate with {{site.base_gateway}}.
+        For example: 
+        ```sh
+        export CERT_ID=3f19b7d1-705f-422a-a116-7dc8282efe21
+        ```
+        icon_url: /assets/icons/file.svg
+    
+cleanup:
+  inline:
+    - title: Clean up Konnect environment
+      include_content: cleanup/platform/konnect
+      icon_url: /assets/icons/gateway.svg
+    - title: Destroy the {{site.base_gateway}} container
+      include_content: cleanup/products/gateway
+      icon_url: /assets/icons/gateway.svg
+
+
+min_version:
+    gateway: '3.4'
+---
+
+@TODO
+
+{{site.base_gateway}} can proxy TLS requests using the client's TLS SNI extension as a forwarding mechanism. This allows a TLS request to be accepted without needing to decrypt it. 
+
+## 1. Retrieve the ID of your certificate
+
+{% capture request %}
+{% control_plane_request %}
+  url: certicates/
+{% endcontrol_plane_request %}
+{% endcapture %}
+
+Copy the UUID in the response body to use in the next step. 
+
+## 2. Associate your certificate with an SNI
+
+{% capture request %}
+{% control_plane_request %}
+  url: certificates/$YOUR_CERT_ID/snis
+  method: POST
+  body:
+      name: "$SNI_NAME"
+{% endcontrol_plane_request %}
+{% endcapture %}
+
+{{request | indent: 3}}
+<!-- vale on -->
+
+
+## 3. Validate 
+
+```
+echo "" | openssl s_client -connect 127.0.0.1 -port 8443 -servername $SNI_NAME 2>/dev/null | openssl x509 -text -noout | head -10
+```
diff --git a/app/_includes/prereqs/certificate.md b/app/_includes/prereqs/certificate.md
@@ -0,0 +1,82 @@
+1. Generate a private key:
+
+    ```sh
+    openssl genpkey -algorithm RSA -out my-key.pem
+    ```
+2. Generate a certificate signing request:
+
+    ```sh
+    openssl req -new -key my-key.pem -out my-csr.pem
+    ```
+3. Create a self-signed certificate:
+
+    ```sh
+    openssl x509 -req -in my-csr.pem -signkey my-key.pem -out my-cert.pem -days 365
+    ```
+
+4. Create a UUID and export it so the value can be used through the rest of the guide:
+
+    ```sh
+    export CERT_ID=$(uuidgen) && echo "CERT_ID=$CERT_ID"
+    ```
+
+4. Using the contents of `my-key.pem`, `my-cert.pem`, and the `CERT_ID`, add the 
+Certificate to {{site.base_gateway}} using decK:
+
+```sh
+echo '
+_format_version: "3.0"
+certificates:
+  - cert: |-
+      -----BEGIN CERTIFICATE-----
+      MIIDRTCCAi2gAwIBAgIUMJERhwxue4l6zF2if4gcCjdzXKwwDQYJKoZIhvcNAQEL
+      BQAwSzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAk5DMQ8wDQYDVQQHDAZCb3N0b24x
+      DTALBgNVBAoMBEtvbmcxDzANBgNVBAMMBm15LXNuaTAeFw0yNTAxMjgxOTQ3MTRa
+      Fw0yNjAxMjgxOTQ3MTRaMEsxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJOQzEPMA0G
+      A1UEBwwGQm9zdG9uMQ0wCwYDVQQKDARLb25nMQ8wDQYDVQQDDAZteS1zbmkwggEi
+      MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC10bdAm7LZZCq3TAVVvwkKufS1
+      1UQ9EsYhnz3isYxxv4zrRaK9jh4GGi8aLJO1/GllCU0oASo9ZWLFLQpjlPsIP9v8
+      LeJ9M7B8Kt55+0uxOsv5XmuX1zposGy6Z0lpY9If032bfHhztTQWmIqpuCgmh6r4
+      k4x+lArN3T/v6OensmtC6iDEaSHzOo2moAtpD5KFyIIiuOmdWNxcraFNbuWjdOPP
+      pv/OUC8ktdGeYoBHzYNNlWXkDufbt0ADC/wzpbvDHT6f2RGZelJttCYm1xm3qDWp
+      NTeejEYXevP6Z6zoEeJsCEEju0xInOHWHiAPIze2GdQZ6U0H/4zKtMyDyJdvAgMB
+      AAGjITAfMB0GA1UdDgQWBBRI8YKbENL6XqNmRv0MQjNvLzK3GDANBgkqhkiG9w0B
+      AQsFAAOCAQEAsIVPxHb1Ll+2KyyftiCKH/dmaeG14MOIp1sVPFbt5DolhBdriFLr
+      EVaefttPd4Z3uq11pyhKdhVmjDJ1a9mUJjD5CVrnp5+7D2qw1QNzU8Y9H9Io1LOI
+      Uofs1OXoIQI5c+oYUZM7PoD+/hcUKKl2vZ44dcPMYBnhn1qZPn95IqDTMPBcbSm+
+      CFiyJ8sF6mF26qaT6gTIbKjOSA9b+XWWJUPpwtUxAd5KjdzbTEmemy3dkeNPQJNM
+      HnWQz/VRQEC2md43lRU6KUxhUamXf+boOOMT4k1b8pj3tEcEqY2cW4CZ8qGgEvyr
+      4/t5YSkmXGTbbC8QwdK+MxjlPbfVqp9nUg==
+      -----END CERTIFICATE-----
+    id: 2D22E0CD-55D8-4901-8500-986C6B515CFC
+    key: |-
+      -----BEGIN PRIVATE KEY-----
+      MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC10bdAm7LZZCq3
+      TAVVvwkKufS11UQ9EsYhnz3isYxxv4zrRaK9jh4GGi8aLJO1/GllCU0oASo9ZWLF
+      LQpjlPsIP9v8LeJ9M7B8Kt55+0uxOsv5XmuX1zposGy6Z0lpY9If032bfHhztTQW
+      mIqpuCgmh6r4k4x+lArN3T/v6OensmtC6iDEaSHzOo2moAtpD5KFyIIiuOmdWNxc
+      raFNbuWjdOPPpv/OUC8ktdGeYoBHzYNNlWXkDufbt0ADC/wzpbvDHT6f2RGZelJt
+      tCYm1xm3qDWpNTeejEYXevP6Z6zoEeJsCEEju0xInOHWHiAPIze2GdQZ6U0H/4zK
+      tMyDyJdvAgMBAAECggEAKP2BueAgPyB0/OP3o/AwoqlvwPq2qqor3vKeqhfrGM3d
+      gEEvwlpi7G9ExTrdhj7EqBGjwmwY0MSlstxHplG1EpQLDVxu3lkj5apog8mis+8U
+      g0DFMvND6Mw1hwS4KTlm6uPsQnyaT0O/3YRAZqjs7FrTsbzaBMNteCH0QysX5tdR
+      LNNViuOjfBvqtlNqoMGkxwHxou52xo+Er6vFAlv9+dHUbQfnxwbPQJrDTB/jZDru
+      SN7En2bDv9EyWNofahAiy9xFhb9PtclhktdiHQWIhD5ZlxKatoU4YAGe6Qyh2nl9
+      3sh7vTfioOwNjE9POzPUxUyCB3ihN9QP+ErR7/gocQKBgQD7N+5zPKcjpNzzZ5Nn
+      YK9D55UxFBC6r44iShgYomYvl8spfPfrW4+IFuJDncdB2KezffEJRK1kwp6jHJf+
+      2skMpNhjlU7f5ShoxYF3BnGIcKVlXCep++TkezCUHZBmtZgN7FYyvx+rISfYJXCY
+      7BH3I0TmJF4NzGBCKNDN1lAX2QKBgQC5R6J0/WbrIUZjVY3qQRlCSZmDzxWE3kMf
+      94Mam4bXu05GIinttQ0Xr9RaeaEXYMdE4+Do3GGLTP16BV9z+piTZVLz6/qIHDnO
+      I3osnagXmMcBWF0jTNG2PzHpKgEIbRXvuz2ltggu3xbySwIOCGImgxyalYapLUnO
+      RgLvpE2khwKBgEGAk+v4JJxmoDXXC9gonYpXF890K+iBXc4TA7VoorxGF/L5Yqs7
+      dHFHhjebLBk/JHrom7CO96cOF87v5bHN2h4x3ToZ9DbsyVyIIvml9HRe6sFDBhSM
+      WWI5vLDiBITDVKJMvSz+KIO2YW06VeGJrCWETLK1SNDQOUkG22rQNpIBAoGAOjC0
+      Zjfb5gcaW0JYgvUVIMuKymn0oTlJLbYH2Ah2rjSmncJHFuAhD4pqkEvY+0Wq8Aj9
+      70Sf4ic5COS9GOjgmJJfHjrEAZGT2hksWuzdCSQzhEmjXt3Wk31/iHJnxqS0Ggnd
+      j7j/EvF//HLwX0XkxaGyDx7dHy8ZGg7FB0y8EesCgYA1Py0mm6WLMUP6xlXnrlhj
+      hzg8ZZ+GB5MZRc2oeKlYPkaRIC3WRd6iXgX58no60ByAzmjimXWvwd9DMJgeAvyW
+      ei+z5QAXvWnkAjatMRedOlf26KkKdAax5QDqNbN3DIk+SIbAPWN0ecYag9YQt/m8
+      mFmxfVBnyBFNNIj1RMmQrg==
+      -----END PRIVATE KEY-----
+' | deck gateway apply - 
+```
diff --git a/tools/track-docs-changes/config/sources.yml b/tools/track-docs-changes/config/sources.yml
@@ -156,7 +156,8 @@ app/_how-tos/verify-signatures-for-signed-images.md:
   - app/_src/gateway/kong-enterprise/signed-images.md
 app/_how-tos/verify-build-provenance-for-signed-images.md:
   - app/_src/gateway/kong-enterprise/provenance-verification.md
-
+app/_how-tos/proxy-tls-passthrough.md: 
+  - app/_src/gateway/how-kong-works/routing-traffic.md
 
 # plugins
 app/_kong_plugins/ai-rate-limiting-advanced/index.md: