github.com/cilium/cilium@v1.16.2/Documentation/network/servicemesh/mutual-authentication/mutual-authentication.rst (about)

     1  .. only:: not (epub or latex or html)
     2  
     3      WARNING: You are looking at unreleased Cilium documentation.
     4      Please use the official rendered version released here:
     5      https://docs.cilium.io
     6  
     7  .. _gs_mutual_authentication:
     8  
     9  ****************************
    10  Mutual Authentication (Beta)
    11  ****************************
    12  
    13  .. note::
    14  
    15      This is a beta feature. Please provide feedback and file a GitHub issue if
    16      you experience any problems.
    17  
    18      This feature is still incomplete, see :ref:`mutual_auth_roadmap` below for more details.
    19  
    20  Mutual Authentication and mTLS Background
    21  #########################################
    22  
    23  Mutual Transport Layer Security (mTLS) is a mechanism that ensures the authenticity, integrity, 
    24  and confidentiality of data exchanged between two entities over a network.
    25  
    26  Unlike traditional TLS, which involves a one-way authentication process where the client verifies the 
    27  server's identity, mutual TLS adds an additional layer of security by requiring both the client and the server to authenticate each other.
    28  
    29  Mutual TLS aims at providing authentication, confidentiality and integrity to service-to-service communications. 
    30  
    31  Mutual Authentication in Cilium
    32  ###############################
    33  
    34  Cilium's mTLS-based Mutual Authentication support brings the mutual authentication handshake out-of-band for regular connections.
    35  
    36  For Cilium to meet most of the common requirements for service-to-service authentication and encryption, users must enable encryption.
    37  
    38  .. Note::
    39  
    40      Cilium's encryption features,  :ref:`encryption_wg` and :ref:`encryption_ipsec`, can be enabled 
    41      to automatically create and maintain encrypted connections between Pods.
    42  
    43  To address the challenge of identity verification in dynamic and heterogeneous environments, 
    44  mutual authentication requires a framework secure identity verification for distributed systems.
    45  
    46  .. Note::
    47  
    48      To learn more about the Mutual Authentication architecture for the Cilium Service Mesh, read the `CFP <https://github.com/cilium/design-cfps/blob/main/cilium/CFP-22215-mutual-auth-for-service-mesh.md>`_.
    49  
    50  .. _identity_management:
    51  
    52  Identity Management
    53  ###################
    54  
    55  In Cilium's current mutual authentication support, identity management is provided through the use of 
    56  SPIFFE (Secure Production Identity Framework for Everyone).
    57  
    58  SPIFFE benefits
    59  ---------------
    60  Here are some of the benefits provided by `SPIFFE <https://spiffe.io/>`_ :
    61  
    62  - Trustworthy identity issuance: SPIFFE provides a standardized mechanism for issuing and managing identities. 
    63    It ensures that each service in a distributed system receives a unique and verifiable identity, even in dynamic environments where services may scale up or down frequently.
    64  - Identity attestation: SPIFFE allows services to prove their identities through attestation. 
    65    It ensures that services can demonstrate their authenticity and integrity by providing verifiable evidence about their identity, like digital signatures or cryptographic proofs.
    66  - Dynamic and scalable environments: SPIFFE addresses the challenges of identity management in dynamic environments. 
    67    It supports automatic identity issuance, rotation, and revocation, which are critical in cloud-native architectures where services may be constantly deployed, updated, or retired.
    68  
    69  Cilium and SPIFFE
    70  -----------------
    71  
    72  SPIFFE provides an API model that allows workloads to request an identity from a central server. In our case, a workload means the same thing that a Cilium Security Identity does - a set of pods described by a label set. 
    73  A SPIFFE identity is a subclass of URI, and looks something like this: ``spiffe://trust.domain/path/with/encoded/info``.
    74  
    75  There are two main parts of a SPIFFE setup:
    76  
    77  - A central SPIRE server, which forms the root of trust for the trust domain.
    78  - A per-node SPIRE agent, which first gets its own identity from the SPIRE server, then validates the identity requests of workloads running on its node.
    79  
    80  When a workload wants to get its identity, usually at startup, it connects to the local SPIRE agent using the SPIFFE workload API, and describes itself to the agent.
    81  
    82  The SPIRE agent then checks that the workload is really who it says it is, and then connects to the SPIRE server and attests that the workload is requesting an identity, and that the request is valid. 
    83  
    84  The SPIRE agent checks a number of things about the workload, that the pod is actually running on the node it's coming from, that the labels match, and so on. 
    85  
    86  Once the SPIRE agent has requested an identity from the SPIRE server, it passes it back to the workload in the SVID (SPIFFE Verified Identity Document) format.
    87  This document includes a TLS keypair in the X.509 version. 
    88  
    89  In the usual flow for SPIRE, the workload requests its own information from the SPIRE server. 
    90  In Cilium's support for SPIFFE, the Cilium agents get a common SPIFFE identity and can themselves ask for identities on behalf of other workloads.
    91  
    92  This is demonstrated in the following example.
    93  
    94  .. include:: installation.rst
    95  
    96  Examples
    97  ########
    98  
    99  Please refer to the following example on how to use and leverage
   100  the mutual authentication feature:
   101  
   102  .. toctree::
   103     :maxdepth: 1
   104     :glob:
   105  
   106     mutual-authentication-example
   107  
   108  .. admonition:: Video
   109   :class: attention
   110  
   111    If you'd like a video explanation and demo of Mutual Authentication in Cilium, check out `eCHO episode 100: Next-gen mutual authentication in Cilium <https://www.youtube.com/watch?v=BWjDlynXhzg>`__.
   112  
   113  Limitations
   114  ###########
   115  * Cilium Mutual Authentication is still in development and considered beta. Several planned security features have not been implemented yet, see below for details.
   116  * Cilium's Mutual authentication has only been validated with SPIRE, the production-ready implementation of SPIFFE.
   117    As Cilium uses SPIFFE APIs, it's possible that other SPIFFE implementations may work.
   118    However, Cilium is currently only tested with the supplied SPIRE install, and using any other SPIFFE implementation is currently not supported.
   119  * There is no current option to build a single trust domain across multiple clusters for combining Cluster Mesh and Service Mesh.
   120    Therefore clusters connected in a Cluster Mesh are not currently compatible with Mutual Authentication.
   121  * The current support of mutual authentication only works within a Cilium-managed cluster and is not compatible with an external mTLS solution.
   122  
   123  
   124  .. _mutual_auth_roadmap:
   125  
   126  Detailed Roadmap Status
   127  #######################
   128  
   129  The following table shows the roadmap status of the mutual authentication feature.
   130  There are several work items outstanding before the feature is complete from a security model perspective.
   131  For details, see the [roadmap issue](https://github.com/cilium/cilium/issues/28986).
   132  
   133  
   134  +--------------------------------------------------+----------------------------------------------------------+
   135  | SPIFFE/SPIRE Integration                         | Beta                                                     |
   136  +--------------------------------------------------+----------------------------------------------------------+
   137  | Authentication API for agent                     | Beta                                                     |
   138  +--------------------------------------------------+----------------------------------------------------------+
   139  | mTLS handshake between agents                    | Beta                                                     |
   140  +--------------------------------------------------+----------------------------------------------------------+
   141  | Auth cache to enable per-identity handshake      | Beta                                                     |
   142  +--------------------------------------------------+----------------------------------------------------------+
   143  | CiliumNetworkPolicy support                      | Beta                                                     |
   144  +--------------------------------------------------+----------------------------------------------------------+
   145  | Integrate with WireGuard                         | TODO                                                     |
   146  +--------------------------------------------------+----------------------------------------------------------+
   147  | Per-connection handshake                         | TODO                                                     |
   148  +--------------------------------------------------+----------------------------------------------------------+
   149  | Sync ipcache with auth data                      | TODO                                                     |
   150  +--------------------------------------------------+----------------------------------------------------------+
   151  | Detailed documentation of security model         | TODO                                                     |
   152  +--------------------------------------------------+----------------------------------------------------------+
   153  | Conduct penetration test of model                | TODO                                                     |
   154  +--------------------------------------------------+----------------------------------------------------------+
   155  | Minimize packet drops                            | TODO                                                     |
   156  +--------------------------------------------------+----------------------------------------------------------+
   157  | Use auth secret for network encryption           | TODO                                                     |
   158  +--------------------------------------------------+----------------------------------------------------------+
   159  | Review maturity and consider for stable          | TODO                                                     |
   160  +--------------------------------------------------+----------------------------------------------------------+