scrypt 1.0.0

data/ext/mri/sha256.h

@@ -0,0 +1,62 @@
+/*-
+ * Copyright 2005,2007,2009 Colin Percival
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ *
+ * $FreeBSD: src/lib/libmd/sha256.h,v 1.2 2006/01/17 15:35:56 phk Exp $
+ */
+
+#ifndef _SHA256_H_
+#define _SHA256_H_
+
+#include <sys/types.h>
+
+#include <stdint.h>
+
+typedef struct SHA256Context {
+	uint32_t state[8];
+	uint32_t count[2];
+	unsigned char buf[64];
+} SHA256_CTX;
+
+typedef struct HMAC_SHA256Context {
+	SHA256_CTX ictx;
+	SHA256_CTX octx;
+} HMAC_SHA256_CTX;
+
+void	SHA256_Init(SHA256_CTX *);
+void	SHA256_Update(SHA256_CTX *, const void *, size_t);
+void	SHA256_Final(unsigned char [32], SHA256_CTX *);
+void	HMAC_SHA256_Init(HMAC_SHA256_CTX *, const void *, size_t);
+void	HMAC_SHA256_Update(HMAC_SHA256_CTX *, const void *, size_t);
+void	HMAC_SHA256_Final(unsigned char [32], HMAC_SHA256_CTX *);
+
+/**
+ * PBKDF2_SHA256(passwd, passwdlen, salt, saltlen, c, buf, dkLen):
+ * Compute PBKDF2(passwd, salt, c, dkLen) using HMAC-SHA256 as the PRF, and
+ * write the output to buf.  The value dkLen must be at most 32 * (2^32 - 1).
+ */
+void	PBKDF2_SHA256(const uint8_t *, size_t, const uint8_t *, size_t,
+    uint64_t, uint8_t *, size_t);
+
+#endif /* !_SHA256_H_ */

data/ext/mri/sysendian.h

@@ -0,0 +1,140 @@
+/*-
+ * Copyright 2007-2009 Colin Percival
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ *
+ * This file was originally written by Colin Percival as part of the Tarsnap
+ * online backup system.
+ */
+#ifndef _SYSENDIAN_H_
+#define _SYSENDIAN_H_
+
+#include "scrypt_platform.h"
+
+/* If we don't have be64enc, the <sys/endian.h> we have isn't usable. */
+#if !HAVE_DECL_BE64ENC
+#undef HAVE_SYS_ENDIAN_H
+#endif
+
+#ifdef HAVE_SYS_ENDIAN_H
+
+#include <sys/endian.h>
+
+#else
+
+#include <stdint.h>
+
+static inline uint32_t
+be32dec(const void *pp)
+{
+	const uint8_t *p = (uint8_t const *)pp;
+
+	return ((uint32_t)(p[3]) + ((uint32_t)(p[2]) << 8) +
+	    ((uint32_t)(p[1]) << 16) + ((uint32_t)(p[0]) << 24));
+}
+
+static inline void
+be32enc(void *pp, uint32_t x)
+{
+	uint8_t * p = (uint8_t *)pp;
+
+	p[3] = x & 0xff;
+	p[2] = (x >> 8) & 0xff;
+	p[1] = (x >> 16) & 0xff;
+	p[0] = (x >> 24) & 0xff;
+}
+
+static inline uint64_t
+be64dec(const void *pp)
+{
+	const uint8_t *p = (uint8_t const *)pp;
+
+	return ((uint64_t)(p[7]) + ((uint64_t)(p[6]) << 8) +
+	    ((uint64_t)(p[5]) << 16) + ((uint64_t)(p[4]) << 24) +
+	    ((uint64_t)(p[3]) << 32) + ((uint64_t)(p[2]) << 40) +
+	    ((uint64_t)(p[1]) << 48) + ((uint64_t)(p[0]) << 56));
+}
+
+static inline void
+be64enc(void *pp, uint64_t x)
+{
+	uint8_t * p = (uint8_t *)pp;
+
+	p[7] = x & 0xff;
+	p[6] = (x >> 8) & 0xff;
+	p[5] = (x >> 16) & 0xff;
+	p[4] = (x >> 24) & 0xff;
+	p[3] = (x >> 32) & 0xff;
+	p[2] = (x >> 40) & 0xff;
+	p[1] = (x >> 48) & 0xff;
+	p[0] = (x >> 56) & 0xff;
+}
+
+static inline uint32_t
+le32dec(const void *pp)
+{
+	const uint8_t *p = (uint8_t const *)pp;
+
+	return ((uint32_t)(p[0]) + ((uint32_t)(p[1]) << 8) +
+	    ((uint32_t)(p[2]) << 16) + ((uint32_t)(p[3]) << 24));
+}
+
+static inline void
+le32enc(void *pp, uint32_t x)
+{
+	uint8_t * p = (uint8_t *)pp;
+
+	p[0] = x & 0xff;
+	p[1] = (x >> 8) & 0xff;
+	p[2] = (x >> 16) & 0xff;
+	p[3] = (x >> 24) & 0xff;
+}
+
+static inline uint64_t
+le64dec(const void *pp)
+{
+	const uint8_t *p = (uint8_t const *)pp;
+
+	return ((uint64_t)(p[0]) + ((uint64_t)(p[1]) << 8) +
+	    ((uint64_t)(p[2]) << 16) + ((uint64_t)(p[3]) << 24) +
+	    ((uint64_t)(p[4]) << 32) + ((uint64_t)(p[5]) << 40) +
+	    ((uint64_t)(p[6]) << 48) + ((uint64_t)(p[7]) << 56));
+}
+
+static inline void
+le64enc(void *pp, uint64_t x)
+{
+	uint8_t * p = (uint8_t *)pp;
+
+	p[0] = x & 0xff;
+	p[1] = (x >> 8) & 0xff;
+	p[2] = (x >> 16) & 0xff;
+	p[3] = (x >> 24) & 0xff;
+	p[4] = (x >> 32) & 0xff;
+	p[5] = (x >> 40) & 0xff;
+	p[6] = (x >> 48) & 0xff;
+	p[7] = (x >> 56) & 0xff;
+}
+#endif /* !HAVE_SYS_ENDIAN_H */
+
+#endif /* !_SYSENDIAN_H_ */

data/lib/scrypt.rb

@@ -0,0 +1,171 @@
+# A wrapper for the scrypt algorithm.
+
+$LOAD_PATH.unshift(File.expand_path(File.join(File.dirname(__FILE__), "..", "ext", "mri")))
+require "scrypt_ext"
+require "openssl"
+require "digest/sha1"
+require "scanf"
+
+
+module SCrypt
+  module Errors
+    class InvalidSalt   < StandardError; end  # The salt parameter provided is invalid.
+    class InvalidHash   < StandardError; end  # The hash parameter provided is invalid.
+    class InvalidSecret < StandardError; end  # The secret parameter provided is invalid.
+  end
+
+  class Engine
+    DEFAULTS = { 
+      :max_mem => 1024 * 1024,
+      :max_memfrac => 0.5,
+      :max_time => 0.2
+    }
+
+    private_class_method :__sc_calibrate
+    private_class_method :__sc_crypt
+
+    # Given a secret and a valid salt (see SCrypt::Engine.generate_salt) calculates an scrypt password hash.
+    def self.hash_secret(secret, salt)
+      if valid_secret?(secret)
+        if valid_salt?(salt)
+          cost = autodetect_cost(salt)
+          salt + "$" + Digest::SHA1.hexdigest(__sc_crypt(secret.to_s, salt, cost))
+        else
+          raise Errors::InvalidSalt.new("invalid salt")
+        end
+      else
+        raise Errors::InvalidSecret.new("invalid secret")
+      end
+    end
+
+    # Generates a random salt with a given computational cost.
+    def self.generate_salt(options = {})
+      options = DEFAULTS.merge(options)
+      cost = calibrate(options)
+      salt = Digest::SHA1.hexdigest(OpenSSL::Random.random_bytes(32))
+      cost + salt
+    end
+
+    # Returns true if +cost+ is a valid cost, false if not.
+    def self.valid_cost?(cost)
+      cost.match(/^[0-9a-z]+\$[0-9a-z]+\$[0-9a-z]+\$$/) != nil
+    end
+
+    # Returns true if +salt+ is a valid salt, false if not.
+    def self.valid_salt?(salt)
+      salt.match(/^[0-9a-z]+\$[0-9a-z]+\$[0-9a-z]+\$[A-Za-z0-9]{20,}$/) != nil
+    end
+
+    # Returns true if +secret+ is a valid secret, false if not.
+    def self.valid_secret?(secret)
+      secret.respond_to?(:to_s)
+    end
+
+    # Returns the cost value which will result in computation limits less than the given options.
+    #
+    # Example:
+    #
+    #   # should take less than 200ms
+    #   SCrypt.calibrate(:max_time => 0.2)
+    #
+    #   # should take less than 1000ms
+    #   SCrypt.calibrate(:max_time => 1)
+    #
+    def self.calibrate(options = {})
+      options = DEFAULTS.merge(options)
+      __sc_calibrate(options[:max_mem], options[:max_memfrac], options[:max_time])
+    end
+    
+    # Computes the memory use of the given +cost+
+    def self.memory_use(cost)
+      n, r, p = cost.scanf("%x$%x$%x$")
+      (128 * r * p) + (256 * r) + (128 * r * n);
+    end
+
+    # Autodetects the cost from the salt string.
+    def self.autodetect_cost(salt)
+      salt[/^[0-9a-z]+\$[0-9a-z]+\$[0-9a-z]+\$/]
+    end
+  end
+
+  # A password management class which allows you to safely store users' passwords and compare them.
+  #
+  # Example usage:
+  #
+  #   include "scrypt"
+  #
+  #   # hash a user's password
+  #   @password = Password.create("my grand secret")
+  #   @password #=> "2000$8$1$f5f2fa5fe5484a7091f1299768fbe92b5a7fbc77$6a385f22c54d92c314b71a4fd5ef33967c93d679"
+  #
+  #   # store it safely
+  #   @user.update_attribute(:password, @password)
+  #
+  #   # read it back
+  #   @user.reload!
+  #   @db_password = Password.new(@user.password)
+  #
+  #   # compare it after retrieval
+  #   @db_password == "my grand secret" #=> true
+  #   @db_password == "a paltry guess"  #=> false
+  #
+  class Password < String
+    # The hash portion of the stored password hash.
+    attr_reader :hash
+    # The salt of the store password hash
+    attr_reader :salt
+    # The cost factor used to create the hash.
+    attr_reader :cost
+
+    class << self
+      # Hashes a secret, returning a SCrypt::Password instance. 
+      # Takes three options (optional), which will determine the cost limits of the computation.
+      # <tt>:max_time</tt> specifies the maximum number of seconds the computation should take.
+      # <tt>:max_mem</tt> specifies the maximum number of bytes the computation should take. A value of 0 specifies no upper limit. The minimum is always 1 MB.
+      # <tt>:max_memfrac</tt> specifies the maximum memory in a fraction of available resources to use. Any value equal to 0 or greater than 0.5 will result in 0.5 being used.
+      # The scrypt key derivation function is designed to be far more secure against hardware brute-force attacks than alternative functions such as PBKDF2 or bcrypt.
+      # The designers of scrypt estimate that on modern (2009) hardware, if 5 seconds are spent computing a derived key, the cost of a hardware brute-force attack against scrypt is roughly 4000 times greater than the cost of a similar attack against bcrypt (to find the same password), and 20000 times greater than a similar attack against PBKDF2.
+      # Default options will result in calculation time of approx. 200 ms with 1 MB memory use.
+      #
+      # Example:
+      #   @password = SCrypt::Password.create("my secret", :max_time => 0.25)
+      def create(secret, options = {})
+        options = SCrypt::Engine::DEFAULTS.merge(options)
+        salt = SCrypt::Engine.generate_salt(options)
+        hash = SCrypt::Engine.hash_secret(secret, salt)
+        Password.new(hash)
+      end
+    end
+
+    # Initializes a SCrypt::Password instance with the data from a stored hash.
+    def initialize(raw_hash)
+      if valid_hash?(raw_hash)
+        self.replace(raw_hash)
+        @cost, @salt, @hash = split_hash(self.to_s)
+      else
+        raise Errors::InvalidHash.new("invalid hash")
+      end
+    end
+
+    # Compares a potential secret against the hash. Returns true if the secret is the original secret, false otherwise.
+    def ==(secret)
+      super(SCrypt::Engine.hash_secret(secret, @cost + @salt))
+    end
+    alias_method :is_password?, :==
+
+  private
+    # Returns true if +h+ is a valid hash.
+    def valid_hash?(h)
+      h.match(/^[0-9a-z]+\$[0-9a-z]+\$[0-9a-z]+\$[A-Za-z0-9]{20,}\$[A-Za-z0-9]{20,}$/) != nil
+    end
+
+    # call-seq:
+    #   split_hash(raw_hash) -> cost, salt, hash
+    #
+    # Splits +h+ into cost, salt, and hash and returns them in that order.
+    def split_hash(h)
+      n, v, r, salt, hash = h.split('$')
+      return [n, v, r].join('$') + "$", salt, hash
+    end
+  end
+end

data/lib/scrypt/version.rb

@@ -0,0 +1,3 @@
+module SCrypt
+  VERSION = "1.0.0"
+end

data/scrypt.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "scrypt/version"
+
+Gem::Specification.new do |s|
+  s.name        = "scrypt"
+  s.version     = SCrypt::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Patrick Hogan"]
+  s.email       = ["pbhogan@gmail.com"]
+  s.homepage    = ""
+  s.summary     = "scrypt password hashing algorithm."
+  s.description = <<-EOF
+    The scrypt key derivation function is designed to be far 
+    more secure against hardware brute-force attacks than 
+    alternative functions such as PBKDF2 or bcrypt.
+  EOF
+
+  s.rubyforge_project = "scrypt"
+
+  s.extensions = ["ext/mri/extconf.rb"]
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/spec/scrypt/engine_spec.rb

@@ -0,0 +1,58 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "spec_helper"))
+
+describe "The SCrypt engine" do
+  it "should calculate a valid cost factor" do
+    first = SCrypt::Engine.calibrate(:max_time => 0.2)
+    SCrypt::Engine.valid_cost?(first).should == true
+  end
+end
+
+describe "Generating SCrypt salts" do
+
+  it "should produce strings" do
+    SCrypt::Engine.generate_salt.should be_an_instance_of(String)
+  end
+
+  it "should produce random data" do
+    SCrypt::Engine.generate_salt.should_not equal(SCrypt::Engine.generate_salt)
+  end
+
+end
+
+describe "Autodetecting of salt cost" do
+
+  it "should work" do
+    SCrypt::Engine.autodetect_cost("2a$08$c3$randomjunkgoeshere").should == "2a$08$c3$"
+  end
+
+end
+
+describe "Generating SCrypt hashes" do
+
+  class MyInvalidSecret
+    undef to_s
+  end
+
+  before :each do
+    @salt = SCrypt::Engine.generate_salt()
+    @password = "woo"
+  end
+
+  it "should produce a string" do
+    SCrypt::Engine.hash_secret(@password, @salt).should be_an_instance_of(String)
+  end
+
+  it "should raise an InvalidSalt error if the salt is invalid" do
+    lambda { SCrypt::Engine.hash_secret(@password, 'nino') }.should raise_error(SCrypt::Errors::InvalidSalt)
+  end
+
+  it "should raise an InvalidSecret error if the secret is invalid" do
+    lambda { SCrypt::Engine.hash_secret(MyInvalidSecret.new, @salt) }.should raise_error(SCrypt::Errors::InvalidSecret)
+    lambda { SCrypt::Engine.hash_secret(nil, @salt) }.should_not raise_error(SCrypt::Errors::InvalidSecret)
+    lambda { SCrypt::Engine.hash_secret(false, @salt) }.should_not raise_error(SCrypt::Errors::InvalidSecret)
+  end
+
+  it "should call #to_s on the secret and use the return value as the actual secret data" do
+    SCrypt::Engine.hash_secret(false, @salt).should == SCrypt::Engine.hash_secret("false", @salt)
+  end
+end