From 37c22bd945f30a095abbf41da2507d9f740040a4 Mon Sep 17 00:00:00 2001 From: shyouhei Date: Mon, 3 Dec 2018 05:46:46 +0000 Subject: string.c: [DOC] deprecate String#crypt [ci skip] [Feature #14915] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@66154 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- string.c | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 54 insertions(+), 11 deletions(-) (limited to 'string.c') diff --git a/string.c b/string.c index 184d7df450..ea72c0be48 100644 --- a/string.c +++ b/string.c @@ -9223,17 +9223,60 @@ rb_str_oct(VALUE str) * call-seq: * str.crypt(salt_str) -> new_str * - * Applies a one-way cryptographic hash to str by invoking the - * standard library function crypt(3) with the given - * salt string. While the format and the result are system and - * implementation dependent, using a salt matching the regular - * expression \A[a-zA-Z0-9./]{2} should be valid and - * safe on any platform, in which only the first two characters are - * significant. - * - * This method is for use in system specific scripts, so if you want - * a cross-platform hash function consider using Digest or OpenSSL - * instead. + * Returns the string generated by calling crypt(3) + * standard library function with str and + * salt_str, in this order, as its arguments. Please do + * not use this method any longer. It is legacy; provided only for + * backward compatibility with ruby scripts in earlier days. It is + * bad to use in contemporary programs for several reasons: + * + * * Behaviour of C's crypt(3) depends on the OS it is + * run. The generated string lacks data portability. + * + * * On some OSes such as Mac OS, crypt(3) never fails + * (i.e. silently ends up in unexpected results). + * + * * On some OSes such as Mac OS, crypt(3) is not + * thread safe. + * + * * So-called "traditional" usage of crypt(3) is very + * very very weak. According to its manpage, Linux's traditional + * crypt(3) output has only 2**56 variations; too + * easy to blute force today. And this is the default behaviour. + * + * * In order to make things robust some OSes implement so-called + * "modular" usage. To go through, you have to do a complex + * build-up of the salt_str parameter, by hand. + * Failure in generation of a proper salt string tends not to + * yield any errors; typo in parameters are normally not + * detectable. + * + * * For instance, in the following example, second invocation + * of String#crypt is wrong; it has typo in + * "round=" (lacks "s"). However the call does not fail and + * something unexpected is generated. + * + * "foo".crypt("$5$rounds=1000$salt$") # OK, proper usage + * "foo".crypt("$5$round=1000$salt$") # Typo not detected + * + * * Even in the "modular" mode, some hash functions are considered + * archaic and no longer recommended at all; for instance module + * $1$ is officially abandoned by its author: see + * http://phk.freebsd.dk/sagas/md5crypt_eol.html . For another + * instance module $3$ is considered completely + * broken: see the manpage of FreeBSD. + * + * * On some OS such as Mac OS, there is no modular mode. Yet, as + * written above, crypt(3) on Mac OS never fails. + * This means even if you build up a proper salt string it + * generates a traditional DES hash anyways, and there is no way + * for you to be aware of. + * + * "foo".crypt("$5$rounds=1000$salt$") # => "$5fNPQMxC5j6." + * + * If for some reason you cannot migrate to other secure contemporary + * password hashing algorithms, install the string-crypt gem and + * requiire 'string/crypt' to continue using it. */ static VALUE -- cgit v1.2.3