Linux heracles.o2switch.net 4.18.0-553.62.1.lve.el8.x86_64 #1 SMP Mon Jul 21 17:50:35 UTC 2025 x86_64

/opt/alt/ruby21/share/ri/2.1.0/system/OpenSSL/Cipher/CipherError/

//opt/alt/ruby21/share/ri/2.1.0/system/OpenSSL/Cipher/CipherError/cdesc-CipherError.ri

U:RDoc::NormalClass[iI"CipherError:ETI"!OpenSSL::Cipher::CipherError;TI"eOSSLError;To:RDoc::Markup::Document:@parts[o;;[o:RDoc::Markup::Paragraph;[I"$Document-class: OpenSSL::Cipher;To:RDoc::Markup::BlankLine�o:RDoc::Markup::Verbatim;[
�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. ;TI" ;TI"*=== Listing all supported algorithms ;TI" ;TI"7A list of supported algorithms can be obtained by ;TI" ;TI"$ puts OpenSSL::Cipher.ciphers ;TI" ;TI" === Instantiating a Cipher ;TI" ;TI"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 ;TI" ;TI"B cipher = OpenSSL::Cipher.new('<name>-<key length>-<mode>') ;TI" ;TI"IThat is, a string consisting of the hyphenated concatenation of the ;TI"Kindividual components name, key length and mode. Either all uppercase ;TI"8or all lowercase strings may be used, for example: ;TI" ;TI"2 cipher = OpenSSL::Cipher.new('AES-128-CBC') ;TI" ;TI"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 ;TI" ;TI" # these are equivalent ;TI"4 cipher = OpenSSL::Cipher::AES.new(128, :CBC) ;TI"5 cipher = OpenSSL::Cipher::AES.new(128, 'CBC') ;TI"4 cipher = OpenSSL::Cipher::AES.new('128-CBC') ;TI" ;TI"GFinally, due to its wide-spread use, there are also extra classes ;TI"0defined for the different key sizes of AES ;TI" ;TI"2 cipher = OpenSSL::Cipher::AES128.new(:CBC) ;TI"2 cipher = OpenSSL::Cipher::AES192.new(:CBC) ;TI"2 cipher = OpenSSL::Cipher::AES256.new(:CBC) ;TI" ;TI"7=== Choosing either encryption or decryption mode ;TI" ;TI"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 ;TI" ;TI" cipher.encrypt ;TI" ;TI"or ;TI" ;TI" cipher.decrypt ;TI" ;TI"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. ;TI" ;TI"=== Choosing a key ;TI" ;TI"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 ;TI" ;TI") cipher = OpenSSL::AES256.new(:CFB) ;TI" cipher.encrypt ;TI"J key = cipher.random_key # also sets the generated key on the Cipher ;TI" ;TI"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"DOpenSSL::PKCS5.pbkdf2_hmac_sha1 or OpenSSL::PKCS5.pbkdf2_hmac. ;TI" ;TI"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. ;TI" ;TI"=== Choosing an IV ;TI" ;TI"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 ;TI" ;TI"J<b>You should never use ECB mode unless you are absolutely sure that ;TI" you absolutely need it</b> ;TI" ;TI"KBecause of this, you will end up with a mode that explicitly requires ;TI"Gan IV in any case. Note that for backwards compatibility reasons, ;TI"Hsetting an IV is not explicitly mandated by the Cipher API. If not ;TI"Fset, OpenSSL itself defaults to an all-zeroes IV ("\\0", not the ;TI"Icharacter). Although the IV can be seen as public information, i.e. ;TI"Jit may be transmitted in public once generated, it should still stay ;TI"Kunpredictable to prevent certain kinds of attacks. Therefore, ideally ;TI" ;TI"F<b>Always create a secure random IV for every encryption of your ;TI"Cipher</b> ;TI" ;TI"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"Aunpredictable. A secure random IV can be created as follows ;TI" ;TI" cipher = ... ;TI" cipher.encrypt ;TI" key = cipher.random_key ;TI"G iv = cipher.random_iv # also sets the generated IV on the Cipher ;TI" ;TI"L Although the key is generally a random value, too, it is a bad choice ;TI"L as an IV. There are elaborate ways how an attacker can take advantage ;TI"K of such an IV. As a general rule of thumb, exposing the key directly ;TI"I or indirectly should be avoided at all cost and exceptions only be ;TI" made with good reason. ;TI" ;TI"=== Calling Cipher#final ;TI" ;TI"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. ;TI" ;TI"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. ;TI" ;TI"-=== Encrypting and decrypting some data ;TI" ;TI"- data = "Very, very confidential data" ;TI" ;TI"4 cipher = OpenSSL::Cipher::AES.new(128, :CBC) ;TI" cipher.encrypt ;TI" key = cipher.random_key ;TI" iv = cipher.random_iv ;TI" ;TI"6 encrypted = cipher.update(data) + cipher.final ;TI" ... ;TI"6 decipher = OpenSSL::Cipher::AES.new(128, :CBC) ;TI" decipher.decrypt ;TI" decipher.key = key ;TI" decipher.iv = iv ;TI" ;TI"; plain = decipher.update(encrypted) + decipher.final ;TI" ;TI"# puts data == plain #=> true ;TI" ;TI"==== Authenticated Encryption and Associated Data (AEAD) ;TI" ;TI"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"Jits validity, the authenticity of a given ciphertext is established. ;TI" ;TI"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. ;TI" ;TI"JIf no associated data is needed for encryption and later decryption, ;TI"Nthe OpenSSL library still requires a value to be set - "" may be used in ;TI"Mcase none is available. An example using the GCM (Galois Counter Mode): ;TI" ;TI"4 cipher = OpenSSL::Cipher::AES.new(128, :GCM) ;TI" cipher.encrypt ;TI" key = cipher.random_key ;TI" iv = cipher.random_iv ;TI" cipher.auth_data = "" ;TI" ;TI"6 encrypted = cipher.update(data) + cipher.final ;TI" tag = cipher.auth_tag ;TI" ;TI"6 decipher = OpenSSL::Cipher::AES.new(128, :GCM) ;TI" decipher.decrypt ;TI" decipher.key = key ;TI" decipher.iv = iv ;TI" decipher.auth_tag = tag ;TI" decipher.auth_data = "" ;TI" ;TI"; plain = decipher.update(encrypted) + decipher.final ;TI" ;TI"" puts data == plain #=> true;T:@format0: @fileI"ext/openssl/ossl_cipher.c;T:0@omit_headings_from_table_of_contents_below0; 0;0[�[�[�[[I" class;T[[:public[�[:protected[�[:private[�[I" instance;T[[;[�[;[�[;[�[�[U:RDoc::Context::Section[i�0o;;[�; 0;0[@
�I"OpenSSL::Cipher;TcRDoc::NormalClass