NOTE

Bun implémente les fonctions `createHash` et `createHmac` de [`node:crypto`](https://nodejs.org/api/crypto.html) en plus des API natives Bun documentées ci-dessous.

---

Bun.password

Bun.password est une collection de fonctions utilitaires pour hacher et vérifier les mots de passe avec divers algorithmes cryptographiquement sécurisés.

const password = "super-secure-pa$$word";

const hash = await Bun.password.hash(password);
// => $argon2id$v=19$m=65536,t=2,p=1$tFq+9AVr1bfPxQdh6E8DQRhEXg/M/SqYCNu6gVdRRNs$GzJ8PuBi+K+BVojzPfS5mjnC8OpLGtv8KJqF99eP6a4

const isMatch = await Bun.password.verify(password, hash);
// => true

Le deuxième argument de Bun.password.hash accepte un objet de paramètres qui vous permet de choisir et de configurer l'algorithme de hachage.

const password = "super-secure-pa$$word";

// utiliser argon2 (par défaut)
const argonHash = await Bun.password.hash(password, {
  algorithm: "argon2id", // "argon2id" | "argon2i" | "argon2d"
  memoryCost: 4, // utilisation mémoire en kibioctets
  timeCost: 3, // nombre d'itérations
});

// utiliser bcrypt
const bcryptHash = await Bun.password.hash(password, {
  algorithm: "bcrypt",
  cost: 4, // nombre entre 4-31
});

L'algorithme utilisé pour créer le hachage est stocké dans le hachage lui-même. Lors de l'utilisation de bcrypt, le hachage retourné est encodé au format Modular Crypt Format pour la compatibilité avec la plupart des implémentations bcrypt existantes ; avec argon2 le résultat est encodé dans le format PHC plus récent.

La fonction verify détecte automatiquement l'algorithme en fonction du hachage d'entrée et utilise la méthode de vérification correcte. Elle peut correctement déduire l'algorithme à partir des hachages encodés en PHC ou MCF.

const password = "super-secure-pa$$word";

const hash = await Bun.password.hash(password, {
  /* config */
});

const isMatch = await Bun.password.verify(password, hash);
// => true

Des versions synchrones de toutes les fonctions sont également disponibles. Gardez à l'esprit que ces fonctions sont coûteuses en calcul, donc l'utilisation d'une API bloquante peut dégrader les performances de l'application.

const password = "super-secure-pa$$word";

const hash = Bun.password.hashSync(password, {
  /* config */
});

const isMatch = Bun.password.verifySync(password, hash);
// => true

Sel

Lorsque vous utilisez Bun.password.hash, un sel est automatiquement généré et inclus dans le hachage.

bcrypt - Modular Crypt Format

Dans le hachage Modular Crypt Format suivant (utilisé par bcrypt) :

Entrée :

await Bun.password.hash("hello", {
  algorithm: "bcrypt",
});

Sortie :

$2b$10$Lyj9kHYZtiyfxh2G60TEfeqs7xkkGiEFFDi3iJGc50ZG/XJ1sxIFi;

Le format est composé de :

• bcrypt : $2b
• rounds : $10 - tours (log10 du nombre réel de tours)
• salt : $Lyj9kHYZtiyfxh2G60TEfeqs7xkkGiEFFDi3iJGc50ZG/XJ1sxIFi
• hash : $GzJ8PuBi+K+BVojzPfS5mjnC8OpLGtv8KJqF99eP6a4

Par défaut, la bibliothèque bcrypt tronque les mots de passe de plus de 72 octets. Dans Bun, si vous passez à Bun.password.hash un mot de passe de plus de 72 octets et utilisez l'algorithme bcrypt, le mot de passe sera haché via SHA-512 avant d'être passé à bcrypt.

await Bun.password.hash("hello".repeat(100), {
  algorithm: "bcrypt",
});

Ainsi, au lieu d'envoyer silencieusement à bcrypt un mot de passe de 500 octets tronqué à 72 octets, Bun hachera le mot de passe en utilisant SHA-512 et enverra le mot de passe haché à bcrypt (seulement s'il dépasse 72 octets). C'est un comportement par défaut plus sécurisé.

argon2 - format PHC

Dans le hachage format PHC suivant (utilisé par argon2) :

Entrée :

await Bun.password.hash("hello", {
  algorithm: "argon2id",
});

Sortie :

$argon2id$v=19$m=65536,t=2,p=1$xXnlSvPh4ym5KYmxKAuuHVlDvy2QGHBNuI6bJJrRDOs$2YY6M48XmHn+s5NoBaL+ficzXajq2Yj8wut3r0vnrwI

Le format est composé de :

• algorithm : $argon2id
• version : $v=19
• memory cost : 65536
• iterations : t=2
• parallelism : p=1
• salt : $xXnlSvPh4ym5KYmxKAuuHVlDvy2QGHBNuI6bJJrRDOs
• hash : $2YY6M48XmHn+s5NoBaL+ficzXajq2Yj8wut3r0vnrwI

---

Bun.hash

Bun.hash est une collection d'utilitaires pour le hachage non cryptographique. Les algorithmes de hachage non cryptographique sont optimisés pour la vitesse de calcul plutôt que pour la résistance aux collisions ou la sécurité.

La fonction Bun.hash standard utilise Wyhash pour générer un hachage de 64 bits à partir d'une entrée de taille arbitraire.

Bun.hash("some data here");
// 11562320457524636935n

L'entrée peut être une chaîne, TypedArray, DataView, ArrayBuffer ou SharedArrayBuffer.

const arr = new Uint8Array([1, 2, 3, 4]);

Bun.hash("some data here");
Bun.hash(arr);
Bun.hash(arr.buffer);
Bun.hash(new DataView(arr.buffer));

En option, une graine entière peut être spécifiée comme deuxième paramètre. Pour les hachages de 64 bits, les graines supérieures à Number.MAX_SAFE_INTEGER doivent être données sous forme de BigInt pour éviter la perte de précision.

Bun.hash("some data here", 1234);
// 15724820720172937558n

Des algorithmes de hachage supplémentaires sont disponibles en tant que propriétés sur Bun.hash. L'API est la même pour chacun, changeant uniquement le type de retour de number pour les hachages de 32 bits à bigint pour les hachages de 64 bits.

Bun.hash.wyhash("data", 1234); // équivalent à Bun.hash()
Bun.hash.crc32("data", 1234);
Bun.hash.adler32("data", 1234);
Bun.hash.cityHash32("data", 1234);
Bun.hash.cityHash64("data", 1234);
Bun.hash.xxHash32("data", 1234);
Bun.hash.xxHash64("data", 1234);
Bun.hash.xxHash3("data", 1234);
Bun.hash.murmur32v3("data", 1234);
Bun.hash.murmur32v2("data", 1234);
Bun.hash.murmur64v2("data", 1234);
Bun.hash.rapidhash("data", 1234);

---

Bun.CryptoHasher

Bun.CryptoHasher est une classe utilitaire polyvalente qui vous permet de calculer de manière incrémentielle un hachage de données de chaîne ou binaires en utilisant une gamme d'algorithmes de hachage cryptographique. Les algorithmes suivants sont pris en charge :

• "blake2b256"
• "blake2b512"
• "md4"
• "md5"
• "ripemd160"
• "sha1"
• "sha224"
• "sha256"
• "sha384"
• "sha512"
• "sha512-224"
• "sha512-256"
• "sha3-224"
• "sha3-256"
• "sha3-384"
• "sha3-512"
• "shake128"
• "shake256"

const hasher = new Bun.CryptoHasher("sha256");
hasher.update("hello world");
hasher.digest();
// Uint8Array(32) [ <octet>, <octet>, ... ]

Une fois initialisé, les données peuvent être alimentées de manière incrémentielle au hacheur en utilisant .update(). Cette méthode accepte string, TypedArray et ArrayBuffer.

const hasher = new Bun.CryptoHasher("sha256");

hasher.update("hello world");
hasher.update(new Uint8Array([1, 2, 3]));
hasher.update(new ArrayBuffer(10));

Si une string est passée, un deuxième paramètre optionnel peut être utilisé pour spécifier l'encodage (par défaut 'utf-8'). Les encodages suivants sont pris en charge :

Catégorie	Encodages
Encodages binaires	"base64" "base64url" "hex" "binary"
Encodages de caractères	"utf8" "utf-8" "utf16le" "latin1"
Anciens encodages de caractères	"ascii" "binary" "ucs2" "ucs-2"

hasher.update("hello world"); // par défaut utf8
hasher.update("hello world", "hex");
hasher.update("hello world", "base64");
hasher.update("hello world", "latin1");

Après que les données ont été alimentées dans le hacheur, un hachage final peut être calculé en utilisant .digest(). Par défaut, cette méthode retourne une Uint8Array contenant le hachage.

const hasher = new Bun.CryptoHasher("sha256");
hasher.update("hello world");

hasher.digest();
// => Uint8Array(32) [ 185, 77, 39, 185, 147, ... ]

La méthode .digest() peut optionnellement retourner le hachage sous forme de chaîne. Pour ce faire, spécifiez un encodage :

hasher.digest("base64");
// => "uU0nuZNNPgilLlLX2n2r+sSE7+N6U4DukIj3rOLvzek="

hasher.digest("hex");
// => "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"

Alternativement, la méthode peut écrire le hachage dans une instance TypedArray préexistante. Cela peut être souhaitable dans certaines applications sensibles aux performances.

const arr = new Uint8Array(32);

hasher.digest(arr);

console.log(arr);
// => Uint8Array(32) [ 185, 77, 39, 185, 147, ... ]

HMAC dans Bun.CryptoHasher

Bun.CryptoHasher peut être utilisé pour calculer des digests HMAC. Pour ce faire, passez la clé au constructeur.

const hasher = new Bun.CryptoHasher("sha256", "secret-key");
hasher.update("hello world");
console.log(hasher.digest("hex"));
// => "095d5a21fe6d0646db223fdf3de6436bb8dfb2fab0b51677ecf6441fcf5f2a67"

Lors de l'utilisation de HMAC, un ensemble plus limité d'algorithmes est pris en charge :

• "blake2b512"
• "md5"
• "sha1"
• "sha224"
• "sha256"
• "sha384"
• "sha512-224"
• "sha512-256"
• "sha512"

Contrairement au Bun.CryptoHasher non-HMAC, l'instance Bun.CryptoHasher HMAC n'est pas réinitialisée après l'appel de .digest(), et tenter de réutiliser la même instance générera une erreur.

D'autres méthodes comme .copy() et .update() sont prises en charge (tant que c'est avant .digest()), mais les méthodes comme .digest() qui finalisent le hacheur ne le sont pas.

const hasher = new Bun.CryptoHasher("sha256", "secret-key");
hasher.update("hello world");

const copy = hasher.copy();
copy.update("!");
console.log(copy.digest("hex"));
// => "3840176c3d8923f59ac402b7550404b28ab11cb0ef1fa199130a5c37864b5497"

console.log(hasher.digest("hex"));
// => "095d5a21fe6d0646db223fdf3de6436bb8dfb2fab0b51677ecf6441fcf5f2a67"