File Manager

Editing 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

Back to Directory File Manager