rbs 3.10.0 → 4.0.0.dev.1

data/stdlib/openssl/0/openssl.rbs

@@ -367,7 +367,7 @@
 # ## SSL and TLS Connections
 #
 # Using our created key and certificate we can create an SSL or TLS connection.
-# An OpenSSL::SSL::SSLContext is used to set up an SSL session.
+# An SSLContext is used to set up an SSL session.
 #
 #     context = OpenSSL::SSL::SSLContext.new
 #
@@ -379,8 +379,8 @@
 #     context.cert = cert
 #     context.key = key
 #
-# Then create an OpenSSL::SSL::SSLServer with a TCP server socket and the
-# context.  Use the SSLServer like an ordinary TCP server.
+# Then create an SSLServer with a TCP server socket and the context.  Use the
+# SSLServer like an ordinary TCP server.
 #
 #     require 'socket'
 #
@@ -401,13 +401,12 @@
 #
 # ### SSL client
 #
-# An SSL client is created with a TCP socket and the context.
-# OpenSSL::SSL::SSLSocket#connect must be called to initiate the SSL handshake
-# and start encryption.  A key and certificate are not required for the client
-# socket.
+# An SSL client is created with a TCP socket and the context. SSLSocket#connect
+# must be called to initiate the SSL handshake and start encryption.  A key and
+# certificate are not required for the client socket.
 #
-# Note that OpenSSL::SSL::SSLSocket#close doesn't close the underlying socket by
-# default. Set OpenSSL::SSL::SSLSocket#sync_close to true if you want.
+# Note that SSLSocket#close doesn't close the underlying socket by default. Set
+# SSLSocket#sync_close to true if you want.
 #
 #     require 'socket'
 #
@@ -456,7 +455,7 @@ module OpenSSL
   #     OpenSSL::Digest("MD5")
   #     # => OpenSSL::Digest::MD5
   #
-  #     OpenSSL::Digest("Foo")
+  #     Digest("Foo")
   #     # => NameError: wrong constant name Foo
   #
   def self.Digest: (String name) -> singleton(Digest)
@@ -465,13 +464,12 @@ module OpenSSL
   #   rdoc-file=ext/openssl/ossl.c
   #   - OpenSSL.debug -> true | false
   # -->
-  # Returns whether Ruby/OpenSSL's debug mode is currently enabled.
   #
   def self.debug: () -> bool
 
   # <!--
   #   rdoc-file=ext/openssl/ossl.c
-  #   - OpenSSL.debug = boolean
+  #   - OpenSSL.debug = boolean -> boolean
   # -->
   # Turns on or off debug mode. With debug mode, all errors added to the OpenSSL
   # error queue will be printed to stderr.
@@ -482,14 +480,10 @@ module OpenSSL
   #   rdoc-file=ext/openssl/ossl.c
   #   - OpenSSL.errors -> [String...]
   # -->
-  # Returns any remaining errors held in the OpenSSL thread-local error queue and
-  # clears the queue. This should normally return an empty array.
+  # See any remaining errors held in queue.
   #
-  # This is intended for debugging Ruby/OpenSSL. If you see any errors here, it
-  # likely indicates a bug in the extension. Please file an issue at
-  # https://github.com/ruby/openssl.
-  #
-  # For debugging your program, OpenSSL.debug= may be useful.
+  # Any errors you see here are probably due to a bug in Ruby's OpenSSL
+  # implementation.
   #
   def self.errors: () -> Array[String]
 
@@ -497,13 +491,12 @@ module OpenSSL
   #   rdoc-file=ext/openssl/ossl.c
   #   - OpenSSL.fips_mode -> true | false
   # -->
-  # Returns whether the FIPS mode is currently enabled.
   #
   def self.fips_mode: () -> bool
 
   # <!--
   #   rdoc-file=ext/openssl/ossl.c
-  #   - OpenSSL.fips_mode = boolean
+  #   - OpenSSL.fips_mode = boolean -> boolean
   # -->
   # Turns FIPS mode on or off. Turning on FIPS mode will obviously only have an
   # effect for FIPS-capable installations of the OpenSSL library. Trying to do so
@@ -517,74 +510,57 @@ module OpenSSL
 
   # <!--
   #   rdoc-file=ext/openssl/ossl.c
-  #   - OpenSSL.fixed_length_secure_compare(string, string) -> true or false
+  #   - OpenSSL.fixed_length_secure_compare(string, string) -> boolean
   # -->
   # Constant time memory comparison for fixed length strings, such as results of
   # HMAC calculations.
   #
   # Returns `true` if the strings are identical, `false` if they are of the same
-  # length but not identical. If the length is different, ArgumentError is raised.
+  # length but not identical. If the length is different, `ArgumentError` is
+  # raised.
   #
   def self.fixed_length_secure_compare: (String, String) -> bool
 
   # <!--
   #   rdoc-file=ext/openssl/lib/openssl.rb
-  #   - OpenSSL.secure_compare(string, string) -> true or false
+  #   - OpenSSL.secure_compare(string, string) -> boolean
   # -->
   # Constant time memory comparison. Inputs are hashed using SHA-256 to mask the
   # length of the secret. Returns `true` if the strings are identical, `false`
   # otherwise.
   #
-  # This method is expensive due to the SHA-256 hashing. In most cases, where the
-  # input lengths are known to be equal or are not sensitive,
-  # OpenSSL.fixed_length_secure_compare should be used instead.
-  #
   def self.secure_compare: (String a, String b) -> bool
 
   # <!-- rdoc-file=ext/openssl/ossl.c -->
-  # Boolean indicating whether the OpenSSL library is FIPS-capable or not. Always
-  # `true` for OpenSSL 3.0 and later.
-  #
-  # This is obsolete and will be removed in the future. See also
-  # OpenSSL.fips_mode.
+  # Boolean indicating whether OpenSSL is FIPS-capable or not
   #
   OPENSSL_FIPS: bool
 
-  # <!-- rdoc-file=ext/openssl/ossl.c -->
-  # OpenSSL library version string currently used at runtime.
-  #
   OPENSSL_LIBRARY_VERSION: String
 
   # <!-- rdoc-file=ext/openssl/ossl.c -->
-  # OpenSSL library version string used to compile the Ruby/OpenSSL extension.
-  # This may differ from the version used at runtime.
+  # Version of OpenSSL the ruby OpenSSL extension was built with
   #
   OPENSSL_VERSION: String
 
   # <!-- rdoc-file=ext/openssl/ossl.c -->
-  # OpenSSL library version number used to compile the Ruby/OpenSSL extension.
-  # This may differ from the version used at runtime.
+  # Version number of OpenSSL the ruby OpenSSL extension was built with (base 16).
+  # The formats are below.
   #
-  # The version number is encoded into a single integer value. The number follows
-  # the format:
+  # OpenSSL 3
+  # :   `0xMNN00PP0 (major minor 00 patch 0)`
   #
-  # OpenSSL 3.0.0 or later
-  # :   `0xMNN00PP0` (major minor 00 patch 0)
-  #
-  # OpenSSL 1.1.1 or earlier
-  # :   `0xMNNFFPPS` (major minor fix patch status)
+  # OpenSSL before 3
+  # :   `0xMNNFFPPS (major minor fix patch status)`
   #
   # LibreSSL
-  # :   `0x20000000` (a fixed value)
+  # :   `0x20000000 (fixed value)`
   #
   #
   # See also the man page OPENSSL_VERSION_NUMBER(3).
   #
   OPENSSL_VERSION_NUMBER: Integer
 
-  # <!-- rdoc-file=ext/openssl/lib/openssl/version.rb -->
-  # The version string of Ruby/OpenSSL.
-  #
   VERSION: String
 
   # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
@@ -955,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.
@@ -972,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.
@@ -989,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.
@@ -1006,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.
@@ -1023,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.
       #
@@ -1057,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.
       #
@@ -1072,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
@@ -1144,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
@@ -2452,28 +2428,24 @@ module OpenSSL
   # prevents malicious modifications of the ciphertext that could otherwise be
   # exploited to modify ciphertexts in ways beneficial to potential attackers.
   #
-  # Associated data, also called additional authenticated data (AAD), is
-  # optionally used where there is additional information, such as headers or some
-  # metadata, that must be also authenticated but not necessarily need to be
-  # encrypted.
+  # An associated data is used where there is additional information, such as
+  # headers or some metadata, that must be also authenticated but not necessarily
+  # need to be encrypted. If no associated data is needed for encryption and later
+  # decryption, the OpenSSL library still requires a value to be set - "" may be
+  # used in case none is available.
   #
   # An example using the GCM (Galois/Counter Mode). You have 16 bytes *key*, 12
   # bytes (96 bits) *nonce* and the associated data *auth_data*. Be sure not to
   # reuse the *key* and *nonce* pair. Reusing an nonce ruins the security
   # guarantees of GCM mode.
   #
-  #     key = OpenSSL::Random.random_bytes(16)
-  #     nonce = OpenSSL::Random.random_bytes(12)
-  #     auth_data = "authenticated but unencrypted data"
-  #     data = "encrypted data"
-  #
   #     cipher = OpenSSL::Cipher.new('aes-128-gcm').encrypt
   #     cipher.key = key
   #     cipher.iv = nonce
   #     cipher.auth_data = auth_data
   #
   #     encrypted = cipher.update(data) + cipher.final
-  #     tag = cipher.auth_tag(16)
+  #     tag = cipher.auth_tag # produces 16 bytes tag by default
   #
   # Now you are the receiver. You know the *key* and have received *nonce*,
   # *auth_data*, *encrypted* and *tag* through an untrusted network. Note that GCM
@@ -2486,17 +2458,13 @@ module OpenSSL
   #     decipher = OpenSSL::Cipher.new('aes-128-gcm').decrypt
   #     decipher.key = key
   #     decipher.iv = nonce
-  #     decipher.auth_tag = tag # could be called at any time before #final
+  #     decipher.auth_tag = tag
   #     decipher.auth_data = auth_data
   #
   #     decrypted = decipher.update(encrypted) + decipher.final
   #
   #     puts data == decrypted #=> true
   #
-  # Note that other AEAD ciphers may require additional steps, such as setting the
-  # expected tag length (#auth_tag_len=) or the total data length (#ccm_data_len=)
-  # in advance. Make sure to read the relevant man page for details.
-  #
   class Cipher
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
@@ -2508,22 +2476,21 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.auth_data = string
-    # -->
-    # Sets additional authenticated data (AAD), also called associated data, for
-    # this Cipher. This method is available for AEAD ciphers.
-    #
-    # The contents of this field should be non-sensitive data which will be added to
-    # the ciphertext to generate the authentication tag which validates the contents
-    # of the ciphertext.
-    #
-    # This method must be called after #key= and #iv= have been set, but before
-    # starting actual encryption or decryption with #update. In some cipher modes,
-    # #auth_tag_len= and #ccm_data_len= may also need to be called before this
-    # method.
-    #
-    # See also the "AEAD Interface" section of the man page EVP_EncryptInit(3). This
-    # method internally calls EVP_CipherUpdate() with the output buffer set to NULL.
+    #   - cipher.auth_data = string -> string
+    # -->
+    # Sets the cipher's additional authenticated data. This field must be set when
+    # using AEAD cipher modes such as GCM or CCM. If no associated data shall be
+    # used, this method must **still** be called with a value of "". The contents of
+    # this field should be non-sensitive data which will be added to the ciphertext
+    # to generate the authentication tag which validates the contents of the
+    # ciphertext.
+    #
+    # The AAD must be set prior to encryption or decryption. In encryption mode, it
+    # must be set after calling Cipher#encrypt and setting Cipher#key= and
+    # Cipher#iv=. When decrypting, the authenticated data must be set after key, iv
+    # and especially **after** the authentication tag has been set. I.e. set it only
+    # after calling Cipher#decrypt, Cipher#key=, Cipher#iv= and Cipher#auth_tag=
+    # first.
     #
     def auth_data=: (String) -> String
 
@@ -2531,54 +2498,42 @@ module OpenSSL
     #   rdoc-file=ext/openssl/ossl_cipher.c
     #   - cipher.auth_tag(tag_len = 16) -> String
     # -->
-    # Gets the generated authentication tag. This method is available for AEAD
-    # ciphers, and should be called after encryption has been finalized by calling
-    # #final.
-    #
-    # The returned tag will be *tag_len* bytes long. Some cipher modes require the
-    # desired length in advance using a separate call to #auth_tag_len=, before
-    # starting encryption.
+    # Gets the authentication tag generated by Authenticated Encryption Cipher modes
+    # (GCM for example). This tag may be stored along with the ciphertext, then set
+    # on the decryption cipher to authenticate the contents of the ciphertext
+    # against changes. If the optional integer parameter *tag_len* is given, the
+    # returned tag will be *tag_len* bytes long. If the parameter is omitted, the
+    # default length of 16 bytes or the length previously set by #auth_tag_len= will
+    # be used. For maximum security, the longest possible should be chosen.
     #
-    # See also the "AEAD Interface" section of the man page EVP_EncryptInit(3). This
-    # method internally calls EVP_CIPHER_CTX_ctrl() with EVP_CTRL_AEAD_GET_TAG.
+    # The tag may only be retrieved after calling Cipher#final.
     #
     def auth_tag: (?Integer tag_len) -> String
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.auth_tag = string
+    #   - cipher.auth_tag = string -> string
     # -->
-    # Sets the authentication tag to verify the integrity of the ciphertext.
-    #
-    # The authentication tag must be set before #final is called. The tag is
-    # verified during the #final call.
-    #
-    # Note that, for CCM mode and OCB mode, the expected length of the tag must be
-    # set before starting decryption by a separate call to #auth_tag_len=. The
-    # content of the tag can be provided at any time before #final is called.
+    # Sets the authentication tag to verify the integrity of the ciphertext. This
+    # can be called only when the cipher supports AE. The tag must be set after
+    # calling Cipher#decrypt, Cipher#key= and Cipher#iv=, but before calling
+    # Cipher#final. After all decryption is performed, the tag is verified
+    # automatically in the call to Cipher#final.
     #
-    # **NOTE**: The caller must ensure that the String passed to this method has the
-    # desired length. Some cipher modes support variable tag lengths, and this
-    # method may accept a truncated tag without raising an exception.
-    #
-    # See also the "AEAD Interface" section of the man page EVP_EncryptInit(3). This
-    # method internally calls EVP_CIPHER_CTX_ctrl() with EVP_CTRL_AEAD_SET_TAG.
+    # For OCB mode, the tag length must be supplied with #auth_tag_len= beforehand.
     #
     def auth_tag=: (String) -> String
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.auth_tag_len = integer
+    #   - cipher.auth_tag_len = Integer -> Integer
     # -->
-    # Sets the length of the expected authentication tag for this Cipher. This
-    # method is available for some of AEAD ciphers that require the length to be set
-    # before starting encryption or decryption, such as CCM mode or OCB mode.
-    #
-    # For CCM mode and OCB mode, the tag length must be set before #iv= is set.
+    # Sets the length of the authentication tag to be generated or to be given for
+    # AEAD ciphers that requires it as in input parameter. Note that not all AEAD
+    # ciphers support this method.
     #
-    # See also the "AEAD Interface" section of the man page EVP_EncryptInit(3). This
-    # method internally calls EVP_CIPHER_CTX_ctrl() with EVP_CTRL_AEAD_SET_TAG and a
-    # NULL buffer.
+    # In OCB mode, the length must be supplied both when encrypting and when
+    # decrypting, and must be before specifying an IV.
     #
     def auth_tag_len=: (Integer) -> Integer
 
@@ -2586,7 +2541,7 @@ module OpenSSL
     #   rdoc-file=ext/openssl/ossl_cipher.c
     #   - cipher.authenticated? -> true | false
     # -->
-    # Indicates whether this Cipher instance uses an AEAD mode.
+    # Indicated whether this Cipher instance uses an Authenticated Encryption mode.
     #
     def authenticated?: () -> bool
 
@@ -2604,9 +2559,11 @@ module OpenSSL
     # -->
     # Initializes the Cipher for decryption.
     #
-    # Make sure to call either #encrypt or #decrypt before using the Cipher for any
-    # operation or setting any parameters.
+    # Make sure to call Cipher#encrypt or Cipher#decrypt before using any of the
+    # following methods:
     #
+    #     #key=, #iv=, #random_key, #random_iv, #pkcs5_keyivgen
+    # :
     # Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, 0).
     #
     def decrypt: () -> self
@@ -2617,9 +2574,11 @@ module OpenSSL
     # -->
     # Initializes the Cipher for encryption.
     #
-    # Make sure to call either #encrypt or #decrypt before using the Cipher for any
-    # operation or setting any parameters.
+    # Make sure to call Cipher#encrypt or Cipher#decrypt before using any of the
+    # following methods:
     #
+    #     #key=, #iv=, #random_key, #random_iv, #pkcs5_keyivgen
+    # :
     # Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, 1).
     #
     def encrypt: () -> self
@@ -2629,37 +2588,28 @@ module OpenSSL
     #   - cipher.final -> string
     # -->
     # Returns the remaining data held in the cipher object. Further calls to
-    # Cipher#update or Cipher#final are invalid. This call should always be made as
-    # the last call of an encryption or decryption operation, after having fed the
-    # entire plaintext or ciphertext to the Cipher instance.
+    # Cipher#update or Cipher#final will return garbage. This call should always be
+    # made as the last call of an encryption or decryption operation, after having
+    # fed the entire plaintext or ciphertext to the Cipher instance.
     #
-    # When encrypting using an AEAD cipher, the authentication tag can be retrieved
-    # by #auth_tag after #final has been called.
-    #
-    # When decrypting using an AEAD cipher, this method will verify the integrity of
-    # the ciphertext and the associated data with the authentication tag, which must
-    # be set by #auth_tag= prior to calling this method. If the verification fails,
-    # CipherError will be raised.
+    # If an authenticated cipher was used, a CipherError is raised if the tag could
+    # not be authenticated successfully. Only call this method after setting the
+    # authentication tag and passing the entire contents of the ciphertext into the
+    # cipher.
     #
     def final: () -> String
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.iv = string
+    #   - cipher.iv = string -> string
     # -->
     # Sets the cipher IV. Please note that since you should never be using ECB mode,
     # an IV is always explicitly required and should be set prior to encryption. The
-    # IV itself can be safely transmitted in public.
-    #
-    # This method expects the String to have the length equal to #iv_len. To use a
-    # different IV length with an AEAD cipher, #iv_len= must be set prior to calling
-    # this method.
+    # IV itself can be safely transmitted in public, but it should be unpredictable
+    # to prevent certain kinds of attacks. You may use Cipher#random_iv to create a
+    # secure random IV.
     #
-    # **NOTE**: In OpenSSL API conventions, the IV value may correspond to the
-    # "nonce" instead in some cipher modes. Refer to the OpenSSL man pages for
-    # details.
-    #
-    # See also the man page EVP_CipherInit_ex(3).
+    # Only call this method after calling Cipher#encrypt or Cipher#decrypt.
     #
     def iv=: (String iv) -> String
 
@@ -2673,20 +2623,17 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.iv_len = integer
+    #   - cipher.iv_len = integer -> integer
     # -->
-    # Sets the IV/nonce length for this Cipher. This method is available for AEAD
-    # ciphers that support variable IV lengths. This method can be called if a
-    # different IV length than OpenSSL's default is desired, prior to calling #iv=.
-    #
-    # See also the "AEAD Interface" section of the man page EVP_EncryptInit(3). This
-    # method internally calls EVP_CIPHER_CTX_ctrl() with EVP_CTRL_AEAD_SET_IVLEN.
+    # Sets the IV/nonce length of the Cipher. Normally block ciphers don't allow
+    # changing the IV length, but some make use of IV for 'nonce'. You may need this
+    # for interoperability with other applications.
     #
     def iv_len=: (Integer) -> Integer
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.key = string
+    #   - cipher.key = string -> string
     # -->
     # Sets the cipher key. To generate a key, you should either use a secure random
     # byte string or, if the key is to be derived from a password, you should rely
@@ -2695,8 +2642,6 @@ module OpenSSL
     #
     # Only call this method after calling Cipher#encrypt or Cipher#decrypt.
     #
-    # See also the man page EVP_CipherInit_ex(3).
-    #
     def key=: (String key) -> String
 
     # <!--
@@ -2709,7 +2654,7 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.key_len = integer
+    #   - cipher.key_len = integer -> integer
     # -->
     # Sets the key length of the cipher.  If the cipher is a fixed length cipher
     # then attempting to set the key length to any value other than the fixed value
@@ -2733,7 +2678,7 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.padding = 1 or 0
+    #   - cipher.padding = integer -> integer
     # -->
     # Enables or disables padding. By default encryption operations are padded using
     # standard block padding and the padding is checked and removed when decrypting.
@@ -2751,16 +2696,19 @@ module OpenSSL
     # -->
     # Generates and sets the key/IV based on a password.
     #
-    # **WARNING**: This method is deprecated and should not be used. This method
-    # corresponds to EVP_BytesToKey(), a non-standard OpenSSL extension of the
-    # legacy PKCS #5 v1.5 key derivation function. See OpenSSL::KDF for other
-    # options to derive keys from passwords.
+    # **WARNING**: This method is only PKCS5 v1.5 compliant when using RC2, RC4-40,
+    # or DES with MD5 or SHA1. Using anything else (like AES) will generate the
+    # key/iv using an OpenSSL specific method. This method is deprecated and should
+    # no longer be used. Use a PKCS5 v2 key generation method from OpenSSL::PKCS5
+    # instead.
     #
     # ### Parameters
     # *   *salt* must be an 8 byte string if provided.
     # *   *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
 
     # <!--
@@ -2807,9 +2755,6 @@ module OpenSSL
     # If *buffer* is given, the encryption/decryption result will be written to it.
     # *buffer* will be resized automatically.
     #
-    # **NOTE**: When decrypting using an AEAD cipher, the integrity of the output is
-    # not verified until #final has been called.
-    #
     def update: (String data, ?String buffer) -> String
 
     private
@@ -2918,7 +2863,7 @@ module OpenSSL
   # configuration. See the value of OpenSSL::Config::DEFAULT_CONFIG_FILE for the
   # location of the file for your host.
   #
-  # See also https://docs.openssl.org/master/man5/config/
+  # See also http://www.openssl.org/docs/apps/config.html
   #
   class Config
     include Enumerable[[ String, String, String ]]
@@ -5097,11 +5042,7 @@ module OpenSSL
   end
 
   # <!-- rdoc-file=ext/openssl/ossl.c -->
-  # Generic error class for OpenSSL. All error classes in this library inherit
-  # from this class.
-  #
-  # This class indicates that an error was reported by the underlying OpenSSL
-  # library.
+  # Generic error, common for all classes under OpenSSL module
   #
   class OpenSSLError < StandardError
   end
@@ -5701,12 +5642,11 @@ module OpenSSL
       def p: () -> BN
 
       # <!--
-      #   rdoc-file=ext/openssl/lib/openssl/pkey.rb
+      #   rdoc-file=ext/openssl/ossl_pkey_dh.c
       #   - dh.params -> hash
       # -->
-      # Stores all parameters of key to a Hash.
-      #
-      # The hash has keys 'p', 'q', 'g', 'pub_key', and 'priv_key'.
+      # 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?]
 
@@ -5858,8 +5798,7 @@ module OpenSSL
       #
       # If called without arguments, an empty instance without any parameter or key
       # components is created. Use #set_pqg to manually set the parameters afterwards
-      # (and optionally #set_key to set private and public key components). This form
-      # is not compatible with OpenSSL 3.0 or later.
+      # (and optionally #set_key to set private and public key components).
       #
       # If a String is given, tries to parse it as a DER- or PEM- encoded parameters.
       # See also OpenSSL::PKey.read which can parse keys of any kinds.
@@ -5878,15 +5817,14 @@ module OpenSSL
       #
       # Examples:
       #     # Creating an instance from scratch
-      #     # Note that this is deprecated and will result in ArgumentError when
-      #     # using OpenSSL 3.0 or later.
+      #     # Note that this is deprecated and will not work on OpenSSL 3.0 or later.
       #     dh = OpenSSL::PKey::DH.new
       #     dh.set_pqg(bn_p, nil, bn_g)
       #
       #     # Generating a parameters and a key pair
       #     dh = OpenSSL::PKey::DH.new(2048) # An alias of OpenSSL::PKey::DH.generate(2048)
       #
-      #     # Reading DH parameters from a PEM-encoded string
+      #     # Reading DH parameters
       #     dh_params = OpenSSL::PKey::DH.new(File.read('parameters.pem')) # loads parameters only
       #     dh = OpenSSL::PKey.generate_key(dh_params) # generates a key pair
       #
@@ -5998,12 +5936,11 @@ module OpenSSL
       def p: () -> BN
 
       # <!--
-      #   rdoc-file=ext/openssl/lib/openssl/pkey.rb
+      #   rdoc-file=ext/openssl/ossl_pkey_dsa.c
       #   - dsa.params -> hash
       # -->
-      # Stores all parameters of key to a Hash.
-      #
-      # The hash has keys 'p', 'q', 'g', 'pub_key', and 'priv_key'.
+      # 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?]
 
@@ -6253,8 +6190,7 @@ module OpenSSL
       # Creates a new DSA instance by reading an existing key from *string*.
       #
       # If called without arguments, creates a new instance with no key components
-      # set. They can be set individually by #set_pqg and #set_key. This form is not
-      # compatible with OpenSSL 3.0 or later.
+      # set. They can be set individually by #set_pqg and #set_key.
       #
       # If called with a String, tries to parse as DER or PEM encoding of a DSA key.
       # See also OpenSSL::PKey.read which can parse keys of any kinds.
@@ -6702,10 +6638,9 @@ module OpenSSL
 
         # <!--
         #   rdoc-file=ext/openssl/ossl_pkey_ec.c
-        #   - group.curve_name -> string or nil
+        #   - group.curve_name  => String
         # -->
-        # Returns the curve name (short name) corresponding to this group, or `nil` if
-        # OpenSSL does not have an OID associated with the group.
+        # Returns the curve name (sn).
         #
         # See the OpenSSL documentation for EC_GROUP_get_curve_name()
         #
@@ -6915,6 +6850,7 @@ module OpenSSL
         # <!--
         #   rdoc-file=ext/openssl/ossl_pkey_ec.c
         #   - point.mul(bn1 [, bn2]) => point
+        #   - point.mul(bns, points [, bn2]) => point
         # -->
         # Performs elliptic curve point multiplication.
         #
@@ -6922,9 +6858,10 @@ module OpenSSL
         # of the group of *point*. *bn2* may be omitted, and in that case, the result is
         # just `bn1 * point`.
         #
-        # Before version 4.0.0, and when compiled with OpenSSL 1.1.1 or older, this
-        # method allowed another form:
-        #     point.mul(bns, points [, bn2]) => point
+        # The second form calculates `bns[0] * point + bns[1] * points[0] + ... +
+        # bns[-1] * points[-1] + bn2 * G`. *bn2* may be omitted. *bns* must be an array
+        # 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) -> self
                | (Array[bn] bns, Array[self], ?bn bn2) -> self
@@ -7166,15 +7103,6 @@ module OpenSSL
     # <!-- rdoc-file=ext/openssl/ossl_pkey.c -->
     # Raised when errors occur during PKey#sign or PKey#verify.
     #
-    # Before version 4.0.0, OpenSSL::PKey::PKeyError had the following subclasses.
-    # These subclasses have been removed and the constants are now defined as
-    # aliases of OpenSSL::PKey::PKeyError.
-    #
-    # *   OpenSSL::PKey::DHError
-    # *   OpenSSL::PKey::DSAError
-    # *   OpenSSL::PKey::ECError
-    # *   OpenSSL::PKey::RSAError
-    #
     class PKeyError < OpenSSL::OpenSSLError
     end
 
@@ -7282,12 +7210,15 @@ module OpenSSL
       def p: () -> BN?
 
       # <!--
-      #   rdoc-file=ext/openssl/lib/openssl/pkey.rb
-      #   - rsa.params -> hash
+      #   rdoc-file=ext/openssl/ossl_pkey_rsa.c
+      #   - rsa.params => hash
       # -->
-      # Stores all parameters of key to a Hash.
+      # THIS METHOD IS INSECURE, PRIVATE INFORMATION CAN LEAK OUT!!!
       #
-      # The hash has keys 'n', 'e', 'd', 'p', 'q', 'dmp1', 'dmq1', and 'iqmp'.
+      # Stores all parameters of key to the hash.  The hash has keys 'n', 'e', 'd',
+      # 'p', 'q', 'dmp1', 'dmq1', 'iqmp'.
+      #
+      # Don't use :-)) (It's up to you)
       #
       def params: () -> Hash[String, BN?]
 
@@ -7412,7 +7343,7 @@ module OpenSSL
       # Signs *data* using the Probabilistic Signature Scheme (RSA-PSS) and returns
       # the calculated signature.
       #
-      # PKeyError will be raised if an error occurs.
+      # RSAError will be raised if an error occurs.
       #
       # See #verify_pss for the verification operation.
       #
@@ -7586,7 +7517,7 @@ module OpenSSL
       # Verifies *data* using the Probabilistic Signature Scheme (RSA-PSS).
       #
       # The return value is `true` if the signature is valid, `false` otherwise.
-      # PKeyError will be raised if an error occurs.
+      # RSAError will be raised if an error occurs.
       #
       # See #sign_pss for the signing operation and an example code.
       #
@@ -7620,7 +7551,7 @@ module OpenSSL
       #
       # If called without arguments, creates a new instance with no key components
       # set. They can be set individually by #set_key, #set_factors, and
-      # #set_crt_params. This form is not compatible with OpenSSL 3.0 or later.
+      # #set_crt_params.
       #
       # If called with a String, tries to parse as DER or PEM encoding of an RSA key.
       # Note that if *password* is not specified, but the key is encrypted with a
@@ -7655,17 +7586,10 @@ module OpenSSL
       SSLV23_PADDING: Integer
     end
 
-    # <!-- rdoc-file=ext/openssl/ossl_pkey.c -->
-    # Raised when errors occur during PKey#sign or PKey#verify.
-    #
-    # Before version 4.0.0, OpenSSL::PKey::PKeyError had the following subclasses.
-    # These subclasses have been removed and the constants are now defined as
-    # aliases of OpenSSL::PKey::PKeyError.
-    #
-    # *   OpenSSL::PKey::DHError
-    # *   OpenSSL::PKey::DSAError
-    # *   OpenSSL::PKey::ECError
-    # *   OpenSSL::PKey::RSAError
+    # <!-- rdoc-file=ext/openssl/ossl_pkey_rsa.c -->
+    # Generic exception that is raised if an operation on an RSA PKey fails
+    # unexpectedly or in case an instantiation of an instance of RSA fails due to
+    # non-conformant input data.
     #
     class RSAError < OpenSSL::PKey::PKeyError
     end
@@ -8105,14 +8029,9 @@ module OpenSSL
       #   - ctx.ciphers = [name, ...]
       #   - ctx.ciphers = [[name, version, bits, alg_bits], ...]
       # -->
-      # Sets the list of available cipher suites for TLS 1.2 and below for this
-      # context.
-      #
-      # Note in a server context some ciphers require the appropriate certificates.
-      # For example, an RSA cipher suite can only be chosen when an RSA certificate is
-      # available.
-      #
-      # This method does not affect TLS 1.3 connections. See also #ciphersuites=.
+      # Sets the list of available cipher suites for this context.  Note in a server
+      # context some ciphers require the appropriate certificates.  For example, an
+      # RSA cipher suite can only be chosen when an RSA certificate is available.
       #
       def ciphers=: (Array[[ String, String, Integer, Integer ]] ciphers) -> void
                   | (Array[String] ciphers) -> void
@@ -8148,25 +8067,24 @@ module OpenSSL
       #
       def client_cert_cb=: (^(Session) -> [ X509::Certificate, PKey::PKey ]? client_cert_cb) -> void
 
-      # <!-- rdoc-file=ext/openssl/ossl_ssl.c -->
-      # Sets the list of supported groups for key agreement for this context.
-      #
-      # For a TLS client, the list is directly used in the "supported_groups"
-      # extension. For a server, the list is used by OpenSSL to determine the set of
-      # shared supported groups. OpenSSL will pick the most appropriate one from it.
-      #
-      # #ecdh_curves= is a deprecated alias for #groups=.
+      # <!--
+      #   rdoc-file=ext/openssl/ossl_ssl.c
+      #   - ctx.ecdh_curves = curve_list -> curve_list
+      # -->
+      # Sets the list of "supported elliptic curves" for this context.
       #
-      # See also the man page SSL_CTX_set1_groups_list(3).
+      # For a TLS client, the list is directly used in the Supported Elliptic Curves
+      # Extension. For a server, the list is used by OpenSSL to determine the set of
+      # shared curves. OpenSSL will pick the most appropriate one from it.
       #
       # ### Example
       #     ctx1 = OpenSSL::SSL::SSLContext.new
-      #     ctx1.groups = "X25519:P-256:P-224"
+      #     ctx1.ecdh_curves = "X25519:P-256:P-224"
       #     svr = OpenSSL::SSL::SSLServer.new(tcp_svr, ctx1)
       #     Thread.new { svr.accept }
       #
       #     ctx2 = OpenSSL::SSL::SSLContext.new
-      #     ctx2.groups = "P-256"
+      #     ctx2.ecdh_curves = "P-256"
       #     cli = OpenSSL::SSL::SSLSocket.new(tcp_sock, ctx2)
       #     cli.connect
       #
@@ -8231,7 +8149,7 @@ module OpenSSL
       def key=: (PKey::PKey) -> PKey::PKey
 
       # <!--
-      #   rdoc-file=ext/openssl/ossl_ssl.c
+      #   rdoc-file=ext/openssl/lib/openssl/ssl.rb
       #   - ctx.max_version = OpenSSL::SSL::TLS1_2_VERSION
       #   - ctx.max_version = :TLS1_2
       #   - ctx.max_version = nil
@@ -8242,7 +8160,7 @@ module OpenSSL
       def max_version=: (tls_version version) -> tls_version
 
       # <!--
-      #   rdoc-file=ext/openssl/ossl_ssl.c
+      #   rdoc-file=ext/openssl/lib/openssl/ssl.rb
       #   - ctx.min_version = OpenSSL::SSL::TLS1_2_VERSION
       #   - ctx.min_version = :TLS1_2
       #   - ctx.min_version = nil
@@ -8251,6 +8169,9 @@ module OpenSSL
       # may be specified by an integer constant named OpenSSL::SSL::*_VERSION, a
       # Symbol, or `nil` which means "any version".
       #
+      # Be careful that you don't overwrite OpenSSL::SSL::OP_NO_{SSL,TLS}v* options by
+      # #options= once you have called #min_version= or #max_version=.
+      #
       # ### Example
       #     ctx = OpenSSL::SSL::SSLContext.new
       #     ctx.min_version = OpenSSL::SSL::TLS1_1_VERSION
@@ -8660,7 +8581,7 @@ module OpenSSL
       #
       def timeout=: (Integer) -> Integer
 
-      # <!-- rdoc-file=ext/openssl/ossl_ssl.c -->
+      # <!-- rdoc-file=ext/openssl/lib/openssl/ssl.rb -->
       # A callback invoked when DH parameters are required for ephemeral DH key
       # exchange.
       #
@@ -8674,7 +8595,7 @@ module OpenSSL
       #
       def tmp_dh_callback: () -> (^(Session, Integer, Integer) -> PKey::DH | nil)
 
-      # <!-- rdoc-file=ext/openssl/ossl_ssl.c -->
+      # <!-- rdoc-file=ext/openssl/lib/openssl/ssl.rb -->
       # A callback invoked when DH parameters are required for ephemeral DH key
       # exchange.
       #
@@ -9023,7 +8944,7 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_ssl.c
-      #   - ssl.client_ca => [x509name, ...] or nil
+      #   - ssl.client_ca => [x509name, ...]
       # -->
       # Returns the list of client CAs. Please note that in contrast to
       # SSLContext#client_ca= no array of X509::Certificate is returned but X509::Name
@@ -9594,33 +9515,65 @@ module OpenSSL
     #     fac.additional_certificates = [ inter1, inter2 ]
     #     timestamp = fac.create_timestamp(p12.key, p12.certificate, req)
     #
+    # ## Attributes
+    #
+    # ### default_policy_id
+    #
+    # Request#policy_id will always be preferred over this if present in the
+    # Request, only if Request#policy_id is nil default_policy will be used. If none
+    # of both is present, a TimestampError will be raised when trying to create a
+    # Response.
+    #
+    # call-seq:
+    #     factory.default_policy_id = "string" -> string
+    #     factory.default_policy_id            -> string or nil
+    #
+    # ### serial_number
+    #
+    # Sets or retrieves the serial number to be used for timestamp creation. Must be
+    # present for timestamp creation.
+    #
+    # call-seq:
+    #     factory.serial_number = number -> number
+    #     factory.serial_number          -> number or nil
+    #
+    # ### gen_time
+    #
+    # Sets or retrieves the Time value to be used in the Response. Must be present
+    # for timestamp creation.
+    #
+    # call-seq:
+    #     factory.gen_time = Time -> Time
+    #     factory.gen_time        -> Time or nil
+    #
+    # ### additional_certs
+    #
+    # Sets or retrieves additional certificates apart from the timestamp certificate
+    # (e.g. intermediate certificates) to be added to the Response. Must be an Array
+    # of OpenSSL::X509::Certificate.
+    #
+    # call-seq:
+    #     factory.additional_certs = [cert1, cert2] -> [ cert1, cert2 ]
+    #     factory.additional_certs                  -> array or nil
+    #
+    # ### allowed_digests
+    #
+    # Sets or retrieves the digest algorithms that the factory is allowed create
+    # timestamps for. Known vulnerable or weak algorithms should not be allowed
+    # where possible. Must be an Array of String or OpenSSL::Digest subclass
+    # instances.
+    #
+    # call-seq:
+    #     factory.allowed_digests = ["sha1", OpenSSL::Digest.new('SHA256').new] -> [ "sha1", OpenSSL::Digest) ]
+    #     factory.allowed_digests                                               -> array or nil
+    #
     class Factory
-      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
-      # Additional certificates apart from the timestamp certificate (e.g.
-      # intermediate certificates) to be added to the Response. Must be an Array of
-      # OpenSSL::X509::Certificate, or `nil`.
-      #
       def additional_certs: () -> Array[X509::Certificate]?
 
-      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
-      # Additional certificates apart from the timestamp certificate (e.g.
-      # intermediate certificates) to be added to the Response. Must be an Array of
-      # OpenSSL::X509::Certificate, or `nil`.
-      #
       def additional_certs=: (Array[X509::Certificate]? certs) -> Array[X509::Certificate]?
 
-      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
-      # The list of digest algorithms that the factory is allowed create timestamps
-      # for. Known vulnerable or weak algorithms should not be allowed where possible.
-      # Must be an Array of String or OpenSSL::Digest subclass instances.
-      #
       def allowed_digests: () -> Array[String | Digest]?
 
-      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
-      # The list of digest algorithms that the factory is allowed create timestamps
-      # for. Known vulnerable or weak algorithms should not be allowed where possible.
-      # Must be an Array of String or OpenSSL::Digest subclass instances.
-      #
       def allowed_digests=: (Array[String | Digest]) -> Array[String | Digest]
 
       # <!--
@@ -9649,48 +9602,16 @@ module OpenSSL
       #
       def create_timestamp: (PKey::PKey key, X509::Certificate cert, Request request) -> Response
 
-      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
-      # A String representing the default policy object identifier, or `nil`.
-      #
-      # Request#policy_id will always be preferred over this if present in the
-      # Request, only if Request#policy_id is `nil` default_policy will be used. If
-      # none of both is present, a TimestampError will be raised when trying to create
-      # a Response.
-      #
       def default_policy_id: () -> String?
 
-      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
-      # A String representing the default policy object identifier, or `nil`.
-      #
-      # Request#policy_id will always be preferred over this if present in the
-      # Request, only if Request#policy_id is `nil` default_policy will be used. If
-      # none of both is present, a TimestampError will be raised when trying to create
-      # a Response.
-      #
       def default_policy_id=: (String) -> String
 
-      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
-      # The Time value to be used in the Response. Must be present for timestamp
-      # creation.
-      #
       def gen_time: () -> Time?
 
-      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
-      # The Time value to be used in the Response. Must be present for timestamp
-      # creation.
-      #
       def gen_time=: (Time) -> Time
 
-      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
-      # The serial number to be used for timestamp creation. Must be present for
-      # timestamp creation. Must be an instance of OpenSSL::BN or Integer.
-      #
       def serial_number: () -> Integer?
 
-      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
-      # The serial number to be used for timestamp creation. Must be present for
-      # timestamp creation. Must be an instance of OpenSSL::BN or Integer.
-      #
       def serial_number=: (Integer) -> Integer
     end
 
@@ -10384,10 +10305,8 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509attr.c
-      #   - attr.oid -> string
+      #   - attr.oid => string
       # -->
-      # Returns the OID of the attribute. Returns the short name or the dotted decimal
-      # notation.
       #
       def oid: () -> String
 
@@ -10549,12 +10468,8 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509crl.c
-      #   - crl.signature_algorithm -> string
+      #   - signature_algorithm()
       # -->
-      # Returns the signature algorithm used to sign this CRL.
-      #
-      # Returns the long name of the signature algorithm, or the dotted decimal
-      # notation if OpenSSL does not define a long name for it.
       #
       def signature_algorithm: () -> String
 
@@ -10734,12 +10649,6 @@ module OpenSSL
       # Compares the two certificates. Note that this takes into account all fields,
       # not just the issuer name and the serial number.
       #
-      # This method uses X509_cmp() from OpenSSL, which compares certificates based on
-      # their cached DER encodings. The comparison can be unreliable if a certificate
-      # is incomplete.
-      #
-      # See also the man page X509_cmp(3).
-      #
       def ==: (self other) -> bool
 
       # <!--
@@ -10773,7 +10682,7 @@ module OpenSSL
       def extensions=: (Array[Extension]) -> Array[Extension]
 
       # <!--
-      #   rdoc-file=ext/openssl/lib/openssl/x509.rb
+      #   rdoc-file=ext/openssl/ossl_x509cert.c
       #   - inspect()
       # -->
       #
@@ -10867,12 +10776,6 @@ module OpenSSL
       #   rdoc-file=ext/openssl/ossl_x509cert.c
       #   - cert.signature_algorithm => string
       # -->
-      # Returns the signature algorithm used to sign this certificate. This returns
-      # the algorithm name found in the TBSCertificate structure, not the outer
-      # Certificate structure.
-      #
-      # Returns the long name of the signature algorithm, or the dotted decimal
-      # notation if OpenSSL does not define a long name for it.
       #
       def signature_algorithm: () -> String
 
@@ -10990,10 +10893,8 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509ext.c
-      #   - ext.oid -> string
+      #   - oid()
       # -->
-      # Returns the OID of the extension. Returns the short name or the dotted decimal
-      # notation.
       #
       def oid: () -> String
 
@@ -11646,12 +11547,8 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509req.c
-      #   - req.signature_algorithm -> string
+      #   - signature_algorithm()
       # -->
-      # Returns the signature algorithm used to sign this request.
-      #
-      # Returns the long name of the signature algorithm, or the dotted decimal
-      # notation if OpenSSL does not define a long name for it.
       #
       def signature_algorithm: () -> String