.\" -*- coding: UTF-8 -*-
.\" Written and revised by Solar Designer <solar at openwall.com> in 2000-2011.
.\" Revised by Zack Weinberg <zackw at panix.com> in 2017.
.\" Converted to mdoc format by Zack Weinberg in 2018.
.\"
.\" No copyright is claimed, and this man page is hereby placed in the public
.\" domain.  In case this attempt to disclaim copyright and place the man page
.\" in the public domain is deemed null and void, then the man page is
.\" Copyright 2000-2011 Solar Designer, 2017, 2018 Zack Weinberg, and it is
.\" hereby released to the general public under the following terms:
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted.
.\"
.\" There's ABSOLUTELY NO WARRANTY, express or implied.
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.Dd 11 października 2017 r.
.Dt CRYPT 3
.Os "Projekt Openwall"
.Sh NAZWA
.Nm crypt , crypt_r , crypt_rn , crypt_ra
.Nd miesza (haszuje) hasła
.Sh BIBLIOTEKA
.Lb libcrypt
.Sh SKŁADNIA
.In crypt.h
.Ft "char *"
.Fo crypt
.Fa "const char *phrase"
.Fa "const char *setting"
.Fc
.Ft "char *"
.Fo crypt_r
.Fa "const char *phrase"
.Fa "const char *setting"
.Fa "struct crypt_data *data"
.Fc
.Ft "char *"
.Fo crypt_rn
.Fa "const char *phrase"
.Fa "const char *setting"
.Fa "struct crypt_data *data"
.Fa "int size"
.Fc
.Ft "char *"
.Fo crypt_ra
.Fa "const char *phrase"
.Fa "const char *setting"
.Fa "void **data"
.Fa "int *size"
.Fc
.Sh OPIS
Funkcje
.Nm crypt ,
.Nm crypt_r ,
.Nm crypt_rn
i
.Nm crypt_ra
nieodwracalnie \[Bq]mieszają\[rq] (haszują) hasła w celu ich przechowywania
w systemowej bazie danych haseł
.Pq Xr shadow 5 ,
za pomocą
kryptograficznej \[Bq]metody mieszającej\[rq]. Wynik operacji zwany jest
\[Bq]skrótem hasła\[rq] lub po prostu \[Bq]skrótem\[rq]
(\[Bq]haszem\[rq]). Metody mieszania opisano w
.Xr crypt 5 .
.Pp
.Fa setting
kontrolują metodę mieszania, która ma zostać zastosowana i
przekazują jej różne parametry, w szczególności losową \[Bq]sól\[rq], która
zapewnia, że żadne dwa przechowywane skróty nie są takie same, nawet przy
takich samych
.Fa phrase .
.Pp
Argument
.Fa data
do
.Nm crypt_r
jest strukturą typu
.Vt "struct crypt_data" .
Ma co najmniej następujące pola:
.Bd -literal -offset indent
struct crypt_data {
    char output[CRYPT_OUTPUT_SIZE];
    char setting[CRYPT_OUTPUT_SIZE];
    char input[CRYPT_MAX_PASSPHRASE_SIZE];
    char initialized;
};
.Ed
.Pp
Po pomyślnym powrocie z
.Nm crypt_r ,
skróty haseł trafią do
.Fa output .
Aplikacje są zachęcane (lecz nie jest to wymagane) do używania pól
.Fa input
i
.Fa setting ,
w celu ich przekazania jako
.Fa input phrase
i
.Fa setting
do
.Nm crypt_r .
W ten sposób łatwiejsze będzie
usunięcie wszystkich wrażliwych danych, które nie są już potrzebne.
.Pp
Pole
.Fa initialized
musi wynosić zero przed pierwszym użyciu obiektu
.Vt "struct crypt_data"
w wywołaniu do
.Fn crypt_r .
Przed pierwszym
użyciem, zaleca się wyzerowanie całego obiektu, a nie tylko
.Fa initialized
i nie jedynie pól udokumentowanych (oczywiście należy to zrobić
przed przechowaniem czegokolwiek w
.Fa setting
i
.Fa input ) .
.Pp
Argument
.Fa data
do
.Nm crypt_rn
powinien również wskazywać na obiekt
.Vt "struct crypt_data" ,
przy czym
.Fa size
powinno być rozmiarem tego
obiektu, rzutowanym na
.Vt int .
Przy użyciu z
.Nm crypt_rn ,
cały
obiekt
.Fa data
(poza polami
.Fa input
i
.Fa setting )
musi być
wyzerowany przed pierwszym użyciem; nie jest to jedynie zalecenie, jak ma to
miejsce w przypadku
.Nm crypt_r .
Poza tym, pola tego obiektu mają te same
zastosowania, co dla
.Nm crypt_r .
.Pp
Przy pierwszym wywołaniu do
.Nm crypt_ra ,
.Fa data
powinno być adresem
zmiennej
.Vt "void *"
ustawionej na NULL, a
.Fa size
powinno być
adresem zmiennej
.Vt int
ustawionej na zero.
.Nm crypt_ra
zaalokuje i
zainicjuje obiekt
.Vt "struct crypt_data" ,
za pomocą
.Xr malloc 3
i
zapisze jego adres i rozmiar do zmiennych, na które wskazują
.Fa data
i
.Fa size .
Można ich później użyć ponownie w kolejnych wywołaniach. Po
tym, jak aplikacja ukończy mieszanie haseł, powinna zdealokować obiekt
.Vt "struct crypt_data"
za pomocą
.Xr free 3 .
.Sh WARTOŚCI ZWRACANE
Po pomyślnym zakończeniu,
.Nm crypt ,
.Nm crypt_r ,
.Nm crypt_rn
i
.Nm crypt_ra
zwracają wskaźnik do łańcucha kodującego zarówno skrót hasła
jak i ustawienia, których użyto, do jego zakodowania. Łańcuch ten może
posłużyć jako bezpośrednie
.Fa setting
w innych wywołaniach do
.Nm crypt ,
.Nm crypt_r ,
.Nm crypt_rn
i
.Nm crypt_ra ,
oraz jako
.Fa prefix
w wywołaniach do
.Nm crypt_gensalt ,
.Nm crypt_gensalt_rn
i
.Nm crypt_gensalt_ra .
Będzie to łańcuch złożony wyłącznie z drukowalnych
znaków ASCII i nie będzie zawierał białych znaków, ani znaków \[Bq]:\[rq],
\[Bq];\[rq], \[Bq]*\[rq], \[Bq]!\[rq] i \[Bq]\e\[rq]. Więcej informacji o
formacie skrótów haseł znajduje się w podręczniku
.Xr crypt 5 .
.Pp
.Nm crypt
umieszcza swój wynik w statycznej przestrzeni przechowywania,
która będzie nadpisana w kolejnych wywołaniach
.Nm crypt .
Nie jest
bezpieczne równoczesne wywoływanie
.Nm crypt
z wielu wątków.
.Pp
.Nm crypt_r ,
.Nm crypt_rn
i
.Nm crypt_ra
umieszczają swoje wyniki w
polu
.Fa output
ich argumentu
.Fa data .
Można bezpiecznie wywoływać je
równocześnie z wielu wątków, o ile tylko używane są różne obiekty
.Fa data
w każdym wątku.
.Pp
Po wystąpieniu błędu,
.Nm crypt_r ,
.Nm crypt_rn
i
.Nm crypt_ra
zapisują
.Em nieprawidłowy
skrót hasła w polu
.Fa output
ich argumentu
.Fa data ,
a
.Nm crypt
zapisze nieprawidłowy skrót w swojej statycznej
przestrzeni przechowywania. Łańcuch ten będzie krótszy niż 13 znaków, będzie
rozpoczynał się od znaku \[Bq]*\[rq], a przy porównaniu nie będzie równy
.Fa setting .
.Pp
Po wystąpieniu błędu,
.Nm crypt_rn
i
.Nm crypt_ra
zwrócą pusty
wskaźnik.
.Nm crypt_r
i
.Nm crypt
również mogą zwrócić pusty wskaźnik,
mogą też zwrócić wskaźnik do nieprawidłowego skrótu, w zależności od
konfiguracji libcrypt (opcja zwrócenia nieprawidłowego skrótu istnieje ze
względu na kompatybilność ze starszymi aplikacjami, które zakładają, że
.Nm crypt
nie może zwrócić pustego wskaźnika; zob.
.Sx UWAGI DOTYCZĄCE PRZENOŚNOŚCI
niżej).
.Pp
Wszystkie cztery funkcje ustawiają
.Va errno
przy niepowodzeniu.
.Sh BŁĘDY
.Bl -tag -width Er
.It Er EINVAL
.Fa setting
jest nieprawidłowe lub żądano nieobsługiwanej metody
mieszania.
.It Er ERANGE
.Fa phrase
jest zbyt długie (dłuższe niż
.Dv CRYPT_MAX_PASSPHRASE_SIZE
znaków; niektóre metody mieszania mogą mieć mniejsze limity).
.br
Tylko
.Nm crypt_rn :
.Fa size
jest zbyt małe dla metody mieszania
zażądanej w
.Fa setting .
.It Er ENOMEM
Nie udało się zaalokować wewnętrznej pamięci \[Bq]scratch\[rq].
.br
Tylko
.Nm crypt_ra :
nie udało się zaalokować pamięci dla
.Fa data .
.It Er ENOSYS No lub Er EOPNOTSUPP
Mieszanie haseł nie jest obsługiwane w tej instalacji lub metoda mieszania
zażądana w
.Fa setting
nie jest obsługiwana. Te statusy błędów nie są
używane w tej wersji libcrypt, ale mogą wystąpić na innych systemach.
.El
.Sh UWAGI DOTYCZĄCE PRZENOŚNOŚCI
.Nm crypt
jest wymienione w POSIX, lecz
.Nm crypt_r ,
.Nm crypt_rn
i
.Nm crypt_ra
nie są częścią żadnego standardu.
.Pp
POSIX nie określa żadnych metod mieszania, ani nie wymaga, aby skróty haseł
były przenośne między systemami. W praktyce, skróty haseł są przenośne, o
ile oba systemy obsługują daną metodę mieszania. Jednak zestaw obsługiwanych
metod mieszania znacznie różni się między systemami.
.Pp
Zachowanie
.Nm crypt
w przypadku błędów nie jest dobrze
zestandaryzowane. Niektóre implementacje nie mogą zawieść (poza załamaniem
programu), inne zwracają pusty wskaźnik lub określony łańcuch. Większość
implementacji nie ustawia
.Va errno ,
lecz niektóre to robią. POSIX
określa zwracanie pustego wskaźnika i ustawianie
.Va errno ,
lecz
definiuje tylko jeden możliwy błąd,
.Er ENOSYS
w przypadku, w którym
.Nm crypt
w ogóle nie jest obsługiwane. Niektóre starsze aplikacje nie są
przygotowane do obsługi pustych wskaźników zwracanych przez
.Nm crypt .
Zachowanie opisane powyżej w tej implementacji, czyli ustawianie
.Va errno
i zwracanie nieprawidłowego skrótu hasła, różnego od
.Fa setting
wybrano, aby takie aplikacje zamknęły się i zawiodły, gdy taki błąd
wystąpi.
.Pp
Z powodów historycznych ograniczeń, dotyczących eksportu oprogramowania
kryptograficznego ze Stanów Zjednoczonych,
.Nm crypt
jest opcjonalną
częścią POSIX. Aplikacje powinny być dlatego przygotowane do sytuacji, gdy
.Nm crypt
nie jest dostępne, bądź zawsze zawodzić (ustawiając
.Va errno
na
.Er ENOSYS )
przy rozruchu.
.Pp
POSIX określa, że
.Nm crypt
jest zadeklarowane w
.In unistd.h ,
lecz tylko gdy makro
.Dv _XOPEN_CRYPT
jest zdefiniowane i ma wartość
większą lub równą zero. Ze względu na to, że libcrypt nie zapewnia
.In unistd.h ,
deklaruje w zamian
.Nm crypt ,
.Nm crypt_r ,
.Nm crypt_rn
i
.Nm crypt_ra
w
.In crypt.h
\&.
.Pp
Na mniejszości systemów (głównie ostatnich wersjach Solarisa),
.Nm crypt
używa statycznego bufora przechowywania przypisanego wątkowi, który czyni
bezpiecznym równoczesne wywoływanie z wielu wątków, lecz nie zapobiega
każdemu wywołaniu z wątku, przed nadpisaniem wyników poprzedniego wywołania.
.Sh USTERKI
Niektóre implementacje
.Nm crypt ,
przy błędzie zwracają nieprawidłowy
skrót, który jest przechowywany w położeniu tylko do odczytu, lub
zainicjowanym jedynie jednokrotnie, co oznacza, że wyczyszczenie bufora, na
który wskazuje wartość zwracana przez
.Nm crypt
jest bezpieczne tylko
wtedy, gdy nie wystąpił błąd.
.Pp
.Vt "struct crypt_data"
może być dość duże (32kB w tej implementacji
libcrypt; ponad 128kB w niektórych innych implementacjach). Jest to na tyle
duża wielkość, że może być nierozsądne alokowanie jej na stosie.
.Pp
Niektóre ostatnio zaprojektowane metody mieszania potrzebują jeszcze więcej
pamięci \[Bq]scratch\[rq], lecz interfejs
.Nm crypt_r
nie umożliwia
zmiany rozmiaru
.Vt "struct crypt_data"
bez złamania kompatybilności
binarnej. Interfejs
.Nm crypt_rn
mógłby dokonywać większych alokacji dla
określonych metod mieszania, lecz wywołujący
.Nm crypt_rn
nie ma sposobu
określenia, jak dużo pamięci zaalokować.
.Nm crypt_ra
sam alokuje pamięć,
lecz może wykonać jedynie pojedyncze wywołanie do
.Xr malloc 3 .
.Sh ATRYBUTY
Informacje o pojęciach używanych w tym rozdziale można znaleźć w podręczniku
.Xr attributes 7 .
.TS
allbox;
lb lb lb
l l l.
Interfejs	Atrybut	Wartość
T{
.Nm crypt
T}	Bezpieczeństwo wątkowe	MT-niebezpieczne race:crypt
T{
.Nm crypt_r ,
.Nm crypt_rn ,
.Nm crypt_ra
T}	Bezpieczeństwo wątkowe	MT-bezpieczne
.TE
.sp
.Sh HISTORIA
Funkcja
.Nm crypt
oparta na wirnikach pojawiła się w
.At v6 .
\[Bq]Tradycyjne\[rq]
.Nm crypt ,
oparte na DES, pojawiło się w
.At v7 .
.Pp
.Nm crypt_r
pochodzi z biblioteki GNU C. Występuje również funkcja
.Nm crypt_r
na HP-UX i MKS Toolkit, lecz prototypy i zachowanie różnią się.
.Pp
.Nm crypt_rn
i
.Nm crypt_ra
pochodzą z projektu Openwall.
.Sh ZOBACZ TAKŻE
.Xr crypt_gensalt 3 ,
.Xr getpass 3 ,
.Xr getpwent 3 ,
.Xr shadow 3 ,
.Xr login 1 ,
.Xr passwd 1 ,
.Xr crypt 5 ,
.Xr passwd 5 ,
.Xr shadow 5 ,
.Xr pam 8
.Pp
.Sh TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są:
Adam Byrtek <alpha@irc.pl>,
Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl>,
Michał Kułach <michal.kulach@gmail.com>
i
Robert Luberda <robert@debian.org>
.
.Pp
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach
licencji można uzyskać zapoznając się z
.Lk https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License w wersji 3
lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.
.Pp
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy
dyskusyjnej
.Mt manpages-pl-list@lists.sourceforge.net
.Me .
