U:RDoc::NormalModule[iI"KDF:ETI"OpenSSL::KDF;T0o:RDoc::Markup::Document:@parts[o;;[o:RDoc::Markup::Paragraph;[I"FProvides functionality of various KDFs (key derivation function).;To:RDoc::Markup::BlankLineo;	;[
I"LKDF is typically used for securely deriving arbitrary length symmetric ;TI"Nkeys to be used with an OpenSSL::Cipher from passwords. Another use case ;TI"Iis for storing passwords: Due to the ability to tweak the effort of ;TI"Ncomputation by increasing the iteration count, computation can be slowed ;TI"Fdown artificially in order to render possible attacks infeasible.;T@o;	;[I"LCurrently, OpenSSL::KDF provides implementations for the following KDF:;T@o:RDoc::Markup::List:
@type:BULLET:@items[o:RDoc::Markup::ListItem:@label0;[o;	;[I"BPKCS #5 PBKDF2 (Password-Based Key Derivation Function 2) in ;TI"combination with HMAC;To;;0;[o;	;[I"scrypt;To;;0;[o;	;[I"	HKDF;T@S:RDoc::Markup::Heading:
leveli:	textI"
Examples;TS;;i;I"5Generating a 128 bit key for a Cipher (e.g. AES);To:RDoc::Markup::Verbatim;[I"pass = "secret"
;TI"-salt = OpenSSL::Random.random_bytes(16)
;TI"iter = 20_000
;TI"key_len = 16
;TI"Hkey = OpenSSL::KDF.pbkdf2_hmac(pass, salt: salt, iterations: iter,
;TI"C                               length: key_len, hash: "sha1")
;T:@format0S;;i;I"Storing Passwords;To;;[I"pass = "secret"
;TI"+# store this with the generated value
;TI"-salt = OpenSSL::Random.random_bytes(16)
;TI"iter = 20_000
;TI"(hash = OpenSSL::Digest::SHA256.new
;TI"len = hash.digest_length
;TI"$# the final value to be stored
;TI"Jvalue = OpenSSL::KDF.pbkdf2_hmac(pass, salt: salt, iterations: iter,
;TI"?                                 length: len, hash: hash)
;T;0S;;i;I")Important Note on Checking Passwords;To;	;[I"JWhen comparing passwords provided by the user with previously stored ;TI"Kvalues, a common mistake made is comparing the two values using "==". ;TI"DTypically, "==" short-circuits on evaluation, and is therefore ;TI"Jvulnerable to timing attacks. The proper way is to use a method that ;TI"Jalways takes the same amount of time when comparing two values, thus ;TI"Hnot leaking any information to potential attackers. To compare two ;TI")values, the following could be used:;T@o;;[I"def eql_time_cmp(a, b)
;TI"#  unless a.length == b.length
;TI"    return false
;TI"  end
;TI"  cmp = b.bytes
;TI"  result = 0
;TI"&  a.bytes.each_with_index {|c,i|
;TI"    result |= c ^ cmp[i]
;TI"	  }
;TI"  result == 0
;TI"	end
;T;0o;	;[I"HPlease note that the premature return in case of differing lengths ;TI"Ktypically does not leak valuable information - when using PBKDF2, the ;TI":length of the values to be compared is of fixed size.;T:
@fileI"ext/openssl/ossl_kdf.c;T:0@omit_headings_from_table_of_contents_below0;0;0[[[[[I"
class;T[[:public[[I"	hkdf;TI")../ruby-2.7.7/ext/openssl/ossl_kdf.c;T[I"pbkdf2_hmac;T@o[I"scrypt;T@o[:protected[[:private[[I"
instance;T[[;[[;[[;[[[U:RDoc::Context::Section[i0o;;[;0;0[I"ext/openssl/ossl.c;TI"OpenSSL;TcRDoc::NormalModule