summaryrefslogtreecommitdiff
path: root/string.c
diff options
context:
space:
mode:
authorshyouhei <shyouhei@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2018-12-03 05:46:46 +0000
committershyouhei <shyouhei@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2018-12-03 05:46:46 +0000
commit37c22bd945f30a095abbf41da2507d9f740040a4 (patch)
tree5a24523e78fa14a354c0dccd35d56181d0df56cd /string.c
parentfb0009cfdc203247f808f4dcd72c7baf272172ce (diff)
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.c65
1 files changed, 54 insertions, 11 deletions
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 <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