✏️ Editing: cdesc-Cipher.ri Read Only

U:RDoc::NormalClass[iI"Cipher:ETI"OpenSSL::Cipher;TI"Object;To:RDoc::Markup::Document:@parts[o;;[�:
@fileI"&ext/openssl/lib/openssl/cipher.rb;T:0@omit_headings_from_table_of_contents_below0o;;[So:RDoc::Markup::Paragraph;[I"FProvides symmetric algorithms for encryption and decryption. The ;TI"Dalgorithms that are available depend on the particular version ;TI""of OpenSSL that is installed.;To:RDoc::Markup::BlankLine�S:RDoc::Markup::Heading:
leveli:	textI"%Listing all supported algorithms;T@o;;[I"6A list of supported algorithms can be obtained by;T@o:RDoc::Markup::Verbatim;[I""puts OpenSSL::Cipher.ciphers
;T:@format0S;
;i;I"Instantiating a Cipher;T@o;;[	I"FThere are several ways to create a Cipher instance. Generally, a ;TI"ICipher algorithm is categorized by its name, the key length in bits ;TI"Fand the cipher mode to be used. The most generic way to create a ;TI"Cipher is the following;T@o;;[I"@cipher = OpenSSL::Cipher.new('<name>-<key length>-<mode>')
;T;0o;;[I"IThat is, a string consisting of the hyphenated concatenation of the ;TI"Kindividual components name, key length and mode. Either all uppercase ;TI"7or all lowercase strings may be used, for example:;T@o;;[I"1cipher = OpenSSL::Cipher.new('AES-128-CBC')
;T;0o;;[I"FFor each algorithm supported, there is a class defined under the ;TI"ICipher class that goes by the name of the cipher, e.g. to obtain an ;TI"(instance of AES, you could also use;T@o;;[	I"# these are equivalent
;TI"2cipher = OpenSSL::Cipher::AES.new(128, :CBC)
;TI"3cipher = OpenSSL::Cipher::AES.new(128, 'CBC')
;TI"2cipher = OpenSSL::Cipher::AES.new('128-CBC')
;T;0o;;[I"GFinally, due to its wide-spread use, there are also extra classes ;TI"/defined for the different key sizes of AES;T@o;;[I"0cipher = OpenSSL::Cipher::AES128.new(:CBC)
;TI"0cipher = OpenSSL::Cipher::AES192.new(:CBC)
;TI"0cipher = OpenSSL::Cipher::AES256.new(:CBC)
;T;0S;
;i;I"2Choosing either encryption or decryption mode;T@o;;[I"EEncryption and decryption are often very similar operations for ;TI"Esymmetric algorithms, this is reflected by not having to choose ;TI"Hdifferent classes for either operation, both can be done using the ;TI"Fsame class. Still, after obtaining a Cipher instance, we need to ;TI"Ftell the instance what it is that we intend to do with it, so we ;TI"need to call either;T@o;;[I"cipher.encrypt
;T;0o;;[I"or;T@o;;[I"cipher.decrypt
;T;0o;;[I"Jon the Cipher instance. This should be the first call after creating ;TI"Kthe instance, otherwise configuration that has already been set could ;TI"get lost in the process.;T@S;
;i;I"Choosing a key;T@o;;[I"MSymmetric encryption requires a key that is the same for the encrypting ;TI"Mand for the decrypting party and after initial key establishment should ;TI"Gbe kept as private information. There are a lot of ways to create ;TI"Minsecure keys, the most notable is to simply take a password as the key ;TI"Iwithout processing the password further. A simple and secure way to ;TI",create a key for a particular Cipher is;T@o;;[I"(cipher = OpenSSL::AES256.new(:CFB)
;TI"cipher.encrypt
;TI"Ikey = cipher.random_key # also sets the generated key on the Cipher
;T;0o;;[	I"EIf you absolutely need to use passwords as encryption keys, you ;TI"Eshould use Password-Based Key Derivation Function 2 (PBKDF2) by ;TI"Ggenerating the key with the help of the functionality provided by ;TI"COpenSSL::PKCS5.pbkdf2_hmac_sha1 or OpenSSL::PKCS5.pbkdf2_hmac.;T@o;;[I"HAlthough there is Cipher#pkcs5_keyivgen, its use is deprecated and ;TI"Kit should only be used in legacy applications because it does not use ;TI"$the newer PKCS#5 v2 algorithms.;T@S;
;i;I"Choosing an IV;T@o;;[
I"HThe cipher modes CBC, CFB, OFB and CTR all need an "initialization ;TI"Lvector", or short, IV. ECB mode is the only mode that does not require ;TI"Ean IV, but there is almost no legitimate use case for this mode ;TI"Fbecause of the fact that it does not sufficiently hide plaintext ;TI"patterns. Therefore;T@o;;[I"J<b>You should never use ECB mode unless you are absolutely sure that ;TI"you absolutely need it</b>;T@o;;[
I"KBecause of this, you will end up with a mode that explicitly requires ;TI"Kan IV in any case. Although the IV can be seen as public information, ;TI"Ji.e. it may be transmitted in public once generated, it should still ;TI"Hstay unpredictable to prevent certain kinds of attacks. Therefore, ;TI"ideally;T@o;;[I"F<b>Always create a secure random IV for every encryption of your ;TI"Cipher</b>;T@o;;[I"LA new, random IV should be created for every encryption of data. Think ;TI"Jof the IV as a nonce (number used once) - it's public but random and ;TI"@unpredictable. A secure random IV can be created as follows;T@o;;[	I"cipher = ...
;TI"cipher.encrypt
;TI"key = cipher.random_key
;TI"Fiv = cipher.random_iv # also sets the generated IV on the Cipher
;T;0o;;[
I"KAlthough the key is generally a random value, too, it is a bad choice ;TI"Kas an IV. There are elaborate ways how an attacker can take advantage ;TI"Jof such an IV. As a general rule of thumb, exposing the key directly ;TI"Hor indirectly should be avoided at all cost and exceptions only be ;TI"made with good reason.;T@S;
;i;I"Calling Cipher#final;T@o;;[
I"HECB (which should not be used) and CBC are both block-based modes. ;TI"FThis means that unlike for the other streaming-based modes, they ;TI"Hoperate on fixed-size blocks of data, and therefore they require a ;TI"K"finalization" step to produce or correctly decrypt the last block of ;TI"Jdata by appropriately handling some form of padding. Therefore it is ;TI"Bessential to add the output of OpenSSL::Cipher#final to your ;TI"Lencryption/decryption buffer or you will end up with decryption errors ;TI"or truncated data.;T@o;;[	I"MAlthough this is not really necessary for streaming-mode ciphers, it is ;TI"Istill recommended to apply the same pattern of adding the output of ;TI"HCipher#final there as well - it also enables you to switch between ;TI"%modes more easily in the future.;T@S;
;i;I"(Encrypting and decrypting some data;T@o;;[I"+data = "Very, very confidential data"
;TI"
;TI"2cipher = OpenSSL::Cipher::AES.new(128, :CBC)
;TI"cipher.encrypt
;TI"key = cipher.random_key
;TI"iv = cipher.random_iv
;TI"
;TI"4encrypted = cipher.update(data) + cipher.final
;TI"	...
;TI"4decipher = OpenSSL::Cipher::AES.new(128, :CBC)
;TI"decipher.decrypt
;TI"decipher.key = key
;TI"decipher.iv = iv
;TI"
;TI"9plain = decipher.update(encrypted) + decipher.final
;TI"
;TI"!puts data == plain #=> true
;T;0S;
;i;I"8Authenticated Encryption and Associated Data (AEAD);T@o;;[I"JIf the OpenSSL version used supports it, an Authenticated Encryption ;TI"Cmode (such as GCM or CCM) should always be preferred over any ;TI"Nunauthenticated mode. Currently, OpenSSL supports AE only in combination ;TI"Nwith Associated Data (AEAD) where additional associated data is included ;TI"Nin the encryption process to compute a tag at the end of the encryption. ;TI"KThis tag will also be used in the decryption process and by verifying ;TI"Iits validity, the authenticity of a given ciphertext is established.;T@o;;[
I"KThis is superior to unauthenticated modes in that it allows to detect ;TI"Fif somebody effectively changed the ciphertext after it had been ;TI"Mencrypted. This prevents malicious modifications of the ciphertext that ;TI"Ncould otherwise be exploited to modify ciphertexts in ways beneficial to ;TI"potential attackers.;T@o;;[
I"OAn associated data is used where there is additional information, such as ;TI"Gheaders or some metadata, that must be also authenticated but not ;TI"Knecessarily need to be encrypted. If no associated data is needed for ;TI"Kencryption and later decryption, the OpenSSL library still requires a ;TI"@value to be set - "" may be used in case none is available.;T@o;;[	I"NAn example using the GCM (Galois/Counter Mode). You have 16 bytes _key_, ;TI"M12 bytes (96 bits) _nonce_ and the associated data _auth_data_. Be sure ;TI"Inot to reuse the _key_ and _nonce_ pair. Reusing an nonce ruins the ;TI"%security guarantees of GCM mode.;T@o;;[I":cipher = OpenSSL::Cipher::AES.new(128, :GCM).encrypt
;TI"cipher.key = key
;TI"cipher.iv = nonce
;TI""cipher.auth_data = auth_data
;TI"
;TI"4encrypted = cipher.update(data) + cipher.final
;TI">tag = cipher.auth_tag # produces 16 bytes tag by default
;T;0o;;[I"MNow you are the receiver. You know the _key_ and have received _nonce_, ;TI"K_auth_data_, _encrypted_ and _tag_ through an untrusted network. Note ;TI"Nthat GCM accepts an arbitrary length tag between 1 and 16 bytes. You may ;TI"Nadditionally need to check that the received tag has the correct length, ;TI"Nor you allow attackers to forge a valid single byte tag for the tampered ;TI",ciphertext with a probability of 1/256.;T@o;;[I"9raise "tag is truncated!" unless tag.bytesize == 16
;TI"<decipher = OpenSSL::Cipher::AES.new(128, :GCM).decrypt
;TI"decipher.key = key
;TI"decipher.iv = nonce
;TI"decipher.auth_tag = tag
;TI"$decipher.auth_data = auth_data
;TI"
;TI"=decrypted = decipher.update(encrypted) + decipher.final
;TI"
;TI"$puts data == decrypted #=> true;T;0;	I"ext/openssl/ossl_cipher.c;T;
0;	0;
0[�[�[�[[I"
class;T[[:public[�[:protected[�[:private[[I"ciphers;TI"ext/openssl/ossl_cipher.c;T[I"new;T@[I"
instance;T[[;[�[;[�[;[[I"auth_data=;T@[I"
auth_tag;T@[I"auth_tag=;T@[I"auth_tag_len=;T@[I"authenticated?;T@[I"block_size;T@[I"decrypt;T@[I"encrypt;T@[I"
final;T@[I"initialize_copy;T@[I"iv=;T@[I"iv_len;T@[I"iv_len=;T@[I"	key=;T@[I"key_len;T@[I"
key_len=;T@[I"	name;T@[I"
padding=;T@[I"pkcs5_keyivgen;T@[I"random_iv;TI"&ext/openssl/lib/openssl/cipher.rb;T[I"random_key;T@D[I"
reset;T@[I"update;T@[�[U:RDoc::Context::Section[i�0o;;[�;	0;
0[I"&ext/openssl/lib/openssl/cipher.rb;TI"ext/openssl/ossl.c;TI"OpenSSL;TcRDoc::NormalModule

✏️ Editing: cdesc-Cipher.ri Read Only

📁 File Manager Pro

📁 File Manager Pro