rbs 3.7.0 → 3.8.0.pre.1

data/stdlib/openssl/0/openssl.rbs

@@ -549,8 +549,10 @@ module OpenSSL
   #
   # OpenSSL 3
   # :   `0xMNN00PP0 (major minor 00 patch 0)`
+  #
   # OpenSSL before 3
   # :   `0xMNNFFPPS (major minor fix patch status)`
+  #
   # LibreSSL
   # :   `0x20000000 (fixed value)`
   #
@@ -627,7 +629,6 @@ module OpenSSL
   # *   `:APPLICATION`
   # *   `:PRIVATE`
   #
-  #
   # ## Tag constants
   #
   # There is a constant defined for each universal tag:
@@ -655,7 +656,6 @@ module OpenSSL
   # *   OpenSSL::ASN1::UNIVERSALSTRING (28)
   # *   OpenSSL::ASN1::BMPSTRING (30)
   #
-  #
   # ## UNIVERSAL_TAG_NAME constant
   #
   # An Array that stores the name of a given tag number. These names are the same
@@ -775,7 +775,6 @@ module OpenSSL
     # *   tag_class: Current tag class (Symbol)
     # *   tag: The current tag number (Integer)
     #
-    #
     # ## Example
     #     der = File.binread('asn1data.der')
     #     OpenSSL::ASN1.traverse(der) do | depth, offset, header_len, length, constructed, tag_class, tag|
@@ -871,7 +870,6 @@ module OpenSSL
     # *   *tag* equal to 1
     # *   *tag_class* equal to `:CONTEXT_SPECIFIC`
     # *   *value* equal to a String that carries the raw encoding of the INTEGER.
-    #
     # This implies that a subsequent decoding step is required to completely decode
     # implicitly tagged values.
     #
@@ -884,7 +882,6 @@ module OpenSSL
     #     OpenSSL::ASN1::Integer, i.e. the inner element is the non-tagged primitive
     #     value, and the tagging is represented in the outer ASN1Data
     #
-    #
     # ## Example - Decoding an implicitly tagged INTEGER
     #     int = OpenSSL::ASN1::Integer.new(1, 0, :IMPLICIT) # implicit 0-tagged
     #     seq = OpenSSL::ASN1::Sequence.new( [int] )
@@ -934,7 +931,7 @@ module OpenSSL
     #     puts int2.value # => 1
     #
     class ASN1Data
-      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
+      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
       # Never `nil`. A boolean value indicating whether the encoding uses indefinite
       # length (in the case of parsing) or whether an indefinite length form shall be
       # used (in the encoding case). In DER, every value uses definite length form.
@@ -951,7 +948,7 @@ module OpenSSL
       #
       def indefinite_length: () -> bool
 
-      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
+      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
       # Never `nil`. A boolean value indicating whether the encoding uses indefinite
       # length (in the case of parsing) or whether an indefinite length form shall be
       # used (in the encoding case). In DER, every value uses definite length form.
@@ -968,7 +965,7 @@ module OpenSSL
       #
       def indefinite_length=: [U] (boolish) -> U
 
-      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
+      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
       # Never `nil`. A boolean value indicating whether the encoding uses indefinite
       # length (in the case of parsing) or whether an indefinite length form shall be
       # used (in the encoding case). In DER, every value uses definite length form.
@@ -985,7 +982,7 @@ module OpenSSL
       #
       alias infinite_length indefinite_length
 
-      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
+      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
       # Never `nil`. A boolean value indicating whether the encoding uses indefinite
       # length (in the case of parsing) or whether an indefinite length form shall be
       # used (in the encoding case). In DER, every value uses definite length form.
@@ -1002,24 +999,24 @@ module OpenSSL
       #
       alias infinite_length= indefinite_length=
 
-      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
+      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
       # An Integer representing the tag number of this ASN1Data. Never `nil`.
       #
       def tag: () -> bn
 
-      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
+      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
       # An Integer representing the tag number of this ASN1Data. Never `nil`.
       #
       def tag=: (::Integer) -> ::Integer
               | (BN) -> BN
 
-      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
+      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
       # A Symbol representing the tag class of this ASN1Data. Never `nil`. See
       # ASN1Data for possible values.
       #
       def tag_class: () -> tag_class
 
-      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
+      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
       # A Symbol representing the tag class of this ASN1Data. Never `nil`. See
       # ASN1Data for possible values.
       #
@@ -1036,13 +1033,13 @@ module OpenSSL
       #
       def to_der: () -> String
 
-      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
+      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
       # Carries the value of a ASN.1 type. Please confer Constructive and Primitive
       # for the mappings between ASN.1 data types and Ruby classes.
       #
       def value: () -> untyped
 
-      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
+      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
       # Carries the value of a ASN.1 type. Please confer Constructive and Primitive
       # for the mappings between ASN.1 data types and Ruby classes.
       #
@@ -1051,7 +1048,7 @@ module OpenSSL
       private
 
       # <!--
-      #   rdoc-file=ext/openssl/ossl_asn1.c
+      #   rdoc-file=ext/openssl/lib/openssl/asn1.rb
       #   - OpenSSL::ASN1::ASN1Data.new(value, tag, tag_class) => ASN1Data
       # -->
       # *value*: Please have a look at Constructive and Primitive to see how Ruby
@@ -1106,7 +1103,6 @@ module OpenSSL
     # encodings are represented by one of the two sub-classes of Constructive:
     # *   OpenSSL::ASN1::Set
     # *   OpenSSL::ASN1::Sequence
-    #
     # Please note that tagged sequences and sets are still parsed as instances of
     # ASN1Data. Find further details on tagged values there.
     #
@@ -1124,7 +1120,7 @@ module OpenSSL
       include Enumerable[ASN1Data]
 
       # <!--
-      #   rdoc-file=ext/openssl/ossl_asn1.c
+      #   rdoc-file=ext/openssl/lib/openssl/asn1.rb
       #   - asn1_ary.each { |asn1| block } => asn1_ary
       # -->
       # Calls the given block once for each element in self, passing that element as
@@ -1190,6 +1186,11 @@ module OpenSSL
 
       private
 
+      # <!--
+      #   rdoc-file=ext/openssl/lib/openssl/asn1.rb
+      #   - new()
+      # -->
+      #
       def initialize: () -> void
     end
 
@@ -1271,7 +1272,7 @@ module OpenSSL
       #   rdoc-file=ext/openssl/ossl_asn1.c
       #   - oid == other_oid => true or false
       # -->
-      # Returns `true` if *other_oid* is the same as *oid*
+      # Returns `true` if *other_oid* is the same as *oid*.
       #
       def ==: (ObjectId other) -> bool
 
@@ -1348,7 +1349,6 @@ module OpenSSL
     # *   OpenSSL::ASN1::UniversalString <=> *value* is a String
     # *   OpenSSL::ASN1::BMPString       <=> *value* is a String
     #
-    #
     # ## OpenSSL::ASN1::BitString
     #
     # ### Additional attributes
@@ -1369,7 +1369,6 @@ module OpenSSL
     # *   *short_name*: alias for *sn*.
     # *   *long_name*: alias for *ln*.
     #
-    #
     # ## Examples
     # With the Exception of OpenSSL::ASN1::EndOfContent, each Primitive class
     # constructor takes at least one parameter, the *value*.
@@ -1854,7 +1853,7 @@ module OpenSSL
     #         bignum is ignored.
     #     *   `10` - Decimal number representation, with a leading '-' for a
     #         negative bignum.
-    #     *   `16` - Hexadeciaml number representation, with a leading '-' for a
+    #     *   `16` - Hexadecimal number representation, with a leading '-' for a
     #         negative bignum.
     #
     def to_s: () -> String
@@ -1896,6 +1895,7 @@ module OpenSSL
     #
     # `string`
     # :   The string to be parsed.
+    #
     # `base`
     # :   The format. Must be one of the following:
     #     *   `0`  - MPI format. See the man page BN_mpi2bn(3) for details.
@@ -1903,7 +1903,7 @@ module OpenSSL
     #         number.
     #     *   `10` - Decimal number representation, with a leading '-' for a
     #         negative number.
-    #     *   `16` - Hexadeciaml number representation, with a leading '-' for a
+    #     *   `16` - Hexadecimal number representation, with a leading '-' for a
     #         negative number.
     #
     def initialize: (instance) -> void
@@ -2013,7 +2013,7 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/lib/openssl/buffering.rb
-    #   - gets(eol=$/, limit=nil)
+    #   - gets(eol=$/, limit=nil, chomp: false)
     # -->
     # Reads the next "line" from the stream.  Lines are separated by *eol*.  If
     # *limit* is provided the result will not be longer than the given number of
@@ -2564,7 +2564,6 @@ module OpenSSL
     #
     #     #key=, #iv=, #random_key, #random_iv, #pkcs5_keyivgen
     # :
-    #
     # Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, 0).
     #
     def decrypt: () -> self
@@ -2580,7 +2579,6 @@ module OpenSSL
     #
     #     #key=, #iv=, #random_key, #random_iv, #pkcs5_keyivgen
     # :
-    #
     # Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, 1).
     #
     def encrypt: () -> self
@@ -2673,8 +2671,8 @@ module OpenSSL
     #   rdoc-file=ext/openssl/ossl_cipher.c
     #   - cipher.name -> string
     # -->
-    # Returns the name of the cipher which may differ slightly from the original
-    # name provided.
+    # Returns the short name of the cipher which may differ slightly from the
+    # original name provided.
     #
     def name: () -> String
 
@@ -2709,7 +2707,6 @@ module OpenSSL
     # *   *iterations* is an integer with a default of 2048.
     # *   *digest* is a Digest object that defaults to 'MD5'
     #
-    #
     # A minimum of 1000 iterations is recommended.
     #
     def pkcs5_keyivgen: (String pass, ?String salt, ?Integer iterations, ?String digest) -> void
@@ -3028,19 +3025,16 @@ module OpenSSL
     # -->
     # Gets the parsable form of the current configuration.
     #
-    # Given the following configuration being created:
+    # Given the following configuration file being loaded:
     #
-    #     config = OpenSSL::Config.new
-    #       #=> #<OpenSSL::Config sections=[]>
-    #     config['default'] = {"foo"=>"bar","baz"=>"buz"}
-    #       #=> {"foo"=>"bar", "baz"=>"buz"}
+    #     config = OpenSSL::Config.load('baz.cnf')
+    #       #=> #<OpenSSL::Config sections=["default"]>
     #     puts config.to_s
     #       #=> [ default ]
     #       #   foo=bar
     #       #   baz=buz
     #
-    # You can parse get the serialized configuration using #to_s and then parse it
-    # later:
+    # You can get the serialized configuration using #to_s and then parse it later:
     #
     #     serialized_config = config.to_s
     #     # much later...
@@ -3125,7 +3119,6 @@ module OpenSSL
   # *   SHA3-224, SHA3-256, SHA3-384 and SHA3-512
   # *   BLAKE2s256 and BLAKE2b512
   #
-  #
   # Each of these algorithms can be instantiated using the name:
   #
   #     digest = OpenSSL::Digest.new('SHA256')
@@ -3226,7 +3219,8 @@ module OpenSSL
     #   rdoc-file=ext/openssl/ossl_digest.c
     #   - digest.name -> string
     # -->
-    # Returns the sn of this Digest algorithm.
+    # Returns the short name of this Digest algorithm which may differ slightly from
+    # the original name provided.
     #
     # ### Example
     #     digest = OpenSSL::Digest.new('SHA512')
@@ -3273,7 +3267,8 @@ module OpenSSL
     #   - Digest.new(string [, data]) -> Digest
     # -->
     # Creates a Digest instance based on *string*, which is either the ln (long
-    # name) or sn (short name) of a supported digest algorithm.
+    # name) or sn (short name) of a supported digest algorithm. A list of supported
+    # algorithms can be obtained by calling OpenSSL::Digest.digests.
     #
     # If *data* (a String) is given, it is used as the initial input to the Digest
     # instance, i.e.
@@ -3562,6 +3557,7 @@ module OpenSSL
     #
     # All flags
     # :   0xFFFF
+    #
     # No flags
     # :   0x0000
     #
@@ -3888,7 +3884,6 @@ module OpenSSL
   # *   scrypt
   # *   HKDF
   #
-  #
   # ## Examples
   # ### Generating a 128 bit key for a Cipher (e.g. AES)
   #     pass = "secret"
@@ -3923,26 +3918,30 @@ module OpenSSL
     #   - KDF.hkdf(ikm, salt:, info:, length:, hash:) -> String
     # -->
     # HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as specified in
-    # [RFC 5869](https://tools.ietf.org/html/rfc5869).
+    # [RFC 5869](https://www.rfc-editor.org/rfc/rfc5869).
     #
     # New in OpenSSL 1.1.0.
     #
     # ### Parameters
     # *ikm*
     # :   The input keying material.
+    #
     # *salt*
     # :   The salt.
+    #
     # *info*
     # :   The context and application specific information.
+    #
     # *length*
     # :   The output length in octets. Must be <= `255 * HashLen`, where HashLen is
     #     the length of the hash function output in octets.
+    #
     # *hash*
     # :   The hash function.
     #
     #
     # ### Example
-    #     # The values from https://datatracker.ietf.org/doc/html/rfc5869#appendix-A.1
+    #     # The values from https://www.rfc-editor.org/rfc/rfc5869#appendix-A.1
     #     ikm = ["0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b"].pack("H*")
     #     salt = ["000102030405060708090a0b0c"].pack("H*")
     #     info = ["f0f1f2f3f4f5f6f7f8f9"].pack("H*")
@@ -3960,22 +3959,26 @@ module OpenSSL
     # *length* bytes.
     #
     # For more information about PBKDF2, see RFC 2898 Section 5.2
-    # (https://tools.ietf.org/html/rfc2898#section-5.2).
+    # (https://www.rfc-editor.org/rfc/rfc2898#section-5.2).
     #
     # ### Parameters
     # pass
     # :   The password.
+    #
     # salt
     # :   The salt. Salts prevent attacks based on dictionaries of common passwords
     #     and attacks based on rainbow tables. It is a public value that can be
     #     safely stored along with the password (e.g. if the derived value is used
     #     for password storage).
+    #
     # iterations
     # :   The iteration count. This provides the ability to tune the algorithm. It
     #     is better to use the highest count possible for the maximum resistance to
     #     brute-force attacks.
+    #
     # length
     # :   The desired length of the derived key in octets.
+    #
     # hash
     # :   The hash algorithm used with HMAC for the PRF. May be a String
     #     representing the algorithm name, or an instance of OpenSSL::Digest.
@@ -3994,22 +3997,27 @@ module OpenSSL
     # attacks using custom hardwares than alternative KDFs such as PBKDF2 or bcrypt.
     #
     # The keyword arguments *N*, *r* and *p* can be used to tune scrypt. RFC 7914
-    # (published on 2016-08, https://tools.ietf.org/html/rfc7914#section-2) states
-    # that using values r=8 and p=1 appears to yield good results.
+    # (published on 2016-08, https://www.rfc-editor.org/rfc/rfc7914#section-2)
+    # states that using values r=8 and p=1 appears to yield good results.
     #
-    # See RFC 7914 (https://tools.ietf.org/html/rfc7914) for more information.
+    # See RFC 7914 (https://www.rfc-editor.org/rfc/rfc7914) for more information.
     #
     # ### Parameters
     # pass
     # :   Passphrase.
+    #
     # salt
     # :   Salt.
+    #
     # N
     # :   CPU/memory cost parameter. This must be a power of 2.
+    #
     # r
     # :   Block size parameter.
+    #
     # p
     # :   Parallelization parameter.
+    #
     # length
     # :   Length in octets of the derived key.
     #
@@ -4065,8 +4073,8 @@ module OpenSSL
   # <!-- rdoc-file=ext/openssl/ossl_ns_spki.c -->
   # OpenSSL::Netscape is a namespace for SPKI (Simple Public Key Infrastructure)
   # which implements Signed Public Key and Challenge. See [RFC
-  # 2692](http://tools.ietf.org/html/rfc2692) and [RFC
-  # 2693](http://tools.ietf.org/html/rfc2692) for details.
+  # 2692](https://www.rfc-editor.org/rfc/rfc2692) and [RFC
+  # 2693](https://www.rfc-editor.org/rfc/rfc2692) for details.
   #
   module Netscape
     # <!-- rdoc-file=ext/openssl/ossl_ns_spki.c -->
@@ -4122,7 +4130,6 @@ module OpenSSL
       # ### Parameters
       # *   *str* - the challenge string to be set for this instance
       #
-      #
       # Sets the challenge to be associated with the SPKI. May be used by the server,
       # e.g. to prevent replay.
       #
@@ -4143,7 +4150,6 @@ module OpenSSL
       # ### Parameters
       # *   *pub* - the public key to be set for this instance
       #
-      #
       # Sets the public key to be associated with the SPKI, an instance of
       # OpenSSL::PKey. This should be the public key corresponding to the private key
       # used for signing the SPKI.
@@ -4158,7 +4164,6 @@ module OpenSSL
       # *   *key* - the private key to be used for signing this instance
       # *   *digest* - the digest to be used for signing this instance
       #
-      #
       # To sign an SPKI, the private key corresponding to the public key set for this
       # instance should be used, in addition to a digest algorithm in the form of an
       # OpenSSL::Digest. The private key should be an instance of OpenSSL::PKey.
@@ -4201,7 +4206,6 @@ module OpenSSL
       # ### Parameters
       # *   *key* - the public key to be used for verifying the SPKI signature
       #
-      #
       # Returns `true` if the signature is valid, `false` otherwise. To verify an
       # SPKI, the public key contained within the SPKI should be used.
       #
@@ -4518,7 +4522,6 @@ module OpenSSL
       # *   OpenSSL::OCSP::V_CERTSTATUS_REVOKED
       # *   OpenSSL::OCSP::V_CERTSTATUS_UNKNOWN
       #
-      #
       # *reason* and *revocation_time* can be given only when *status* is
       # OpenSSL::OCSP::V_CERTSTATUS_REVOKED. *reason* describes the reason for the
       # revocation, and must be one of OpenSSL::OCSP::REVOKED_STATUS_* constants.
@@ -4573,8 +4576,10 @@ module OpenSSL
       # *flags* can include:
       # OpenSSL::OCSP::NOCERTS
       # :   don't include certificates
+      #
       # OpenSSL::OCSP::NOTIME
       # :   don't set producedAt
+      #
       # OpenSSL::OCSP::RESPID_KEY
       # :   use signer's public key hash as responderID
       #
@@ -4774,12 +4779,16 @@ module OpenSSL
       #
       # -1
       # :   nonce in request only.
+      #
       # 0
       # :   nonces both present and not equal.
+      #
       # 1
       # :   nonces present and equal.
+      #
       # 2
       # :   nonces both absent.
+      #
       # 3
       # :   nonce present in response only.
       #
@@ -4939,7 +4948,6 @@ module OpenSSL
       # *   V_CERTSTATUS_REVOKED
       # *   V_CERTSTATUS_UNKNOWN
       #
-      #
       # When the status is V_CERTSTATUS_REVOKED, the time at which the certificate was
       # revoked can be retrieved by #revocation_time.
       #
@@ -5056,7 +5064,6 @@ module OpenSSL
     #     *   The public_key portion of the certificate must contain a valid public
     #         key.
     #     *   The not_before and not_after fields must be filled in.
-    #
     # *   *ca* - An optional array of X509::Certificate's.
     # *   *key_pbe* - string
     # *   *cert_pbe* - string
@@ -5064,7 +5071,6 @@ module OpenSSL
     # *   *mac_iter* - integer
     # *   *keytype* - An integer representing an MSIE specific extension.
     #
-    #
     # Any optional arguments may be supplied as `nil` to preserve the OpenSSL
     # defaults.
     #
@@ -5137,8 +5143,13 @@ module OpenSSL
   class PKCS7
     # <!--
     #   rdoc-file=ext/openssl/ossl_pkcs7.c
-    #   - PKCS7.encrypt(certs, data, [, cipher [, flags]]) => pkcs7
+    #   - PKCS7.encrypt(certs, data, cipher, flags = 0) => pkcs7
     # -->
+    # Creates a PKCS #7 enveloped-data structure.
+    #
+    # Before version 3.3.0, `cipher` was optional and defaulted to `"RC2-40-CBC"`.
+    #
+    # See also the man page PKCS7_encrypt(3).
     #
     def self.encrypt: (X509::Certificate certs, String data, ?Cipher cipher, ?Integer flags) -> instance
 
@@ -5466,7 +5477,6 @@ module OpenSSL
   # *   RSA (OpenSSL::PKey::RSA)
   # *   DSA (OpenSSL::PKey::DSA)
   # *   Elliptic Curve Cryptography (OpenSSL::PKey::EC)
-  #
   # Each of these implementations is in fact a sub-class of the abstract PKey
   # class which offers the interface for supporting digital signatures in the form
   # of PKey#sign and PKey#verify.
@@ -5509,11 +5519,14 @@ module OpenSSL
     # ### Accessor methods for the Diffie-Hellman parameters
     # DH#p
     # :   The prime (an OpenSSL::BN) of the Diffie-Hellman parameters.
+    #
     # DH#g
     # :   The generator (an OpenSSL::BN) g of the Diffie-Hellman parameters.
+    #
     # DH#pub_key
     # :   The per-session public key (an OpenSSL::BN) matching the private key. This
     #     needs to be passed to DH#compute_key.
+    #
     # DH#priv_key
     # :   The per-session private key, an OpenSSL::BN.
     #
@@ -5550,6 +5563,7 @@ module OpenSSL
       #
       # `size`
       # :   The desired key size in bits.
+      #
       # `generator`
       # :   The generator.
       #
@@ -5793,8 +5807,10 @@ module OpenSSL
       #
       # `string`
       # :   A String that contains the DER or PEM encoded key.
+      #
       # `size`
       # :   See DH.generate.
+      #
       # `generator`
       # :   See DH.generate.
       #
@@ -5877,6 +5893,7 @@ module OpenSSL
       #     X.509 SubjectPublicKeyInfo regardless of whether it is a public key or a
       #     private key.
       #
+      #
       # When the key contains private components, and no parameters are given
       # :   Serializes it into a traditional OpenSSL DSAPrivateKey.
       #
@@ -5886,6 +5903,7 @@ module OpenSSL
       #         [...]
       #         -----END DSA PRIVATE KEY-----
       #
+      #
       # When the key contains private components, and *cipher* and *password* are given
       # :   Serializes it into a traditional OpenSSL DSAPrivateKey and encrypts it in
       #     OpenSSL's traditional PEM encryption format. *cipher* must be a cipher
@@ -6023,6 +6041,7 @@ module OpenSSL
       #
       # `digest`
       # :   A message digest of the original input data to be signed.
+      #
       # `sig`
       # :   A DSA signature value.
       #
@@ -6060,6 +6079,7 @@ module OpenSSL
       #     X.509 SubjectPublicKeyInfo regardless of whether it is a public key or a
       #     private key.
       #
+      #
       # When the key contains private components, and no parameters are given
       # :   Serializes it into a traditional OpenSSL DSAPrivateKey.
       #
@@ -6069,6 +6089,7 @@ module OpenSSL
       #         [...]
       #         -----END DSA PRIVATE KEY-----
       #
+      #
       # When the key contains private components, and *cipher* and *password* are given
       # :   Serializes it into a traditional OpenSSL DSAPrivateKey and encrypts it in
       #     OpenSSL's traditional PEM encryption format. *cipher* must be a cipher
@@ -6112,6 +6133,7 @@ module OpenSSL
       #     X.509 SubjectPublicKeyInfo regardless of whether it is a public key or a
       #     private key.
       #
+      #
       # When the key contains private components, and no parameters are given
       # :   Serializes it into a traditional OpenSSL DSAPrivateKey.
       #
@@ -6121,6 +6143,7 @@ module OpenSSL
       #         [...]
       #         -----END DSA PRIVATE KEY-----
       #
+      #
       # When the key contains private components, and *cipher* and *password* are given
       # :   Serializes it into a traditional OpenSSL DSAPrivateKey and encrypts it in
       #     OpenSSL's traditional PEM encryption format. *cipher* must be a cipher
@@ -6177,8 +6200,10 @@ module OpenSSL
       #
       # `string`
       # :   A String that contains a DER or PEM encoded key.
+      #
       # `pass`
       # :   A String that contains an optional password.
+      #
       # `size`
       # :   See DSA.generate.
       #
@@ -6311,6 +6336,7 @@ module OpenSSL
       #     X.509 SubjectPublicKeyInfo regardless of whether it is a public key or a
       #     private key.
       #
+      #
       # When the key contains private components, and no parameters are given
       # :   Serializes it into a SEC 1/RFC 5915 ECPrivateKey.
       #
@@ -6320,6 +6346,7 @@ module OpenSSL
       #         [...]
       #         -----END EC PRIVATE KEY-----
       #
+      #
       # When the key contains private components, and *cipher* and *password* are given
       # :   Serializes it into a SEC 1/RFC 5915 ECPrivateKey and encrypts it in
       #     OpenSSL's traditional PEM encryption format. *cipher* must be a cipher
@@ -6488,6 +6515,7 @@ module OpenSSL
       #     X.509 SubjectPublicKeyInfo regardless of whether it is a public key or a
       #     private key.
       #
+      #
       # When the key contains private components, and no parameters are given
       # :   Serializes it into a SEC 1/RFC 5915 ECPrivateKey.
       #
@@ -6497,6 +6525,7 @@ module OpenSSL
       #         [...]
       #         -----END EC PRIVATE KEY-----
       #
+      #
       # When the key contains private components, and *cipher* and *password* are given
       # :   Serializes it into a SEC 1/RFC 5915 ECPrivateKey and encrypts it in
       #     OpenSSL's traditional PEM encryption format. *cipher* must be a cipher
@@ -6593,7 +6622,6 @@ module OpenSSL
         # *   EC::NAMED_CURVE
         # *   EC::EXPLICIT_CURVE
         #
-        #
         # See the OpenSSL documentation for EC_GROUP_set_asn1_flag().
         #
         def asn1_flag=: (Integer) -> Integer
@@ -6677,8 +6705,10 @@ module OpenSSL
         # `:compressed`
         # :   Encoded as z||x, where z is an octet indicating which solution of the
         #     equation y is. z will be 0x02 or 0x03.
+        #
         # `:uncompressed`
         # :   Encoded as z||x||y, where z is an octet 0x04.
+        #
         # `:hybrid`
         # :   Encodes as z||x||y, where z is an octet indicating which solution of the
         #     equation y is. z will be 0x06 or 0x07.
@@ -7008,8 +7038,10 @@ module OpenSSL
       #     the PKey type requires no digest algorithm. For backwards compatibility,
       #     this can be an instance of OpenSSL::Digest. Its state will not affect the
       #     signature.
+      #
       # `data`
       # :   A String. The data to be hashed and signed.
+      #
       # `options`
       # :   A Hash that contains algorithm specific control operations to OpenSSL. See
       #     OpenSSL's man page EVP_PKEY_CTX_ctrl_str(3) for details. `options`
@@ -7044,10 +7076,13 @@ module OpenSSL
       #
       # `digest`
       # :   See #sign.
+      #
       # `signature`
       # :   A String containing the signature to be verified.
+      #
       # `data`
       # :   See #sign.
+      #
       # `options`
       # :   See #sign. `options` parameter was added in version 3.0.
       #
@@ -7094,6 +7129,7 @@ module OpenSSL
       #
       # `size`
       # :   The desired key size in bits.
+      #
       # `exponent`
       # :   An odd Integer, normally 3, 17, or 65537.
       #
@@ -7129,6 +7165,7 @@ module OpenSSL
       #     X.509 SubjectPublicKeyInfo regardless of whether the key is a public key
       #     or a private key.
       #
+      #
       # When the key contains private components, and no parameters are given
       # :   Serializes it into a PKCS #1 RSAPrivateKey.
       #
@@ -7138,6 +7175,7 @@ module OpenSSL
       #         [...]
       #         -----END RSA PRIVATE KEY-----
       #
+      #
       # When the key contains private components, and *cipher* and *password* are given
       # :   Serializes it into a PKCS #1 RSAPrivateKey and encrypts it in OpenSSL's
       #     traditional PEM encryption format. *cipher* must be a cipher name
@@ -7312,13 +7350,16 @@ module OpenSSL
       # ### Parameters
       # *digest*
       # :   A String containing the message digest algorithm name.
+      #
       # *data*
       # :   A String. The data to be signed.
+      #
       # *salt_length*
       # :   The length in octets of the salt. Two special values are reserved:
       #     `:digest` means the digest length, and `:max` means the maximum possible
       #     length for the combination of the private key and the selected message
       #     digest algorithm.
+      #
       # *mgf1_hash*
       # :   The hash algorithm used in MGF1 (the currently supported mask generation
       #     function (MGF)).
@@ -7366,6 +7407,7 @@ module OpenSSL
       #     X.509 SubjectPublicKeyInfo regardless of whether the key is a public key
       #     or a private key.
       #
+      #
       # When the key contains private components, and no parameters are given
       # :   Serializes it into a PKCS #1 RSAPrivateKey.
       #
@@ -7375,6 +7417,7 @@ module OpenSSL
       #         [...]
       #         -----END RSA PRIVATE KEY-----
       #
+      #
       # When the key contains private components, and *cipher* and *password* are given
       # :   Serializes it into a PKCS #1 RSAPrivateKey and encrypts it in OpenSSL's
       #     traditional PEM encryption format. *cipher* must be a cipher name
@@ -7418,6 +7461,7 @@ module OpenSSL
       #     X.509 SubjectPublicKeyInfo regardless of whether the key is a public key
       #     or a private key.
       #
+      #
       # When the key contains private components, and no parameters are given
       # :   Serializes it into a PKCS #1 RSAPrivateKey.
       #
@@ -7427,6 +7471,7 @@ module OpenSSL
       #         [...]
       #         -----END RSA PRIVATE KEY-----
       #
+      #
       # When the key contains private components, and *cipher* and *password* are given
       # :   Serializes it into a PKCS #1 RSAPrivateKey and encrypts it in OpenSSL's
       #     traditional PEM encryption format. *cipher* must be a cipher name
@@ -7479,12 +7524,15 @@ module OpenSSL
       # ### Parameters
       # *digest*
       # :   A String containing the message digest algorithm name.
+      #
       # *data*
       # :   A String. The data to be signed.
+      #
       # *salt_length*
       # :   The length in octets of the salt. Two special values are reserved:
       #     `:digest` means the digest length, and `:auto` means automatically
       #     determining the length based on the signature.
+      #
       # *mgf1_hash*
       # :   The hash algorithm used in MGF1.
       #
@@ -7834,8 +7882,10 @@ module OpenSSL
       # ### Parameters
       # *certificate*
       # :   A certificate. An instance of OpenSSL::X509::Certificate.
+      #
       # *pkey*
       # :   The private key for *certificate*. An instance of OpenSSL::PKey::PKey.
+      #
       # *extra_certs*
       # :   Optional. An array of OpenSSL::X509::Certificate. When sending a
       #     certificate chain, the certificates specified by this are sent following
@@ -8194,7 +8244,7 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_ssl.c
-      #   - options()
+      #   - ctx.options -> integer
       # -->
       # Gets various OpenSSL options.
       #
@@ -8202,9 +8252,16 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_ssl.c
-      #   - options=(p1)
+      #   - ctx.options = integer
       # -->
-      # Sets various OpenSSL options.
+      # Sets various OpenSSL options. The options are a bit field and can be combined
+      # with the bitwise OR operator (`|`). Available options are defined as constants
+      # in OpenSSL::SSL that begin with `OP_`.
+      #
+      # For backwards compatibility, passing `nil` has the same effect as passing
+      # OpenSSL::SSL::OP_ALL.
+      #
+      # See also man page SSL_CTX_set_options(3).
       #
       def options=: (Integer ssl_options) -> Integer
 
@@ -8349,26 +8406,37 @@ module OpenSSL
       #
       # :accept
       # :   Number of started SSL/TLS handshakes in server mode
+      #
       # :accept_good
       # :   Number of established SSL/TLS sessions in server mode
+      #
       # :accept_renegotiate
       # :   Number of start renegotiations in server mode
+      #
       # :cache_full
       # :   Number of sessions that were removed due to cache overflow
+      #
       # :cache_hits
       # :   Number of successfully reused connections
+      #
       # :cache_misses
       # :   Number of sessions proposed by clients that were not found in the cache
+      #
       # :cache_num
       # :   Number of sessions in the internal session cache
+      #
       # :cb_hits
       # :   Number of sessions retrieved from the external cache in server mode
+      #
       # :connect
       # :   Number of started SSL/TLS handshakes in client mode
+      #
       # :connect_good
       # :   Number of established SSL/TLS sessions in client mode
+      #
       # :connect_renegotiate
       # :   Number of start renegotiations in client mode
+      #
       # :timeouts
       # :   Number of sessions proposed by clients that were found in the cache but
       #     had expired due to timeouts
@@ -9521,13 +9589,11 @@ module OpenSSL
       # *   Request#algorithm
       # *   Request#message_imprint
       #
-      #
       # Mandatory parameters that need to be set in the Factory:
       # *   Factory#serial_number
       # *   Factory#gen_time
       # *   Factory#allowed_digests
       #
-      #
       # In addition one of either Request#policy_id or Factory#default_policy_id must
       # be set.
       #
@@ -10971,7 +11037,7 @@ module OpenSSL
         #   - crl_uris()
         # -->
         # Get the distributionPoint fullName URI from the certificate's CRL distribution
-        # points extension, as described in RFC5280 Section 4.2.1.13
+        # points extension, as described in RFC 5280 Section 4.2.1.13.
         #
         # Returns an array of strings or nil or raises ASN1::ASN1Error.
         #
@@ -11136,7 +11202,6 @@ module OpenSSL
       #     `#to_s(OpenSSL::X509::Name::COMPAT)`. For example: `DC=com, DC=example,
       #     CN=nobody`
       #
-      #
       # Neither of them is standardized and has quirks and inconsistencies in handling
       # of escaped characters or multi-valued RDNs.
       #
@@ -11172,14 +11237,19 @@ module OpenSSL
       #
       # C
       # :   Country Name
+      #
       # CN
       # :   Common Name
+      #
       # DC
       # :   Domain Component
+      #
       # O
       # :   Organization Name
+      #
       # OU
       # :   Organizational Unit Name
+      #
       # ST
       # :   State or Province Name
       #
@@ -11265,7 +11335,6 @@ module OpenSSL
       # *   OpenSSL::X509::Name::ONELINE
       # *   OpenSSL::X509::Name::MULTILINE
       #
-      #
       # If *format* is omitted, the largely broken and traditional OpenSSL format
       # (`X509_NAME_oneline()` format) is chosen.
       #
@@ -11785,7 +11854,6 @@ module OpenSSL
       # *   X509::PURPOSE_OCSP_HELPER
       # *   X509::PURPOSE_TIMESTAMP_SIGN
       #
-      #
       # OpenSSL::X509::StoreContext#purpose= can be used to change the value for a
       # single verification operation.
       #
@@ -11804,7 +11872,6 @@ module OpenSSL
       # *   OpenSSL::X509::DEFAULT_CERT_FILE
       # *   OpenSSL::X509::DEFAULT_CERT_DIR
       #
-      #
       # See also the man page X509_STORE_set_default_paths(3).
       #
       def set_default_paths: () -> nil