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

NEWS

@@ -281,6 +281,8 @@ sufficient information, see the ChangeLog file or Redmine
 
 [String]
 
+  * String#crypt is now deprecated. [Feature #14915]
+
   [New features]
 
     * String#split yields each substring to the block if given. [Feature #4780]

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.
+ *  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:
  *
- *  This method is for use in system specific scripts, so if you want
- *  a cross-platform hash function consider using Digest or OpenSSL
- *  instead.
+ *    * 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