module OpenSSL::PKCS5

Provides password-based encryption functionality based on PKCS#5. Typically used for securely deriving arbitrary length symmetric keys to be used with an OpenSSL::Cipher from passwords. Another use case is for storing passwords: Due to the ability to tweak the effort of computation by increasing the iteration count, computation can be slowed down artificially in order to render possible attacks infeasible.

PKCS5 offers support for PBKDF2 with an OpenSSL::Digest::SHA1-based HMAC, or an arbitrary Digest if the underlying version of OpenSSL already supports it (>= 0.9.4).

Parameters

Password

Typically an arbitrary String that represents the password to be used for deriving a key.

Salt

Prevents attacks based on dictionaries of common passwords. It is a public value that can be safely stored along with the password (e.g. if PBKDF2 is used for password storage). For maximum security, a fresh, random salt should be generated for each stored password. According to PKCS#5, a salt should be at least 8 bytes long.

Iteration Count

Allows to tweak the length that the actual computation will take. The larger the iteration count, the longer it will take.

Key Length

Specifies the length in bytes of the output that will be generated. Typically, the key length should be larger than or equal to the output length of the underlying digest function, otherwise an attacker could simply try to brute-force the key. According to PKCS#5, security is limited by the output length of the underlying digest function, i.e. security is not improved if a key length strictly larger than the digest output length is chosen. Therefore, when using PKCS5 for password storage, it suffices to store values equal to the digest output length, nothing is gained by storing larger values.

Examples

Generating a 128 bit key for a Cipher (e.g. AES)

pass = "secret"
salt = OpenSSL::Random.random_bytes(16)
iter = 20000
key_len = 16
key = OpenSSL::PKCS5.pbkdf2_hmac_sha1(pass, salt, iter, key_len)

Storing Passwords

pass = "secret"
salt = OpenSSL::Random.random_bytes(16) #store this with the generated value
iter = 20000
digest = OpenSSL::Digest::SHA256.new
len = digest.digest_length
#the final value to be stored
value = OpenSSL::PKCS5.pbkdf2_hmac(pass, salt, iter, len, digest)

Important Note on Checking Passwords

When comparing passwords provided by the user with previously stored values, a common mistake made is comparing the two values using “==”. Typically, “==” short-circuits on evaluation, and is therefore vulnerable to timing attacks. The proper way is to use a method that always takes the same amount of time when comparing two values, thus not leaking any information to potential attackers. To compare two values, the following could be used:

def eql_time_cmp(a, b)
  unless a.length == b.length
    return false
  end
  cmp = b.bytes.to_a
  result = 0
  a.bytes.each_with_index {|c,i|
    result |= c ^ cmp[i]
  }
  result == 0
end

Please note that the premature return in case of differing lengths typically does not leak valuable information - when using PKCS#5, the length of the values to be compared is of fixed size.