rbs 3.9.5 → 3.10.0

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 SSLContext is used to set up an SSL session.
+# An OpenSSL::SSL::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 SSLServer with a TCP server socket and the context.  Use the
-# SSLServer like an ordinary TCP server.
+# Then create an OpenSSL::SSL::SSLServer with a TCP server socket and the
+# context.  Use the SSLServer like an ordinary TCP server.
 #
 #     require 'socket'
 #
@@ -401,12 +401,13 @@
 #
 # ### SSL client
 #
-# 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.
+# 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.
 #
-# Note that SSLSocket#close doesn't close the underlying socket by default. Set
-# SSLSocket#sync_close to true if you want.
+# 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.
 #
 #     require 'socket'
 #
@@ -455,7 +456,7 @@ module OpenSSL
   #     OpenSSL::Digest("MD5")
   #     # => OpenSSL::Digest::MD5
   #
-  #     Digest("Foo")
+  #     OpenSSL::Digest("Foo")
   #     # => NameError: wrong constant name Foo
   #
   def self.Digest: (String name) -> singleton(Digest)
@@ -464,12 +465,13 @@ 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 -> boolean
+  #   - OpenSSL.debug = boolean
   # -->
   # Turns on or off debug mode. With debug mode, all errors added to the OpenSSL
   # error queue will be printed to stderr.
@@ -480,10 +482,14 @@ module OpenSSL
   #   rdoc-file=ext/openssl/ossl.c
   #   - OpenSSL.errors -> [String...]
   # -->
-  # See any remaining errors held in queue.
+  # Returns any remaining errors held in the OpenSSL thread-local error queue and
+  # clears the queue. This should normally return an empty array.
   #
-  # Any errors you see here are probably due to a bug in Ruby's OpenSSL
-  # implementation.
+  # 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.
   #
   def self.errors: () -> Array[String]
 
@@ -491,12 +497,13 @@ 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 -> boolean
+  #   - OpenSSL.fips_mode = 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
@@ -510,57 +517,74 @@ module OpenSSL
 
   # <!--
   #   rdoc-file=ext/openssl/ossl.c
-  #   - OpenSSL.fixed_length_secure_compare(string, string) -> boolean
+  #   - OpenSSL.fixed_length_secure_compare(string, string) -> true or false
   # -->
   # 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) -> boolean
+  #   - OpenSSL.secure_compare(string, string) -> true or false
   # -->
   # 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 OpenSSL is FIPS-capable or not
+  # 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.
   #
   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 -->
-  # Version of OpenSSL the ruby OpenSSL extension was built with
+  # OpenSSL library version string used to compile the Ruby/OpenSSL extension.
+  # This may differ from the version used at runtime.
   #
   OPENSSL_VERSION: String
 
   # <!-- rdoc-file=ext/openssl/ossl.c -->
-  # Version number of OpenSSL the ruby OpenSSL extension was built with (base 16).
-  # The formats are below.
+  # OpenSSL library version number used to compile the Ruby/OpenSSL extension.
+  # This may differ from the version used at runtime.
   #
-  # OpenSSL 3
-  # :   `0xMNN00PP0 (major minor 00 patch 0)`
+  # The version number is encoded into a single integer value. The number follows
+  # the format:
   #
-  # OpenSSL before 3
-  # :   `0xMNNFFPPS (major minor fix patch status)`
+  # OpenSSL 3.0.0 or later
+  # :   `0xMNN00PP0` (major minor 00 patch 0)
+  #
+  # OpenSSL 1.1.1 or earlier
+  # :   `0xMNNFFPPS` (major minor fix patch status)
   #
   # LibreSSL
-  # :   `0x20000000 (fixed value)`
+  # :   `0x20000000` (a 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 -->
@@ -931,7 +955,7 @@ module OpenSSL
     #     puts int2.value # => 1
     #
     class ASN1Data
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # 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.
@@ -948,7 +972,7 @@ module OpenSSL
       #
       def indefinite_length: () -> bool
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # 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.
@@ -965,7 +989,7 @@ module OpenSSL
       #
       def indefinite_length=: [U] (boolish) -> U
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # 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 +1006,7 @@ module OpenSSL
       #
       alias infinite_length indefinite_length
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # 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,24 +1023,24 @@ module OpenSSL
       #
       alias infinite_length= indefinite_length=
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # An Integer representing the tag number of this ASN1Data. Never `nil`.
       #
       def tag: () -> bn
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # An Integer representing the tag number of this ASN1Data. Never `nil`.
       #
       def tag=: (::Integer) -> ::Integer
               | (BN) -> BN
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # 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/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # A Symbol representing the tag class of this ASN1Data. Never `nil`. See
       # ASN1Data for possible values.
       #
@@ -1033,13 +1057,13 @@ module OpenSSL
       #
       def to_der: () -> String
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # 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/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # Carries the value of a ASN.1 type. Please confer Constructive and Primitive
       # for the mappings between ASN.1 data types and Ruby classes.
       #
@@ -1048,7 +1072,7 @@ module OpenSSL
       private
 
       # <!--
-      #   rdoc-file=ext/openssl/lib/openssl/asn1.rb
+      #   rdoc-file=ext/openssl/ossl_asn1.c
       #   - OpenSSL::ASN1::ASN1Data.new(value, tag, tag_class) => ASN1Data
       # -->
       # *value*: Please have a look at Constructive and Primitive to see how Ruby
@@ -1120,7 +1144,7 @@ module OpenSSL
       include Enumerable[ASN1Data]
 
       # <!--
-      #   rdoc-file=ext/openssl/lib/openssl/asn1.rb
+      #   rdoc-file=ext/openssl/ossl_asn1.c
       #   - asn1_ary.each { |asn1| block } => asn1_ary
       # -->
       # Calls the given block once for each element in self, passing that element as
@@ -2428,24 +2452,28 @@ module OpenSSL
   # prevents malicious modifications of the ciphertext that could otherwise be
   # exploited to modify ciphertexts in ways beneficial to potential attackers.
   #
-  # 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.
+  # 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 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 # produces 16 bytes tag by default
+  #     tag = cipher.auth_tag(16)
   #
   # 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
@@ -2458,13 +2486,17 @@ module OpenSSL
   #     decipher = OpenSSL::Cipher.new('aes-128-gcm').decrypt
   #     decipher.key = key
   #     decipher.iv = nonce
-  #     decipher.auth_tag = tag
+  #     decipher.auth_tag = tag # could be called at any time before #final
   #     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
@@ -2476,21 +2508,22 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - 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.
+    #   - 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.
     #
     def auth_data=: (String) -> String
 
@@ -2498,42 +2531,54 @@ module OpenSSL
     #   rdoc-file=ext/openssl/ossl_cipher.c
     #   - cipher.auth_tag(tag_len = 16) -> String
     # -->
-    # 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.
+    # 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.
     #
-    # The tag may only be retrieved after calling Cipher#final.
+    # 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.
     #
     def auth_tag: (?Integer tag_len) -> String
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.auth_tag = string -> string
+    #   - cipher.auth_tag = string
     # -->
-    # 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.
+    # 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.
     #
-    # For OCB mode, the tag length must be supplied with #auth_tag_len= beforehand.
+    # **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.
     #
     def auth_tag=: (String) -> String
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.auth_tag_len = Integer -> Integer
+    #   - cipher.auth_tag_len = integer
     # -->
-    # 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.
+    # 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.
     #
-    # In OCB mode, the length must be supplied both when encrypting and when
-    # decrypting, and must be before specifying an 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_TAG and a
+    # NULL buffer.
     #
     def auth_tag_len=: (Integer) -> Integer
 
@@ -2541,7 +2586,7 @@ module OpenSSL
     #   rdoc-file=ext/openssl/ossl_cipher.c
     #   - cipher.authenticated? -> true | false
     # -->
-    # Indicated whether this Cipher instance uses an Authenticated Encryption mode.
+    # Indicates whether this Cipher instance uses an AEAD mode.
     #
     def authenticated?: () -> bool
 
@@ -2559,11 +2604,9 @@ module OpenSSL
     # -->
     # Initializes the Cipher for decryption.
     #
-    # Make sure to call Cipher#encrypt or Cipher#decrypt before using any of the
-    # following methods:
+    # Make sure to call either #encrypt or #decrypt before using the Cipher for any
+    # operation or setting any parameters.
     #
-    #     #key=, #iv=, #random_key, #random_iv, #pkcs5_keyivgen
-    # :
     # Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, 0).
     #
     def decrypt: () -> self
@@ -2574,11 +2617,9 @@ module OpenSSL
     # -->
     # Initializes the Cipher for encryption.
     #
-    # Make sure to call Cipher#encrypt or Cipher#decrypt before using any of the
-    # following methods:
+    # Make sure to call either #encrypt or #decrypt before using the Cipher for any
+    # operation or setting any parameters.
     #
-    #     #key=, #iv=, #random_key, #random_iv, #pkcs5_keyivgen
-    # :
     # Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, 1).
     #
     def encrypt: () -> self
@@ -2588,28 +2629,37 @@ module OpenSSL
     #   - cipher.final -> string
     # -->
     # Returns the remaining data held in the cipher object. Further calls to
-    # 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.
+    # 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.
     #
-    # 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.
+    # 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.
     #
     def final: () -> String
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.iv = string -> string
+    #   - cipher.iv = 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, but it should be unpredictable
-    # to prevent certain kinds of attacks. You may use Cipher#random_iv to create a
-    # secure random IV.
+    # IV itself can be safely transmitted in public.
     #
-    # Only call this method after calling Cipher#encrypt or Cipher#decrypt.
+    # 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.
+    #
+    # **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).
     #
     def iv=: (String iv) -> String
 
@@ -2623,17 +2673,20 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.iv_len = integer -> integer
+    #   - cipher.iv_len = integer
     # -->
-    # 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.
+    # 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.
     #
     def iv_len=: (Integer) -> Integer
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.key = string -> string
+    #   - cipher.key = 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
@@ -2642,6 +2695,8 @@ 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
 
     # <!--
@@ -2654,7 +2709,7 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.key_len = integer -> integer
+    #   - cipher.key_len = 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
@@ -2678,7 +2733,7 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.padding = integer -> integer
+    #   - cipher.padding = 1 or 0
     # -->
     # Enables or disables padding. By default encryption operations are padded using
     # standard block padding and the padding is checked and removed when decrypting.
@@ -2696,19 +2751,16 @@ module OpenSSL
     # -->
     # Generates and sets the key/IV based on a password.
     #
-    # **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.
+    # **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.
     #
     # ### 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
 
     # <!--
@@ -2755,6 +2807,9 @@ 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
@@ -2863,7 +2918,7 @@ module OpenSSL
   # configuration. See the value of OpenSSL::Config::DEFAULT_CONFIG_FILE for the
   # location of the file for your host.
   #
-  # See also http://www.openssl.org/docs/apps/config.html
+  # See also https://docs.openssl.org/master/man5/config/
   #
   class Config
     include Enumerable[[ String, String, String ]]
@@ -5042,7 +5097,11 @@ module OpenSSL
   end
 
   # <!-- rdoc-file=ext/openssl/ossl.c -->
-  # Generic error, common for all classes under OpenSSL module
+  # 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.
   #
   class OpenSSLError < StandardError
   end
@@ -5642,11 +5701,12 @@ module OpenSSL
       def p: () -> BN
 
       # <!--
-      #   rdoc-file=ext/openssl/ossl_pkey_dh.c
+      #   rdoc-file=ext/openssl/lib/openssl/pkey.rb
       #   - dh.params -> hash
       # -->
-      # Stores all parameters of key to the hash INSECURE: PRIVATE INFORMATIONS CAN
-      # LEAK OUT!!! Don't use :-)) (I's up to you)
+      # Stores all parameters of key to a Hash.
+      #
+      # The hash has keys 'p', 'q', 'g', 'pub_key', and 'priv_key'.
       #
       def params: () -> Hash[String, BN?]
 
@@ -5798,7 +5858,8 @@ 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).
+      # (and optionally #set_key to set private and public key components). This form
+      # is not compatible with OpenSSL 3.0 or later.
       #
       # 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.
@@ -5817,14 +5878,15 @@ module OpenSSL
       #
       # Examples:
       #     # Creating an instance from scratch
-      #     # Note that this is deprecated and will not work on OpenSSL 3.0 or later.
+      #     # Note that this is deprecated and will result in ArgumentError when
+      #     # using 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
+      #     # Reading DH parameters from a PEM-encoded string
       #     dh_params = OpenSSL::PKey::DH.new(File.read('parameters.pem')) # loads parameters only
       #     dh = OpenSSL::PKey.generate_key(dh_params) # generates a key pair
       #
@@ -5936,11 +5998,12 @@ module OpenSSL
       def p: () -> BN
 
       # <!--
-      #   rdoc-file=ext/openssl/ossl_pkey_dsa.c
+      #   rdoc-file=ext/openssl/lib/openssl/pkey.rb
       #   - dsa.params -> hash
       # -->
-      # Stores all parameters of key to the hash INSECURE: PRIVATE INFORMATIONS CAN
-      # LEAK OUT!!! Don't use :-)) (I's up to you)
+      # Stores all parameters of key to a Hash.
+      #
+      # The hash has keys 'p', 'q', 'g', 'pub_key', and 'priv_key'.
       #
       def params: () -> Hash[String, BN?]
 
@@ -6190,7 +6253,8 @@ 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.
+      # set. They can be set individually by #set_pqg and #set_key. This form is not
+      # compatible with OpenSSL 3.0 or later.
       #
       # 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.
@@ -6638,9 +6702,10 @@ module OpenSSL
 
         # <!--
         #   rdoc-file=ext/openssl/ossl_pkey_ec.c
-        #   - group.curve_name  => String
+        #   - group.curve_name -> string or nil
         # -->
-        # Returns the curve name (sn).
+        # Returns the curve name (short name) corresponding to this group, or `nil` if
+        # OpenSSL does not have an OID associated with the group.
         #
         # See the OpenSSL documentation for EC_GROUP_get_curve_name()
         #
@@ -6850,7 +6915,6 @@ 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.
         #
@@ -6858,10 +6922,9 @@ module OpenSSL
         # of the group of *point*. *bn2* may be omitted, and in that case, the result is
         # just `bn1 * 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]`.
+        # 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
         #
         def mul: (bn bn1, ?bn bn2) -> self
                | (Array[bn] bns, Array[self], ?bn bn2) -> self
@@ -7103,6 +7166,15 @@ 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
 
@@ -7210,15 +7282,12 @@ module OpenSSL
       def p: () -> BN?
 
       # <!--
-      #   rdoc-file=ext/openssl/ossl_pkey_rsa.c
-      #   - rsa.params => hash
+      #   rdoc-file=ext/openssl/lib/openssl/pkey.rb
+      #   - rsa.params -> hash
       # -->
-      # THIS METHOD IS INSECURE, PRIVATE INFORMATION CAN LEAK OUT!!!
+      # Stores all parameters of key to a Hash.
       #
-      # 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)
+      # The hash has keys 'n', 'e', 'd', 'p', 'q', 'dmp1', 'dmq1', and 'iqmp'.
       #
       def params: () -> Hash[String, BN?]
 
@@ -7343,7 +7412,7 @@ module OpenSSL
       # Signs *data* using the Probabilistic Signature Scheme (RSA-PSS) and returns
       # the calculated signature.
       #
-      # RSAError will be raised if an error occurs.
+      # PKeyError will be raised if an error occurs.
       #
       # See #verify_pss for the verification operation.
       #
@@ -7517,7 +7586,7 @@ module OpenSSL
       # Verifies *data* using the Probabilistic Signature Scheme (RSA-PSS).
       #
       # The return value is `true` if the signature is valid, `false` otherwise.
-      # RSAError will be raised if an error occurs.
+      # PKeyError will be raised if an error occurs.
       #
       # See #sign_pss for the signing operation and an example code.
       #
@@ -7551,7 +7620,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.
+      # #set_crt_params. This form is not compatible with OpenSSL 3.0 or later.
       #
       # 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
@@ -7586,10 +7655,17 @@ module OpenSSL
       SSLV23_PADDING: Integer
     end
 
-    # <!-- 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.
+    # <!-- 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 RSAError < OpenSSL::PKey::PKeyError
     end
@@ -8029,9 +8105,14 @@ module OpenSSL
       #   - ctx.ciphers = [name, ...]
       #   - ctx.ciphers = [[name, version, bits, alg_bits], ...]
       # -->
-      # 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.
+      # 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=.
       #
       def ciphers=: (Array[[ String, String, Integer, Integer ]] ciphers) -> void
                   | (Array[String] ciphers) -> void
@@ -8067,24 +8148,25 @@ module OpenSSL
       #
       def client_cert_cb=: (^(Session) -> [ X509::Certificate, PKey::PKey ]? client_cert_cb) -> void
 
-      # <!--
-      #   rdoc-file=ext/openssl/ossl_ssl.c
-      #   - ctx.ecdh_curves = curve_list -> curve_list
-      # -->
-      # Sets the list of "supported elliptic curves" for this context.
+      # <!-- 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=.
       #
-      # 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.
+      # See also the man page SSL_CTX_set1_groups_list(3).
       #
       # ### Example
       #     ctx1 = OpenSSL::SSL::SSLContext.new
-      #     ctx1.ecdh_curves = "X25519:P-256:P-224"
+      #     ctx1.groups = "X25519:P-256:P-224"
       #     svr = OpenSSL::SSL::SSLServer.new(tcp_svr, ctx1)
       #     Thread.new { svr.accept }
       #
       #     ctx2 = OpenSSL::SSL::SSLContext.new
-      #     ctx2.ecdh_curves = "P-256"
+      #     ctx2.groups = "P-256"
       #     cli = OpenSSL::SSL::SSLSocket.new(tcp_sock, ctx2)
       #     cli.connect
       #
@@ -8149,7 +8231,7 @@ module OpenSSL
       def key=: (PKey::PKey) -> PKey::PKey
 
       # <!--
-      #   rdoc-file=ext/openssl/lib/openssl/ssl.rb
+      #   rdoc-file=ext/openssl/ossl_ssl.c
       #   - ctx.max_version = OpenSSL::SSL::TLS1_2_VERSION
       #   - ctx.max_version = :TLS1_2
       #   - ctx.max_version = nil
@@ -8160,7 +8242,7 @@ module OpenSSL
       def max_version=: (tls_version version) -> tls_version
 
       # <!--
-      #   rdoc-file=ext/openssl/lib/openssl/ssl.rb
+      #   rdoc-file=ext/openssl/ossl_ssl.c
       #   - ctx.min_version = OpenSSL::SSL::TLS1_2_VERSION
       #   - ctx.min_version = :TLS1_2
       #   - ctx.min_version = nil
@@ -8169,9 +8251,6 @@ 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
@@ -8581,7 +8660,7 @@ module OpenSSL
       #
       def timeout=: (Integer) -> Integer
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/ssl.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_ssl.c -->
       # A callback invoked when DH parameters are required for ephemeral DH key
       # exchange.
       #
@@ -8595,7 +8674,7 @@ module OpenSSL
       #
       def tmp_dh_callback: () -> (^(Session, Integer, Integer) -> PKey::DH | nil)
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/ssl.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_ssl.c -->
       # A callback invoked when DH parameters are required for ephemeral DH key
       # exchange.
       #
@@ -8944,7 +9023,7 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_ssl.c
-      #   - ssl.client_ca => [x509name, ...]
+      #   - ssl.client_ca => [x509name, ...] or nil
       # -->
       # 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
@@ -9515,65 +9594,33 @@ 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]
 
       # <!--
@@ -9602,16 +9649,48 @@ 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
 
@@ -10305,8 +10384,10 @@ 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
 
@@ -10468,8 +10549,12 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509crl.c
-      #   - signature_algorithm()
+      #   - crl.signature_algorithm -> string
       # -->
+      # 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
 
@@ -10649,6 +10734,12 @@ 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
 
       # <!--
@@ -10682,7 +10773,7 @@ module OpenSSL
       def extensions=: (Array[Extension]) -> Array[Extension]
 
       # <!--
-      #   rdoc-file=ext/openssl/ossl_x509cert.c
+      #   rdoc-file=ext/openssl/lib/openssl/x509.rb
       #   - inspect()
       # -->
       #
@@ -10776,6 +10867,12 @@ 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
 
@@ -10893,8 +10990,10 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509ext.c
-      #   - oid()
+      #   - ext.oid -> string
       # -->
+      # Returns the OID of the extension. Returns the short name or the dotted decimal
+      # notation.
       #
       def oid: () -> String
 
@@ -11547,8 +11646,12 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509req.c
-      #   - signature_algorithm()
+      #   - req.signature_algorithm -> string
       # -->
+      # 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