rbs 2.8.4 → 3.8.1

data/stdlib/openssl/0/openssl.rbs

@@ -20,23 +20,21 @@
 #
 #     key = OpenSSL::PKey::RSA.new 2048
 #
-#     open 'private_key.pem', 'w' do |io| io.write key.to_pem end
-#     open 'public_key.pem', 'w' do |io| io.write key.public_key.to_pem end
+#     File.write 'private_key.pem', key.private_to_pem
+#     File.write 'public_key.pem', key.public_to_pem
 #
 # ### Exporting a Key
 #
 # Keys saved to disk without encryption are not secure as anyone who gets ahold
 # of the key may use it unless it is encrypted.  In order to securely export a
-# key you may export it with a pass phrase.
+# key you may export it with a password.
 #
 #     cipher = OpenSSL::Cipher.new 'aes-256-cbc'
-#     pass_phrase = 'my secure pass phrase goes here'
+#     password = 'my secure password goes here'
 #
-#     key_secure = key.export cipher, pass_phrase
+#     key_secure = key.private_to_pem cipher, password
 #
-#     open 'private.secure.pem', 'w' do |io|
-#       io.write key_secure
-#     end
+#     File.write 'private.secure.pem', key_secure
 #
 # OpenSSL::Cipher.ciphers returns a list of available ciphers.
 #
@@ -56,13 +54,13 @@
 #
 # ### Loading an Encrypted Key
 #
-# OpenSSL will prompt you for your pass phrase when loading an encrypted key. If
-# you will not be able to type in the pass phrase you may provide it when
-# loading the key:
+# OpenSSL will prompt you for your password when loading an encrypted key. If
+# you will not be able to type in the password you may provide it when loading
+# the key:
 #
 #     key4_pem = File.read 'private.secure.pem'
-#     pass_phrase = 'my secure pass phrase goes here'
-#     key4 = OpenSSL::PKey.read key4_pem, pass_phrase
+#     password = 'my secure password goes here'
+#     key4 = OpenSSL::PKey.read key4_pem, password
 #
 # ## RSA Encryption
 #
@@ -175,44 +173,6 @@
 #     decrypted = cipher.update encrypted
 #     decrypted << cipher.final
 #
-# ## PKCS #5 Password-based Encryption
-#
-# PKCS #5 is a password-based encryption standard documented at
-# [RFC2898](http://www.ietf.org/rfc/rfc2898.txt).  It allows a short password or
-# passphrase to be used to create a secure encryption key. If possible, PBKDF2
-# as described above should be used if the circumstances allow it.
-#
-# PKCS #5 uses a Cipher, a pass phrase and a salt to generate an encryption key.
-#
-#     pass_phrase = 'my secure pass phrase goes here'
-#     salt = '8 octets'
-#
-# ### Encryption
-#
-# First set up the cipher for encryption
-#
-#     encryptor = OpenSSL::Cipher.new 'aes-256-cbc'
-#     encryptor.encrypt
-#     encryptor.pkcs5_keyivgen pass_phrase, salt
-#
-# Then pass the data you want to encrypt through
-#
-#     encrypted = encryptor.update 'top secret document'
-#     encrypted << encryptor.final
-#
-# ### Decryption
-#
-# Use a new Cipher instance set up for decryption
-#
-#     decryptor = OpenSSL::Cipher.new 'aes-256-cbc'
-#     decryptor.decrypt
-#     decryptor.pkcs5_keyivgen pass_phrase, salt
-#
-# Then pass the data you want to decrypt through
-#
-#     plain = decryptor.update encrypted
-#     plain << decryptor.final
-#
 # ## X509 Certificates
 #
 # ### Creating a Certificate
@@ -290,12 +250,12 @@
 # not readable by other users.
 #
 #     ca_key = OpenSSL::PKey::RSA.new 2048
-#     pass_phrase = 'my secure pass phrase goes here'
+#     password = 'my secure password goes here'
 #
-#     cipher = OpenSSL::Cipher.new 'aes-256-cbc'
+#     cipher = 'aes-256-cbc'
 #
 #     open 'ca_key.pem', 'w', 0400 do |io|
-#       io.write ca_key.export(cipher, pass_phrase)
+#       io.write ca_key.private_to_pem(cipher, password)
 #     end
 #
 # ### CA Certificate
@@ -584,7 +544,20 @@ module OpenSSL
   OPENSSL_VERSION: String
 
   # <!-- rdoc-file=ext/openssl/ossl.c -->
-  # Version number of OpenSSL the ruby OpenSSL extension was built with (base 16)
+  # Version number of OpenSSL the ruby OpenSSL extension was built with (base 16).
+  # The formats are below.
+  #
+  # OpenSSL 3
+  # :   `0xMNN00PP0 (major minor 00 patch 0)`
+  #
+  # OpenSSL before 3
+  # :   `0xMNNFFPPS (major minor fix patch status)`
+  #
+  # LibreSSL
+  # :   `0x20000000 (fixed value)`
+  #
+  #
+  # See also the man page OPENSSL_VERSION_NUMBER(3).
   #
   OPENSSL_VERSION_NUMBER: Integer
 
@@ -656,7 +629,6 @@ module OpenSSL
   # *   `:APPLICATION`
   # *   `:PRIVATE`
   #
-  #
   # ## Tag constants
   #
   # There is a constant defined for each universal tag:
@@ -684,12 +656,11 @@ 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
   # as the name of the tag constant that is additionally defined, e.g.
-  # +[UNIVERSAL_TAG_NAME](2) = "INTEGER"+ and +OpenSSL::ASN1::INTEGER = 2+.
+  # `UNIVERSAL_TAG_NAME[2] = "INTEGER"` and `OpenSSL::ASN1::INTEGER = 2`.
   #
   # ## Example usage
   #
@@ -804,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|
@@ -812,7 +782,7 @@ module OpenSSL
     #       puts "Header length: #{header_len} Tag: #{tag} Tag class: #{tag_class} Constructed: #{constructed}"
     #     end
     #
-    def self.traverse: (String | _ToDer der) { (::Integer, ::Integer, ::Integer, ::Integer, bool, tag_class, ::Integer) -> void } -> void
+    def self.traverse: (String | _ToDer der) { ([::Integer, ::Integer, ::Integer, ::Integer, bool, tag_class, ::Integer]) -> void } -> void
 
     BIT_STRING: Integer
 
@@ -900,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.
     #
@@ -913,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] )
@@ -963,9 +931,7 @@ module OpenSSL
     #     puts int2.value # => 1
     #
     class ASN1Data
-      public
-
-      # <!-- 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.
@@ -982,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.
@@ -999,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.
@@ -1016,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.
@@ -1033,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.
       #
@@ -1067,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.
       #
@@ -1082,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
@@ -1111,8 +1077,6 @@ module OpenSSL
     end
 
     class BitString < OpenSSL::ASN1::Primitive
-      public
-
       def unused_bits: () -> ::Integer
 
       def unused_bits=: (::Integer) -> ::Integer
@@ -1139,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.
     #
@@ -1156,10 +1119,8 @@ module OpenSSL
     class Constructive < OpenSSL::ASN1::ASN1Data
       include Enumerable[ASN1Data]
 
-      public
-
       # <!--
-      #   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
@@ -1221,12 +1182,15 @@ module OpenSSL
     end
 
     class EndOfContent < OpenSSL::ASN1::ASN1Data
-      public
-
       def to_der: () -> String
 
       private
 
+      # <!--
+      #   rdoc-file=ext/openssl/lib/openssl/asn1.rb
+      #   - new()
+      # -->
+      #
       def initialize: () -> void
     end
 
@@ -1304,13 +1268,11 @@ module OpenSSL
 
       def value=: (String) -> String
 
-      public
-
       # <!--
       #   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
 
@@ -1387,7 +1349,6 @@ module OpenSSL
     # *   OpenSSL::ASN1::UniversalString <=> *value* is a String
     # *   OpenSSL::ASN1::BMPString       <=> *value* is a String
     #
-    #
     # ## OpenSSL::ASN1::BitString
     #
     # ### Additional attributes
@@ -1408,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*.
@@ -1422,8 +1382,6 @@ module OpenSSL
     #     prim_zero_tagged_explicit = <class>.new(value, 0, :EXPLICIT)
     #
     class Primitive < OpenSSL::ASN1::ASN1Data
-      public
-
       # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # May be used as a hint for encoding a value either implicitly or explicitly by
       # setting it either to `:IMPLICIT` or to `:EXPLICIT`. *tagging* is not set when
@@ -1564,8 +1522,6 @@ module OpenSSL
     #
     def self.rand_range: (untyped) -> untyped
 
-    public
-
     # <!--
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - bn % bn2 => aBN
@@ -1897,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
@@ -1939,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.
@@ -1946,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
@@ -1979,8 +1936,6 @@ module OpenSSL
   module Buffering
     include Enumerable[untyped]
 
-    public
-
     # <!--
     #   rdoc-file=ext/openssl/lib/openssl/buffering.rb
     #   - <<(s)
@@ -2058,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
@@ -2519,8 +2474,6 @@ module OpenSSL
     #
     def self.ciphers: () -> Array[String]
 
-    public
-
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
     #   - cipher.auth_data = string -> string
@@ -2611,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
@@ -2627,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
@@ -2720,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
 
@@ -2756,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
@@ -2937,8 +2887,6 @@ module OpenSSL
     #
     def self.parse_config: (IO io) -> Hash[String, Hash[String, String]]
 
-    public
-
     # <!--
     #   rdoc-file=ext/openssl/ossl_config.c
     #   - config[section] -> hash
@@ -3077,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...
@@ -3174,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')
@@ -3213,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)
@@ -3221,18 +3165,12 @@ module OpenSSL
     # Return the hash value computed with *name* Digest. *name* is either the long
     # name or short name of a supported digest algorithm.
     #
-    # ### Examples
+    # ### Example
     #
     #     OpenSSL::Digest.digest("SHA256", "abc")
     #
-    # which is equivalent to:
-    #
-    #     OpenSSL::Digest.digest('SHA256', "abc")
-    #
     def self.digest: (String name, String data) -> String
 
-    public
-
     # <!-- rdoc-file=ext/openssl/ossl_digest.c -->
     # Not every message digest can be computed in one single pass. If a message
     # digest is to be computed from several subsequent sources, then each may be
@@ -3281,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')
@@ -3328,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.
@@ -3489,8 +3429,6 @@ module OpenSSL
     #
     def self.load: (?String name) -> (true | nil)
 
-    public
-
     # <!--
     #   rdoc-file=ext/openssl/ossl_engine.c
     #   - engine.cipher(name) -> OpenSSL::Cipher
@@ -3619,6 +3557,7 @@ module OpenSSL
     #
     # All flags
     # :   0xFFFF
+    #
     # No flags
     # :   0x0000
     #
@@ -3722,7 +3661,22 @@ module OpenSSL
     #
     def self.hexdigest: (String | Digest algo, String key, String data) -> String
 
-    public
+    # <!--
+    #   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
@@ -3771,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
@@ -3922,7 +3884,6 @@ module OpenSSL
   # *   scrypt
   # *   HKDF
   #
-  #
   # ## Examples
   # ### Generating a 128 bit key for a Cipher (e.g. AES)
   #     pass = "secret"
@@ -3957,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*")
@@ -3994,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 passphrase.
+    # :   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.
@@ -4028,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.
     #
@@ -4079,8 +4053,6 @@ module OpenSSL
     #
     def self.included: (untyped base) -> untyped
 
-    public
-
     # <!--
     #   rdoc-file=ext/openssl/lib/openssl/marshal.rb
     #   - _dump(_level)
@@ -4089,8 +4061,6 @@ module OpenSSL
     def _dump: (untyped _level) -> untyped
 
     module ClassMethods
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/lib/openssl/marshal.rb
       #   - _load(string)
@@ -4103,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 -->
@@ -4145,8 +4115,6 @@ module OpenSSL
     #     #proceed
     #
     class SPKI
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_ns_spki.c
       #   - spki.challenge => string
@@ -4162,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.
       #
@@ -4183,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.
@@ -4198,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.
@@ -4241,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.
       #
@@ -4312,7 +4276,7 @@ module OpenSSL
   #     require 'net/http'
   #
   #     http_response =
-  #       Net::HTTP.start ocsp_uri.hostname, ocsp.port do |http|
+  #       Net::HTTP.start ocsp_uri.hostname, ocsp_uri.port do |http|
   #         http.post ocsp_uri.path, request.to_der,
   #                   'content-type' => 'application/ocsp-request'
   #     end
@@ -4538,8 +4502,6 @@ module OpenSSL
     # detailed than a Response.
     #
     class BasicResponse
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_ocsp.c
       #   - basic_response.add_nonce(nonce = nil)
@@ -4560,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.
@@ -4615,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
       #
@@ -4677,8 +4640,6 @@ module OpenSSL
     # status check can be performed.
     #
     class CertificateId
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_ocsp.c
       #   - certificate_id.cmp(other) -> true or false
@@ -4780,8 +4741,6 @@ module OpenSSL
     # certificate or from a DER-encoded request created elsewhere.
     #
     class Request
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_ocsp.c
       #   - request.add_certid(certificate_id) -> request
@@ -4820,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.
       #
@@ -4917,8 +4880,6 @@ module OpenSSL
       #
       def self.create: (Integer status, ?BasicResponse response) -> instance
 
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_ocsp.c
       #   - response.basic
@@ -4976,8 +4937,6 @@ module OpenSSL
     # which contains the basic information of the status of the certificate.
     #
     class SingleResponse
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_ocsp.c
       #   - single_response.cert_status -> Integer
@@ -4989,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.
       #
@@ -5106,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
@@ -5114,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.
     #
@@ -5122,8 +5078,6 @@ module OpenSSL
     #
     def self.create: (String pass, String name, PKey::PKey key, X509::Certificate cert, ?Array[X509::Certificate]? ca, ?String? key_pbe, ?String? cert_pbe, ?Integer? key_iter, ?Integer? mac_iter, ?Integer? keytype) -> instance
 
-    public
-
     def ca_certs: () -> Array[X509::Certificate]?
 
     def certificate: () -> X509::Certificate
@@ -5189,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
 
@@ -5215,8 +5174,6 @@ module OpenSSL
     #
     def self.write_smime: (instance pkcs7, ?String data, ?Integer flags) -> String
 
-    public
-
     # <!--
     #   rdoc-file=ext/openssl/ossl_pkcs7.c
     #   - add_certificate(p1)
@@ -5426,8 +5383,6 @@ module OpenSSL
     end
 
     class RecipientInfo
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_pkcs7.c
       #   - enc_key()
@@ -5460,8 +5415,6 @@ module OpenSSL
     end
 
     class SignerInfo
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_pkcs7.c
       #   - issuer()
@@ -5524,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.
@@ -5567,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.
     #
@@ -5608,13 +5563,12 @@ module OpenSSL
       #
       # `size`
       # :   The desired key size in bits.
+      #
       # `generator`
       # :   The generator.
       #
       def self.generate: (Integer size, ?Integer generator) -> instance
 
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/lib/openssl/pkey.rb
       #   - dh.compute_key(pub_bn) -> string
@@ -5637,9 +5591,20 @@ module OpenSSL
       #   - dh.to_pem -> aString
       #   - dh.to_s -> aString
       # -->
-      # Encodes this DH to its PEM encoding. Note that any existing per-session
-      # public/private keys will **not** get encoded, just the Diffie-Hellman
-      # parameters will be encoded.
+      # Serializes the DH parameters to a PEM-encoding.
+      #
+      # Note that any existing per-session public/private keys will **not** get
+      # encoded, just the Diffie-Hellman parameters will be encoded.
+      #
+      # PEM-encoded parameters will look like:
+      #
+      #     -----BEGIN DH PARAMETERS-----
+      #     [...]
+      #     -----END DH PARAMETERS-----
+      #
+      # See also #public_to_pem (X.509 SubjectPublicKeyInfo) and #private_to_pem (PKCS
+      # #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) for serialization with the
+      # private or public key components.
       #
       def export: () -> String
 
@@ -5765,23 +5730,50 @@ module OpenSSL
       #   rdoc-file=ext/openssl/ossl_pkey_dh.c
       #   - dh.to_der -> aString
       # -->
-      # Encodes this DH to its DER encoding. Note that any existing per-session
-      # public/private keys will **not** get encoded, just the Diffie-Hellman
-      # parameters will be encoded.
+      # Serializes the DH parameters to a DER-encoding
+      #
+      # Note that any existing per-session public/private keys will **not** get
+      # encoded, just the Diffie-Hellman parameters will be encoded.
+      #
+      # See also #public_to_der (X.509 SubjectPublicKeyInfo) and #private_to_der (PKCS
+      # #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) for serialization with the
+      # private or public key components.
       #
       def to_der: () -> String
 
       # <!-- rdoc-file=ext/openssl/ossl_pkey_dh.c -->
-      # Encodes this DH to its PEM encoding. Note that any existing per-session
-      # public/private keys will **not** get encoded, just the Diffie-Hellman
-      # parameters will be encoded.
+      # Serializes the DH parameters to a PEM-encoding.
+      #
+      # Note that any existing per-session public/private keys will **not** get
+      # encoded, just the Diffie-Hellman parameters will be encoded.
+      #
+      # PEM-encoded parameters will look like:
+      #
+      #     -----BEGIN DH PARAMETERS-----
+      #     [...]
+      #     -----END DH PARAMETERS-----
+      #
+      # See also #public_to_pem (X.509 SubjectPublicKeyInfo) and #private_to_pem (PKCS
+      # #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) for serialization with the
+      # private or public key components.
       #
       alias to_pem export
 
       # <!-- rdoc-file=ext/openssl/ossl_pkey_dh.c -->
-      # Encodes this DH to its PEM encoding. Note that any existing per-session
-      # public/private keys will **not** get encoded, just the Diffie-Hellman
-      # parameters will be encoded.
+      # Serializes the DH parameters to a PEM-encoding.
+      #
+      # Note that any existing per-session public/private keys will **not** get
+      # encoded, just the Diffie-Hellman parameters will be encoded.
+      #
+      # PEM-encoded parameters will look like:
+      #
+      #     -----BEGIN DH PARAMETERS-----
+      #     [...]
+      #     -----END DH PARAMETERS-----
+      #
+      # See also #public_to_pem (X.509 SubjectPublicKeyInfo) and #private_to_pem (PKCS
+      # #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) for serialization with the
+      # private or public key components.
       #
       alias to_s export
 
@@ -5815,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,24 +5871,62 @@ module OpenSSL
       #
       def self.generate: (Integer size) -> instance
 
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_pkey_dsa.c
       #   - dsa.export([cipher, password]) -> aString
       #   - dsa.to_pem([cipher, password]) -> aString
       #   - dsa.to_s([cipher, password]) -> aString
       # -->
-      # Encodes this DSA to its PEM encoding.
+      # Serializes a private or public key to a PEM-encoding.
       #
-      # ### Parameters
-      # *   *cipher* is an OpenSSL::Cipher.
-      # *   *password* is a string containing your password.
+      # When the key contains public components only
+      # :   Serializes it into an X.509 SubjectPublicKeyInfo. The parameters *cipher*
+      #     and *password* are ignored.
       #
+      #     A PEM-encoded key will look like:
       #
-      # ### Examples
-      #     DSA.to_pem -> aString
-      #     DSA.to_pem(cipher, 'mypassword') -> aString
+      #         -----BEGIN PUBLIC KEY-----
+      #         [...]
+      #         -----END PUBLIC KEY-----
+      #
+      #     Consider using #public_to_pem instead. This serializes the key into an
+      #     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.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN DSA PRIVATE KEY-----
+      #         [...]
+      #         -----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
+      #     name understood by OpenSSL::Cipher.new or an instance of OpenSSL::Cipher.
+      #
+      #     An encrypted PEM-encoded key will look like:
+      #
+      #         -----BEGIN DSA PRIVATE KEY-----
+      #         Proc-Type: 4,ENCRYPTED
+      #         DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0
+      #
+      #         [...]
+      #         -----END DSA PRIVATE KEY-----
+      #
+      #     Note that this format uses MD5 to derive the encryption key, and hence
+      #     will not be available on FIPS-compliant systems.
+      #
+      #
+      # **This method is kept for compatibility.** This should only be used when the
+      # traditional, non-standard OpenSSL format is required.
+      #
+      # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
+      # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
       #
       def export: (String cipher, String password) -> String
                 | () -> String
@@ -6009,6 +6041,7 @@ module OpenSSL
       #
       # `digest`
       # :   A message digest of the original input data to be signed.
+      #
       # `sig`
       # :   A DSA signature value.
       #
@@ -6018,35 +6051,122 @@ module OpenSSL
       #   rdoc-file=ext/openssl/ossl_pkey_dsa.c
       #   - dsa.to_der -> aString
       # -->
-      # Encodes this DSA to its DER encoding.
+      # Serializes a private or public key to a DER-encoding.
+      #
+      # See #to_pem for details.
+      #
+      # **This method is kept for compatibility.** This should only be used when the
+      # traditional, non-standard OpenSSL format is required.
+      #
+      # Consider using #public_to_der or #private_to_der instead.
       #
       def to_der: () -> String
 
       # <!-- rdoc-file=ext/openssl/ossl_pkey_dsa.c -->
-      # Encodes this DSA to its PEM encoding.
+      # Serializes a private or public key to a PEM-encoding.
       #
-      # ### Parameters
-      # *   *cipher* is an OpenSSL::Cipher.
-      # *   *password* is a string containing your password.
+      # When the key contains public components only
+      # :   Serializes it into an X.509 SubjectPublicKeyInfo. The parameters *cipher*
+      #     and *password* are ignored.
       #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN PUBLIC KEY-----
+      #         [...]
+      #         -----END PUBLIC KEY-----
+      #
+      #     Consider using #public_to_pem instead. This serializes the key into an
+      #     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.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN DSA PRIVATE KEY-----
+      #         [...]
+      #         -----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
+      #     name understood by OpenSSL::Cipher.new or an instance of OpenSSL::Cipher.
+      #
+      #     An encrypted PEM-encoded key will look like:
+      #
+      #         -----BEGIN DSA PRIVATE KEY-----
+      #         Proc-Type: 4,ENCRYPTED
+      #         DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0
+      #
+      #         [...]
+      #         -----END DSA PRIVATE KEY-----
+      #
+      #     Note that this format uses MD5 to derive the encryption key, and hence
+      #     will not be available on FIPS-compliant systems.
       #
-      # ### Examples
-      #     DSA.to_pem -> aString
-      #     DSA.to_pem(cipher, 'mypassword') -> aString
+      #
+      # **This method is kept for compatibility.** This should only be used when the
+      # traditional, non-standard OpenSSL format is required.
+      #
+      # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
+      # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
       #
       alias to_pem export
 
       # <!-- rdoc-file=ext/openssl/ossl_pkey_dsa.c -->
-      # Encodes this DSA to its PEM encoding.
+      # Serializes a private or public key to a PEM-encoding.
       #
-      # ### Parameters
-      # *   *cipher* is an OpenSSL::Cipher.
-      # *   *password* is a string containing your password.
+      # When the key contains public components only
+      # :   Serializes it into an X.509 SubjectPublicKeyInfo. The parameters *cipher*
+      #     and *password* are ignored.
       #
+      #     A PEM-encoded key will look like:
       #
-      # ### Examples
-      #     DSA.to_pem -> aString
-      #     DSA.to_pem(cipher, 'mypassword') -> aString
+      #         -----BEGIN PUBLIC KEY-----
+      #         [...]
+      #         -----END PUBLIC KEY-----
+      #
+      #     Consider using #public_to_pem instead. This serializes the key into an
+      #     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.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN DSA PRIVATE KEY-----
+      #         [...]
+      #         -----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
+      #     name understood by OpenSSL::Cipher.new or an instance of OpenSSL::Cipher.
+      #
+      #     An encrypted PEM-encoded key will look like:
+      #
+      #         -----BEGIN DSA PRIVATE KEY-----
+      #         Proc-Type: 4,ENCRYPTED
+      #         DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0
+      #
+      #         [...]
+      #         -----END DSA PRIVATE KEY-----
+      #
+      #     Note that this format uses MD5 to derive the encryption key, and hence
+      #     will not be available on FIPS-compliant systems.
+      #
+      #
+      # **This method is kept for compatibility.** This should only be used when the
+      # traditional, non-standard OpenSSL format is required.
+      #
+      # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
+      # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
       #
       alias to_s export
 
@@ -6080,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.
       #
@@ -6153,8 +6275,6 @@ module OpenSSL
       #
       def self.generate: (String | Group pem_or_der_or_group_or_curve_name) -> instance
 
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_pkey_ec.c
       #   - key.check_key   => true
@@ -6197,13 +6317,59 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_pkey_ec.c
-      #   - key.export([cipher, pass_phrase]) => String
-      #   - key.to_pem([cipher, pass_phrase]) => String
+      #   - key.export([cipher, password]) => String
+      #   - key.to_pem([cipher, password]) => String
       # -->
-      # Outputs the EC key in PEM encoding.  If *cipher* and *pass_phrase* are given
-      # they will be used to encrypt the key.  *cipher* must be an OpenSSL::Cipher
-      # instance. Note that encryption will only be effective for a private key,
-      # public keys will always be encoded in plain text.
+      # Serializes a private or public key to a PEM-encoding.
+      #
+      # When the key contains public components only
+      # :   Serializes it into an X.509 SubjectPublicKeyInfo. The parameters *cipher*
+      #     and *password* are ignored.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN PUBLIC KEY-----
+      #         [...]
+      #         -----END PUBLIC KEY-----
+      #
+      #     Consider using #public_to_pem instead. This serializes the key into an
+      #     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.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN EC PRIVATE KEY-----
+      #         [...]
+      #         -----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
+      #     name understood by OpenSSL::Cipher.new or an instance of OpenSSL::Cipher.
+      #
+      #     An encrypted PEM-encoded key will look like:
+      #
+      #         -----BEGIN EC PRIVATE KEY-----
+      #         Proc-Type: 4,ENCRYPTED
+      #         DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0
+      #
+      #         [...]
+      #         -----END EC PRIVATE KEY-----
+      #
+      #     Note that this format uses MD5 to derive the encryption key, and hence
+      #     will not be available on FIPS-compliant systems.
+      #
+      #
+      # **This method is kept for compatibility.** This should only be used when the
+      # SEC 1/RFC 5915 ECPrivateKey format is required.
+      #
+      # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
+      # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
       #
       def export: (String cipher, String password) -> String
                 | () -> String
@@ -6321,15 +6487,68 @@ module OpenSSL
       #   rdoc-file=ext/openssl/ossl_pkey_ec.c
       #   - key.to_der   => String
       # -->
-      # See the OpenSSL documentation for i2d_ECPrivateKey_bio()
+      # Serializes a private or public key to a DER-encoding.
+      #
+      # See #to_pem for details.
+      #
+      # **This method is kept for compatibility.** This should only be used when the
+      # SEC 1/RFC 5915 ECPrivateKey format is required.
+      #
+      # Consider using #public_to_der or #private_to_der instead.
       #
       def to_der: () -> String
 
       # <!-- rdoc-file=ext/openssl/ossl_pkey_ec.c -->
-      # Outputs the EC key in PEM encoding.  If *cipher* and *pass_phrase* are given
-      # they will be used to encrypt the key.  *cipher* must be an OpenSSL::Cipher
-      # instance. Note that encryption will only be effective for a private key,
-      # public keys will always be encoded in plain text.
+      # Serializes a private or public key to a PEM-encoding.
+      #
+      # When the key contains public components only
+      # :   Serializes it into an X.509 SubjectPublicKeyInfo. The parameters *cipher*
+      #     and *password* are ignored.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN PUBLIC KEY-----
+      #         [...]
+      #         -----END PUBLIC KEY-----
+      #
+      #     Consider using #public_to_pem instead. This serializes the key into an
+      #     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.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN EC PRIVATE KEY-----
+      #         [...]
+      #         -----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
+      #     name understood by OpenSSL::Cipher.new or an instance of OpenSSL::Cipher.
+      #
+      #     An encrypted PEM-encoded key will look like:
+      #
+      #         -----BEGIN EC PRIVATE KEY-----
+      #         Proc-Type: 4,ENCRYPTED
+      #         DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0
+      #
+      #         [...]
+      #         -----END EC PRIVATE KEY-----
+      #
+      #     Note that this format uses MD5 to derive the encryption key, and hence
+      #     will not be available on FIPS-compliant systems.
+      #
+      #
+      # **This method is kept for compatibility.** This should only be used when the
+      # SEC 1/RFC 5915 ECPrivateKey format is required.
+      #
+      # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
+      # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
       #
       alias to_pem export
 
@@ -6375,8 +6594,6 @@ module OpenSSL
       type point_conversion_format = :compressed | :uncompressed | :hybrid
 
       class Group
-        public
-
         # <!-- rdoc-file=ext/openssl/ossl_pkey_ec.c -->
         # Returns `true` if the two groups use the same curve and have the same
         # parameters, `false` otherwise.
@@ -6405,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
@@ -6489,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.
@@ -6582,8 +6800,6 @@ module OpenSSL
       end
 
       class Point
-        public
-
         # <!--
         #   rdoc-file=ext/openssl/ossl_pkey_ec.c
         #   - ==(p1)
@@ -6732,8 +6948,6 @@ module OpenSSL
     # *   OpenSSL::PKey::EC
     #
     class PKey
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_pkey.c
       #   - pkey.inspect -> string
@@ -6771,6 +6985,18 @@ module OpenSSL
       # Serializes the private key to PEM-encoded PKCS #8 format. See #private_to_der
       # for more details.
       #
+      # An unencrypted PEM-encoded key will look like:
+      #
+      #     -----BEGIN PRIVATE KEY-----
+      #     [...]
+      #     -----END PRIVATE KEY-----
+      #
+      # An encrypted PEM-encoded key will look like:
+      #
+      #     -----BEGIN ENCRYPTED PRIVATE KEY-----
+      #     [...]
+      #     -----END ENCRYPTED PRIVATE KEY-----
+      #
       def private_to_pem: (String cipher, String password) -> String
                         | () -> String
 
@@ -6788,6 +7014,12 @@ module OpenSSL
       # -->
       # Serializes the public key to PEM-encoded X.509 SubjectPublicKeyInfo format.
       #
+      # A PEM-encoded key will look like:
+      #
+      #     -----BEGIN PUBLIC KEY-----
+      #     [...]
+      #     -----END PUBLIC KEY-----
+      #
       def public_to_pem: () -> String
 
       # <!--
@@ -6806,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`
@@ -6842,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.
       #
@@ -6892,13 +7129,12 @@ module OpenSSL
       #
       # `size`
       # :   The desired key size in bits.
+      #
       # `exponent`
       # :   An odd Integer, normally 3, 17, or 65537.
       #
       def self.generate: (Integer size, ?Integer exponent) -> instance
 
-      public
-
       def d: () -> BN?
 
       def dmp1: () -> BN?
@@ -6909,13 +7145,60 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_pkey_rsa.c
-      #   - rsa.export([cipher, pass_phrase]) => PEM-format String
-      #   - rsa.to_pem([cipher, pass_phrase]) => PEM-format String
-      #   - rsa.to_s([cipher, pass_phrase]) => PEM-format String
+      #   - rsa.export([cipher, password]) => PEM-format String
+      #   - rsa.to_pem([cipher, password]) => PEM-format String
+      #   - rsa.to_s([cipher, password]) => PEM-format String
       # -->
-      # Outputs this keypair in PEM encoding.  If *cipher* and *pass_phrase* are given
-      # they will be used to encrypt the key.  *cipher* must be an OpenSSL::Cipher
-      # instance.
+      # Serializes a private or public key to a PEM-encoding.
+      #
+      # When the key contains public components only
+      # :   Serializes it into an X.509 SubjectPublicKeyInfo. The parameters *cipher*
+      #     and *password* are ignored.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN PUBLIC KEY-----
+      #         [...]
+      #         -----END PUBLIC KEY-----
+      #
+      #     Consider using #public_to_pem instead. This serializes the key into an
+      #     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.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN RSA PRIVATE KEY-----
+      #         [...]
+      #         -----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
+      #     understood by OpenSSL::Cipher.new or an instance of OpenSSL::Cipher.
+      #
+      #     An encrypted PEM-encoded key will look like:
+      #
+      #         -----BEGIN RSA PRIVATE KEY-----
+      #         Proc-Type: 4,ENCRYPTED
+      #         DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0
+      #
+      #         [...]
+      #         -----END RSA PRIVATE KEY-----
+      #
+      #     Note that this format uses MD5 to derive the encryption key, and hence
+      #     will not be available on FIPS-compliant systems.
+      #
+      #
+      # **This method is kept for compatibility.** This should only be used when the
+      # PKCS #1 RSAPrivateKey format is required.
+      #
+      # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
+      # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
       #
       def export: (String cipher, String password) -> String
                 | () -> String
@@ -6953,7 +7236,8 @@ module OpenSSL
       #   - rsa.private_decrypt(string, padding) -> String
       # -->
       # Decrypt `string`, which has been encrypted with the public key, with the
-      # private key. `padding` defaults to PKCS1_PADDING.
+      # private key. `padding` defaults to PKCS1_PADDING, which is known to be
+      # insecure but is kept for backwards compatibility.
       #
       # **Deprecated in version 3.0**. Consider using PKey::PKey#encrypt and
       # PKey::PKey#decrypt instead.
@@ -6965,8 +7249,9 @@ module OpenSSL
       #   - rsa.private_encrypt(string)          -> String
       #   - rsa.private_encrypt(string, padding) -> String
       # -->
-      # Encrypt `string` with the private key.  `padding` defaults to PKCS1_PADDING.
-      # The encrypted string output can be decrypted using #public_decrypt.
+      # Encrypt `string` with the private key.  `padding` defaults to PKCS1_PADDING,
+      # which is known to be insecure but is kept for backwards compatibility. The
+      # encrypted string output can be decrypted using #public_decrypt.
       #
       # **Deprecated in version 3.0**. Consider using PKey::PKey#sign_raw and
       # PKey::PKey#verify_raw, and PKey::PKey#verify_recover instead.
@@ -6988,7 +7273,8 @@ module OpenSSL
       #   - rsa.public_decrypt(string, padding) -> String
       # -->
       # Decrypt `string`, which has been encrypted with the private key, with the
-      # public key.  `padding` defaults to PKCS1_PADDING.
+      # public key.  `padding` defaults to PKCS1_PADDING which is known to be insecure
+      # but is kept for backwards compatibility.
       #
       # **Deprecated in version 3.0**. Consider using PKey::PKey#sign_raw and
       # PKey::PKey#verify_raw, and PKey::PKey#verify_recover instead.
@@ -7000,8 +7286,9 @@ module OpenSSL
       #   - rsa.public_encrypt(string)          -> String
       #   - rsa.public_encrypt(string, padding) -> String
       # -->
-      # Encrypt `string` with the public key.  `padding` defaults to PKCS1_PADDING.
-      # The encrypted string output can be decrypted using #private_decrypt.
+      # Encrypt `string` with the public key.  `padding` defaults to PKCS1_PADDING,
+      # which is known to be insecure but is kept for backwards compatibility. The
+      # encrypted string output can be decrypted using #private_decrypt.
       #
       # **Deprecated in version 3.0**. Consider using PKey::PKey#encrypt and
       # PKey::PKey#decrypt instead.
@@ -7063,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)).
@@ -7089,21 +7379,122 @@ module OpenSSL
       #   rdoc-file=ext/openssl/ossl_pkey_rsa.c
       #   - rsa.to_der => DER-format String
       # -->
-      # Outputs this keypair in DER encoding.
+      # Serializes a private or public key to a DER-encoding.
+      #
+      # See #to_pem for details.
+      #
+      # **This method is kept for compatibility.** This should only be used when the
+      # PKCS #1 RSAPrivateKey format is required.
+      #
+      # Consider using #public_to_der or #private_to_der instead.
       #
       def to_der: () -> String
 
       # <!-- rdoc-file=ext/openssl/ossl_pkey_rsa.c -->
-      # Outputs this keypair in PEM encoding.  If *cipher* and *pass_phrase* are given
-      # they will be used to encrypt the key.  *cipher* must be an OpenSSL::Cipher
-      # instance.
+      # Serializes a private or public key to a PEM-encoding.
+      #
+      # When the key contains public components only
+      # :   Serializes it into an X.509 SubjectPublicKeyInfo. The parameters *cipher*
+      #     and *password* are ignored.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN PUBLIC KEY-----
+      #         [...]
+      #         -----END PUBLIC KEY-----
+      #
+      #     Consider using #public_to_pem instead. This serializes the key into an
+      #     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.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN RSA PRIVATE KEY-----
+      #         [...]
+      #         -----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
+      #     understood by OpenSSL::Cipher.new or an instance of OpenSSL::Cipher.
+      #
+      #     An encrypted PEM-encoded key will look like:
+      #
+      #         -----BEGIN RSA PRIVATE KEY-----
+      #         Proc-Type: 4,ENCRYPTED
+      #         DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0
+      #
+      #         [...]
+      #         -----END RSA PRIVATE KEY-----
+      #
+      #     Note that this format uses MD5 to derive the encryption key, and hence
+      #     will not be available on FIPS-compliant systems.
+      #
+      #
+      # **This method is kept for compatibility.** This should only be used when the
+      # PKCS #1 RSAPrivateKey format is required.
+      #
+      # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
+      # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
       #
       alias to_pem export
 
       # <!-- rdoc-file=ext/openssl/ossl_pkey_rsa.c -->
-      # Outputs this keypair in PEM encoding.  If *cipher* and *pass_phrase* are given
-      # they will be used to encrypt the key.  *cipher* must be an OpenSSL::Cipher
-      # instance.
+      # Serializes a private or public key to a PEM-encoding.
+      #
+      # When the key contains public components only
+      # :   Serializes it into an X.509 SubjectPublicKeyInfo. The parameters *cipher*
+      #     and *password* are ignored.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN PUBLIC KEY-----
+      #         [...]
+      #         -----END PUBLIC KEY-----
+      #
+      #     Consider using #public_to_pem instead. This serializes the key into an
+      #     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.
+      #
+      #     A PEM-encoded key will look like:
+      #
+      #         -----BEGIN RSA PRIVATE KEY-----
+      #         [...]
+      #         -----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
+      #     understood by OpenSSL::Cipher.new or an instance of OpenSSL::Cipher.
+      #
+      #     An encrypted PEM-encoded key will look like:
+      #
+      #         -----BEGIN RSA PRIVATE KEY-----
+      #         Proc-Type: 4,ENCRYPTED
+      #         DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0
+      #
+      #         [...]
+      #         -----END RSA PRIVATE KEY-----
+      #
+      #     Note that this format uses MD5 to derive the encryption key, and hence
+      #     will not be available on FIPS-compliant systems.
+      #
+      #
+      # **This method is kept for compatibility.** This should only be used when the
+      # PKCS #1 RSAPrivateKey format is required.
+      #
+      # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
+      # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
       #
       alias to_s export
 
@@ -7133,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.
       #
@@ -7149,8 +7543,8 @@ module OpenSSL
       # <!--
       #   rdoc-file=ext/openssl/ossl_pkey_rsa.c
       #   - RSA.new -> rsa
-      #   - RSA.new(encoded_key [, passphrase]) -> rsa
-      #   - RSA.new(encoded_key) { passphrase } -> rsa
+      #   - RSA.new(encoded_key [, password ]) -> rsa
+      #   - RSA.new(encoded_key) { password } -> rsa
       #   - RSA.new(size [, exponent]) -> rsa
       # -->
       # Generates or loads an RSA keypair.
@@ -7160,9 +7554,9 @@ module OpenSSL
       # #set_crt_params.
       #
       # If called with a String, tries to parse as DER or PEM encoding of an RSA key.
-      # Note that, if *passphrase* is not specified but the key is encrypted with a
-      # passphrase, OpenSSL will prompt for it. See also OpenSSL::PKey.read which can
-      # parse keys of any kinds.
+      # Note that if *password* is not specified, but the key is encrypted with a
+      # password, OpenSSL will prompt for it. See also OpenSSL::PKey.read which can
+      # parse keys of any kind.
       #
       # If called with a number, generates a new key pair. This form works as an alias
       # of RSA.generate.
@@ -7170,7 +7564,7 @@ module OpenSSL
       # Examples:
       #     OpenSSL::PKey::RSA.new 2048
       #     OpenSSL::PKey::RSA.new File.read 'rsa.pem'
-      #     OpenSSL::PKey::RSA.new File.read('rsa.pem'), 'my pass phrase'
+      #     OpenSSL::PKey::RSA.new File.read('rsa.pem'), 'my password'
       #
       def initialize: () -> void
                     | (Integer key_size) -> void
@@ -7471,8 +7865,6 @@ module OpenSSL
     # be frozen afterward.
     #
     class SSLContext
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_ssl.c
       #   - ctx.add_certificate(certificate, pkey [, extra_certs]) -> self
@@ -7490,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
@@ -7850,7 +8244,7 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_ssl.c
-      #   - options()
+      #   - ctx.options -> integer
       # -->
       # Gets various OpenSSL options.
       #
@@ -7858,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
 
@@ -8005,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
@@ -8382,8 +8794,6 @@ module OpenSSL
     class SSLServer
       include OpenSSL::SSL::SocketForwarder
 
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/lib/openssl/ssl.rb
       #   - accept()
@@ -8414,7 +8824,7 @@ module OpenSSL
       # -->
       # See BasicSocket#shutdown for details.
       #
-      def shutdown: (Symbol | String | Integer how) -> void
+      def shutdown: (interned | Integer how) -> void
 
       # <!-- rdoc-file=ext/openssl/lib/openssl/ssl.rb -->
       # When true then #accept works exactly the same as TCPServer#accept
@@ -8474,8 +8884,6 @@ module OpenSSL
       #
       def self.open: (untyped remote_host, untyped remote_port, ?untyped local_host, ?untyped local_port, ?context: untyped) -> untyped
 
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_ssl.c
       #   - ssl.accept => self
@@ -8865,8 +9273,6 @@ module OpenSSL
     end
 
     class Session
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_ssl_session.c
       #   - session1 == session2 -> boolean
@@ -8965,8 +9371,6 @@ module OpenSSL
     end
 
     module SocketForwarder
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/lib/openssl/ssl.rb
       #   - addr()
@@ -9164,8 +9568,6 @@ module OpenSSL
     #     factory.allowed_digests                                               -> array or nil
     #
     class Factory
-      public
-
       def additional_certs: () -> Array[X509::Certificate]?
 
       def additional_certs=: (Array[X509::Certificate]? certs) -> Array[X509::Certificate]?
@@ -9187,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.
       #
@@ -9224,8 +9624,6 @@ module OpenSSL
     # *   algorithm, message_imprint, policy_id, and nonce are set to `false`
     #
     class Request
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_ts.c
       #   - request.algorithm    -> string
@@ -9368,8 +9766,6 @@ module OpenSSL
     # Response.
     #
     class Response
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_ts.c
       #   - response.failure_info -> nil or symbol
@@ -9532,8 +9928,6 @@ module OpenSSL
     # Response.
     #
     class TokenInfo
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_ts.c
       #   - token_info.algorithm -> string or nil
@@ -9902,8 +10296,6 @@ module OpenSSL
 
       extend OpenSSL::Marshal::ClassMethods
 
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/lib/openssl/x509.rb
       #   - ==(other)
@@ -9974,8 +10366,6 @@ module OpenSSL
 
       extend OpenSSL::Marshal::ClassMethods
 
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/lib/openssl/x509.rb
       #   - ==(other)
@@ -10252,8 +10642,6 @@ module OpenSSL
 
       extend OpenSSL::Marshal::ClassMethods
 
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509cert.c
       #   - cert1 == cert2 -> true | false
@@ -10482,8 +10870,6 @@ module OpenSSL
 
       extend OpenSSL::Marshal::ClassMethods
 
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/lib/openssl/x509.rb
       #   - ==(other)
@@ -10595,8 +10981,6 @@ module OpenSSL
       module AuthorityInfoAccess
         include OpenSSL::X509::Extension::Helpers
 
-        public
-
         # <!--
         #   rdoc-file=ext/openssl/lib/openssl/x509.rb
         #   - ca_issuer_uris()
@@ -10633,8 +11017,6 @@ module OpenSSL
       module AuthorityKeyIdentifier
         include OpenSSL::X509::Extension::Helpers
 
-        public
-
         # <!--
         #   rdoc-file=ext/openssl/lib/openssl/x509.rb
         #   - authority_key_identifier()
@@ -10650,14 +11032,12 @@ module OpenSSL
       module CRLDistributionPoints
         include OpenSSL::X509::Extension::Helpers
 
-        public
-
         # <!--
         #   rdoc-file=ext/openssl/lib/openssl/x509.rb
         #   - 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.
         #
@@ -10665,8 +11045,6 @@ module OpenSSL
       end
 
       module Helpers
-        public
-
         # <!--
         #   rdoc-file=ext/openssl/lib/openssl/x509.rb
         #   - find_extension(oid)
@@ -10678,8 +11056,6 @@ module OpenSSL
       module SubjectKeyIdentifier
         include OpenSSL::X509::Extension::Helpers
 
-        public
-
         # <!--
         #   rdoc-file=ext/openssl/lib/openssl/x509.rb
         #   - subject_key_identifier()
@@ -10697,8 +11073,6 @@ module OpenSSL
     end
 
     class ExtensionFactory
-      public
-
       def config: () -> Config?
 
       def config=: (Config config) -> Config
@@ -10828,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.
       #
@@ -10848,8 +11221,6 @@ module OpenSSL
       #
       def self.parse_rfc2253: (String str, ?template template) -> instance
 
-      public
-
       # <!-- rdoc-file=ext/openssl/ossl_x509name.c -->
       # Compares this Name with *other* and returns `0` if they are the same and `-1`
       # or `+1` if they are greater or less than each other respectively. Returns
@@ -10866,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
       #
@@ -10959,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.
       #
@@ -11121,8 +11496,6 @@ module OpenSSL
 
       extend OpenSSL::Marshal::ClassMethods
 
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/lib/openssl/x509.rb
       #   - ==(other)
@@ -11264,8 +11637,6 @@ module OpenSSL
     end
 
     class Revoked
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/lib/openssl/x509.rb
       #   - ==(other)
@@ -11385,8 +11756,6 @@ module OpenSSL
     #     ssl_socket = OpenSSL::SSL::SSLSocket.new tcp_socket, ssl_context
     #
     class Store
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509store.c
       #   - store.add_cert(cert) -> self
@@ -11485,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.
       #
@@ -11504,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
@@ -11595,8 +11962,6 @@ module OpenSSL
     # status involved.
     #
     class StoreContext
-      public
-
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509store.c
       #   - stctx.chain -> nil | Array of X509::Certificate