Docs: crypto providers

Author: jaredbeck

UPGRADING.md

@@ -4,9 +4,11 @@ Supplemental instructions to complement CHANGELOG.md.
 
 ## 3.4.0
 
-In version 3.4.0, the default crypto_provider was changed from *Sha512* to *SCrypt*.
+In version 3.4.0, released 2014-03-03, the default crypto_provider was changed
+from *Sha512* to *SCrypt*.
 
-If you never set a crypto_provider and are upgrading, your passwords will break unless you set the original:
+If you never set a crypto_provider and are upgrading, your passwords will break
+unless you specify `Sha512`.
 
 ``` ruby
 c.crypto_provider = Authlogic::CryptoProviders::Sha512

lib/authlogic.rb

@@ -1,7 +1,9 @@
-# Authlogic uses ActiveSupport's core extensions like `strip_heredoc`, which
-# ActiveRecord does not `require`. It's possible that we could save a few
-# milliseconds by loading only the specific core extensions we need, but
-# `all.rb` is simpler. We can revisit this decision if it becomes a problem.
+# Authlogic uses ActiveSupport's core extensions like `strip_heredoc` and
+# `squish`. ActiveRecord does not `require` these exensions, so we must.
+#
+# It's possible that we could save a few milliseconds by loading only the
+# specific core extensions we need, but `all.rb` is simpler. We can revisit this
+# decision if it becomes a problem.
 require "active_support/all"
 
 require "active_record"

lib/authlogic/acts_as_authentic/password.rb

@@ -195,9 +195,18 @@ def merge_validates_length_of_password_confirmation_field_options(options = {})
             validates_length_of_password_confirmation_field_options.merge(options)
         end
 
-        # The class you want to use to encrypt and verify your encrypted passwords. See
-        # the Authlogic::CryptoProviders module for more info on the available methods and
-        # how to create your own.
+        # The class you want to use to encrypt and verify your encrypted
+        # passwords. See the Authlogic::CryptoProviders module for more info on
+        # the available methods and how to create your own.
+        #
+        # The family of adaptive hash functions (BCrypt, SCrypt, PBKDF2) is the
+        # best choice for password storage today. We recommend SCrypt. Other
+        # one-way functions like SHA512 are inferior, but widely used.
+        # Reverisbile functions like AES256 are the worst choice.
+        #
+        # You can use the `transition_from_crypto_providers` option to gradually
+        # transition to a better crypto provider without causing your users any
+        # pain.
         #
         # * <tt>Default:</tt> CryptoProviders::SCrypt
         # * <tt>Accepts:</tt> Class

lib/authlogic/crypto_providers.rb

@@ -1,4 +1,25 @@
 module Authlogic
+  # The acts_as_authentic method has a crypto_provider option. This allows you
+  # to use any type of encryption you like. Just create a class with a class
+  # level encrypt and matches? method. See example below.
+  #
+  # === Example
+  #
+  #   class MyAwesomeEncryptionMethod
+  #     def self.encrypt(*tokens)
+  #       # The tokens passed will be an array of objects, what type of object
+  #       # is irrelevant, just do what you need to do with them and return a
+  #       # single encrypted string. For example, you will most likely join all
+  #       # of the objects into a single string and then encrypt that string.
+  #     end
+  #
+  #     def self.matches?(crypted, *tokens)
+  #       # Return true if the crypted string matches the tokens. Depending on
+  #       # your algorithm you might decrypt the string then compare it to the
+  #       # token, or you might encrypt the tokens and make sure it matches the
+  #       # crypted string, its up to you.
+  #     end
+  #   end
   module CryptoProviders
     autoload :MD5,    "authlogic/crypto_providers/md5"
     autoload :Sha1,   "authlogic/crypto_providers/sha1"

lib/authlogic/crypto_providers/aes256.rb

@@ -2,21 +2,23 @@
 
 module Authlogic
   module CryptoProviders
-    # This encryption method is reversible if you have the supplied key. So in order to
-    # use this encryption method you must supply it with a key first. In an initializer,
-    # or before your application initializes, you should do the following:
+    # This encryption method is reversible if you have the supplied key. So in
+    # order to use this encryption method you must supply it with a key first.
+    # In an initializer, or before your application initializes, you should do
+    # the following:
     #
     #   Authlogic::CryptoProviders::AES256.key = "long, unique, and random key"
     #
-    # My final comment is that this is a strong encryption method, but its main weakness
-    # is that it's reversible. If you do not need to reverse the hash then you should
-    # consider Sha512 or BCrypt instead.
+    # My final comment is that this is a strong encryption method, but its main
+    # weakness is that it's reversible. If you do not need to reverse the hash
+    # then you should consider Sha512 or BCrypt instead.
     #
-    # Keep your key in a safe place, some even say the key should be stored on a separate
-    # server. This won't hurt performance because the only time it will try and access the
-    # key on the separate server is during initialization, which only happens once. The
-    # reasoning behind this is if someone does compromise your server they won't have the
-    # key also. Basically, you don't want to store the key with the lock.
+    # Keep your key in a safe place, some even say the key should be stored on a
+    # separate server. This won't hurt performance because the only time it will
+    # try and access the key on the separate server is during initialization,
+    # which only happens once. The reasoning behind this is if someone does
+    # compromise your server they won't have the key also. Basically, you don't
+    # want to store the key with the lock.
     class AES256
       class << self
         attr_writer :key
@@ -53,6 +55,9 @@ def aes
         # (https://github.com/ruby/openssl/commit/5c20a4c014) when openssl
         # became a gem. Its first release as a gem was 2.0.0, in ruby 2.4.
         # (See https://github.com/ruby/ruby/blob/v2_4_0/NEWS)
+        #
+        # When we eventually drop support for ruby < 2.4, we can probably also
+        # drop support for openssl gem < 2.
         def openssl_cipher_class
           if ::Gem::Version.new(::OpenSSL::VERSION) < ::Gem::Version.new("2.0.0")
             ::OpenSSL::Cipher::Cipher

lib/authlogic/crypto_providers/sha1.rb

@@ -2,18 +2,19 @@
 
 module Authlogic
   module CryptoProviders
-    # This class was made for the users transitioning from restful_authentication. I
-    # highly discourage using this crypto provider as it is far inferior to your other
-    # options. Please use any other provider offered by Authlogic.
+    # This class was made for the users transitioning from
+    # restful_authentication. Use of this crypto provider is highly discouraged.
+    # It is far inferior to your other options. Please use any other provider
+    # offered by Authlogic.
     class Sha1
       class << self
         def join_token
           @join_token ||= "--"
         end
         attr_writer :join_token
 
-        # The number of times to loop through the encryption. This is ten because that is
-        # what restful_authentication defaults to.
+        # The number of times to loop through the encryption. This is ten
+        # because that is what restful_authentication defaults to.
         def stretches
           @stretches ||= 10
         end
@@ -29,8 +30,8 @@ def encrypt(*tokens)
           digest
         end
 
-        # Does the crypted password match the tokens? Uses the same tokens that were used
-        # to encrypt.
+        # Does the crypted password match the tokens? Uses the same tokens that
+        # were used to encrypt.
         def matches?(crypted, *tokens)
           encrypt(*tokens) == crypted
         end

lib/authlogic/crypto_providers/sha512.rb

@@ -1,27 +1,6 @@
 require "digest/sha2"
 
 module Authlogic
-  # The acts_as_authentic method has a crypto_provider option. This allows you
-  # to use any type of encryption you like. Just create a class with a class
-  # level encrypt and matches? method. See example below.
-  #
-  # === Example
-  #
-  #   class MyAwesomeEncryptionMethod
-  #     def self.encrypt(*tokens)
-  #       # The tokens passed will be an array of objects, what type of object
-  #       # is irrelevant, just do what you need to do with them and return a
-  #       # single encrypted string. For example, you will most likely join all
-  #       # of the objects into a single string and then encrypt that string.
-  #     end
-  #
-  #     def self.matches?(crypted, *tokens)
-  #       # Return true if the crypted string matches the tokens. Depending on
-  #       # your algorithm you might decrypt the string then compare it to the
-  #       # token, or you might encrypt the tokens and make sure it matches the
-  #       # crypted string, its up to you.
-  #     end
-  #   end
   module CryptoProviders
     # = Sha512
     #