ebpf

type BoringSSLOffsets ¶ added in v0.2.0

type BoringSSLOffsets struct {
	SSLToS3      uint32 // SSL* → SSL3_STATE* (pointer deref)
	S3ToAEAD     uint32 // SSL3_STATE* → SSLAEADContext* (pointer deref, aead_write_ctx)
	AEADToAESKey uint32 // SSLAEADContext* → AES_KEY.rd_key (direct read)
	SSLToWBIO    uint32 // SSL* → wbio BIO* (socket fd recovery, same role as OpenSSL)
}

BoringSSLOffsets contains the struct offsets for walking an SSL* object to the AES-GCM hash key on a BoringSSL build. Unlike OpenSSL — whose provider GCM context persists the raw 16-byte hash subkey H (gcm128_context.H) — BoringSSL's GCM128_KEY stores only the precomputed, platform-specific GHASH powers table (Htable); the raw subkey ghash_key = AES_encrypt(0) is a local in CRYPTO_gcm128_init_aes_key that is discarded after the table is built.

The chain is shorter than OpenSSL's (no OSSL_RECORD_LAYER indirection):

SSL* + SSLToS3        → SSL3_STATE*       (pointer deref)
     + S3ToAEAD       → SSLAEADContext*   (pointer deref; UniquePtr aead_write_ctx)
     + AEADToAESKey    → AES_KEY.rd_key   (direct read of the round-key schedule)

AEADToAESKey collapses the embedded hops SSLAEADContext.ctx_ (EVP_AEAD_CTX, an embedded ScopedEVP_AEAD_CTX) → EVP_AEAD_CTX.state (embedded union) → aead_aes_gcm_ctx.key (GCM128_KEY) → gcm128_key_st.aes (AES_KEY). All hops after the first two are embedded structs, so AEADToAESKey is one additive offset.

Why the AES_KEY and not the GHASH table: BoringSSL's GCM128_KEY persists only the precomputed, CPU-specific GHASH powers table (Htable) — never the raw 16-byte subkey H that kloak's tag recomputation needs. But it DOES keep the AES round-key schedule, and BoringSSL itself derives H exactly as H = AES_encrypt(0) over that schedule (see CRYPTO_gcm128_init_aes_key). So the BPF data plane reads AES_KEY.rd_key + rounds and recomputes H = AES_block(0) in-kernel (see the BoringSSL branch in pkg/ebpf/bpf/tls_uprobe.c). This is architecture- and GHASH-impl-independent, unlike recovering H from the Htable representation.

AES_KEY layout: uint32_t rd_key[60] then uint32_t rounds, so the round count sits at AESKeyRoundsOff (240) bytes past rd_key.

Offsets are discovered via pahole in tools/boringssl-offsets/ and committed to tools/boringssl-offsets/results/; TestBoringSSLOffsets_AgainstReferenceJSON asserts this table matches them.

func DetectBoringSSL(pid int, libPath string) (key string, offsets BoringSSLOffsets, err error)

type BunOffsets ¶ added in v0.2.0

type BunOffsets struct {
	SSLWriteOffset uint64
	BoringSSL      BoringSSLOffsets
}

BunOffsets holds the file offset of SSL_write in a Bun single-executable plus the BoringSSL struct chain needed to walk SSL* → AES-GCM H subkey.

Bun statically links BoringSSL with all internal symbols stripped from production and profile builds. The SSL_write file offset is pre-extracted from the official Bun profile release (same optimisation flags as production, symbol table retained) for each (version, arch) pair and stored here. Offset extraction is automated by tools/bun-offsets/.

BoringSSL struct offsets reuse the same SSL→s3→aead_write_ctx→AES_KEY chain as the shared-library BoringSSL path (see boringssl_offsets.go). The layout has been stable across tracked Bun+BoringSSL revisions.

func DetectBun(binPath string) (BunOffsets, string, bool)

type GoTLSOffsets ¶

type GoTLSOffsets struct {
	ConnToCipher uint32 // Conn.out offset + halfConn.cipher offset + 8 (interface data_ptr)
	AEADIfaceOff uint32 // prefixNonceAEAD.aead offset + 8 (interface data_ptr)
	H2HiOff      uint32 // GCM + off → high 64 bits of H×2 (byte-swapped)
	H2LoOff      uint32 // GCM + off → low 64 bits of H×2 (byte-swapped)
	ConnVersOff  uint32 // Conn + off → uint16 negotiated TLS version (e.g. 0x0303, 0x0304)
}

GoTLSOffsets contains struct offsets for extracting the GHASH H key from Go's crypto/tls internal structures. The layout must match struct go_tls_offsets in tls_uprobe.c exactly.

H extraction chain (3 pointer dereferences + GF(2^128) halving):

Conn + ConnToCipher → cipher interface data_ptr → AEAD wrapper
  + AEADIfaceOff → inner aead interface data_ptr → GCM struct
    + H2HiOff / H2LoOff → H×2 (two 64-bit words from productTable[224])

Go's gcmAesInit assembly computes H = AES_K(0^128), byte-swaps, then doubles in GF(2^128) before storing at productTable offset 224. The BPF code reads the two words and applies GF halving to recover standard H.

The word order at offset 224 is architecture-dependent:

• AMD64 (PSHUFB full reversal): hi word at +8, lo word at +0
• ARM64 (VREV64 per-lane reversal): hi word at +0, lo word at +8

func DetectGoTLSOffsets(exePath string) (version string, offsets GoTLSOffsets, err error)

type SecretBindingMode ¶ added in v0.2.0

type SecretBindingMode string

SecretBindingMode selects what the data plane does when a process redeems a placeholder of a secret its pod does not reference (see secret_acl in tls_uprobe.c).

const (
	// SecretBindingEnforce refuses the rewrite: the placeholder goes out
	// unchanged. This is the default and the BPF map's zero value.
	SecretBindingEnforce SecretBindingMode = "enforce"
	// SecretBindingAudit lets the rewrite go ahead but still reports it.
	// Meant for finding workloads that redeem secrets they don't mount
	// before switching to enforce.
	SecretBindingAudit SecretBindingMode = "audit"
)

func ParseSecretBindingMode(s string) (SecretBindingMode, error)

type TCAttachMode ¶ added in v0.2.0

type TCAttachMode string

TCAttachMode selects how the tc patch program is attached to an interface.

const (
	// TCAttachAuto uses TCX when the kernel supports it (Linux 6.6+) and
	// falls back to a classic clsact/cls_bpf filter otherwise.
	TCAttachAuto TCAttachMode = "auto"
	// TCAttachTCX always uses TCX links. Fails on kernels older than 6.6.
	TCAttachTCX TCAttachMode = "tcx"
	// TCAttachClsact always uses a classic clsact qdisc + cls_bpf filter.
	// Works on every kernel Kloak supports (5.17+). Mainly useful to
	// exercise the fallback path on a TCX-capable kernel.
	TCAttachClsact TCAttachMode = "clsact"
)

func ParseTCAttachMode(s string) (TCAttachMode, error)

type TLSOffsets ¶

type TLSOffsets struct {
	SSLToWRL       uint32 // 4-hop: SSL* → WRL*. 3-hop: SSL* → EVP_CIPHER_CTX* (when WRLToEncCtx=0)
	WRLToEncCtx    uint32 // wrl* → EVP_CIPHER_CTX*. 0 = 3-hop mode (no record layer)
	EncCtxToAlgctx uint32 // enc_ctx* + off → algctx/PROV_GCM_CTX* (pointer deref)
	AlgctxToH      uint32 // algctx* + off → H (16 bytes, direct read)
	SSLToVersion   uint32 // SSL_CONNECTION* + off → int version (0xFFFFFFFF=unknown, use heuristic)
	// SSLToWBIO is the offset from the SSL/SSL_CONNECTION pointer to its
	// `wbio` BIO* field. The BPF data plane reads SSL → wbio → BIO.num to
	// recover the socket fd, then looks it up in conn_ip_map to confirm
	// client-mode (set by connect()). 3.0/3.1 use struct ssl_st where
	// wbio sits at 24; 3.2+ wrapped SSL in ssl_connection_st and moved it
	// to 88. Before this field existed, the BPF program hardcoded 88 —
	// which silently broke every 3.0/3.1 workload by reading garbage and
	// tripping the server-mode guard in bpf_uprobe_ssl_write.
	SSLToWBIO uint32

	// The next three drive ossl_read_gcm_h in the BPF data plane (issue #275).
	// 0 means "not calibrated": the data plane falls back to the legacy
	// "raw H non-zero ⇒ GCM" heuristic and has no AVX-512 recovery.
	//
	// AlgctxToGCMKey is algctx → GCM128_CONTEXT.key and AlgctxToKeySched is
	// algctx → PROV_AES_GCM_CTX.ks. Every keyed OpenSSL GCM context points
	// gcm.key at its own ks, so the pair is a self-pointer gate that non-GCM
	// contexts (whose bytes at AlgctxToH are unrelated) cannot pass.
	AlgctxToGCMKey   uint32
	AlgctxToKeySched uint32
	// AlgctxToVAESHKey1 is algctx → GCM128_CONTEXT.Htable[15]. On x86-64 CPUs
	// with AVX-512 + VAES + VPCLMULQDQ, OpenSSL ≥ 3.1 never writes the raw H
	// field; ossl_aes_gcm_init_avx512 stores HashKey_1 = bswap128(H)<<1 mod P
	// there instead, which the data plane inverts. 0 for versions without that
	// code path (3.0) or whose asm layout discovery did not recognise.
	AlgctxToVAESHKey1 uint32
}

TLSOffsets contains struct offsets for extracting TLS key material from an SSL* object at runtime. Two chain variants exist:

4-hop (OpenSSL 3.2+):

SSL* + SSLToWRL → WRL* + WRLToEncCtx → EVP_CIPHER_CTX* + EncCtxToAlgctx → algctx* + AlgctxToH → H

3-hop (OpenSSL 3.0-3.1):

SSL* + SSLToWRL → EVP_CIPHER_CTX* + EncCtxToAlgctx → algctx* + AlgctxToH → H

The 3-hop chain skips the record layer indirection. SSLToWRL stores the enc_write_ctx offset directly, and WRLToEncCtx=0 signals 3-hop mode to BPF.

These are version-specific and must match the OpenSSL build in the container.

func DetectOpenSSLVersion(pid int, libPath string) (version string, offsets TLSOffsets, err error)

type TLSUprobeManager ¶

type TLSUprobeManager struct {
	// contains filtered or unexported fields
}

TLSUprobeManager manages the loading and attaching of eBPF uprobes for TLS interception.

func NewTLSUprobeManager(secretSource secrets.Source, cgroupRoot, egressInterface string, log *zap.SugaredLogger) (*TLSUprobeManager, error)

func (m *TLSUprobeManager) AttachTLS(pid int, cgroupID uint64) error

func (m *TLSUprobeManager) BindPodSecrets(podUID, pod string, cgroupIDs []uint64, refs []secrets.Ref)

func (m *TLSUprobeManager) Close() error

func (m *TLSUprobeManager) DumpDebugCounters()

func (m *TLSUprobeManager) PollEvents(ctx context.Context) error

func (m *TLSUprobeManager) PollExecEvents(ctx context.Context) error

func (m *TLSUprobeManager) PopulateTrustedDNSServers(ips []net.IP) error

func (m *TLSUprobeManager) RecordCgroupNetns(cgroupID uint64, pid int)

func (m *TLSUprobeManager) SetSecretBindingMode(mode SecretBindingMode)

func (m *TLSUprobeManager) SetTCAttachMode(mode TCAttachMode)

func (m *TLSUprobeManager) TrackCgroup(cgroupID uint64, cgroupPath string) error

func (m *TLSUprobeManager) TrackTGID(tgid uint32) error

func (m *TLSUprobeManager) UnbindPod(podUID string)

func (m *TLSUprobeManager) UntrackCgroup(cgroupID uint64) error

func (m *TLSUprobeManager) UntrackTGID(tgid uint32) error