rbs 3.6.1 → 3.9.5

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*.
@@ -1528,49 +1527,49 @@ module OpenSSL
     #   - bn % bn2 => aBN
     # -->
     #
-    def %: (int) -> instance
+    def %: (bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - bn * bn2 => aBN
     # -->
     #
-    def *: (int) -> instance
+    def *: (bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - bn ** bn2 => aBN
     # -->
     #
-    def **: (int) -> instance
+    def **: (bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - bn + bn2 => aBN
     # -->
     #
-    def +: (int) -> instance
+    def +: (bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - +bn -> aBN
     # -->
     #
-    def +@: () -> instance
+    def +@: () -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - bn - bn2 => aBN
     # -->
     #
-    def -: (int) -> instance
+    def -: (bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - -bn -> aBN
     # -->
     #
-    def -@: () -> instance
+    def -@: () -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
@@ -1578,14 +1577,14 @@ module OpenSSL
     # -->
     # Division of OpenSSL::BN instances
     #
-    def /: (int) -> [ instance, instance ]
+    def /: (bn) -> [ self, self ]
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - bn << bits -> aBN
     # -->
     #
-    def <<: (int) -> instance
+    def <<: (int) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
@@ -1636,7 +1635,7 @@ module OpenSSL
     #   - bn.cmp(bn2) => integer
     # -->
     #
-    def cmp: (Integer) -> Integer
+    def cmp: (bn) -> Integer
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
@@ -1651,7 +1650,7 @@ module OpenSSL
     #   - copy(p1)
     # -->
     #
-    def copy: (int) -> instance
+    def copy: (bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
@@ -1667,7 +1666,7 @@ module OpenSSL
     #   - bn.gcd(bn2) => aBN
     # -->
     #
-    def gcd: (int) -> instance
+    def gcd: (bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
@@ -1693,42 +1692,42 @@ module OpenSSL
     #   - bn.mod_add(bn1, bn2) -> aBN
     # -->
     #
-    def mod_add: (int, int) -> instance
+    def mod_add: (bn, bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - bn.mod_exp(bn1, bn2) -> aBN
     # -->
     #
-    def mod_exp: (int, int) -> instance
+    def mod_exp: (bn, bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - bn.mod_inverse(bn2) => aBN
     # -->
     #
-    def mod_inverse: (int) -> instance
+    def mod_inverse: (bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - bn.mod_mul(bn1, bn2) -> aBN
     # -->
     #
-    def mod_mul: (int, int) -> instance
+    def mod_mul: (bn, bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - bn.mod_sqr(bn2) => aBN
     # -->
     #
-    def mod_sqr: (int) -> instance
+    def mod_sqr: (bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - bn.mod_sub(bn1, bn2) -> aBN
     # -->
     #
-    def mod_sub: (int, int) -> instance
+    def mod_sub: (bn, bn) -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
@@ -1816,7 +1815,7 @@ module OpenSSL
     #   - bn.sqr => aBN
     # -->
     #
-    def sqr: () -> instance
+    def sqr: () -> self
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
@@ -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
@@ -1869,7 +1868,7 @@ module OpenSSL
     #   - bn.ucmp(bn2) => integer
     # -->
     #
-    def ucmp: (int bn2) -> ::Integer
+    def ucmp: (bn bn2) -> ::Integer
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
@@ -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,11 +1903,11 @@ 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
-                  | (int) -> void
+    def initialize: (self) -> void
+                  | (Integer) -> void
                   | (string) -> void
                   | (string, 0 | 2 | 10 | 16) -> void
 
@@ -1916,7 +1916,7 @@ module OpenSSL
     #   - initialize_copy(p1)
     # -->
     #
-    def initialize_copy: (instance other) -> instance
+    def initialize_copy: (self other) -> self
   end
 
   # <!-- rdoc-file=ext/openssl/ossl_bn.c -->
@@ -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
@@ -2025,7 +2025,7 @@ module OpenSSL
     #
     # Unlike IO#gets the separator must be provided if a limit is provided.
     #
-    def gets: (?String | Regexp eol, ?Integer limit) -> String?
+    def gets: (?String | Regexp eol, ?Integer limit, ?chomp: boolish) -> String?
 
     # <!--
     #   rdoc-file=ext/openssl/lib/openssl/buffering.rb
@@ -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...
@@ -3075,7 +3069,7 @@ module OpenSSL
     #   - initialize_copy(p1)
     # -->
     #
-    def initialize_copy: (instance other) -> void
+    def initialize_copy: (self other) -> void
 
     # <!-- rdoc-file=ext/openssl/ossl_config.c -->
     # The default system configuration file for OpenSSL.
@@ -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')
@@ -3164,7 +3157,7 @@ module OpenSSL
   #     sha256.reset
   #     digest2 = sha256.digest(data2)
   #
-  class Digest
+  class Digest < ::Digest::Class
     # <!--
     #   rdoc-file=ext/openssl/lib/openssl/digest.rb
     #   - digest(name, data)
@@ -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.
@@ -3292,7 +3287,7 @@ module OpenSSL
     #   - initialize_copy(p1)
     # -->
     #
-    def initialize_copy: (instance) -> void
+    def initialize_copy: (self) -> void
 
     class Digest < OpenSSL::Digest
     end
@@ -3562,6 +3557,7 @@ module OpenSSL
     #
     # All flags
     # :   0xFFFF
+    #
     # No flags
     # :   0x0000
     #
@@ -3665,6 +3661,23 @@ module OpenSSL
     #
     def self.hexdigest: (String | Digest algo, String key, String data) -> String
 
+    # <!--
+    #   rdoc-file=ext/openssl/lib/openssl/hmac.rb
+    #   - HMAC.base64digest(digest, key, data) -> aString
+    # -->
+    # Returns the authentication code as a Base64-encoded string. The *digest*
+    # parameter specifies the digest algorithm to use. This may be a String
+    # representing the algorithm name or an instance of OpenSSL::Digest.
+    #
+    # ### Example
+    #     key = 'key'
+    #     data = 'The quick brown fox jumps over the lazy dog'
+    #
+    #     hmac = OpenSSL::HMAC.base64digest('SHA1', key, data)
+    #     #=> "3nybhbi3iqa8ino29wqQcBydtNk="
+    #
+    def self.base64digest: (String | Digest algo, String key, String data) -> String
+
     # <!-- rdoc-file=ext/openssl/ossl_hmac.c -->
     # Returns *hmac* updated with the message to be authenticated. Can be called
     # repeatedly with chunks of the message.
@@ -3687,7 +3700,7 @@ module OpenSSL
     # -->
     # Securely compare with another HMAC instance in constant time.
     #
-    def ==: (instance other) -> bool
+    def ==: (self other) -> bool
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_hmac.c
@@ -3712,6 +3725,14 @@ module OpenSSL
     #
     def hexdigest: () -> String
 
+    # <!--
+    #   rdoc-file=ext/openssl/lib/openssl/hmac.rb
+    #   - hmac.base64digest -> string
+    # -->
+    # Returns the authentication code an a Base64-encoded string.
+    #
+    def base64digest: () -> String
+
     # <!-- rdoc-file=ext/openssl/lib/openssl/hmac.rb -->
     # Returns the authentication code as a hex-encoded string. The *digest*
     # parameter specifies the digest algorithm to use. This may be a String
@@ -3814,7 +3835,7 @@ module OpenSSL
     #   - initialize_copy(p1)
     # -->
     #
-    def initialize_copy: (instance) -> void
+    def initialize_copy: (self) -> void
   end
 
   # <!-- rdoc-file=ext/openssl/ossl_hmac.c -->
@@ -3863,7 +3884,6 @@ module OpenSSL
   # *   scrypt
   # *   HKDF
   #
-  #
   # ## Examples
   # ### Generating a 128 bit key for a Cipher (e.g. AES)
   #     pass = "secret"
@@ -3898,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*")
@@ -3935,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.
@@ -3969,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.
     #
@@ -4040,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 -->
@@ -4097,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.
       #
@@ -4118,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.
@@ -4133,12 +4164,11 @@ 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.
       #
-      def sign: (PKey::PKey key, Digest digest) -> instance
+      def sign: (PKey::PKey key, Digest digest) -> self
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_ns_spki.c
@@ -4176,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.
       #
@@ -4493,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.
@@ -4548,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
       #
@@ -4602,7 +4632,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
     end
 
     # <!-- rdoc-file=ext/openssl/ossl_ocsp.c -->
@@ -4617,7 +4647,7 @@ module OpenSSL
       # Compares this certificate id with *other* and returns `true` if they are the
       # same.
       #
-      def cmp: (instance other) -> bool
+      def cmp: (self other) -> bool
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_ocsp.c
@@ -4626,7 +4656,7 @@ module OpenSSL
       # Compares this certificate id's issuer with *other* and returns `true` if they
       # are the same.
       #
-      def cmp_issuer: (instance other) -> bool
+      def cmp_issuer: (self other) -> bool
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_ocsp.c
@@ -4696,7 +4726,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
     end
 
     # <!-- rdoc-file=ext/openssl/ossl_ocsp.c -->
@@ -4749,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.
       #
@@ -4830,7 +4864,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
     end
 
     # <!-- rdoc-file=ext/openssl/ossl_ocsp.c -->
@@ -4895,7 +4929,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
     end
 
     # <!-- rdoc-file=ext/openssl/ossl_ocsp.c -->
@@ -4914,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.
       #
@@ -5004,7 +5037,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
     end
   end
 
@@ -5031,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
@@ -5039,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.
     #
@@ -5079,7 +5110,7 @@ module OpenSSL
     #   - initialize_copy(p1)
     # -->
     #
-    def initialize_copy: (instance) -> void
+    def initialize_copy: (self) -> void
 
     class PKCS12Error < OpenSSL::OpenSSLError
     end
@@ -5112,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
 
@@ -5321,7 +5357,7 @@ module OpenSSL
     #   - initialize_copy(p1)
     # -->
     #
-    def initialize_copy: (instance) -> untyped
+    def initialize_copy: (self) -> untyped
 
     BINARY: Integer
 
@@ -5441,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.
@@ -5484,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.
     #
@@ -5525,6 +5563,7 @@ module OpenSSL
       #
       # `size`
       # :   The desired key size in bits.
+      #
       # `generator`
       # :   The generator.
       #
@@ -5609,7 +5648,7 @@ module OpenSSL
       # Stores all parameters of key to the hash INSECURE: PRIVATE INFORMATIONS CAN
       # LEAK OUT!!! Don't use :-)) (I's up to you)
       #
-      def params: () -> Hash[String, BN]
+      def params: () -> Hash[String, BN?]
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_pkey_dh.c
@@ -5667,7 +5706,7 @@ module OpenSSL
       #     dhcopy = dh1.public_key
       #     p dhcopy.priv_key #=> nil
       #
-      def public_key: () -> instance
+      def public_key: () -> self
 
       def q: () -> BN
 
@@ -5768,8 +5807,10 @@ module OpenSSL
       #
       # `string`
       # :   A String that contains the DER or PEM encoded key.
+      #
       # `size`
       # :   See DH.generate.
+      #
       # `generator`
       # :   See DH.generate.
       #
@@ -5796,7 +5837,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
     end
 
     # <!-- rdoc-file=ext/openssl/ossl_pkey_dh.c -->
@@ -5852,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.
       #
@@ -5861,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
@@ -5899,7 +5942,7 @@ module OpenSSL
       # Stores all parameters of key to the hash INSECURE: PRIVATE INFORMATIONS CAN
       # LEAK OUT!!! Don't use :-)) (I's up to you)
       #
-      def params: () -> Hash[String, BN]
+      def params: () -> Hash[String, BN?]
 
       def priv_key: () -> BN
 
@@ -5936,7 +5979,7 @@ module OpenSSL
       # For the purpose of serializing the public key, to PEM or DER encoding of X.509
       # SubjectPublicKeyInfo format, check PKey#public_to_pem and PKey#public_to_der.
       #
-      def public_key: () -> instance
+      def public_key: () -> self
 
       def q: () -> BN
 
@@ -5998,6 +6041,7 @@ module OpenSSL
       #
       # `digest`
       # :   A message digest of the original input data to be signed.
+      #
       # `sig`
       # :   A DSA signature value.
       #
@@ -6035,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.
       #
@@ -6044,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
@@ -6087,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.
       #
@@ -6096,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
@@ -6152,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.
       #
@@ -6176,7 +6226,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
     end
 
     # <!-- rdoc-file=ext/openssl/ossl_pkey_dsa.c -->
@@ -6286,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.
       #
@@ -6295,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
@@ -6463,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.
       #
@@ -6472,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
@@ -6520,7 +6574,7 @@ module OpenSSL
       # Creates a new EC object from given arguments.
       #
       def initialize: () -> void
-                    | (instance ec_key) -> void
+                    | (self ec_key) -> void
                     | (Group group) -> void
                     | (String pem_or_der_or_curve, ?String pass) -> void
 
@@ -6529,7 +6583,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
 
       EXPLICIT_CURVE: Integer
 
@@ -6568,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
@@ -6609,7 +6662,7 @@ module OpenSSL
         # Returns `true` if the two groups use the same curve and have the same
         # parameters, `false` otherwise.
         #
-        def eql?: (instance other) -> bool
+        def eql?: (self other) -> bool
 
         # <!--
         #   rdoc-file=ext/openssl/ossl_pkey_ec.c
@@ -6652,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.
@@ -6728,7 +6783,7 @@ module OpenSSL
         # If the first argument is :GFp or :GF2m, creates a new curve with given
         # parameters.
         #
-        def initialize: (instance group) -> void
+        def initialize: (self group) -> void
                       | (String pem_or_der_encoded) -> void
                       | (ec_method ec_method) -> void
                       | (:GFp | :GF2m ec_method, Integer bignum_p, Integer bignum_a, Integer bignum_b) -> void
@@ -6738,7 +6793,7 @@ module OpenSSL
         #   - initialize_copy(p1)
         # -->
         #
-        def initialize_copy: (instance) -> void
+        def initialize_copy: (self) -> void
 
         class Error < OpenSSL::OpenSSLError
         end
@@ -6758,7 +6813,7 @@ module OpenSSL
         # -->
         # Performs elliptic curve point addition.
         #
-        def add: (instance point) -> instance
+        def add: (self point) -> self
 
         # <!--
         #   rdoc-file=ext/openssl/ossl_pkey_ec.c
@@ -6766,7 +6821,7 @@ module OpenSSL
         #   - point1 == point2 => true | false
         # -->
         #
-        def eql?: (instance other) -> bool
+        def eql?: (self other) -> bool
 
         def group: () -> Group
 
@@ -6808,8 +6863,8 @@ module OpenSSL
         # of OpenSSL::BN. *points* must be an array of OpenSSL::PKey::EC::Point. Please
         # note that `points[0]` is not multiplied by `bns[0]`, but `bns[1]`.
         #
-        def mul: (bn bn1, ?bn bn2) -> instance
-               | (Array[bn] bns, Array[instance], ?bn bn2) -> instance
+        def mul: (bn bn1, ?bn bn2) -> self
+               | (Array[bn] bns, Array[self], ?bn bn2) -> self
 
         # <!--
         #   rdoc-file=ext/openssl/ossl_pkey_ec.c
@@ -6867,7 +6922,7 @@ module OpenSSL
         # *encoded_point* is the octet string representation of the point. This must be
         # either a String or an OpenSSL::BN.
         #
-        def initialize: (instance point) -> void
+        def initialize: (self point) -> void
                       | (Group group, ?String | BN encoded_point) -> void
 
         # <!--
@@ -6875,7 +6930,7 @@ module OpenSSL
         #   - initialize_copy(p1)
         # -->
         #
-        def initialize_copy: (instance) -> void
+        def initialize_copy: (self) -> void
 
         class Error < OpenSSL::OpenSSLError
         end
@@ -6983,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`
@@ -7019,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.
       #
@@ -7069,6 +7129,7 @@ module OpenSSL
       #
       # `size`
       # :   The desired key size in bits.
+      #
       # `exponent`
       # :   An odd Integer, normally 3, 17, or 65537.
       #
@@ -7104,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.
       #
@@ -7113,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
@@ -7157,7 +7220,7 @@ module OpenSSL
       #
       # Don't use :-)) (It's up to you)
       #
-      def params: () -> Hash[String, BN]
+      def params: () -> Hash[String, BN?]
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_pkey_rsa.c
@@ -7244,7 +7307,7 @@ module OpenSSL
       # For the purpose of serializing the public key, to PEM or DER encoding of X.509
       # SubjectPublicKeyInfo format, check PKey#public_to_pem and PKey#public_to_der.
       #
-      def public_key: () -> instance
+      def public_key: () -> self
 
       def q: () -> BN?
 
@@ -7287,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)).
@@ -7341,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.
       #
@@ -7350,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
@@ -7393,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.
       #
@@ -7402,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
@@ -7454,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.
       #
@@ -7502,7 +7575,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
 
       NO_PADDING: Integer
 
@@ -7809,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
@@ -8169,7 +8244,7 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_ssl.c
-      #   - options()
+      #   - ctx.options -> integer
       # -->
       # Gets various OpenSSL options.
       #
@@ -8177,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
 
@@ -8324,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
@@ -9186,7 +9279,7 @@ module OpenSSL
       # -->
       # Returns `true` if the two Session is the same, `false` if not.
       #
-      def ==: (instance other) -> bool
+      def ==: (self other) -> bool
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_ssl_session.c
@@ -9271,7 +9364,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
 
       class SessionError < OpenSSL::OpenSSLError
       end
@@ -9496,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.
       #
@@ -9776,7 +9867,7 @@ module OpenSSL
       #     it is not conformant to the Request, or if validation of the timestamp
       #     certificate chain fails.
       #
-      def verify: (Request request, X509::Store store, ?X509::Certificate intermediate_cert) -> instance
+      def verify: (Request request, X509::Store store, ?X509::Certificate intermediate_cert) -> self
 
       private
 
@@ -10210,7 +10301,7 @@ module OpenSSL
       #   - ==(other)
       # -->
       #
-      def ==: (instance other) -> bool
+      def ==: (self other) -> bool
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509attr.c
@@ -10262,7 +10353,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
     end
 
     class AttributeError < OpenSSL::OpenSSLError
@@ -10280,7 +10371,7 @@ module OpenSSL
       #   - ==(other)
       # -->
       #
-      def ==: (instance other) -> bool
+      def ==: (self other) -> bool
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509crl.c
@@ -10445,7 +10536,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
     end
 
     class CRLError < OpenSSL::OpenSSLError
@@ -10558,7 +10649,7 @@ module OpenSSL
       # Compares the two certificates. Note that this takes into account all fields,
       # not just the issuer name and the serial number.
       #
-      def ==: (instance other) -> bool
+      def ==: (self other) -> bool
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509cert.c
@@ -10768,7 +10859,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
     end
 
     class CertificateError < OpenSSL::OpenSSLError
@@ -10784,7 +10875,7 @@ module OpenSSL
       #   - ==(other)
       # -->
       #
-      def ==: (instance other) -> bool
+      def ==: (self other) -> bool
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509ext.c
@@ -10885,7 +10976,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
 
       module AuthorityInfoAccess
         include OpenSSL::X509::Extension::Helpers
@@ -10946,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.
         #
@@ -11111,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.
       #
@@ -11147,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
       #
@@ -11183,7 +11278,7 @@ module OpenSSL
       # -->
       # Returns true if *name* and *other* refer to the same hash key.
       #
-      def eql?: (instance other) -> bool
+      def eql?: (self other) -> bool
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509name.c
@@ -11240,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.
       #
@@ -11291,7 +11385,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
 
       # <!-- rdoc-file=ext/openssl/ossl_x509name.c -->
       # A flag for #to_s.
@@ -11536,7 +11630,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
     end
 
     class RequestError < OpenSSL::OpenSSLError
@@ -11622,7 +11716,7 @@ module OpenSSL
       #   - initialize_copy(p1)
       # -->
       #
-      def initialize_copy: (instance) -> void
+      def initialize_copy: (self) -> void
     end
 
     class RevokedError < OpenSSL::OpenSSLError
@@ -11760,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.
       #
@@ -11779,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