Current File : //opt/cpanel/ea-ruby24/root/usr/share/ri/system/OpenSSL/PKCS5/cdesc-PKCS5.ri
U:RDoc::NormalModule[iI"
PKCS5:ETI"OpenSSL::PKCS5;T0o:RDoc::Markup::Document: @parts[o;;[ o: RDoc::Markup::Paragraph;[ I"GProvides password-based encryption functionality based on PKCS#5. ;TI"JTypically used for securely deriving arbitrary length symmetric keys ;TI"Ito 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"Gcomputation by increasing the iteration count, computation can be ;TI"Mslowed down artificially in order to render possible attacks infeasible.;To: RDoc::Markup::BlankLine o; ;[I"IPKCS5 offers support for PBKDF2 with an OpenSSL::Digest::SHA1-based ;TI"GHMAC, or an arbitrary Digest if the underlying version of OpenSSL ;TI"$already supports it (>= 1.0.0).;T@S:RDoc::Markup::Heading:
leveli: textI"Parameters;TS; ; i ;
I"
Password;To; ;[I"KTypically an arbitrary String that represents the password to be used ;TI"for deriving a key.;TS; ; i ;
I" Salt;To; ;[
I"IPrevents attacks based on dictionaries of common passwords. It is a ;TI"Jpublic value that can be safely stored along with the password (e.g. ;TI"Mif PBKDF2 is used for password storage). For maximum security, a fresh, ;TI"Irandom salt should be generated for each stored password. According ;TI"7to PKCS#5, a salt should be at least 8 bytes long.;TS; ; i ;
I"Iteration Count;To; ;[I"KAllows to tweak the length that the actual computation will take. The ;TI"9larger the iteration count, the longer it will take.;TS; ; i ;
I"Key Length;To; ;[I"ISpecifies the length in bytes of the output that will be generated. ;TI"LTypically, the key length should be larger than or equal to the output ;TI"Klength of the underlying digest function, otherwise an attacker could ;TI"Isimply try to brute-force the key. According to PKCS#5, security is ;TI"Jlimited by the output length of the underlying digest function, i.e. ;TI"Gsecurity is not improved if a key length strictly larger than the ;TI"Edigest output length is chosen. Therefore, when using PKCS5 for ;TI"Gpassword storage, it suffices to store values equal to the digest ;TI"?output length, nothing is gained by storing larger values.;T@S; ; i;
I"
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 = 20000
;TI"key_len = 16
;TI"Fkey = OpenSSL::PKCS5.pbkdf2_hmac_sha1(pass, salt, iter, key_len)
;T: @format0S; ; i;
I"Storing Passwords;To;;[ I"pass = "secret"
;TI"Rsalt = OpenSSL::Random.random_bytes(16) #store this with the generated value
;TI"iter = 20000
;TI"*digest = OpenSSL::Digest::SHA256.new
;TI" len = digest.digest_length
;TI"##the final value to be stored
;TI"Gvalue = OpenSSL::PKCS5.pbkdf2_hmac(pass, salt, iter, len, digest)
;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:;To;;[I" def eql_time_cmp(a, b)
;TI"# unless a.length == b.length
;TI" return false
;TI" end
;TI" cmp = b.bytes.to_a
;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 PKCS#5, the ;TI":length of the values to be compared is of fixed size.;T:
@fileI" ext/openssl/ossl_pkcs5.c;T:0@omit_headings_from_table_of_contents_below0;0;0[ [ [ [[I"
class;T[[: public[[I"pbkdf2_hmac;TI" ext/openssl/ossl_pkcs5.c;T[I"pbkdf2_hmac_sha1;T@~[:protected[ [: private[ [I"
instance;T[[;[ [;[ [;[ [ [U:RDoc::Context::Section[i 0o;;[ ;0;0[I"ext/openssl/ossl.c;TI" OpenSSL;FcRDoc::NormalModule
Mini Shell