This exception is raised if the nesting of parsed data structures is too deep.
FIXME: This isn’t documented in Nutshell.
Since MonitorMixin.new_cond
returns a ConditionVariable
, and the example above calls while_wait and signal, this class should be documented.
Provides symmetric algorithms for encryption and decryption. The algorithms that are available depend on the particular version of OpenSSL
that is installed.
A list of supported algorithms can be obtained by
puts OpenSSL::Cipher.ciphers
Cipher
There are several ways to create a Cipher
instance. Generally, a Cipher
algorithm is categorized by its name, the key length in bits and the cipher mode to be used. The most generic way to create a Cipher
is the following
cipher = OpenSSL::Cipher.new('<name>-<key length>-<mode>')
That is, a string consisting of the hyphenated concatenation of the individual components name, key length and mode. Either all uppercase or all lowercase strings may be used, for example:
cipher = OpenSSL::Cipher.new('AES-128-CBC')
For each algorithm supported, there is a class defined under the Cipher
class that goes by the name of the cipher, e.g. to obtain an instance of AES, you could also use
# these are equivalent cipher = OpenSSL::Cipher::AES.new(128, :CBC) cipher = OpenSSL::Cipher::AES.new(128, 'CBC') cipher = OpenSSL::Cipher::AES.new('128-CBC')
Finally, due to its wide-spread use, there are also extra classes defined for the different key sizes of AES
cipher = OpenSSL::Cipher::AES128.new(:CBC) cipher = OpenSSL::Cipher::AES192.new(:CBC) cipher = OpenSSL::Cipher::AES256.new(:CBC)
Encryption and decryption are often very similar operations for symmetric algorithms, this is reflected by not having to choose different classes for either operation, both can be done using the same class. Still, after obtaining a Cipher
instance, we need to tell the instance what it is that we intend to do with it, so we need to call either
cipher.encrypt
or
cipher.decrypt
on the Cipher
instance. This should be the first call after creating the instance, otherwise configuration that has already been set could get lost in the process.
Symmetric encryption requires a key that is the same for the encrypting and for the decrypting party and after initial key establishment should be kept as private information. There are a lot of ways to create insecure keys, the most notable is to simply take a password as the key without processing the password further. A simple and secure way to create a key for a particular Cipher
is
cipher = OpenSSL::AES256.new(:CFB) cipher.encrypt key = cipher.random_key # also sets the generated key on the Cipher
If you absolutely need to use passwords as encryption keys, you should use Password-Based Key Derivation Function 2 (PBKDF2) by generating the key with the help of the functionality provided by OpenSSL::PKCS5.pbkdf2_hmac_sha1
or OpenSSL::PKCS5.pbkdf2_hmac
.
Although there is Cipher#pkcs5_keyivgen
, its use is deprecated and it should only be used in legacy applications because it does not use the newer PKCS#5 v2 algorithms.
The cipher modes CBC, CFB, OFB and CTR all need an “initialization vector”, or short, IV. ECB mode is the only mode that does not require an IV, but there is almost no legitimate use case for this mode because of the fact that it does not sufficiently hide plaintext patterns. Therefore
You should never use ECB mode unless you are absolutely sure that you absolutely need it
Because of this, you will end up with a mode that explicitly requires an IV in any case. Although the IV can be seen as public information, i.e. it may be transmitted in public once generated, it should still stay unpredictable to prevent certain kinds of attacks. Therefore, ideally
Always create a secure random IV for every encryption of your Cipher
A new, random IV should be created for every encryption of data. Think of the IV as a nonce (number used once) - it’s public but random and unpredictable. A secure random IV can be created as follows
cipher = ... cipher.encrypt key = cipher.random_key iv = cipher.random_iv # also sets the generated IV on the Cipher
Although the key is generally a random value, too, it is a bad choice as an IV. There are elaborate ways how an attacker can take advantage of such an IV. As a general rule of thumb, exposing the key directly or indirectly should be avoided at all cost and exceptions only be made with good reason.
Cipher#final
ECB (which should not be used) and CBC are both block-based modes. This means that unlike for the other streaming-based modes, they operate on fixed-size blocks of data, and therefore they require a “finalization” step to produce or correctly decrypt the last block of data by appropriately handling some form of padding. Therefore it is essential to add the output of OpenSSL::Cipher#final
to your encryption/decryption buffer or you will end up with decryption errors or truncated data.
Although this is not really necessary for streaming-mode ciphers, it is still recommended to apply the same pattern of adding the output of Cipher#final
there as well - it also enables you to switch between modes more easily in the future.
data = "Very, very confidential data" cipher = OpenSSL::Cipher::AES.new(128, :CBC) cipher.encrypt key = cipher.random_key iv = cipher.random_iv encrypted = cipher.update(data) + cipher.final ... decipher = OpenSSL::Cipher::AES.new(128, :CBC) decipher.decrypt decipher.key = key decipher.iv = iv plain = decipher.update(encrypted) + decipher.final puts data == plain #=> true
Data
(AEAD) If the OpenSSL
version used supports it, an Authenticated Encryption mode (such as GCM or CCM) should always be preferred over any unauthenticated mode. Currently, OpenSSL
supports AE only in combination with Associated Data
(AEAD) where additional associated data is included in the encryption process to compute a tag at the end of the encryption. This tag will also be used in the decryption process and by verifying its validity, the authenticity of a given ciphertext is established.
This is superior to unauthenticated modes in that it allows to detect if somebody effectively changed the ciphertext after it had been encrypted. This prevents malicious modifications of the ciphertext that could otherwise be exploited to modify ciphertexts in ways beneficial to potential attackers.
An associated data is used where there is additional information, such as headers or some metadata, that must be also authenticated but not necessarily need to be encrypted. If no associated data is needed for encryption and later decryption, the OpenSSL
library still requires a value to be set - “” may be used in case none is available.
An example using the GCM (Galois/Counter Mode). You have 16 bytes key, 12 bytes (96 bits) nonce and the associated data auth_data. Be sure not to reuse the key and nonce pair. Reusing an nonce ruins the security guarantees of GCM mode.
cipher = OpenSSL::Cipher::AES.new(128, :GCM).encrypt cipher.key = key cipher.iv = nonce cipher.auth_data = auth_data encrypted = cipher.update(data) + cipher.final tag = cipher.auth_tag # produces 16 bytes tag by default
Now you are the receiver. You know the key and have received nonce, auth_data, encrypted and tag through an untrusted network. Note that GCM accepts an arbitrary length tag between 1 and 16 bytes. You may additionally need to check that the received tag has the correct length, or you allow attackers to forge a valid single byte tag for the tampered ciphertext with a probability of 1/256.
raise "tag is truncated!" unless tag.bytesize == 16 decipher = OpenSSL::Cipher::AES.new(128, :GCM).decrypt decipher.key = key decipher.iv = nonce decipher.auth_tag = tag decipher.auth_data = auth_data decrypted = decipher.update(encrypted) + decipher.final puts data == decrypted #=> true
OpenSSL::Digest
allows you to compute message digests (sometimes interchangeably called “hashes”) of arbitrary data that are cryptographically secure, i.e. a Digest
implements a secure one-way function.
One-way functions offer some useful properties. E.g. given two distinct inputs the probability that both yield the same output is highly unlikely. Combined with the fact that every message digest algorithm has a fixed-length output of just a few bytes, digests are often used to create unique identifiers for arbitrary data. A common example is the creation of a unique id for binary documents that are stored in a database.
Another useful characteristic of one-way functions (and thus the name) is that given a digest there is no indication about the original data that produced it, i.e. the only way to identify the original input is to “brute-force” through every possible combination of inputs.
These characteristics make one-way functions also ideal companions for public key signature algorithms: instead of signing an entire document, first a hash of the document is produced with a considerably faster message digest algorithm and only the few bytes of its output need to be signed using the slower public key algorithm. To validate the integrity of a signed document, it suffices to re-compute the hash and verify that it is equal to that in the signature.
Among the supported message digest algorithms are:
SHA, SHA1, SHA224, SHA256, SHA384 and SHA512
MD2, MD4, MDC2 and MD5
RIPEMD160
DSS, DSS1 (Pseudo algorithms to be used for DSA signatures. DSS is equal to SHA and DSS1 is equal to SHA1)
For each of these algorithms, there is a sub-class of Digest
that can be instantiated as simply as e.g.
digest = OpenSSL::Digest::SHA1.new
Digest
class and sn/ln The sn (short names) and ln (long names) are defined in <openssl/object.h> and <openssl/obj_mac.h>. They are textual representations of ASN.1 OBJECT IDENTIFIERs. Each supported digest algorithm has an OBJECT IDENTIFIER associated to it and those again have short/long names assigned to them. E.g. the OBJECT IDENTIFIER for SHA-1 is 1.3.14.3.2.26 and its sn is “SHA1” and its ln is “sha1”.
sn: MD2
ln: md2
sn: MD4
ln: md4
sn: MD5
ln: md5
sn: SHA
ln: SHA
sn: SHA1
ln: sha1
sn: SHA224
ln: sha224
sn: SHA256
ln: sha256
sn: SHA384
ln: sha384
sn: SHA512
ln: sha512
“Breaking” a message digest algorithm means defying its one-way function characteristics, i.e. producing a collision or finding a way to get to the original data by means that are more efficient than brute-forcing etc. Most of the supported digest algorithms can be considered broken in this sense, even the very popular MD5 and SHA1 algorithms. Should security be your highest concern, then you should probably rely on SHA224, SHA256, SHA384 or SHA512.
data = File.read('document') sha256 = OpenSSL::Digest::SHA256.new digest = sha256.digest(data)
data1 = File.read('file1') data2 = File.read('file2') data3 = File.read('file3') sha256 = OpenSSL::Digest::SHA256.new sha256 << data1 sha256 << data2 sha256 << data3 digest = sha256.digest
Digest
instance data1 = File.read('file1') sha256 = OpenSSL::Digest::SHA256.new digest1 = sha256.digest(data1) data2 = File.read('file2') sha256.reset digest2 = sha256.digest(data2)
This class works in conjunction with Psych::Parser
to build an in-memory parse tree that represents a YAML document.
parser = Psych::Parser.new Psych::TreeBuilder.new parser.parse('--- foo') tree = parser.handler.root
See Psych::Handler
for documentation on the event methods used in this class.
Zlib::GzipFile
is an abstract class for handling a gzip formatted compressed file. The operations are defined in the subclasses, Zlib::GzipReader
for reading, and Zlib::GzipWriter
for writing.
GzipReader
should be used by associating an IO
, or IO-like, object.
Method
Catalogue comment= (Zlib::GzipWriter#comment=
)
eof? (Zlib::GzipReader#eof?
)
lineno (Zlib::GzipReader#lineno
)
lineno= (Zlib::GzipReader#lineno=
)
mtime= (Zlib::GzipWriter#mtime=
)
path (when the underlying IO
supports path)
(due to internal structure, documentation may appear under Zlib::GzipReader
or Zlib::GzipWriter
)
Zlib::GzipReader
is the class for reading a gzipped file. GzipReader
should be used as an IO
, or -IO-like, object.
Zlib::GzipReader.open('hoge.gz') {|gz| print gz.read } File.open('hoge.gz') do |f| gz = Zlib::GzipReader.new(f) print gz.read gz.close end
Method
Catalogue The following methods in Zlib::GzipReader
are just like their counterparts in IO
, but they raise Zlib::Error
or Zlib::GzipFile::Error
exception if an error was found in the gzip file.
Be careful of the footer of the gzip file. A gzip file has the checksum of pre-compressed data in its footer. GzipReader
checks all uncompressed data against that checksum at the following cases, and if it fails, raises Zlib::GzipFile::NoFooter
, Zlib::GzipFile::CRCError
, or Zlib::GzipFile::LengthError
exception.
When an reading request is received beyond the end of file (the end of compressed data). That is, when Zlib::GzipReader#read
, Zlib::GzipReader#gets
, or some other methods for reading returns nil.
When Zlib::GzipFile#close
method is called after the object reaches the end of file.
When Zlib::GzipReader#unused
method is called after the object reaches the end of file.
The rest of the methods are adequately described in their own documentation.
Objects of class File::Stat
encapsulate common status information for File
objects. The information is recorded at the moment the File::Stat
object is created; changes made to the file after that point will not be reflected. File::Stat
objects are returned by IO#stat
, File::stat
, File#lstat
, and File::lstat
. Many of these methods return platform-specific values, and not all values are meaningful on all systems. See also Kernel#test
.
exception to wait for reading by EAGAIN. see IO.select
.
exception to wait for writing by EAGAIN. see IO.select
.
exception to wait for reading by EWOULDBLOCK. see IO.select
.
exception to wait for writing by EWOULDBLOCK. see IO.select
.
exception to wait for reading by EINPROGRESS. see IO.select
.
exception to wait for writing by EINPROGRESS. see IO.select
.
Note: Don’t use this class directly. This is an internal class.
An entry in an ACL
Error
raised by the DRbProtocol
module when it cannot find any protocol implementation support the scheme specified in a URI
.
Timer id conversion keeps objects alive for a certain amount of time after their last access. The default time period is 600 seconds and can be changed upon initialization.
To use TimerIdConv:
DRb.install_id_conv TimerIdConv.new 60 # one minute
HTTP request class. This class wraps together the request header and the request path. You cannot use this class directly. Instead, you should use one of its subclasses: Net::HTTP::Get
, Net::HTTP::Post
, Net::HTTP::Head
.