.\" Written by Solar Designer and placed in the public domain.
.\" french translation by Denis Ducamp <Denis.Ducamp@groar.org>
.\"
.\" Cette page de manuel dans cette forme actuelle est destiné à être
.\" utilisée sur les systèmes basés sur la bibliothèque C GNU avec le patch
.\" crypt_blowfish dans libcrypt.
.\"
.TH CRYPT 3 "3 June 2001" "Projet Openwall" "Fonctions de bibliothèque"
.ad l
.\" No macros in NAME to keep makewhatis happy.
.SH NAME
\fBcrypt\fR, \fBcrypt_r\fR, \fBcrypt_rn\fR, \fBcrypt_ra\fR,
\fBcrypt_gensalt\fR, \fBcrypt_gensalt_rn\fR, \fBcrypt_gensalt_ra\fR
\- hachage de mots de passe
.SH SYNOPSIS
.B #define _XOPEN_SOURCE
.br
.B #include <unistd.h>
.sp
.in +8
.ti -8
.BI "char *crypt(const char *" key ", const char *" setting );
.in -8
.sp
.B #define _GNU_SOURCE
.br
.B #include <crypt.h>
.sp
.in +8
.ti -8
.BI "char *crypt_r(const char *" key ", const char *" setting ", struct crypt_data *" data );
.in -8
.sp
.B #define _OW_SOURCE
.br
.B #include <crypt.h>
.sp
.in +8
.ti -8
.BI "char *crypt_rn(const char *" key ", const char *" setting ", void *" data ", int " size );
.ti -8
.BI "char *crypt_ra(const char *" key ", const char *" setting ", void **" data ", int *" size );
.ti -8
.BI "char *crypt_gensalt(const char *" prefix ", unsigned long " count ", const char *" input ", int " size );
.ti -8
.BI "char *crypt_gensalt_rn(const char *" prefix ", unsigned long " count ", const char *" input ", int " size ", char *" output ", int " output_size );
.ti -8
.BI "char *crypt_gensalt_ra(const char *" prefix ", unsigned long " count ", const char *" input ", int " size );
.ad b
.de crypt
.BR crypt ,
.BR crypt_r ,
.BR crypt_rn "\\$1"
.ie "\\$2"" .B crypt_ra
.el .BR crypt_ra "\\$2"
..
.de crypt_gensalt
.BR crypt_gensalt ,
.BR crypt_gensalt_rn "\\$1"
.ie "\\$2"" .B crypt_gensalt_ra
.el .BR crypt_gensalt_ra "\\$2"
..
.SH DESCRIPTION
Les fonctions
.crypt " et"
calculent une fonction de hachage cryptographique de
.I key
avec une des méthodes supportées comme demandé par
.IR setting ,
qui est également utilisé pour passer une graine et peut-être d'autres
paramètres pour choisir la méthode.
Les méthodes de hachage sont expliquées ci-dessous.
.PP
Contrairement à
.BR crypt ,
les fonctions
.BR crypt_r ,
.BR crypt_rn " et"
.B crypt_ra
sont réentrante.
Elles placent leurs résultats et toutes leurs données privées dans une aire
.I data
de
.I size
octets comme passées par une application et/ou en mémoire qu'elles allouent
dynamiquement. Quelques algorithmes de hachage peuvent utiliser l'aire data
pour mettre en cache des valeurs intermédiaires précalculées au travers
d'appels. Ainsi, les applications doivent initialiser proprement l'aire data
avant sa première utilisation.
.B crypt_r
requière seulement que
.I data->initialized
soit remis à zéro;
.BR crypt_rn " et " crypt_ra
requièrent soit que l'aire data soit mise à zéro en entier ou, dans le cas
de
.BR crypt_ra ,
.I *data
soit NULL. Quand appelé avec un
.I *data
NULL ou un
.I *size
insuffisant pour l'algorithme de hachage demandé,
.B crypt_ra
utilise
.BR realloc (3)
pour allouer la quantité requise de mémoire dynamique. Ainsi,
.B crypt_ra
possède le besoin supplémentaire que
.IR *data ,
quand il est non NULL, doit pointer vers une aire allouée soit avec un appel
précédent à 
.B crypt_ra
ou avec un appel à la famille
.BR malloc (3).
La mémoire allouée par
.B crypt_ra
devrait être libérée avec
.BR free "(3)."
.PP
Les fonctions
.crypt_gensalt " et"
compilent une chaîne à utiliser comme
.I setting
\- avec le
.I prefix
donné (utilisé pour choisir une méthode de hachage), le nombre d'itérations
.I count
(si supporté par la méthode choisie) et jusqu'à
.I size
octets aléatoires cryptographiquement dans
.I input
à utiliser comme graine exacte.
Si
.I count
est 0, un défaut bas sera choisi.
Les octets aléatoires peuvent être obtenus depuis
.BR /dev/urandom .
Contrairement à
.BR crypt_gensalt ,
les fonctions
.BR crypt_gensalt_rn " et " crypt_gensalt_ra
sont réentrantes.
.B crypt_gensalt_rn
place ses résultats dans le tampon
.I output
de
.I output_size
octets.
.B crypt_gensalt_ra
alloue dynamiquement de la mémoire pour ses résultats. La mémoire devrait
être libérée avec
.BR free "(3)."
.SH RETURN VALUE
Après une terminaison avec succès, les fonctions
.crypt " et"
retournent un pointeur vers une chaîne retournant les définitions qui
étaient réellement utilisés et un encodage imprimable de la valeur de la
fonction de hachage.
La chaîne en entier est utilisable directement comme
.I setting
avec d'autres appels à
.crypt " et"
et comme
.I prefix
avec des appels à
.crypt_gensalt " et" .
.PP
Le comportement de
.B crypt
sur les erreurs n'est pas bien standardisé. Quelques mises en oeuvre ne
peuvent simplement pas échouer (à moins que le processus ne meure, cas dans
lequel elles ne peuvent évidemment pas retourner), d'autres retournent NULL
ou une chaîne fixe. La plupart des mises en oeuvre ne définissent pas
.IR errno ,
mais quelques unes le font. SUSv2 spécifie seulement le renvoie de NULL et
la définition de
.I errno
comme un comportement valide, et définit seulement une seule erreur possible
.RB "(" ENOSYS ,
"La fonctionnalité n'est pas supportée dans cette mise en oeuvre.")
Malheureusement, la plupart des applications existantes ne sont pas
préparées à traiter des retours NULL de
.BR crypt .
La description ci-dessous correspond seulement à cette mise en oeuvre de
.BR crypt " et " crypt_r ","
et à
.BR crypt_rn " et " crypt_ra .
Le comportement peut changer pour correspondre aux standards, à d'autres
mises en oeuvre ou à des applications existantes.
.PP
.BR crypt " et " crypt_r
peuvent seulement échouer (et retourner) en passant un 
.I setting
invalide ou non supporté, cas dans lequel elles retournent un pointeur vers
une chaîne magique qui est plus courte que 13 caractères et est garantie
d'être différente de
.IR setting .
Ce comportement est sain pour les applications plus anciennes qui assument
que
.B crypt
ne peut échouer, en définissant à la fois des nouveaux mots de passe et en
authentifiant auprès d'empreintes de mots de passe existantes.
.BR crypt_rn " et " crypt_ra
retournent NULL pour indiquer un échec. Les quatre fonctions définissent
toutes
.I errno
quand elles échouent.
.PP
Les fonctions
.crypt_gensalt " et"
retournent un pointeur à la chaîne compilée pour
.IR setting ,
ou NULL sur une erreur cas dans lequel
.I errno
est défini.
.SH ERRORS
.TP
.B EINVAL
.crypt , " :"
.I setting
est invalide ou non supporté dans cette mise en oeuvre;
.sp
.crypt_gensalt , " :"
.I prefix
est invalide ou non supporté par cette implémentation;
.I count
est invalide pour le
.I prefix
demandé;
.I input
est NULL.
.TP
.B ERANGE
.BR crypt_rn " :"
la taille
.I size
de l'aire de données fournie est insuffisante pour l'algorithme de hachage
demandé;
.sp
.crypt_gensalt , " :"
la taille
.I size
de l'entrée est insuffisante pour la plus petite graine valide avec le
.I prefix
demandé;
.sp
.BR crypt_gensalt_rn " :"
.I output_size
est trop petit pour contenir la chaîne
.I setting
compilée.
.TP
.B ENOMEM
.B crypt
(seulement la glibc originale) :
échoue à allouer de la mémoire pour le tampon de sortie (que des appels
ultérieurs réutiliseraient);
.sp
.BR crypt_ra " :"
.I *data
est NULL ou
.I *size
est insuffisant pour l'algorithme de hachage demandé et
.BR realloc (3)
a échoué;
.sp
.BR crypt_gensalt_ra " :"
a échoué à allouer de la mémoire pour la chaîne
.I setting
compilée.
.TP
.B ENOSYS
.B crypt
(SUSv2) :
la fonctionnalité n'est pas supportée dans cette mise en oeuvre;
.sp
.BR crypt ,
.B crypt_r
(seulement de glibc 2.0 à 2.0.1) :
.de no-crypt-add-on
aucun ajout à crypt n'a été compilé et
.I setting
demande quelque chose d'autre que l'algorithme basé sur MD5.
..
.no-crypt-add-on
.TP
.B EOPNOTSUPP
.BR crypt ,
.B crypt_r
(seulement de glibc 2.0.2 à 2.1.3) :
.no-crypt-add-on
.SH HASHING METHODS
Les méthodes de hachage mises en oeuvre sont spécifiquement prévues pour
traiter les mots de passe utilisateurs pour la sauvegarde et
l'authentification;
.PP
Il est important de comprendre que le hachage de mots de passe n'est pas un
remplacement des mots de passe forts.
Il est toujours possible pour un attaquant avec accès aux empreintes des
mots de passe d'essayer de deviner des mots de passe candidats contre les
empreintes.
Il y a, toutefois, certaines propriétés qu'une méthode de hachage de mots de
passe peut avoir qui rendent ces attaques de recherche de clés plus dures.
.PP
Toutes les méthodes de hachage de clés utilisent une graine telle que la
même
.I key
peut produire beaucoup d'empreintes possibles.
Une utilisation correcte des graines met en échec un certain nombre
d'attaques, incluant :
.TP
1.
La possibilité d'essayer des mots de passe candidats contre de multiples
empreintes au pris d'un seul.
.TP
2.
L'utilisation de listes de mots de passe pré-calculés.
.TP
3.
La possibilité de déterminer si deux utilisateurs (ou deux comptes d'un
utilisateur) ont le même mot de passe ou des différents sans avoir vraiment
à deviner l'un des mots de passe.
.PP
Les attaques de recherche de clés dépendent du calcul des empreintes d'un
grand nombre de mots de passe candidats.
Ainsi, le coût de calcul d'une bonne méthode de hachage de mots de passe
doit être élevé \- mais bien sûr pas trop haut pour ne pas la rendre
inutilisable.
.PP
Toutes les méthodes de hachage mises en oeuvre dans les interfaces
.crypt " et"
utilisent de multiples itérations d'une primitive cryptographique
sous-jacente afin d'augmenter le coût d'essai d'un mot de passe candidat.
Malheureusement, à cause des améliorations des matériels, les méthodes de
hachage qui ont un coût fixe deviennent de moins en moins sûres au cours du
temps.
.PP
En plus des graines, les méthodes modernes de hachage de mots de passe
acceptent un nombre variable d'itérations
.IR count .
Ceci rend possible l'adaptation de leurs coûts aux améliorations des
matériels tout en maintenant toujours la compatibilité.
.PP
Les méthodes de hachage suivantes sont ou peuvent être mises en oeuvre au
travers des interfaces décrites :
.PP
.de hash
.ad l
.TP
.I prefix
.ie "\\$1"" \{\
"" (chaîne vide);
.br
une chaîne correspondant à ^[./0-9A-Za-z]{2} (voir
.BR regex (7))
.\}
.el "\\$1"
.TP
.B Syntaxe de codage
\\$2
.TP
.B Longueur maximale de mot de passe
\\$3 (utilise des caractères de \\$4-bits)
.TP
.B Taille de clé effective
.ie "\\$5"" seulement limitée par la taille de l'empreinte
.el jusqu'à \\$5 bits
.TP
.B Taille de l'empreinte
\\$6 bits
.TP
.B Taille de la graine
\\$7 bits
.TP
.B Nombre d'itérations
\\$8
.ad b
..
.ti -2
.B Méthode traditionnelle basée sur le DES
.br
Cette méthode est supportée par la plupart des mises en oeuvre de
.BR crypt .
Malheureusement, elle n'offre plus une sécurité suffisante à cause de ses
nombreuses limites.
Ainsi, elle ne doit pas être utilisée pour de nouveaux mots de passe à moins
que vous deviez absolument être capable de migrer les empreintes de mots de
passe vers d'autres systèmes.
.hash "" "[./0-9A-Za-z]{13}" 8 7 56 64 12 25
.PP
.ti -2
.B Méthode étendue de style BSDI basée sur le DES
.br
Cette méthode est utilisée sur BSDI et est également disponible au moins sur
NetBSD, OpenBSD et FreeBSD à cause de l'utilisation de la bibliothèque
FreeSec de David Burren.
Il n'y a pas actuellement de mise en oeuvre réentrante.
.hash _ "_[./0-9A-Za-z]{19}" illimitée 7 56 64 24 "1 à 2**24-1 (doit être impair)"
.PP
.ti -2
.B Méthode de style FreeBSD basée sur le MD5
.br
C'est la méthode de hachage de mots de passe basée sur le MD5 de
Poul-Henning Kamp originellement développée pour FreeBSD.
Elle est actuellement supportée sur de nombreux systèmes Unix libres et fait
partie de la glibc officielle.
Son principal défaut est le nombre fixe d'itérations, qui est déjà trop bas
pour les matériels actuellement disponibles.
.hash "$1$" "\e$1\e$[^$]{1,8}\e$[./0-9A-Za-z]{22}" illimitée 8 "" 128 "6 à 48" 1000
.PP
.ti -2
.BR "Méthode de style OpenBSD basée sur le Blowfish" " (" bcrypt )
.br
.B bcrypt
était développée originellement par Niels Provos et David Mazieres pour
OpenBSD et est également supportée sur les versions récentes de FreeBSD et
sur plusieurs distributions GNU/*/Linux.
Elle ne fait, toutefois, pas partie de la glibc officielle.
.PP
Alors que
.B bcrypt
et le hachage de style BSDI basé sur le DES offrent un nombre variable
d'itérations,
.B bcrypt
peut s'adapter à des matériels encore plus rapides, ne permet pas certaines
optimisations spécifiques seulement au craquage de mots de passe, n'a pas de
limitation de taille de clé effective, et utilise des caractères 8 bits dans
les mots de passe.
.hash "$2a$" "\e$2a\e$[0-9]{2}\e$[./A-Za-z0-9]{53}" 72 8 "" 184 128 "2**4 à 2**99 (les mises en oeuvre actuelles sont limitées à 2**31 itérations)"
.PP
Avec
.BR bcrypt ,
le nombre
.I count
passé à
.crypt_gensalt " et"
est le logarithme en base 2 du nombre réel d'itérations.
.SH PORTABILITY NOTES
Les programmes utilisant n'importe laquelle de ces fonctions sur un système
glibc 2.x doivent être liés à
.BR libcrypt .
Toutefois, beaucoup de systèmes d'exploitation Unix et les versions plus
anciennes de la bibliothèque C GNU incluent la fonction
.BR crypt " dans " libc .
.PP
Les fonctions
.BR crypt_r ,
.BR crypt_rn ,
.BR crypt_ra ,
.crypt_gensalt " et"
sont très non-portables.
.PP
L'ensemble des méthodes de hachage supportées est dépendant de la mise en
oeuvre.
.SH CONFORMING TO
La fonction
.B crypt
est conforme à SVID, X/OPEN, et est disponible sur BSD 4.3.
Les chaînes retournées par
.B crypt
ne sont pas requises d'être portables parmi les systèmes conformes.
.PP
.B crypt_r
est une extension GNU.
Il y a aussi la fonction
.B crypt_r
sur HP-UX et dans MKS Toolkit, mais les prototypes et les sémantiques
diffèrent.
.PP
.BR crypt_rn ,
.BR crypt_ra ,
.crypt_gensalt " et"
sont des extensions Openwall.
.SH HISTORY
Une fonction
.B crypt
basée sur un rotor est apparue dans AT&T UNIX Version 6.
La fonction
.B crypt
"traditionnelle" est apparue en premier dans AT&T UNIX Version 7.
.PP
La fonction
.B crypt_r
a été introduite durant le développement de la glibc 2.0.
.SH BUGS
Les valeurs de retour de
.BR crypt " et " crypt_gensalt
pointent vers un tampon statique qui est écrasé par les appels ultérieurs.
Ces fonctions ne sont pas sûres d'utilisation dans des threads.
.RB ( crypt
sur des versions récentes de Solaris utilisent des données spécifiques à
chaque thread et sont réellement sûres d'utilisation dans des threads.)
.PP
Les chaînes retournées par certaines mises en oeuvre de
.B crypt
lors d'une erreur peuvent être stockées dans des endroits en lecture seule
ou initialisées seulement une fois, ce qui rend non sûr de tenter de
toujours mettre à zéro le tampon normalement pointé par la valeur de retour
de
.B crypt
comme il serait autrement préférable pour des raisons de sécurité.
Le problème pourrait être évité avec l'utilisation de
.BR crypt_r ,
.BR crypt_rn " ou"
.B crypt_ra
où l'application a le contrôle total sur les tampons de sortie de ces
fonctions (et souvent sur quelques unes de leurs données privées également).
Malheureusement, les fonctions ne sont pas (encore ?) disponibles sur les
plates-formes où
.B crypt
a cette propriété non désirable.
.PP
Les applications utilisant la fonction
.B crypt_r
sûre d'utilisation dans des thread ont besoin d'allouer de l'espace pour la
grande structure (plus de 128 Ko)
.IR "struct crypt_data" .
Chaque thread a besoin d'une instance séparée de la structure. L'interface
.B crypt_r
rend possible de mettre en oeuvre un algorithme de hachage qui nécessiterait
de garder une quantité encore plus grande de données, sans casser la
compatibilité binaire.
.B crypt_ra
permet d'augmenter dynamiquement la taille d'allocation comme requis par
l'algorithme de hachage qui est vraiment utilisé. Malheureusement,
.B crypt_ra
est encore plus non-portable que
.BR crypt_r .
.PP
Les applications multi-threadées ou les fonctions de bibliothèques qui sont
censées être sûres d'utilisation dans des threads devraient utiliser
.BR crypt_gensalt_rn " ou " crypt_gensalt_ra
plutôt que
.BR crypt_gensalt .
.SH SEE ALSO
.BR login (1),
.BR passwd (1),
.BR crypto (3),
.BR encrypt (3),
.BR free (3),
.BR getpass (3),
.BR getpwent (3),
.BR malloc (3),
.BR realloc (3),
.BR shadow (3),
.BR passwd (5),
.BR shadow (5),
.BR regex (7),
.BR pam (8)
.sp
Niels Provos and David Mazieres.  A Future-Adaptable Password Scheme.
Proceedings of the 1999 USENIX Annual Technical Conference, June 1999.
.br
http://www.usenix.org/events/usenix99/provos.html
.sp
Robert Morris and Ken Thompson.  Password Security: A Case History.
Unix Seventh Edition Manual, Volume 2, April 1978.
.br
http://plan9.bell-labs.com/7thEdMan/vol2/password