.\" -*- coding: UTF-8 -*- .\" Written and revised by Solar Designer in 2000-2011. .\" Revised by Zack Weinberg 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 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. Jeśli funkcje się powiodą, wartość .Va errno jest nieokreślona i nie powinna być brana pod uwagę. .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, 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 Tłumaczenie niniejszej strony podręcznika: Adam Byrtek , Andrzej Krzysztofowicz , Michał Kułach i Robert Luberda . .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 .