istio.io/istio@v0.0.0-20240520182934-d79c90f27776/architecture/ambient/peer-authentication.md (about)

     1  # PeerAuthentication Implementation in Ambient
     2  
     3  The PeerAuthentication resource defines policy for whether or not traffic to a given mesh workload must be mTLS encrypted (through Istio mTLS specifically). While the semantics for sidecars are [relatively well defined](https://istio.io/latest/docs/reference/config/security/peer_authentication/), the architectural differences of ambient workloads have implications for how PeerAuthentication is enforced in that context. This document describes those details.
     4  
     5  ## PeerAuthentication and ztunnel
     6  
     7  The goal of ztunnel is to be a minimal L4 proxy, and as such, its xDS configuration is purposefully limited. In particular, ztunnel only supports 2 (custom) xDS resources: [`Workload`](../../pkg/workloadapi/workload.proto) and [`Authorization`](../../pkg/workloadapi/security/authorization.proto). As such, ztunnel does not receive `PeerAuthentication`s directly; when istiod detects a `PeerAuthentication` resource that targets an Ambient captured workload, it computes the effective policy for that workload (taking into account the mesh-wide -> namespace -> workload precedence rules) and sends that policy to ztunnel. The exact details of this conversion is out of scope for this document at the time of writing, but as an example, this `PeerAuthentication`:
     8  
     9  ```yaml
    10  apiVersion: security.istio.io/v1beta1
    11  kind: PeerAuthentication
    12  metadata:
    13    name: strict-and-permissive-mtls
    14  spec:
    15    selector:
    16      matchLabels:
    17        app: a
    18    mtls:
    19      mode: STRICT
    20    portLevelMtls:
    21      9090:
    22        mode: PERMISSIVE
    23  ```
    24  
    25  will be translated into this `Authorization`:
    26  
    27  ```yaml
    28  action: DENY
    29  groups:
    30  - rules:
    31    - matches:
    32      - notPrincipals:
    33        - presence: {}
    34  - rules:
    35    - matches:
    36      - notDestinationPorts:
    37        - 9090
    38  name: converted_peer_authentication_strict-and-permissive-mtls
    39  scope: WORKLOAD_SELECTOR
    40  ```
    41  
    42  The above policies reject unauthenticated traffic at the ztunnel unless its destination is port 9090. For more complete examples, read through the [test cases](../../pilot/pkg/serviceregistry/kube/controller/ambientindex_test.go) in the `TestRBACConvert` function.
    43  
    44  ## PeerAuthentication and the Waypoint Proxy
    45  
    46  (Note: this section is not yet implemented and is dependent upon discussion in the [ztunnel hairpinning doc](https://docs.google.com/document/d/1uM1c3zzoehiijh1ZpZuJ1-SzuVVupenv8r5yuCaFshs/edit#heading=h.dwbqvwmg6ud3))
    47  
    48  When a ztunnel receives traffic (authenticated or not) from a workload, it will forward that traffic to the Waypoint proxy **after** applying any `TRANSPORT` layer policies (i.e. `Authorization`s). Thus, if the destination workload has at least the equivalent of a `STRICT` `PeerAuthentication`, unauthenticated traffic will be rejected before it reaches the Waypoint proxy. If the effective policy is `PERMISSIVE` (the default), the ztunnel will open a vanilla TLS HBONE tunnel (NOTE: this is not mTLS) to the Waypoint proxy and forward the traffic over that connection without presenting a client certificate. Therefore, it is absolutely critical that the waypoint proxy not assume any identity from incoming connections, even if the ztunnel is hairpinning. In other words, all traffic over TLS HBONE tunnels must be considered to be untrusted. From there, traffic is returned to the ztunnel (still over the TLS HBONE tunnel) and forwarded to the destination workload.
    49  
    50  The following diagram illustrates the flow of unauthenticated traffic with a `PERMISSIVE` policy:
    51  
    52  ```mermaid
    53  graph TD;
    54  src[src pod]-->|plaintext port|ztunnel{"ztunnel (L4 policy applied here)"}
    55  ztunnel{ztunnel}-->|TLS|wp{waypoint}
    56  wp-->|mTLS|ztunnel
    57  ztunnel-->|plaintext|dst[dst pod]
    58  ```
    59  
    60  And here's an example of an authenticated request to a captured destination:
    61  
    62  ```mermaid
    63  graph TD;
    64  src[src pod]-->|15008|ztunnel{ztunnel}
    65  ztunnel-->|HBONE|dwp{"destination waypoint (all policy applied here)"}
    66  dwp{destination waypoint}-->|15008|dztunnel{destination ztunnel}
    67  dztunnel-->|host network|dst[dst pod]
    68  ```