diff --git a/reference/password/constants.xml b/reference/password/constants.xml new file mode 100644 index 00000000..27edacd7 --- /dev/null +++ b/reference/password/constants.xml @@ -0,0 +1,258 @@ + + + + + + &reftitle.constants; + &extension.constants.core; + + + + + + PASSWORD_BCRYPT + (string) + + + + PASSWORD_BCRYPT jest używana do tworzenia nowych hashy haseł + przy pomocy algorytmu CRYPT_BLOWFISH. + + + Hash zawsze będzie używał formatu "$2y$" i zawsze będzie miał szerokość 60 znaków. + + + Obsługiwane opcje: + + + + + Jeżeli pomięto, losowa sól zostanie wygenerowana przez password_hash + dla każdego hasła. Jest to zalecany sposób postępowania. + + + Jeśli pominięto, password_hash wygeneruje losową sól dla + każdego z hashowanych haseł. Jest to zalecany sposób postępowania + a od PHP 7.0.0 opcja salt jest przestarzała. + + + + + cost (int) - oznacza koszt algorytmu, który powinien zostać użyty. + Przykładowe wartości można znaleźć na stronie funkcji + crypt. + + + Jeżeli pominięto, to zostanie użyta domyślna wartość 10. Stanowi ona rozsądny + koszt wyjściowy, ale możesz rozważyć jego zwiększenie w zależności od sprzętu, którym dysponujesz. + + + + + + + + PASSWORD_BCRYPT_DEFAULT_COST + (int) + + + + + + + + + + + PASSWORD_ARGON2I + (string) + + + + PASSWORD_ARGON2I jest używana do tworzenia nowych hashy haseł + przy pomocy algorytmu Argon2i. + + + Obsługiwane opcje: + + + + + memory_cost (int) - Maksymalna ilość pamięci (w bajtach), która może + być użyta, aby obliczyć hash Argon2. Domyślnie ma wartość PASSWORD_ARGON2_DEFAULT_MEMORY_COST. + + + + + time_cost (int) - Maksymalna ilość czasu, która + może być użyta, aby obliczyć hash Argon2. Domyślnie ma wartość PASSWORD_ARGON2_DEFAULT_TIME_COST. + + + + + threads (int) - Liczba wątków, których należy użyć dla obliczenia + hasha Argon2. Domyślna wartość to PASSWORD_ARGON2_DEFAULT_THREADS. + Dostępne tylko, gdy PHP używa libargon2, nie implementacji libsodium. + + + + + Dostępna od PHP 7.2.0. + + + + + + PASSWORD_ARGON2ID + (string) + + + + PASSWORD_ARGON2ID jest używana do tworzenia nowych hashy haseł + przy pomocy algorytmu Argon2id. Obsługuje takie same opcje jak + PASSWORD_ARGON2I. + + + Dostępna od PHP 7.3.0. + + + + + + PASSWORD_ARGON2_DEFAULT_MEMORY_COST + (int) + + + + Domyślna ilość pamięci w bajtach, która będzie użyta podczas pró”y + obliczenia hasha. + + + Dostępna od PHP 7.2.0. + + + + + + PASSWORD_ARGON2_DEFAULT_TIME_COST + (int) + + + + Domyślna ilość czasu, który zostanie poświęcony na próbę obliczenia hasha. + + + Dostępna od PHP 7.2.0. + + + + + + PASSWORD_ARGON2_DEFAULT_THREADS + (int) + + + + Domyślna ilość wątków, których użyje Argon2lib. + Niedostępna z implementacją libsodium. + + + Dostępna od PHP 7.2.0. + + + + + + PASSWORD_ARGON2_PROVIDER + (string) + + + + + + Dostępna od PHP 7.4.0. + + + + + + PASSWORD_DEFAULT + (mixed) + + + + Domyślny algorytm używany do hashowania, jeśli nie został podany algorytm. + Ta wartość może zmieniać się w kolejnych wydaniach PHP, gdy pojawi się wsparcie + dla nowszych i mocniejszych algorytmów hashujących. + + + Warto zauważyć, że z biegiem czasu wartość tej stałej najprawdopodobniej się + zmieni. W związku z tym należy mieć świadomość, że długość wynikowego + hasha może się zmienić. Tak więc, jeśli używasz PASSWORD_DEFAULT, + to hash powinien być zapisany w taki sposób, który może przechowywać więcej niż 60 + znaków (255 to zalecana długość). + + + Wartości tej stałej: + + + + + PHP 5.5.0 - PASSWORD_BCRYPT + + + + + + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 7.4.0 + + Wartości identyfikatorów algorytmów haseł (PASSWORD_BCRYPT, PASSWORD_ARGON2I, + PASSWORD_ARGON2ID and PASSWORD_DEFAULT) są teraz typu &string;. + Wcześniej były to liczby (&integer;). + + + + + + + + + + + + diff --git a/reference/password/functions/password-algos.xml b/reference/password/functions/password-algos.xml new file mode 100644 index 00000000..98417d81 --- /dev/null +++ b/reference/password/functions/password-algos.xml @@ -0,0 +1,80 @@ + + + + + + + password_algos + Pobiera identyfikatory dostępnych algorytmów hashujących hasła + + + + &reftitle.description; + + arraypassword_algos + + + + Zwraca pełną listę identyfikatorów zarejestrowanych algorytmów hashujących hasła jako tablicę ciągów znaków. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Zwraca identyfikatory dostępnych algorytmów hashujących hasła. + + + + + &reftitle.examples; + + Podstawowe użycie <function>password</function> + + +]]> + + &example.outputs.similar; + + 2y + [1] => argon2i + [2] => argon2id +) +]]> + + + + + + + diff --git a/reference/password/functions/password-hash.xml b/reference/password/functions/password-hash.xml index ff6f610f..d374a01c 100644 --- a/reference/password/functions/password-hash.xml +++ b/reference/password/functions/password-hash.xml @@ -1,7 +1,6 @@ - + - password_hash @@ -12,15 +11,13 @@ &reftitle.description; stringpassword_hash - stringhasło - integeralgorytm - arrayopcje + #[\SensitiveParameter]stringpassword + stringintnullalgo + arrayoptions[] password_hash tworzy hash hasła używając silnego, jednokierunkowego - algorytmu. password_hash jest kompatybilny z crypt. - Dzięki temu hashe utworzone przez crypt mogą być użyte z - password_hash. + algorytmu. Następujące algorytmy są obecnie wspierane: @@ -42,32 +39,83 @@ stworzenia hasha. To ustawienie zwróci hash kompatybilny z crypt używając identyfikatora "$2y$". Rezultatem tej funkcji będzie zawsze 60-znakowy ciąg&return.falseforfailure;. + + + + PASSWORD_ARGON2I - Używa algorytmu Argon2i do stworzenia hasha. + Ten algorytm jest dostępny tylko, jeśli PHP został skompilowany z obsługą Argon2. + + + + + PASSWORD_ARGON2ID - Używa algorytmu Argon2id do stworzenia hasha. + Ten algorytm jest dostępny tylko, jeśli PHP został skompilowany z obsługą Argon2. + + + + + + Obsługiwane opcje dla PASSWORD_BCRYPT: + + + + - Wspierane opcje + salt (string) - pozwala na ręczne podanie soli przy generowaniu hasła. + Zwróć uwagę, że to ustawienie zapobiegnie automatycznemu wygenerowaniu soli. + + + Jeżeli pomięto, losowa sól zostanie wygenerowana przez password_hash + dla każdego hasła. Jest to zalecany sposób postępowania. + + + + Opcja salt jest przestarzała. Zaleca + się teraz, aby po prostu skorzystać z domyślnie wygenerowanej soli. + Od PHP 8.0.0 podana jawnie sól jest ignorowana. + + + + + + cost (int) - oznacza koszt algorytmu, który powinien zostać użyty. + Przykładowe wartości można znaleźć na stronie funkcji crypt. + + + Jeżeli pominięto, to zostanie użyta domyślna wartość 10. Stanowi ona rozsądny + koszt wyjściowy, ale możesz rozważyć jego zwiększenie w zależności od sprzętu, którym dysponujesz. - - - - salt - pozwala na ręczne podanie soli przy generowaniu hasła. - Zwróć uwagę, że to ustawienie zapobiegnie automatycznemu wygenerowaniu soli. - - - Jeżeli pomięto, losowa sól zostanie wygenerowa przez password_hash - dla każdego hasła. Jest to zalecany tryb postępowania. - - - - - cost - oznacza koszt algorytmu, który może zostać użyty. - Przykładowe wartości można znaleźć na stronie funkcji crypt. - - - Domyślną wartością jest 10. Stanowi ona optymalny balans pomiędzy - siłą hashowania i czasem, ale możesz rozważyć jej zwiększenie, zależnie od sprzętu, - którym dysponujesz. - - - + + + + + Wspierane opcja dla PASSWORD_ARGON2I + i PASSWORD_ARGON2ID: + + + + + + memory_cost (int) - Maksymalna ilość pamięci (w bajtach), która może + być użyta, aby obliczyć hash Argon2. Domyślnie ma wartość PASSWORD_ARGON2_DEFAULT_MEMORY_COST. + + + + + time_cost (int) - Maksymalna ilość czasu, która + może być użyta, aby obliczyć hash Argon2. Domyślnie ma wartość PASSWORD_ARGON2_DEFAULT_TIME_COST. + + + + + threads (int) - Liczba wątków, których należy użyć dla obliczenia + hasha Argon2. Domyślna wartość to PASSWORD_ARGON2_DEFAULT_THREADS. + + + + Dostępne tylko gdy PHP używa libargon2, nie implementacji libsodium. + + @@ -84,9 +132,10 @@ - Użycie stałej PASSWORD_BCRYPT dla parametru - algorytm spowoduje, że parametr algo - zostanie obcięty do maksymalnie 72 znaków. + Użycie PASSWORD_BCRYPT jako + algorytmu spowoduje, że parametr + password zostanie przycięty do + maksymalnie 72 bajtów. @@ -117,7 +166,7 @@ &reftitle.returnvalues; - Zwraca zahashowane hasło &return.falseforfailure;. + Zwraca zahashowane hasło. Użyty algorytm, koszt oraz sól są zwracane jako część hasha. Dzięki temu @@ -127,6 +176,64 @@ + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.0.0 + + password_hash nie zwraca już &false; w wypadku błędu; zamiast tego + rzucony zostanie ValueError jeśli algorytm hashujący jest + niepoprawny lub Error jeśli hashowanie hasła nie powiodło się + ze względu na nieznany błąd. + + + + 8.0.0 + + Parametr algo akceptuje teraz &null;. + + + + 7.4.0 + + Parametr algo oczekuje teraz typu &string;, ale wciąż przyjmuje + liczby (&integer;) ze względu na kompatybilność wsteczną. + + + + 7.4.0 + + Rozszerzenie sodium zapewnia alternatywną implementację dla haseł Argon2. + + + + 7.3.0 + + Dodano wsparcie dla haseł Argon2id przy użyciu PASSWORD_ARGON2ID. + + + + 7.2.0 + + Dodano wsparcie dla haseł Argon2i przy użyciu PASSWORD_ARGON2I. + + + + + + + + &reftitle.examples; @@ -139,10 +246,10 @@ * Chcemy po prostu hahashować nasze hasło przy użyciu domyślnego algorytmu * Obecnie jest to BCRYPT i zwróci 60-znakowy hash. * - * Pamiętaj że domyślny algorytm może z czasem ulec zmianie, więc przygotuj się + * Pamiętaj, że domyślny algorytm może z czasem ulec zmianie, więc przygotuj się * zwiększając ilość znaków w bazie danych na więcej niż 60 (255 będzie dobrym wyborem) */ -echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT)."\n"; +echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT); ?> ]]> @@ -183,61 +290,53 @@ $2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K - Ręczne ustawianie soli + Znajdowanie optymalnego kosztu 11, - 'salt' => mcrypt_create_iv(22, MCRYPT_DEV_URANDOM), -]; -echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options)."\n"; +$timeTarget = 0.350; // 350 milisekund + +$cost = 10; +do { + $cost++; + $start = microtime(true); + password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]); + $end = microtime(true); +} while (($end - $start) < $timeTarget); + +echo "Odpowiedni koszt znaleziony: " . $cost; ?> ]]> &example.outputs.similar; - Znajdowanie optymalnego kosztu + Przykład użycia <function>password_hash</function> z Argon2i $cost]); - $end = microtime(true); -} while (($end - $start) < $timeTarget); - -echo "Zalecany koszt znaleziony: " . $cost . "\n"; +echo 'Hash Argon2i: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I); ?> ]]> &example.outputs.similar; @@ -248,15 +347,21 @@ Zalecany koszt znaleziony: 11 &reftitle.notes; - Jest wysoce zalecane, aby nie generować soli dla tej funkcji samodzielnie. - Sól zostanie dla Ciebie stworzona automatycznie, jeżeli nie podasz żadnej. + Jest wysoce zalecane, aby nie generować soli dla tej funkcji + samodzielnie. Bezpieczna sól zostanie dla Ciebie stworzona automatycznie, jeżeli + nie podasz żadnej. + + + Jak podano wyżej, użycie opcji salt w PHP 7.0 + wygeneruje ostrzeżenie o przestarzałym kodzie. Wsparcie dla ręcznego podawania soli + zostało usunięte w PHP 8.0. - Jest zalecane aby przetestować tę funkcję na swoim serwerze i dostosować koszt, tak aby - wykonanie funkcji zajmowało około 0,1 do 0,5 sekundy. Skrypt powyżej pozwoli Ci wybrać - odpowiednią wartość dla Twojego sprzętu. + Zaleca się, aby przetestować tę funkcję na swoim serwerze i dostosować koszt, tak aby + wykonanie funkcji zajmowało mniej niż 350 milisekund dla systemów interaktywnych. + Skrypt powyżej pozwoli Ci wybrać odpowiednią wartość dla Twojego sprzętu. @@ -267,17 +372,19 @@ Zalecany koszt znaleziony: 11 - Algorytm musi być obecny w rdzeniu PHP przynajmniej od jednego pełnego wydania, aby - stać się domyślnym. Więc jeżeli przykładowo nowy algorytm został dodany w wersji 5.5.5, - nie powinien być domyślnym do wersji 5.7 (wersja 5.6 stanowi pierwsze pełne wydanie). Jeżeli jednak - inny algorytm został dodany w 5.6.0 będzie mógł zostać domyślnym od wersji 5.7.0. + + Algorytm musi być obecny w rdzeniu PHP przynajmniej od jednego pełnego wydania, zanim + będzie mógł stać się domyślnym. Więc jeżeli przykładowo nowy algorytm został dodany + w wersji 7.5.5, nie będzie mógł być domyślnym do wersji 7.7 (jako że wersja 7.6 + stanowi pierwsze pełne wydanie). Jeżeli jednak inny algorytm zostanie dodany + w 7.6.0, to będzie mógł zostać domyślnym od wersji 7.7.0. - Domyślny algorytm powinien zmieniać się jedynie w pełnych wydaniach (5.6.0, 6.0.0 itd). + Domyślny algorytm powinien zmieniać się jedynie w pełnych wydaniach (7.3.0, 8.0.0 itd.). Jedynym wyjątkiem od tej reguły jest sytuacja, gdy zostanie znaleziona krytyczna luka - bezpieczeństwa w obecnym algorytmie. + bezpieczeństwa w obecnie domyślnym algorytmie. @@ -290,14 +397,14 @@ Zalecany koszt znaleziony: 11 password_verify + password_needs_rehash crypt - implementacja użytkownika + sodium_crypto_pwhash_str - + @@ -10,13 +10,13 @@ &reftitle.description; - booleanpassword_needs_rehash + boolpassword_needs_rehash stringhash - integeralgorytm - arrayopcje + stringintnullalgo + arrayoptions[] - Ta funkcja sprawdza czy podany hash implementuje podany algorytm i opcje. + Ta funkcja sprawdza, czy podany hash implementuje podany algorytm i opcje. Jeżeli nie, przyjmuje się, że hash powinien zostać wygenerowany ponownie. @@ -33,7 +33,7 @@ - algorytm + algo &password.parameter.algo; @@ -41,7 +41,7 @@ - opcje + options &password.parameter.options; @@ -51,6 +51,40 @@ + + &reftitle.returnvalues; + + Zwraca &true; jeśli hash powinien zostać zahashowany ponownie, aby pasował do podanych argumentów + algo i options, &false; + w przeciwnym wypadku. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 7.4.0 + + Parametr algo oczekuje teraz typu &string;, ale wciąż przyjmuje + liczby (&integer;) ze względu na kompatybilność wsteczną. + + + + + + + + &reftitle.examples; @@ -63,16 +97,18 @@ $password = 'rasmuslerdorf'; $hash = '$2y$10$YCFsG6elYca568hBi2pZ0.3LDL5wjgxct1N8w/oLR/jfHsiQwCqTS'; -// Parametr cost może zmieniać się z czasem, wraz z poprawą sprzętu -$options = array('cost' => 11); +$algorithm = PASSWORD_BCRYPT; +// Parametr cost dla bcrypt może zmieniać się z czasem, wraz z poprawą sprzętu +$options = ['cost' => 12]; // Porównaj trzymany hash z hasłem w czystym tekście if (password_verify($password, $hash)) { - // Sprawdź czy jest dostępny nowszy algorytm hashujący - // lub czy zmienił się parametr cost - if (password_needs_rehash($hash, PASSWORD_DEFAULT, $options)) { + // Sprawdź czy zmienił się algorytm lub jego opcje + if (password_needs_rehash($hash, $algorithm, $options)) { // Jeśli tak, stwórz nowy hash i zamień stary - $newHash = password_hash($password, PASSWORD_DEFAULT, $options); + $newHash = password_hash($password, $algorithm, $options); + + // Zaktualizuj wiersz użytkownika używając wartości $newHash } // Zaloguj użytkownika @@ -83,15 +119,6 @@ if (password_verify($password, $hash)) { - - - &reftitle.returnvalues; - - Zwraca &true; jeżeli wymagany jest rehash, aby spełnić podany - algorytm i opcje lub &false; - w przeciwnym wypadku. - - - + password_verify @@ -10,12 +9,16 @@ &reftitle.description; - booleanpassword_verify - stringhasło + boolpassword_verify + #[\SensitiveParameter]stringpassword stringhash Weryfikuje czy podany hash pasuje do podanego hasła. + password_verify jest kompatybilna z crypt. + Dzięki temu hashe utworzone przez crypt mogą być użyte z + password_verify. + Zauważ że password_hash zwraca algorytm, koszt i sól jako @@ -62,11 +65,15 @@ Przykład użycia <function>password_verify</function> + + Jest to uproszczony przykład; zaleca się aby przehashować poprawne hasło, + jeśli jest to konieczne; zobacz funkcję password_needs_rehash, aby zobaczyć przykład. + + password_needs_rehash password_hash implementacja użytkownika + sodium_crypto_pwhash_str_verify - + - + &reftitle.setup;
&reftitle.required; &no.requirement; + + Hashowanie przy użyciu Argon2 wymaga jednakże libargon2. + Od PHP 7.3.0 wymagana jest biblioteka libargon2 w wersji 20161029 lub + nowszej. +
&reftitle.install; &no.install; + + Jednakże by włączyć wsparcie dla hashowania Argon2, PHP musi zostać skompilowane z obsługą + z libargon2 przy użyciu opcji konfiguracyjnej . + + + Przed PHP 8.1.0, określenie katalogu z argon2 było możliwe za pomocą + . +