ipsec

Documentation

Overview

Package ipsec provides the Linux datapath specific abstraction and useful helpers to manage IPSec via Linux xfrm.

Index

• Constants
• Variables
• func DeleteIPsecEncryptRoute(log *slog.Logger)
• func DeleteIPsecEndpoint(log *slog.Logger, nodeID uint16) error
• func DeleteXFRM(log *slog.Logger, reqID int) error
• func IPsecDefaultDropPolicy(log *slog.Logger, ipv6 bool) error
• func IpSecReplacePolicyFwd(dst *net.IPNet, tmplDst net.IP, reqID int) error
• func LoadIPSecKeys(log *slog.Logger, r io.Reader) (int, uint8, error)
• func LoadIPSecKeysFile(log *slog.Logger, path string) (int, uint8, error)
• func NewXFRMCollector(log *slog.Logger) prometheus.Collector
• func NewXfrmStateListCache(ttl time.Duration) *xfrmStateListCache
• func ProbeXfrmStateOutputMask() (e error)
• func SetIPSecSPI(log *slog.Logger, spi uint8) error
• func StartKeyfileWatcher(log *slog.Logger, group job.Group, keyfilePath string, ...) error
• func UpsertIPsecEndpoint(log *slog.Logger, local, remote *net.IPNet, outerLocal, outerRemote net.IP, ...) (uint8, error)
• type IPSecDir

Constants

const (
	IPSecDirIn      IPSecDir = "IPSEC_IN"
	IPSecDirOut     IPSecDir = "IPSEC_OUT"
	IPSecDirBoth    IPSecDir = "IPSEC_BOTH"
	IPSecDirOutNode IPSecDir = "IPSEC_OUT_NODE"

	// The request ID which signifies all Cilium managed policies and states.
	AllReqID = 0

	// DefaultReqID is the default reqid used for all IPSec rules.
	DefaultReqID = 1

	// EncryptedOverlayReqID is the reqid used for encrypting overlay traffic.
	EncryptedOverlayReqID = 2
)

Variables

var Cell = cell.Module(
	"ipsec-key-custodian",
	"Handles initial key setup and knows the key size",

	cell.Provide(newKeyCustodian),
)

The IPsec key custodian handles key-related initialisation tasks for the ipsec subsystem. It's an incremental step towards a more encompassing modularisation of the subsystem.

Functions

func DeleteIPsecEncryptRoute

func DeleteIPsecEncryptRoute(log *slog.Logger)

DeleteIPsecEncryptRoute removes nodes in main routing table by walking routes and matching route protocol type.

func DeleteIPsecEndpoint

func DeleteIPsecEndpoint(log *slog.Logger, nodeID uint16) error

DeleteIPsecEndpoint deletes a endpoint associated with the remote IP address

func DeleteXFRM

func DeleteXFRM(log *slog.Logger, reqID int) error

DeleteXFRM will remove XFRM policies and states by their XFRM request ID.

AllReqID can be used for `reqID` to remove all Cilium managed XFRM policies and states.

func IPsecDefaultDropPolicy

func IPsecDefaultDropPolicy(log *slog.Logger, ipv6 bool) error

Installs a catch-all policy for outgoing traffic that has the encryption bit. The goal here is to catch any traffic that may passthrough our encryption while we are replacing XFRM policies & states. Those operations cannot always be performed atomically so we may have brief moments where there is no XFRM policy to encrypt a subset of traffic. This policy ensures we drop such traffic and don't let it flow in plain text.

We do need to match on the mark because there is also traffic flowing through XFRM that we don't want to encrypt (e.g., hostns traffic).

func IpSecReplacePolicyFwd

func IpSecReplacePolicyFwd(dst *net.IPNet, tmplDst net.IP, reqID int) error

func LoadIPSecKeys

func LoadIPSecKeys(log *slog.Logger, r io.Reader) (int, uint8, error)

func LoadIPSecKeysFile

func LoadIPSecKeysFile(log *slog.Logger, path string) (int, uint8, error)

LoadIPSecKeysFile imports IPSec auth and crypt keys from a file. The format is to put a key per line as follows, (auth-algo auth-key enc-algo enc-key) Returns the authentication overhead in bytes, the key ID, and an error.

func NewXFRMCollector

func NewXFRMCollector(log *slog.Logger) prometheus.Collector

func NewXfrmStateListCache

func NewXfrmStateListCache(ttl time.Duration) *xfrmStateListCache

func ProbeXfrmStateOutputMask

func ProbeXfrmStateOutputMask() (e error)

ProbeXfrmStateOutputMask probes the kernel to determine if it supports setting the xfrm state output mask (Linux 4.19+). It returns an error if the output mask is not supported or if an error occurred, nil otherwise.

func SetIPSecSPI

func SetIPSecSPI(log *slog.Logger, spi uint8) error

func StartKeyfileWatcher

func StartKeyfileWatcher(log *slog.Logger, group job.Group, keyfilePath string, nodeHandler datapath.NodeHandler) error

func UpsertIPsecEndpoint

func UpsertIPsecEndpoint(log *slog.Logger, local, remote *net.IPNet, outerLocal, outerRemote net.IP, remoteNodeID uint16, remoteBootID string, dir IPSecDir, outputMark, remoteRebooted bool, reqID int) (uint8, error)

UpsertIPsecEndpoint updates the IPSec context for a new endpoint inserted in * the ipcache. Currently we support a global crypt/auth keyset that will encrypt * all traffic between endpoints. An IPSec context consists of two pieces a policy * and a state, the security policy database (SPD) and security association * database (SAD). These are implemented using the Linux kernels XFRM implementation. * * For all traffic that matches a policy, the policy tuple used is * (sip/mask, dip/mask, dev) with an optional mark field used in the Cilium implementation * to ensure only expected traffic is encrypted. The state hashtable is searched for * a matching state associated with that flow. The Linux kernel will do a series of * hash lookups to find the most specific state (xfrm_dst) possible. The hash keys searched are * the following, (daddr, saddr, reqid, encap_family), (daddr, wildcard, reqid, encap), * (mark, daddr, spi, proto, encap). Any "hits" in the hash table will subsequently * have the SPI checked to ensure it also matches. Encap is ignored in our case here * and can be used with UDP encap if wanted. * * The implications of the (inflexible!) hash key implementation is that in-order * to have a policy/state match we _must_ insert a state for each daddr. For Cilium * this translates to a state entry per node. We learn the nodes/endpoints by * listening to ipcache events. Finally, because IPSec is unidirectional a state * is needed for both ingress and egress. Denoted by the DIR on the xfrm cmd line * in the policy lookup. In the Cilium case, where we have IPSec between all * endpoints this results in two policy rules per node, one for ingress * and one for egress. * * For a concrete example consider two cluster nodes using transparent mode e.g. * without an IPSec tunnel IP. Cluster Node A has host_ip 10.156.0.1 with an * endpoint assigned to IP 10.156.2.2 and cluster Node B has host_ip 10.182.0.1 * with an endpoint using IP 10.182.3.3. Then on Node A there will be a two policy * entries and a set of State entries, * * Policy1(src=10.182.0.0/16,dst=10.156.0.1/16,dir=in,tmpl(spi=#spi,reqid=#reqid)) * Policy2(src=10.156.0.0/16,dst=10.182.0.1/16,dir=out,tmpl(spi=#spi,reqid=#reqid)) * State1(src=*,dst=10.182.0.1,spi=#spi,reqid=#reqid,...) * State2(src=*,dst=10.156.0.1,spi=#spi,reqid=#reqid,...) * * Design Note: For newer kernels a BPF xfrm interface would greatly simplify the * state space. Basic idea would be to reference a state using any key generated * from BPF program allowing for a single state per security ctx.

Types

type IPSecDir

type IPSecDir string