air_sys_types/

security.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

//! Types de la famille `security` — seccomp-BPF (primitif) et Landlock.
//!
//! Cf. `docs/specs/layer-0/family-security.md`.
//!
//! **API couche 0 :** cette crate expose uniquement les types primitifs.
//! L'API déclarative (compilation de règles en BPF) appartient à la couche 1.

use bitflags::bitflags;

use crate::errno::Errno;

// ─────────────────────────────────────────────────────────────────────────
// seccomp-BPF — types primitifs pour charger un programme BPF précompilé.
// ─────────────────────────────────────────────────────────────────────────

/// Une instruction de filtre BPF classique — layout exact de `struct sock_filter`.
///
/// Opaque du point de vue de la couche 0 : la couche 0 ne compile pas ces
/// instructions, elle les charge telles quelles dans le kernel via
/// `seccomp(SECCOMP_SET_MODE_FILTER, …)`.
///
/// Cf. `linux/filter.h` et RFC 4972.
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct SockFilter {
    /// Opcode BPF (instruction code).
    pub code: u16,
    /// Jump true offset.
    pub jt: u8,
    /// Jump false offset.
    pub jf: u8,
    /// Generic multiuse field.
    pub k: u32,
}

/// Programme BPF complet prêt à charger dans le kernel.
///
/// Emprunte une tranche d'instructions [`SockFilter`] appartenant à l'appelant
/// (zéro allocation heap). Correspond à `struct sock_fprog` du kernel
/// (`linux/filter.h`).
///
/// Construit via [`SockFprog::new`] ; invalide si la tranche est vide ou
/// dépasse `BPF_MAXINSNS` (4096 instructions).
#[derive(Debug)]
pub struct SockFprog<'a> {
    len: u16,
    filter: *const SockFilter,
    _marker: core::marker::PhantomData<&'a [SockFilter]>,
}

impl<'a> SockFprog<'a> {
    /// Construit un programme BPF à partir d'une tranche d'instructions.
    ///
    /// # Errors
    ///
    /// Retourne `Err(Errno::EINVAL)` si la tranche est vide ou dépasse
    /// `BPF_MAXINSNS` (4096 instructions).
    ///
    /// # Examples
    ///
    /// ```
    /// use air_sys_types::security::{SockFilter, SockFprog};
    ///
    /// // Instruction BPF minimale : RET K avec valeur SECCOMP_RET_ALLOW (0x7fff0000).
    /// let allow = SockFilter { code: 0x0006, jt: 0, jf: 0, k: 0x7fff_0000 };
    /// let instructions = [allow];
    /// let prog = SockFprog::new(&instructions).expect("programme valide");
    /// assert_eq!(prog.len(), 1);
    /// ```
    pub fn new(instructions: &'a [SockFilter]) -> Result<Self, Errno> {
        const BPF_MAXINSNS: usize = 4096;
        if instructions.is_empty() || instructions.len() > BPF_MAXINSNS {
            return Err(Errno::EINVAL);
        }
        // SAFETY: length <= 4096 < 65535 ; la troncature u16 est sans perte.
        #[allow(clippy::cast_possible_truncation)]
        Ok(Self {
            len: instructions.len() as u16,
            filter: instructions.as_ptr(),
            _marker: core::marker::PhantomData,
        })
    }

    /// Longueur du programme (nombre d'instructions).
    #[must_use]
    pub fn len(&self) -> u16 {
        self.len
    }

    /// Retourne `true` si le programme est vide.
    ///
    /// En pratique, [`SockFprog::new`] refuse les tranches vides, donc un
    /// `SockFprog` construit correctement a toujours `is_empty() == false`.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    /// Pointeur brut vers le tableau d'instructions (pour appel syscall).
    #[must_use]
    pub fn as_ptr(&self) -> *const SockFilter {
        self.filter
    }
}

// SAFETY: SockFprog emprunte des données immuables derrière une référence
// partagée ; Send + Sync sont corrects dès lors que les données référencées
// sont elles-mêmes Send + Sync. Le raw pointer n'introduit pas de non-Send :
// il est uniquement dérivé d'une référence valide pour la durée de vie 'a.
unsafe impl Send for SockFprog<'_> {}
// SAFETY: même raison que `Send` — le pointeur dérive d'une référence partagée `&'a`
// à des filtres immuables ; le partager entre fils ne permet que de les lire.
unsafe impl Sync for SockFprog<'_> {}

bitflags! {
    /// Drapeaux pour `seccomp(SECCOMP_SET_MODE_FILTER, flags, …)`.
    ///
    /// Cf. `linux/seccomp.h`.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct SeccompFilterFlags: u32 {
        /// Synchronise le filtre à tous les threads du processus.
        const TSYNC           = 1;
        /// Logue chaque syscall correspondant au filtre.
        const LOG             = 2;
        /// Désactive la migration de spectres (speculation store bypass).
        const SPEC_ALLOW      = 4;
        /// Crée un fd `seccomp_unotify` pour l'observation (Linux 5.0+).
        const NEW_LISTENER    = 8;
        /// Retourne `ESRCH` si `TSYNC` et un thread résiste (Linux 5.7+).
        const TSYNC_ESRCH     = 16;
        /// Bloque le signal kill jusqu'à réception de la réponse unotify.
        const WAIT_KILLABLE_RECV = 32;
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Landlock — filtrage d'accès filesystem sans privilège.
// ─────────────────────────────────────────────────────────────────────────

bitflags! {
    /// Permissions filesystem Landlock (cf. `linux/landlock.h`).
    ///
    /// La disponibilité de certains bits dépend de la version ABI Landlock
    /// du kernel. Utilisez `landlock_supported_abi()` pour connaître la
    /// version disponible et masquer les bits non supportés.
    ///
    /// | Bit | Depuis | Signification |
    /// |-----|--------|---------------|
    /// | EXECUTE … MAKE_SYM | Landlock v1 (Linux 5.13) | permissions de base |
    /// | REFER | Landlock v2 (Linux 5.19) | déplacement inter-répertoires |
    /// | TRUNCATE | Landlock v3 (Linux 6.2) | troncature de fichiers |
    /// | IOCTL_DEV | Landlock v5 (Linux 6.10) | ioctl sur devices |
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct LandlockAccessFs: u64 {
        /// Exécution de fichiers.
        const EXECUTE    = 1 << 0;
        /// Écriture dans les fichiers (pas troncature : voir `TRUNCATE`).
        const WRITE_FILE = 1 << 1;
        /// Lecture de fichiers.
        const READ_FILE  = 1 << 2;
        /// Listage de répertoires.
        const READ_DIR   = 1 << 3;
        /// Suppression de répertoires.
        const REMOVE_DIR = 1 << 4;
        /// Suppression de fichiers.
        const REMOVE_FILE = 1 << 5;
        /// Création de fichiers caractère.
        const MAKE_CHAR  = 1 << 6;
        /// Création de répertoires.
        const MAKE_DIR   = 1 << 7;
        /// Création de fichiers réguliers.
        const MAKE_REG   = 1 << 8;
        /// Création de sockets Unix.
        const MAKE_SOCK  = 1 << 9;
        /// Création de FIFOs.
        const MAKE_FIFO  = 1 << 10;
        /// Création de fichiers bloc.
        const MAKE_BLOCK = 1 << 11;
        /// Création de liens symboliques.
        const MAKE_SYM   = 1 << 12;
        /// Déplacement de fichiers entre répertoires (Landlock v2+).
        const REFER      = 1 << 13;
        /// Troncature de fichiers (Landlock v3+).
        const TRUNCATE   = 1 << 14;
        /// Opérations ioctl sur devices (Landlock v5+).
        const IOCTL_DEV  = 1 << 15;
    }
}

bitflags! {
    /// Permissions **réseau** Landlock (cf. `linux/landlock.h`), ABI **v4+**
    /// (Linux 6.7).
    ///
    /// Landlock ne borne le réseau que sur **TCP**, et seulement pour ces deux
    /// verbes. Ce n'est pas un pare-feu : il ne filtre ni les adresses, ni UDP,
    /// ni les paquets. Il répond à une question plus étroite — *ce processus
    /// a-t-il le droit d'écouter, ou de se connecter, sur ce port ?* — et il y
    /// répond dans le noyau, sans démon ni règle globale.
    ///
    /// Le confondre avec un pare-feu serait une erreur de conception : une
    /// application qui reçoit `CONNECT_TCP` sur le port 443 peut joindre
    /// **n'importe quelle** machine sur ce port.
    ///
    /// | Bit | Depuis | Signification |
    /// |-----|--------|---------------|
    /// | BIND_TCP | Landlock v4 (Linux 6.7) | se lier à un port en écoute |
    /// | CONNECT_TCP | Landlock v4 (Linux 6.7) | se connecter à un port |
    ///
    /// Comme pour [`LandlockAccessFs`], demander un bit que le noyau ne connaît
    /// pas fait échouer la création du ruleset (`EINVAL`) : interroger
    /// `landlock_supported_abi()` avant de composer.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct LandlockAccessNet: u64 {
        /// Se lier à un port TCP (`bind`) — Landlock v4+.
        const BIND_TCP    = 1 << 0;
        /// Se connecter à un port TCP (`connect`) — Landlock v4+.
        const CONNECT_TCP = 1 << 1;
    }
}

bitflags! {
    /// **Portées** Landlock (cf. `linux/landlock.h`), ABI **v6+** (Linux 6.12).
    ///
    /// # Ce que le *scoping* borne, et que rien d'autre ne bornait
    ///
    /// Ce ne sont **pas** des droits par chemin. Ils ne disent pas *ce qu'on a le droit de
    /// faire sur telle ressource*, mais *jusqu'où un domaine peut atteindre en dehors de
    /// lui-même*. Deux voies latérales, précisément celles qu'aucune règle de fichier ne
    /// pouvait voir :
    ///
    /// - un socket UNIX **abstrait** n'a **pas de chemin** — il vit dans un espace de noms
    ///   à part, sans entrée de système de fichiers. Aucune règle Landlock de fichier ne
    ///   pouvait donc l'atteindre : deux processus confinés séparément pouvaient dialoguer
    ///   sans que leur cage en sache rien ;
    /// - un **signal** ne traverse aucun descripteur et ne touche aucun chemin.
    ///
    /// | Bit | Depuis | Ce qui devient interdit |
    /// |-----|--------|-------------------------|
    /// | `ABSTRACT_UNIX_SOCKET` | Landlock v6 (Linux 6.12) | se connecter à un socket UNIX abstrait créé **hors** du domaine |
    /// | `SIGNAL` | Landlock v6 (Linux 6.12) | envoyer un signal à un processus **hors** du domaine |
    ///
    /// # La direction compte
    ///
    /// La borne est **sortante** : elle empêche le processus confiné d'atteindre l'extérieur,
    /// et non l'extérieur de l'atteindre. Un parent non confiné garde donc la main sur son
    /// enfant — ce qui est nécessaire, sans quoi un lanceur ne pourrait plus arrêter ce qu'il
    /// a lancé.
    ///
    /// # À l'intérieur du domaine, rien ne change
    ///
    /// Deux processus du **même** domaine continuent de se joindre et de se signaler. Le
    /// *scoping* isole des domaines les uns des autres, il ne fragmente pas un domaine.
    ///
    /// Comme pour [`LandlockAccessFs`] et [`LandlockAccessNet`], demander un bit que le noyau
    /// ne connaît pas fait échouer la création du ruleset : interroger
    /// `landlock_supported_abi()` avant de composer.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct LandlockScope: u64 {
        /// Se connecter à un socket UNIX **abstrait** créé hors du domaine — Landlock v6+.
        const ABSTRACT_UNIX_SOCKET = 1 << 0;
        /// Envoyer un signal à un processus hors du domaine — Landlock v6+.
        const SIGNAL               = 1 << 1;
    }
}

bitflags! {
    /// Drapeaux de `landlock_restrict_self(2)` (cf. `linux/landlock.h`).
    ///
    /// # Deux familles, deux natures
    ///
    /// - les trois premiers ne changent **aucune** décision d'accès : ils disent au noyau ce
    ///   qu'il doit **tracer** d'un refus (ABI v7). Utiles au diagnostic, ils appartiennent à
    ///   l'appelant ([ADR-156] D5) ;
    /// - le quatrième, [`TSYNC`](Self::TSYNC), change ce qui est **borné** — et c'est le seul
    ///   qui ferme quelque chose.
    ///
    /// # Ce que `TSYNC` répare
    ///
    /// Sans lui, `landlock_restrict_self` ne borne que le **fil appelant**. Dans un processus
    /// multifil qui se met lui-même en cage, les fils frères restent **hors** du domaine : la
    /// cage se contourne en changeant de fil. Avec lui, la configuration s'applique
    /// **atomiquement à tous les fils** du processus.
    ///
    /// Le noyau propage aussi `no_new_privs` aux fils frères quand le fil appelant le porte —
    /// ce qui évite l'incohérence d'un fil confiné et d'un fil qui peut encore élever ses
    /// privilèges.
    ///
    /// **Le noyau dit qu'il « écrase » la configuration des fils frères, quels que soient les
    /// domaines déjà établis sur eux.** Ce que cela fait exactement d'un fil frère **plus
    /// strictement** confiné est vérifié par un test dédié plutôt que supposé — c'est la
    /// différence entre borner et croire borner.
    ///
    /// [ADR-156]: ../../../docs/adrs/ADR-156-landlock-abi-v7-fr.md
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct LandlockRestrictFlags: u32 {
        /// Ne journalise pas les refus venant du fil qui crée le domaine, ni de ses enfants
        /// tant qu'ils exécutent le même code (ABI v7).
        const LOG_SAME_EXEC_OFF  = 1 << 0;
        /// Journalise les refus **après** un `execve` dans le domaine créé (ABI v7).
        const LOG_NEW_EXEC_ON    = 1 << 1;
        /// Ne journalise pas les refus venant des **sous-domaines** créés par l'appelant ou
        /// ses descendants (ABI v7).
        const LOG_SUBDOMAINS_OFF = 1 << 2;
        /// Applique la configuration **à tous les fils** du processus, atomiquement.
        const TSYNC              = 1 << 3;
    }
}

#[cfg(test)]
mod tests;