add gateway security docs

cli/config/example-infisical-relay.yaml

@@ -0,0 +1,8 @@
+public_ip: 127.0.0.1
+auth_secret: example-auth-secret
+realm: infisical.org
+# set port 5349 for tls
+# port: 5349
+# tls_private_key_path: /full-path
+# tls_ca_path:  /full-path
+# tls_cert_path: /full-path

cli/go.mod

@@ -140,4 +140,4 @@ require (
 
 replace github.com/zalando/go-keyring => github.com/Infisical/go-keyring v1.0.2
 
-replace github.com/pion/turn/v4 => github.com/Infisical/turn/v4 v4.0.0
+replace github.com/pion/turn/v4 => github.com/Infisical/turn/v4 v4.0.1

cli/go.sum

@@ -49,8 +49,8 @@ github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03
 github.com/BurntSushi/xgb v0.0.0-20160522181843-27f122750802/go.mod h1:IVnqGOEym/WlBOVXweHU+Q+/VP0lqqI8lqeDx9IjBqo=
 github.com/Infisical/go-keyring v1.0.2 h1:dWOkI/pB/7RocfSJgGXbXxLDcVYsdslgjEPmVhb+nl8=
 github.com/Infisical/go-keyring v1.0.2/go.mod h1:LWOnn/sw9FxDW/0VY+jHFAfOFEe03xmwBVSfJnBowto=
-github.com/Infisical/turn/v4 v4.0.0 h1:NvN+CiBbsAOzJa3y4kkxDoWpTJkmY3Z6fS5ep7FFfu4=
-github.com/Infisical/turn/v4 v4.0.0/go.mod h1:pMMKP/ieNAG/fN5cZiN4SDuyKsXtNTr0ccN7IToA1zs=
+github.com/Infisical/turn/v4 v4.0.1 h1:omdelNsnFfzS5cu86W5OBR68by68a8sva4ogR0lQQnw=
+github.com/Infisical/turn/v4 v4.0.1/go.mod h1:pMMKP/ieNAG/fN5cZiN4SDuyKsXtNTr0ccN7IToA1zs=
 github.com/alessio/shellescape v1.4.1 h1:V7yhSDDn8LP4lc4jS8pFkt0zCnzVJlG5JXy9BVKJUX0=
 github.com/alessio/shellescape v1.4.1/go.mod h1:PZAiSCk0LJaZkiCSkPv8qIobYglO3FPpyFjDCtHLS30=
 github.com/antihax/optional v1.0.0/go.mod h1:uupD/76wgC+ih3iEmQUL+0Ugr19nfwCT1kdvxnR2qWY=

cli/packages/cmd/gateway.go

@@ -137,15 +137,10 @@ var gatewayRelayCmd = &cobra.Command{
 }
 
 func init() {
-	gatewayCmd.SetHelpFunc(func(command *cobra.Command, strings []string) {
-		command.Flags().MarkHidden("domain")
-		command.Parent().HelpFunc()(command, strings)
-	})
 	gatewayCmd.Flags().String("token", "", "Connect with Infisical using machine identity access token")
 
 	gatewayRelayCmd.Flags().String("config", "", "Relay config yaml file path")
 
 	gatewayCmd.AddCommand(gatewayRelayCmd)
-
 	rootCmd.AddCommand(gatewayCmd)
 }

cli/packages/gateway/gateway.go

@@ -176,7 +176,7 @@ func (g *Gateway) Listen(ctx context.Context) error {
 		KeepAlivePeriod: 2 * time.Second,
 	}
 
-	g.registerRelayIsActive(ctx, relayUdpConnection.LocalAddr().String(), errCh)
+	g.registerRelayIsActive(ctx, errCh)
 	quicListener, err := quic.Listen(relayUdpConnection, tlsConfig, quicConfig)
 	if err != nil {
 		return fmt.Errorf("Failed to listen for QUIC: %w", err)
@@ -320,39 +320,49 @@ func (g *Gateway) createPermissionForStaticIps(staticIps string) error {
 	return nil
 }
 
-func (g *Gateway) registerRelayIsActive(ctx context.Context, relayAddress string, errCh chan error) error {
-	ticker := time.NewTicker(10 * time.Second)
+func (g *Gateway) registerRelayIsActive(ctx context.Context, errCh chan error) error {
+	ticker := time.NewTicker(15 * time.Second)
 	maxFailures := 3
 	failures := 0
 
+	log.Info().Msg("Starting relay connection health check")
+
 	go func() {
-		time.Sleep(2 * time.Second)
+		time.Sleep(5 * time.Second)
 		for {
 			select {
 			case <-ctx.Done():
+				log.Info().Msg("Stopping relay connection health check")
 				return
 			case <-ticker.C:
-				// Configure TLS to skip verification
-				tlsConfig := &tls.Config{
-					InsecureSkipVerify: true,
-					NextProtos:         []string{"infisical-gateway"},
-				}
-				quicConfig := &quic.Config{
-					EnableDatagrams: true,
-				}
 				func() {
-					checkCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
-					defer cancel()
-					conn, err := quic.DialAddr(checkCtx, relayAddress, tlsConfig, quicConfig)
-					if err != nil {
+					log.Debug().Msg("Performing relay connection health check")
+
+					if g.client == nil {
 						failures++
-						log.Warn().Err(err).Int("failures", failures).Msg("Relay connection check failed")
+						log.Warn().Int("failures", failures).Msg("TURN client is nil")
+						if failures >= maxFailures {
+							errCh <- fmt.Errorf("relay connection check failed: TURN client is nil")
+						}
+						return
+					}
+
+					// we try to refresh permissions - this is a lightweight operation
+					// that will fail immediately if the UDP connection is broken. good for health check
+					log.Debug().Msg("Refreshing TURN permissions to verify connection")
+					if err := g.createPermissionForStaticIps(g.config.InfisicalStaticIp); err != nil {
+						failures++
+						log.Warn().Err(err).Int("failures", failures).Msg("Failed to refresh TURN permissions")
 						if failures >= maxFailures {
 							errCh <- fmt.Errorf("relay connection check failed: %w", err)
 						}
+						return
 					}
-					if conn != nil {
-						conn.CloseWithError(0, "closed")
+
+					log.Debug().Msg("Successfully refreshed TURN permissions - connection is healthy")
+					if failures > 0 {
+						log.Info().Int("previous_failures", failures).Msg("Relay connection restored")
+						failures = 0
 					}
 				}()
 			}

docs/documentation/platform/gateways/gateway-security.mdx

@@ -0,0 +1,110 @@
+---
+title: "Gateway Security Architecture"
+sidebarTitle: "Architecture"
+description: "Understand the security model and tenant isolation of Infisical's Gateway"
+---
+
+# Gateway Security Architecture
+
+The Infisical Gateway enables Infisical Cloud to securely interact with private resources using mutual TLS authentication and private PKI (Public Key Infrastructure) system to ensure secure, isolated communication between multiple tenants. 
+This document explains the internal security architecture and how tenant isolation is maintained.
+
+## Security Model Overview
+
+### Private PKI System
+Each organization (tenant) in Infisical has its own private PKI system consisting of:
+
+1. **Root CA**: The ultimate trust anchor for the organization
+2. **Intermediate CAs**:
+   - Client CA: Issues certificates for cloud components
+   - Gateway CA: Issues certificates for gateway instances
+
+This hierarchical structure ensures complete isolation between organizations as each has its own independent certificate chain.
+
+### Certificate Hierarchy
+```
+Root CA (Organization Specific)
+├── Client CA
+│   └── Client Certificates (Cloud Components)
+└── Gateway CA
+    └── Gateway Certificates (Gateway Instances)
+```
+
+## Communication Security
+
+### 1. Gateway Registration
+When a gateway is first deployed:
+
+1. Establishes initial connection using machine identity token
+2. Allocates a relay address for communication
+3. Exchanges certificates through a secure handshake:
+   - Gateway receives a unique certificate signed by organization's Gateway CA along with certificate chain for verification
+
+### 2. Mutual TLS Authentication
+All communication between gateway and cloud uses mutual TLS (mTLS):
+
+- **Gateway Authentication**:
+  - Presents certificate signed by organization's Gateway CA
+  - Certificate contains unique identifiers (Organization ID, Gateway ID)
+  - Cloud validates complete certificate chain
+
+- **Cloud Authentication**:
+  - Presents certificate signed by organization's Client CA
+  - Certificate includes required organizational unit ("gateway-client")
+  - Gateway validates certificate chain back to organization's root CA
+
+### 3. Relay Communication
+The relay system provides secure tunneling:
+
+1. **Connection Establishment**:
+   - Uses QUIC protocol over UDP for efficient, secure communication
+   - Provides built-in encryption, congestion control, and multiplexing
+   - Enables faster connection establishment and reduced latency
+   - Each organization's traffic is isolated using separate relay sessions
+
+2. **Traffic Isolation**:
+   - Each gateway gets unique relay credentials
+   - Traffic is end-to-end encrypted using QUIC's TLS 1.3
+   - Organization's private keys never leave their environment
+
+## Tenant Isolation
+
+### Certificate-Based Isolation
+- Each organization has unique root CA and intermediate CAs
+- Certificates contain organization-specific identifiers
+- Cross-tenant communication is cryptographically impossible
+
+### Gateway-Project Mapping
+- Gateways are explicitly mapped to specific projects
+- Access controls enforce organization boundaries
+- Project-level permissions determine resource accessibility
+
+### Resource Access Control
+1. **Project Verification**:
+   - Gateway verifies project membership
+   - Validates organization ownership
+   - Enforces project-level permissions
+
+2. **Resource Restrictions**:
+   - Gateways only accept connections to approved resources
+   - Each connection requires explicit project authorization
+   - Resources remain private to their assigned organization
+
+## Security Measures
+
+### Certificate Lifecycle
+- Certificates have limited validity periods
+- Automatic certificate rotation
+- Immediate certificate revocation capabilities
+
+### Monitoring and Verification
+1. **Continuous Verification**:
+   - Regular heartbeat checks
+   - Certificate chain validation
+   - Connection state monitoring
+
+2. **Security Controls**:
+   - Automatic connection termination on verification failure
+   - Audit logging of all access attempts
+   - Machine identity based authentication
+

docs/mint.json

@@ -203,7 +203,7 @@
         },
         {
           "group": "Gateway",
-          "pages": ["documentation/platform/gateways/overview"]
+          "pages": ["documentation/platform/gateways/overview", "documentation/platform/gateways/gateway-security"]
         },
         "documentation/platform/project-templates",
         {