Spec couche 0 — Famille system

Spécification technique — Version 1.0

Vue d’ensemble de la famille

Le module air-sys-syscall::system expose les primitives système diverses : information sur le système, identité de la machine, génération d’entropie cryptographique. C’est la plus petite famille de la couche 0, mais elle contient des fonctions essentielles comme getrandom.

Périmètre de la famille.

Quatre catégories :

1. Informations système : uname, sysinfo.
2. Identité machine : gethostname, sethostname.
3. Entropie cryptographique : getrandom.
4. Actions système privilégiées : reboot (mentionnée mais non exposée).

Caractéristiques transverses.

1. Hétérogénéité. Les fonctions ont peu en commun sémantiquement.
2. Quelques opérations privilégiées. sethostname, reboot demandent CAP_SYS_ADMIN.
3. getrandom est l’élément le plus important. Cryptographie, génération d’identifiants.

Sous-section 1 : Informations système

uname

#![allow(unused)]
fn main() {
pub fn uname() -> Result<UtsName, Errno>;

#[derive(Debug, Clone)]
pub struct UtsName {
    pub sysname: CString,
    pub nodename: CString,
    pub release: CString,
    pub version: CString,
    pub machine: CString,
    pub domainname: CString,
}
}

Comportement.

Retourne des informations sur le système :

• sysname : nom de l’OS (“Linux”).
• nodename : nom de la machine.
• release : version du kernel (“5.15.0-91-generic”).
• version : informations de build du kernel.
• machine : architecture matérielle (“x86_64”, “aarch64”).
• domainname : nom de domaine NIS (Linux-spécifique).

Performance. ~1-2 µs.

sysinfo

#![allow(unused)]
fn main() {
pub fn sysinfo() -> Result<SystemInfo, Errno>;

#[derive(Debug, Clone)]
pub struct SystemInfo {
    pub uptime: Duration,
    pub load_average: [f64; 3],  // 1, 5, 15 minutes
    pub total_ram: u64,
    pub free_ram: u64,
    pub shared_ram: u64,
    pub buffer_ram: u64,
    pub total_swap: u64,
    pub free_swap: u64,
    pub processes: u16,
    pub total_high: u64,
    pub free_high: u64,
    pub mem_unit: u32,
}
}

Comportement.

Retourne des statistiques globales sur le système. Utile pour les outils de monitoring.

Notes sur le wrapper.

La struct kernel utilise des mem_unit. Le wrapper Air fait la multiplication en interne et expose des valeurs en octets directement.

Les load_average sont convertis en f64 par le wrapper.

Limites de précision.

sysinfo est rapide mais imprécis. Pour des stats détaillées, lire /proc/meminfo etc.

Performance. ~1-2 µs.

Sous-section 2 : Identité machine

gethostname et sethostname

#![allow(unused)]
fn main() {
pub fn gethostname() -> Result<CString, Errno>;
pub fn sethostname(name: &CStr) -> Result<(), Errno>;
}

Préconditions.

Pour sethostname : CAP_SYS_ADMIN requis. name doit avoir une longueur ≤ HOST_NAME_MAX (typiquement 64 octets).

Comportement.

gethostname est implémenté via uname() et extrait le champ nodename.

sethostname change le hostname. Action privilégiée, rarement utilisée par les applications.

Sous-section 3 : Entropie cryptographique

getrandom

#![allow(unused)]
fn main() {
pub fn getrandom(
    buf: &mut [u8],
    flags: GetrandomFlags,
) -> Result<usize, Errno>;

bitflags! {
    pub struct GetrandomFlags: u32 {
        const NONBLOCK = 1;
        const RANDOM = 2;
        const INSECURE = 4;
    }
}
}

Syscall sous-jacent. getrandom (x86_64 n°318, ARM64 n°278). Disponible depuis Linux 3.17.

Comportement.

Remplit le buffer avec des octets aléatoires cryptographiquement sûrs. Mécanisme moderne et préféré pour obtenir de l’entropie sur Linux.

Sémantique des flags.

• Aucun flag (défaut) : utilise le pool urandom. Bloque si pas encore initialisé.
• NONBLOCK : retourne EAGAIN au lieu de bloquer.
• RANDOM : utilise le pool random. À éviter sauf cas spéciaux (cryptographiquement équivalent à urandom sur Linux moderne).
• INSECURE : retourne immédiatement même si non initialisé, mais qualité réduite. Strictement réservé aux cas non-cryptographiques.

Recommandation Air.

Pour 99% des usages : GetrandomFlags::empty().

Comportement avec grands buffers.

getrandom peut retourner moins d’octets que demandé pour les grands buffers. Boucle si nécessaire :

#![allow(unused)]
fn main() {
fn fill_random(buf: &mut [u8]) -> Result<(), Errno> {
    let mut offset = 0;
    while offset < buf.len() {
        let n = getrandom(&mut buf[offset..], GetrandomFlags::empty())?;
        offset += n;
    }
    Ok(())
}
}

Air pourra fournir un helper getrandom_exact en couche 1.

Performance. ~1-2 µs pour de petits buffers. Pour les grands, débit limité par le CSPRNG kernel.

Tests.

• Test nominal : remplir un buffer de 32 octets, vérifier qu’il n’est pas tout à zéro.
• Test variation : deux appels successifs, vérifier que les buffers sont différents.
• Test buffer grand : 4 KB avec boucle.

Sous-section 4 : Opérations privilégiées non exposées

reboot

reboot(2) permet de redémarrer ou arrêter la machine. Pas exposé en API publique Air. Le contrôle de cycle de vie système est du ressort de systemd.

Listé dans UNSUPPORTED.md avec justification.

Récapitulatif de la famille system

Fonctions exposées :

Total : 5 fonctions publiques principales.

Syscalls non-wrappés (listés dans UNSUPPORTED.md) :

• reboot : action système réservée à init.
• syslog (lecture kernel ring buffer) : marginal.
• setdomainname : NIS legacy, marginal.
• iopl, ioperm : accès I/O direct ports, privilégié et rare.
• personality : changement de personality processus, hors phase 0.

Types ajoutés à air-sys-types

• UtsName
• SystemInfo
• GetrandomFlags

Soit 3 types supplémentaires.

Décisions de fond émergées dans la famille system

1. gethostname implémenté via uname.

Plutôt qu’un syscall séparé. Économise un syscall théorique.

2. getrandom est volontairement minimaliste.

Pas de helper “génère N octets cryptographiques” sophistiqué en couche 0. Les couches supérieures fourniront ces helpers.

3. INSECURE est exposé mais déconseillé.

Le flag existe en kernel ; Air ne le cache pas. Mais la documentation insiste sur le fait que c’est réservé aux cas non-cryptographiques.

4. reboot non exposé.

Pas le rôle d’une application Air normale.

Bilan global de la couche 0

Avec la famille system, la couche 0 est entièrement spécifiée.

Récapitulatif par famille.

Total approximatif : ~213 fonctions wrapper publiques dans la couche 0.

Crate air-sys-types : ~187 types publics.

Licence du document : MPL 2.0 Statut : Spécification technique du module air-sys-syscall::system (couche 0).