When using Psych.load to deserialize a YAML document, the document is translated to an intermediary AST. That intermediary AST is then translated in to a Ruby object graph.
In the opposite direction, when using Psych.dump, the Ruby object graph is translated to an intermediary AST which is then converted to a YAML document.
Psych::Nodes contains all of the classes that make up the nodes of a YAML AST. You can manually build an AST and use one of the visitors (see Psych::Visitors) to convert that AST to either a YAML document or to a Ruby object graph.
Here is an example of building an AST that represents a list with one scalar:
# Create our nodes stream = Psych::Nodes::Stream.new doc = Psych::Nodes::Document.new seq = Psych::Nodes::Sequence.new scalar = Psych::Nodes::Scalar.new('foo') # Build up our tree stream.children << doc doc.children << seq seq.children << scalar
The stream is the root of the tree. We can then convert the tree to YAML:
stream.to_yaml => "---\n- foo\n"
Or convert it to Ruby:
stream.to_ruby => [["foo"]]
YAML AST Requirements A valid YAML AST must have one Psych::Nodes::Stream at the root. A Psych::Nodes::Stream node must have 1 or more Psych::Nodes::Document nodes as children.
Psych::Nodes::Document nodes must have one and only one child. That child may be one of:
Psych::Nodes::Sequence and Psych::Nodes::Mapping nodes may have many children, but Psych::Nodes::Mapping nodes should have an even number of children.
All of these are valid children for Psych::Nodes::Sequence and Psych::Nodes::Mapping nodes:
Psych::Nodes::Scalar and Psych::Nodes::Alias are both terminal nodes and should not have any children.
The GC profiler provides access to information on GC runs including time, length and object space size.
Example:
GC::Profiler.enable require 'rdoc/rdoc' GC::Profiler.report GC::Profiler.disable
See also GC.count, GC.malloc_allocated_size and GC.malloc_allocations
Extends command line arguments array (ARGV) to parse itself.
Acceptable argument classes. Now contains DecimalInteger, OctalInteger and DecimalNumeric. See Acceptable argument classes (in source code).
Flags for arguments nodes.
Flags for array nodes.
Flags for call nodes.
Flags for interpolated string nodes that indicated mutability if they are also marked as literals.
Flags for keyword hash nodes.
Flags for return nodes.
An SSLContext is used to set various options regarding certificates, algorithms, verification, session caching, etc. The SSLContext is used to create an SSLSocket.
All attributes must be set before creating an SSLSocket as the SSLContext will be frozen afterward.
A StoreContext is used while validating a single certificate and holds the status involved.
Implementation of an X.509 certificate as specified in RFC 5280. Provides access to a certificate’s attributes and allows certificates to be read from a string, but also supports the creation of new certificates from scratch.
Certificate is capable of handling DER-encoded certificates and certificates encoded in OpenSSL’s PEM format.
raw = File.binread "cert.cer" # DER- or PEM-encoded certificate = OpenSSL::X509::Certificate.new raw
A certificate may be encoded in DER format
cert = ... File.open("cert.cer", "wb") { |f| f.print cert.to_der }
or in PEM format
cert = ... File.open("cert.pem", "wb") { |f| f.print cert.to_pem }
X.509 certificates are associated with a private/public key pair, typically a RSA, DSA or ECC key (see also OpenSSL::PKey::RSA, OpenSSL::PKey::DSA and OpenSSL::PKey::EC), the public key itself is stored within the certificate and can be accessed in form of an OpenSSL::PKey. Certificates are typically used to be able to associate some form of identity with a key pair, for example web servers serving pages over HTTPs use certificates to authenticate themselves to the user.
The public key infrastructure (PKI) model relies on trusted certificate authorities (“root CAs”) that issue these certificates, so that end users need to base their trust just on a selected few authorities that themselves again vouch for subordinate CAs issuing their certificates to end users.
The OpenSSL::X509 module provides the tools to set up an independent PKI, similar to scenarios where the ‘openssl’ command line tool is used for issuing certificates in a private PKI.
First, we need to create a “self-signed” root certificate. To do so, we need to generate a key first. Please note that the choice of “1” as a serial number is considered a security flaw for real certificates. Secure choices are integers in the two-digit byte range and ideally not sequential but secure random numbers, steps omitted here to keep the example concise.
root_key = OpenSSL::PKey::RSA.new 2048 # the CA's public/private key root_ca = OpenSSL::X509::Certificate.new root_ca.version = 2 # cf. RFC 5280 - to make it a "v3" certificate root_ca.serial = 1 root_ca.subject = OpenSSL::X509::Name.parse "/DC=org/DC=ruby-lang/CN=Ruby CA" root_ca.issuer = root_ca.subject # root CA's are "self-signed" root_ca.public_key = root_key.public_key root_ca.not_before = Time.now root_ca.not_after = root_ca.not_before + 2 * 365 * 24 * 60 * 60 # 2 years validity ef = OpenSSL::X509::ExtensionFactory.new ef.subject_certificate = root_ca ef.issuer_certificate = root_ca root_ca.add_extension(ef.create_extension("basicConstraints","CA:TRUE",true)) root_ca.add_extension(ef.create_extension("keyUsage","keyCertSign, cRLSign", true)) root_ca.add_extension(ef.create_extension("subjectKeyIdentifier","hash",false)) root_ca.add_extension(ef.create_extension("authorityKeyIdentifier","keyid:always",false)) root_ca.sign(root_key, OpenSSL::Digest.new('SHA256'))
The next step is to create the end-entity certificate using the root CA certificate.
key = OpenSSL::PKey::RSA.new 2048 cert = OpenSSL::X509::Certificate.new cert.version = 2 cert.serial = 2 cert.subject = OpenSSL::X509::Name.parse "/DC=org/DC=ruby-lang/CN=Ruby certificate" cert.issuer = root_ca.subject # root CA is the issuer cert.public_key = key.public_key cert.not_before = Time.now cert.not_after = cert.not_before + 1 * 365 * 24 * 60 * 60 # 1 years validity ef = OpenSSL::X509::ExtensionFactory.new ef.subject_certificate = cert ef.issuer_certificate = root_ca cert.add_extension(ef.create_extension("keyUsage","digitalSignature", true)) cert.add_extension(ef.create_extension("subjectKeyIdentifier","hash",false)) cert.sign(root_key, OpenSSL::Digest.new('SHA256'))
The parent class for all primitive encodings. Attributes are the same as for ASN1Data, with the addition of tagging. Primitive values can never be encoded with indefinite length form, thus it is not possible to set the indefinite_length attribute for Primitive and its sub-classes.
Primitive sub-classes and their mapping to Ruby classes OpenSSL::ASN1::EndOfContent <=> value is always nil
OpenSSL::ASN1::Boolean <=> value is true or false
OpenSSL::ASN1::Integer <=> value is an OpenSSL::BN
OpenSSL::ASN1::BitString <=> value is a String
OpenSSL::ASN1::OctetString <=> value is a String
OpenSSL::ASN1::Null <=> value is always nil
OpenSSL::ASN1::Object <=> value is a String
OpenSSL::ASN1::Enumerated <=> value is an OpenSSL::BN
OpenSSL::ASN1::UTF8String <=> value is a String
OpenSSL::ASN1::NumericString <=> value is a String
OpenSSL::ASN1::PrintableString <=> value is a String
OpenSSL::ASN1::T61String <=> value is a String
OpenSSL::ASN1::VideotexString <=> value is a String
OpenSSL::ASN1::IA5String <=> value is a String
OpenSSL::ASN1::UTCTime <=> value is a Time
OpenSSL::ASN1::GeneralizedTime <=> value is a Time
OpenSSL::ASN1::GraphicString <=> value is a String
OpenSSL::ASN1::ISO64String <=> value is a String
OpenSSL::ASN1::GeneralString <=> value is a String
OpenSSL::ASN1::UniversalString <=> value is a String
OpenSSL::ASN1::BMPString <=> value is a String
unused_bits: if the underlying BIT STRING’s length is a multiple of 8 then unused_bits is 0. Otherwise unused_bits indicates the number of bits that are to be ignored in the final octet of the BitString’s value.
OpenSSL::ASN1::ObjectId NOTE: While OpenSSL::ASN1::ObjectId.new will allocate a new ObjectId, it is not typically allocated this way, but rather that are received from parsed ASN1 encodings.
sn: the short name as defined in <openssl/objects.h>.
ln: the long name as defined in <openssl/objects.h>.
oid: the object identifier as a String, e.g. “1.2.3.4.5”
short_name: alias for sn.
long_name: alias for ln.
With the Exception of OpenSSL::ASN1::EndOfContent, each Primitive class constructor takes at least one parameter, the value.
eoc = OpenSSL::ASN1::EndOfContent.new
Primitive prim = <class>.new(value) # <class> being one of the sub-classes except EndOfContent prim_zero_tagged_implicit = <class>.new(value, 0, :IMPLICIT) prim_zero_tagged_explicit = <class>.new(value, 0, :EXPLICIT)
An OpenSSL::OCSP::Response contains the status of a certificate check which is created from an OpenSSL::OCSP::Request.
An OpenSSL::OCSP::BasicResponse contains the status of a certificate check which is created from an OpenSSL::OCSP::Request. A BasicResponse is more detailed than a Response.
An OpenSSL::OCSP::CertificateId identifies a certificate to the CA so that a status check can be performed.
Generic exception class of the Timestamp module.
Immutable and read-only representation of a timestamp response returned from a timestamp server after receiving an associated Request. Allows access to specific information about the response but also allows to verify the Response.
Used to generate a Response from scratch.
Please bear in mind that the implementation will always apply and prefer the policy object identifier given in the request over the default policy id specified in the Factory. As a consequence, default_policy_id will only be applied if no Request#policy_id was given. But this also means that one needs to check the policy identifier in the request manually before creating the Response, e.g. to check whether it complies to a specific set of acceptable policies.
There exists also the possibility to add certificates (instances of OpenSSL::X509::Certificate) besides the timestamping certificate that will be included in the resulting timestamp token if Request#cert_requested? is true. Ideally, one would also include any intermediate certificates (the root certificate can be left out - in order to trust it any verifying party will have to be in its possession anyway). This simplifies validation of the timestamp since these intermediate certificates are “already there” and need not be passed as external parameters to Response#verify anymore, thus minimizing external resources needed for verification.
Assume we received a timestamp request that has set Request#policy_id to nil and Request#cert_requested? to true. The raw request bytes are stored in a variable called req_raw. We’d still like to integrate the necessary intermediate certificates (in inter1.cer and inter2.cer) to simplify validation of the resulting Response. ts.p12 is a PKCS#12-compatible file including the private key and the timestamping certificate.
req = OpenSSL::Timestamp::Request.new(raw_bytes) p12 = OpenSSL::PKCS12.new(File.binread('ts.p12'), 'pwd') inter1 = OpenSSL::X509::Certificate.new(File.binread('inter1.cer')) inter2 = OpenSSL::X509::Certificate.new(File.binread('inter2.cer')) fac = OpenSSL::Timestamp::Factory.new fac.gen_time = Time.now fac.serial_number = 1 fac.allowed_digests = ["sha256", "sha384", "sha512"] #needed because the Request contained no policy identifier fac.default_policy_id = '1.2.3.4.5' fac.additional_certificates = [ inter1, inter2 ] timestamp = fac.create_timestamp(p12.key, p12.certificate, req)
default_policy_id Request#policy_id will always be preferred over this if present in the Request, only if Request#policy_id is nil default_policy will be used. If none of both is present, a TimestampError will be raised when trying to create a Response.
call-seq:
factory.default_policy_id = "string" -> string factory.default_policy_id -> string or nil
serial_number Sets or retrieves the serial number to be used for timestamp creation. Must be present for timestamp creation.
call-seq:
factory.serial_number = number -> number factory.serial_number -> number or nil
gen_time Sets or retrieves the Time value to be used in the Response. Must be present for timestamp creation.
call-seq:
factory.gen_time = Time -> Time factory.gen_time -> Time or nil
additional_certs Sets or retrieves additional certificates apart from the timestamp certificate (e.g. intermediate certificates) to be added to the Response. Must be an Array of OpenSSL::X509::Certificate.
call-seq:
factory.additional_certs = [cert1, cert2] -> [ cert1, cert2 ] factory.additional_certs -> array or nil
allowed_digests Sets or retrieves the digest algorithms that the factory is allowed create timestamps for. Known vulnerable or weak algorithms should not be allowed where possible. Must be an Array of String or OpenSSL::Digest subclass instances.
call-seq:
factory.allowed_digests = ["sha1", OpenSSL::Digest.new('SHA256').new] -> [ "sha1", OpenSSL::Digest) ]
factory.allowed_digests -> array or nil