rbs 3.9.5 → 3.10.0.pre.1

data/stdlib/openssl/0/openssl.rbs

@@ -536,6 +536,9 @@ module OpenSSL
   #
   OPENSSL_FIPS: bool
 
+  # <!-- rdoc-file=ext/openssl/ossl.c -->
+  # Version of OpenSSL the ruby OpenSSL extension is running with
+  #
   OPENSSL_LIBRARY_VERSION: String
 
   # <!-- rdoc-file=ext/openssl/ossl.c -->
@@ -2428,24 +2431,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 +2465,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 +2487,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 +2510,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 +2565,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 +2583,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 +2596,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 +2608,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 +2652,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 +2674,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 +2688,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 +2712,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 +2730,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 +2786,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 +2897,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 ]]
@@ -5642,11 +5676,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 +5833,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 +5853,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 +5973,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 +6228,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.
@@ -6850,7 +6889,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 +6896,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 +7140,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 +7256,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 the hash.  The hash has keys 'n', 'e', 'd',
-      # 'p', 'q', 'dmp1', 'dmq1', 'iqmp'.
+      # Stores all parameters of key to a Hash.
       #
-      # 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 +7386,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 +7560,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 +7594,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 +7629,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 +8079,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 +8122,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 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.
+      # 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=.
+      #
+      # 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 +8205,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 +8216,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 +8225,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 +8634,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 +8648,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 +8997,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
@@ -9524,38 +9577,22 @@ module OpenSSL
     # 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
@@ -9563,10 +9600,6 @@ module OpenSSL
     # 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
       def additional_certs: () -> Array[X509::Certificate]?