random_bytes

(PHP 7, PHP 8)

random_bytes — Récupère des octets aléatoires cryptographiquement sécurisés

Description

random_bytes(int $length): string

Génère une chaîne contenant des octets aléatoires uniformément sélectionnés avec la longueur demandée.

Les octets retournés étant choisis de manière totalement aléatoire, la chaîne résultante contiendra probablement des caractères non imprimables ou des séquences UTF-8 invalides. Il peut être nécessaire de l'encoder avant la transmission ou l'affichage.

La randomisation générée par cette fonction est adaptée à toutes les applications, y compris la génération de secrets à long terme, tels que des clés de chiffrement.

Les sources de hasard par ordre de priorité sont les suivantes :

  • Linux: » getrandom(), /dev/urandom

  • FreeBSD >= 12 (PHP >= 7.3): » getrandom(), /dev/urandom

  • Windows (PHP >= 7.2): » CNG-API

    Windows: » CryptGenRandom

  • macOS (PHP >= 8.2; >= 8.1.9; >= 8.0.22 si CCRandomGenerateBytes est disponible au moment de la compilation): CCRandomGenerateBytes()

    macOS (PHP >= 8.1; >= 8.0.2): arc4random_buf(), /dev/urandom

  • NetBSD >= 7 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), /dev/urandom

  • OpenBSD >= 5.5 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), /dev/urandom

  • DragonflyBSD (PHP >= 8.1): » getrandom(), /dev/urandom

  • Solaris (PHP >= 8.1): » getrandom(), /dev/urandom

  • Toute combinaison d'un système d'exploitation et d'une version de PHP non mentionnée précédemment: /dev/urandom.
  • Si aucune des sources de hasard n'est disponible ou si elles échouent toutes à générer de l'aléatoire, une exception de type Random\RandomException sera levée.

Note: Bien que cette fonction ait été ajoutée en PHP 7.0, une » implementation en espace utilisateur est disponible pour PHP 5.2 jusqu'à 5.6, inclus.

Liste de paramètres

length

La longueur de la chaîne de caractères aléatoire qui doit être retournée en octets; doit être supérieur ou égal à 1.

Valeurs de retour

Retourne une chaîne de caractères contenant le nombre demandé d'octets cryptographiquement sécurisés.

Erreurs / Exceptions

  • Si aucune source de données aléatoires n'est trouvée, une Random\RandomException sera lancée.
  • Si la valeur de length est inférieure à 1, une ValueError sera lancée.

Historique

Version Description
8.2.0 En cas d'échec CSPRNG, cette fonction lancera désormais une Random\RandomException. Auparavant une Exception basique était lancé.

Exemples

Exemple #1 Exemple avec random_bytes()

<?php
$bytes = random_bytes(5);
var_dump(bin2hex($bytes));
?>

Résultat de l'exemple ci-dessus est similaire à :

string(10) "385e33f741"

Voir aussi