diff options
author | shyouhei <shyouhei@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2018-12-03 05:46:46 +0000 |
---|---|---|
committer | shyouhei <shyouhei@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2018-12-03 05:46:46 +0000 |
commit | 37c22bd945f30a095abbf41da2507d9f740040a4 (patch) | |
tree | 5a24523e78fa14a354c0dccd35d56181d0df56cd /string.c | |
parent | fb0009cfdc203247f808f4dcd72c7baf272172ce (diff) | |
download | ruby-37c22bd945f30a095abbf41da2507d9f740040a4.tar.gz |
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
Diffstat (limited to 'string.c')
-rw-r--r-- | string.c | 65 |
1 files changed, 54 insertions, 11 deletions
@@ -9223,17 +9223,60 @@ rb_str_oct(VALUE str) * call-seq: * str.crypt(salt_str) -> new_str * - * Applies a one-way cryptographic hash to <i>str</i> by invoking the - * standard library function <code>crypt(3)</code> with the given - * salt string. While the format and the result are system and - * implementation dependent, using a salt matching the regular - * expression <code>\A[a-zA-Z0-9./]{2}</code> 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 <code>crypt(3)</code> + * standard library function with <code>str</code> and + * <code>salt_str</code>, 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 <code>crypt(3)</code> depends on the OS it is + * run. The generated string lacks data portability. + * + * * On some OSes such as Mac OS, <code>crypt(3)</code> never fails + * (i.e. silently ends up in unexpected results). + * + * * On some OSes such as Mac OS, <code>crypt(3)</code> is not + * thread safe. + * + * * So-called "traditional" usage of <code>crypt(3)</code> is very + * very very weak. According to its manpage, Linux's traditional + * <code>crypt(3)</code> 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 <code>salt_str</code> 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 <code>String#crypt</code> 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 + * <code>$1$</code> is officially abandoned by its author: see + * http://phk.freebsd.dk/sagas/md5crypt_eol.html . For another + * instance module <code>$3$</code> 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, <code>crypt(3)</code> 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 + * <code>requiire 'string/crypt'</code> to continue using it. */ static VALUE |