mongo 2.26.1 → 2.26.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 39d9792c95b149dbbcb1b065df222c345eea9c84912e03de9a8994d7aea32ab8
4
- data.tar.gz: b491401e88ffde8324e802267b35f75f6f92997f5746b3634612e1a9d63f11e8
3
+ metadata.gz: a4dfa71c9688fae83124ffe96a6140aa3311f1d39f40463da86a7f4daed87d74
4
+ data.tar.gz: cbaf4ce8e9f68ab04e5f72770b66765d83cddf3daddec159fae022dbf711e687
5
5
  SHA512:
6
- metadata.gz: aad7e612834dd20849a707f6fde3d5a8101765af93df37eee119ad0418dd518b738ec8834689f0aeac267ac117aab2f89f84362f0c588f8714b96c1c87c286ef
7
- data.tar.gz: 6a1c05b23598ac63e37267393de256bd0f2d250f14e881e2fda7a436a2ee2775d60e61d076c4fbaaa77230e7135f89095c55a737edca13a3434f048fdf8aa5db
6
+ metadata.gz: 0138b1673aeccd44470a08f6ec2226dc8cca34665bedb0b30351f8f46f05a5fa98390602478d2a22365c253067dc8552f81a78d5c859d98f42c1058275832621
7
+ data.tar.gz: e992ad9fce6e2470ecfbc5565b79a339ceff6178a4719307bbeafad9dc49ec51bf543fb0a59f8d9bf949815dcdae1c34e373c1db4a0e882fa74df2abba8808c7
@@ -20,6 +20,12 @@ module Mongo
20
20
  module Validator
21
21
  # Takes an address string in ipv4/ipv6/hostname/socket path format and
22
22
  # validates its format.
23
+ #
24
+ # Error messages describe the component at fault without quoting the
25
+ # address: a malformed connection string may not have had its
26
+ # credentials delimited, in which case the text being validated is
27
+ # itself the credential. See "Disclosure of Sensitive Values" in the
28
+ # connection string specification.
23
29
  def validate_address_str!(address_str)
24
30
  case address_str
25
31
  when /\A\[[\d:]+\](?::(\d+))?\z/
@@ -41,19 +47,18 @@ module Mongo
41
47
  # Not a host:port nor an ipv4 address with optional port.
42
48
  # Possibly botched ipv6 address with e.g. port delimiter present and
43
49
  # port missing, or extra junk before or after.
44
- raise Error::InvalidAddress,
45
- "Invalid hostname: #{address_str}"
50
+ raise Error::InvalidAddress, 'Invalid host identifier.'
46
51
  when /:.*:/m
47
52
  raise Error::InvalidAddress,
48
- "Multiple port delimiters are not allowed: #{address_str}"
53
+ 'Multiple port delimiters are not allowed in the host identifier.'
49
54
  else
50
55
  # host:port or ipv4 address with optional port number
51
56
  host, port = address_str.split(':')
52
- raise Error::InvalidAddress, "Host is empty: #{address_str}" if host.empty?
57
+ raise Error::InvalidAddress, 'Host is empty.' if host.empty?
53
58
 
54
59
  validate_hostname!(host)
55
60
 
56
- raise Error::InvalidAddress, "Port is empty: #{address_str}" if port && port.empty?
61
+ raise Error::InvalidAddress, 'Port is empty.' if port && port.empty?
57
62
 
58
63
  validate_port_str!(port)
59
64
  end
@@ -72,18 +77,18 @@ module Mongo
72
77
  # and runs of multiple dots. DNS resolution of SRV records yields
73
78
  # hostnames with trailing dots, those trailing dots are removed
74
79
  # during normalization process prior to validation.
75
- raise Error::InvalidAddress, "Hostname cannot start with a dot: #{host}" if host.start_with?('.')
76
- raise Error::InvalidAddress, "Hostname cannot end with a dot: #{host}" if host.end_with?('.')
80
+ raise Error::InvalidAddress, 'Hostname cannot start with a dot.' if host.start_with?('.')
81
+ raise Error::InvalidAddress, 'Hostname cannot end with a dot.' if host.end_with?('.')
77
82
  return unless host.include?('..')
78
83
 
79
- raise Error::InvalidAddress, "Runs of multiple dots are not allowed in hostname: #{host}"
84
+ raise Error::InvalidAddress, 'Runs of multiple dots are not allowed in a hostname.'
80
85
  end
81
86
 
82
87
  def validate_port_str!(port)
83
88
  return if port.nil? || (port.length > 0 && port.to_i > 0 && port.to_i <= 65_535)
84
89
 
85
90
  raise Error::InvalidAddress,
86
- "Invalid port: #{port}. Port must be an integer greater than 0 and less than 65536"
91
+ 'Invalid port. Port must be an integer greater than 0 and less than 65536'
87
92
  end
88
93
  end
89
94
  end
data/lib/mongo/auth.rb CHANGED
@@ -109,17 +109,22 @@ module Mongo
109
109
  class InvalidMechanism < InvalidConfiguration
110
110
  # Instantiate the new error.
111
111
  #
112
+ # The mechanism is not included in the message: an unrecognized value
113
+ # comes from the connection string and may contain text the user
114
+ # intended as a credential. The known mechanisms are listed so the
115
+ # message stays actionable.
116
+ #
112
117
  # @example Instantiate the error.
113
118
  # Mongo::Auth::InvalidMechanism.new(:test)
114
119
  #
115
- # @param [ Symbol ] mechanism The provided mechanism.
120
+ # @param [ Symbol | String | nil ] _mechanism The provided mechanism.
116
121
  #
117
122
  # @since 2.0.0
118
- def initialize(mechanism)
123
+ def initialize(_mechanism = nil)
119
124
  known_mechanisms = SOURCES.keys.sort.map do |key|
120
125
  key.inspect
121
126
  end.join(', ')
122
- super("#{mechanism.inspect} is invalid, please use one of the following mechanisms: #{known_mechanisms}")
127
+ super("Invalid authentication mechanism, please use one of the following mechanisms: #{known_mechanisms}")
123
128
  end
124
129
  end
125
130
 
data/lib/mongo/client.rb CHANGED
@@ -531,6 +531,18 @@ module Mongo
531
531
  # encryption key cache, in milliseconds. Must be a non-negative
532
532
  # integer. A value of 0 means the cache never expires. Defaults to
533
533
  # 60000.
534
+ # - :kms_connect_callback => Proc | Method | #call | nil, a callable
535
+ # invoked as call(host, port, timeout_ms) when the driver needs to
536
+ # reach a KMS host. It must return an fd-backed IO (a real IO or Socket)
537
+ # already connected to host:port (for example, after performing an HTTP
538
+ # CONNECT handshake with a proxy). The driver wraps the returned object
539
+ # in TLS to the KMS host, and Ruby's OpenSSL requires an fd-backed
540
+ # object, so the callback cannot return another OpenSSL::SSL::SSLSocket;
541
+ # a TLS-to-proxy connection needs a socketpair bridge. The driver
542
+ # bounds the call by the connect budget, so a callback that blocks
543
+ # cannot outlive the operation; the callback should still honor
544
+ # timeout_ms for its own work. See Mongo::ClientEncryption#initialize
545
+ # for a usage example.
534
546
  #
535
547
  # Notes on automatic encryption:
536
548
  # - Automatic encryption is an enterprise only feature that only applies
@@ -1345,9 +1357,10 @@ module Mongo
1345
1357
  processed[:addresses] = addresses
1346
1358
  processed[:options] = options
1347
1359
 
1348
- addresses.each do |addr|
1360
+ addresses.each_with_index do |addr, index|
1349
1361
  if %r{\Amongodb(\+srv)?://}i.match?(addr)
1350
- raise ArgumentError, "Host '#{addr}' should not contain protocol. Did you mean to not use an array?"
1362
+ raise ArgumentError, "Host at index #{index} should not contain protocol. " \
1363
+ 'Did you mean to not use an array?'
1351
1364
  end
1352
1365
  end
1353
1366
 
@@ -1496,6 +1509,9 @@ module Mongo
1496
1509
  _options[key] = compressors unless compressors.empty?
1497
1510
  elsif key == :srv_max_hosts
1498
1511
  if v && (!v.is_a?(Integer) || v < 0)
1512
+ # A value for srv_max_hosts that is not a non-negative integer
1513
+ # can only come from the Ruby options: the URI converter drops
1514
+ # such values. It is therefore safe to report it.
1499
1515
  log_warn("#{v} is not a valid integer for srv_max_hosts")
1500
1516
  else
1501
1517
  _options[key] = v
@@ -1541,12 +1557,12 @@ module Mongo
1541
1557
  connect = options[:connect]&.to_sym
1542
1558
 
1543
1559
  if connect && !%i[direct replica_set sharded load_balanced].include?(connect)
1544
- raise ArgumentError, "Invalid :connect option value: #{connect}"
1560
+ raise ArgumentError, 'Invalid :connect option value'
1545
1561
  end
1546
1562
 
1547
1563
  if options[:direct_connection]
1548
1564
  if connect && connect != :direct
1549
- raise ArgumentError, "Conflicting client options: direct_connection=true and connect=#{connect}"
1565
+ raise ArgumentError, 'Conflicting client options: direct_connection=true and a connect option other than direct'
1550
1566
  end
1551
1567
  # When a new client is created, we get the list of seed addresses
1552
1568
  if addresses && addresses.length > 1
@@ -1572,7 +1588,7 @@ module Mongo
1572
1588
  end
1573
1589
 
1574
1590
  if connect && connect != :load_balanced
1575
- raise ArgumentError, "connect=#{connect} cannot be used with load_balanced=true"
1591
+ raise ArgumentError, 'A connect option other than load_balanced cannot be used with load_balanced=true'
1576
1592
  end
1577
1593
 
1578
1594
  raise ArgumentError, 'load_balanced=true cannot be used with replica_set option' if options[:replica_set]
@@ -1587,7 +1603,7 @@ module Mongo
1587
1603
  end
1588
1604
 
1589
1605
  if options[:direct_connection] == false && connect && connect == :direct
1590
- raise ArgumentError, "Conflicting client options: direct_connection=false and connect=#{connect}"
1606
+ raise ArgumentError, 'Conflicting client options: direct_connection=false and connect=direct'
1591
1607
  end
1592
1608
 
1593
1609
  %i[connect_timeout socket_timeout].each do |key|
@@ -1681,6 +1697,18 @@ module Mongo
1681
1697
  raise Mongo::Auth::InvalidConfiguration, "Password is required for auth mechanism #{auth_mech}"
1682
1698
  end
1683
1699
 
1700
+ if auth_mech == :plain
1701
+ if user.include?("\0")
1702
+ raise Mongo::Auth::InvalidConfiguration,
1703
+ 'PLAIN authentication username cannot contain NUL characters'
1704
+ end
1705
+
1706
+ if password.include?("\0")
1707
+ raise Mongo::Auth::InvalidConfiguration,
1708
+ 'PLAIN authentication password cannot contain NUL characters'
1709
+ end
1710
+ end
1711
+
1684
1712
  if password && auth_mech == :mongodb_x509
1685
1713
  raise Mongo::Auth::InvalidConfiguration, 'Password is not supported for :mongodb_x509 auth mechanism'
1686
1714
  end
@@ -1693,7 +1721,7 @@ module Mongo
1693
1721
  if %i[aws gssapi mongodb_x509].include?(auth_mech)
1694
1722
  unless [ '$external', nil ].include?(auth_source)
1695
1723
  raise Mongo::Auth::InvalidConfiguration,
1696
- "#{auth_source} is an invalid auth source for #{auth_mech}; valid options are $external and nil"
1724
+ "Invalid auth source for #{auth_mech}; valid options are $external and nil"
1697
1725
  end
1698
1726
  elsif auth_source == ''
1699
1727
  # Auth source is the database name, and thus cannot be the empty string.
@@ -1712,7 +1740,7 @@ module Mongo
1712
1740
 
1713
1741
  true
1714
1742
  else
1715
- log_warn("Unsupported compressor '#{compressor}' in list '#{compressors}'. " +
1743
+ log_warn('Unsupported compressor in the compressors list. ' +
1716
1744
  'This compressor will not be used.')
1717
1745
  false
1718
1746
  end
@@ -1769,6 +1797,9 @@ module Mongo
1769
1797
  # for custom classes implementing key access ([]).
1770
1798
  # Instead reject common cases of strings and symbols.
1771
1799
  if read.is_a?(String) || read.is_a?(Symbol)
1800
+ # Only a Ruby option can be a bare string or symbol here: URI
1801
+ # parsing always produces a Hash for the read preference. It is
1802
+ # therefore safe to include the value in the message.
1772
1803
  raise Error::InvalidReadOption.new(read,
1773
1804
  "the read preference must be specified as a hash: { mode: #{read.inspect} }")
1774
1805
  end
@@ -1776,7 +1807,7 @@ module Mongo
1776
1807
  if (mode = read[:mode])
1777
1808
  mode = mode.to_sym
1778
1809
  unless Mongo::ServerSelector::PREFERENCES.include?(mode)
1779
- raise Error::InvalidReadOption.new(read, "mode #{mode} is not one of recognized modes")
1810
+ raise Error::InvalidReadOption.new(read, 'the mode is not one of the recognized modes')
1780
1811
  end
1781
1812
  end
1782
1813
  end
@@ -46,6 +46,51 @@ module Mongo
46
46
  # encryption key cache, in milliseconds. Must be a non-negative integer.
47
47
  # An explicit value of 0 means the cache never expires. The default is
48
48
  # 60000.
49
+ # @option options [ Proc | Method | #call ] :kms_connect_callback A callable
50
+ # invoked as +call(host, port, timeout_ms)+ when the driver needs to reach
51
+ # a KMS host. It must return an fd-backed IO (a real +IO+ or +Socket+)
52
+ # already connected to +host:port+ (for example, after performing an HTTP
53
+ # CONNECT handshake with a proxy). The driver wraps the returned object in
54
+ # TLS to the KMS host, and Ruby's OpenSSL requires an fd-backed object, so
55
+ # the callback cannot return another +OpenSSL::SSL::SSLSocket+; a
56
+ # TLS-to-proxy connection needs a socketpair bridge (see the example
57
+ # below). The driver bounds the call by the connect budget (the remaining
58
+ # operation timeout, or the driver's connect timeout when no timeout is
59
+ # set), so a callback that blocks cannot outlive the operation. The
60
+ # callback should still honor +timeout_ms+ for its own work, so it can
61
+ # fail cleanly and close any socket it opened.
62
+ #
63
+ # @example Tunnel KMS traffic through an HTTP CONNECT proxy.
64
+ # connect_via_proxy = lambda do |host, port, timeout_ms|
65
+ # timeout = timeout_ms ? timeout_ms / 1_000.0 : nil
66
+ # socket = Socket.tcp('proxy.example.com', 9004, connect_timeout: timeout)
67
+ # begin
68
+ # socket.write("CONNECT #{host}:#{port} HTTP/1.1\r\n" \
69
+ # "Host: #{host}:#{port}\r\n\r\n")
70
+ # status = socket.gets
71
+ # unless status&.start_with?('HTTP/1.1 200')
72
+ # raise "proxy CONNECT failed: #{status.inspect}"
73
+ # end
74
+ #
75
+ # # Consume the rest of the response headers up to the blank line, so
76
+ # # the TLS handshake does not read them as tunneled bytes.
77
+ # loop do
78
+ # line = socket.gets
79
+ # break if line.nil? || line == "\r\n"
80
+ # end
81
+ # rescue StandardError
82
+ # socket.close
83
+ # raise
84
+ # end
85
+ # socket
86
+ # end
87
+ #
88
+ # client_encryption = Mongo::ClientEncryption.new(
89
+ # key_vault_client,
90
+ # key_vault_namespace: 'keyvault.datakeys',
91
+ # kms_providers: { aws: { access_key_id: '...', secret_access_key: '...' } },
92
+ # kms_connect_callback: connect_via_proxy
93
+ # )
49
94
  #
50
95
  # @raise [ ArgumentError ] If required options are missing or incorrectly
51
96
  # formatted.
@@ -56,7 +101,8 @@ module Mongo
56
101
  Crypt::KMS::Credentials.new(options[:kms_providers]),
57
102
  Crypt::KMS::Validations.validate_tls_options(options[:kms_tls_options]),
58
103
  options[:timeout_ms],
59
- options[:key_expiration_ms]
104
+ options[:key_expiration_ms],
105
+ options[:kms_connect_callback]
60
106
  )
61
107
  end
62
108
 
@@ -90,7 +90,7 @@ module Mongo
90
90
  connect = options[:connect]&.to_sym
91
91
  cls = if options[:direct_connection]
92
92
  if connect && connect != :direct
93
- raise ArgumentError, "Conflicting topology options: direct_connection=true and connect=#{connect}"
93
+ raise ArgumentError, 'Conflicting topology options: direct_connection=true and a connect option other than direct'
94
94
  end
95
95
  if options[:load_balanced]
96
96
  raise ArgumentError, 'Conflicting topology options: direct_connection=true and load_balanced=true'
@@ -98,11 +98,11 @@ module Mongo
98
98
 
99
99
  Single
100
100
  elsif options[:direct_connection] == false && connect && connect == :direct
101
- raise ArgumentError, "Conflicting topology options: direct_connection=false and connect=#{connect}"
101
+ raise ArgumentError, 'Conflicting topology options: direct_connection=false and connect=direct'
102
102
  elsif connect && connect != :load_balanced
103
103
  if options[:load_balanced]
104
104
  raise ArgumentError,
105
- "Conflicting topology options: connect=#{options[:connect].inspect} and load_balanced=true"
105
+ 'Conflicting topology options: a connect option other than load_balanced and load_balanced=true'
106
106
  end
107
107
 
108
108
  OPTIONS.fetch(options[:connect].to_sym)
@@ -84,6 +84,19 @@ module Mongo
84
84
  # @option options [ Integer | nil ] :key_expiration_ms The lifetime of the
85
85
  # data encryption key cache, in milliseconds. A value of 0 means the
86
86
  # cache never expires. Defaults to 60000.
87
+ # @option options [ Proc | Method | #call ] :kms_connect_callback A callable
88
+ # invoked as +call(host, port, timeout_ms)+ when the driver needs to
89
+ # reach a KMS host. It must return an fd-backed IO (a real +IO+ or
90
+ # +Socket+) already connected to +host:port+ (for example, after
91
+ # performing an HTTP CONNECT handshake with a proxy). The driver wraps
92
+ # the returned object in TLS to the KMS host, and Ruby's OpenSSL
93
+ # requires an fd-backed object, so the callback cannot return another
94
+ # +OpenSSL::SSL::SSLSocket+; a TLS-to-proxy connection needs a socketpair
95
+ # bridge. +timeout_ms+ is the remaining operation timeout in
96
+ # milliseconds, or nil when no timeout is set. The driver bounds the
97
+ # call by the connect budget, so a callback that blocks cannot outlive
98
+ # the operation; the callback should still honor +timeout_ms+ for its
99
+ # own work. See Mongo::ClientEncryption#initialize for a usage example.
87
100
  #
88
101
  # @raise [ ArgumentError ] If required options are missing or incorrectly
89
102
  # formatted.
@@ -134,7 +147,8 @@ module Mongo
134
147
  key_vault_namespace: @options[:key_vault_namespace],
135
148
  key_vault_client: @key_vault_client,
136
149
  metadata_client: @metadata_client,
137
- mongocryptd_options: @mongocryptd_options
150
+ mongocryptd_options: @mongocryptd_options,
151
+ kms_connect_callback: @options[:kms_connect_callback]
138
152
  )
139
153
  rescue StandardError
140
154
  begin
@@ -95,7 +95,7 @@ module Mongo
95
95
  when :need_mongo_markings
96
96
  provide_markings(timeout_ms)
97
97
  when :need_kms
98
- feed_kms
98
+ feed_kms(timeout_holder)
99
99
  when :need_kms_credentials
100
100
  Binding.ctx_provide_kms_providers(
101
101
  self,
@@ -158,14 +158,27 @@ module Mongo
158
158
  mongocrypt_done
159
159
  end
160
160
 
161
- def feed_kms
161
+ # Sends KMS requests to the KMS provider(s) on behalf of libmongocrypt,
162
+ # retrying transient failures in place.
163
+ #
164
+ # The remaining timeout budget is recomputed for every request: the state
165
+ # machine can need several KMS contexts, and a single context can be
166
+ # retried, so a budget snapshotted once per state-machine iteration would
167
+ # let later attempts run past the operation deadline.
168
+ #
169
+ # @param [ CsotTimeoutHolder ] timeout_holder CSOT timeouts for the
170
+ # operation.
171
+ #
172
+ # @raise [ Error::TimeoutError ] If the operation deadline has passed.
173
+ def feed_kms(timeout_holder)
162
174
  while (kms_context = Binding.ctx_next_kms_ctx(self))
163
175
  begin
164
176
  delay = Binding.kms_ctx_usleep(kms_context)
165
- sleep(delay / 1_000_000.0) unless delay.nil?
177
+ sleep_before_kms_request(delay, timeout_holder) unless delay.nil?
178
+ timeout_ms = timeout_holder.remaining_timeout_ms!
166
179
  provider = Binding.kms_ctx_get_kms_provider(kms_context)
167
180
  tls_options = @mongocrypt_handle.kms_tls_options(provider)
168
- @encryption_io.feed_kms(kms_context, tls_options)
181
+ @encryption_io.feed_kms(kms_context, tls_options, timeout_ms: timeout_ms)
169
182
  rescue Error::KmsError => e
170
183
  raise unless e.network_error?
171
184
  next if Binding.kms_ctx_fail(kms_context)
@@ -176,6 +189,19 @@ module Mongo
176
189
  Binding.ctx_kms_done(self)
177
190
  end
178
191
 
192
+ # Sleep for the backoff libmongocrypt asks for before the next KMS
193
+ # request, clamped so the wait never runs past the operation deadline.
194
+ #
195
+ # @param [ Integer ] delay_us The requested backoff, in microseconds.
196
+ # @param [ CsotTimeoutHolder ] timeout_holder CSOT timeouts for the
197
+ # operation.
198
+ def sleep_before_kms_request(delay_us, timeout_holder)
199
+ delay_sec = delay_us / 1_000_000.0
200
+ remaining_sec = timeout_holder.remaining_timeout_sec
201
+ delay_sec = remaining_sec if remaining_sec && remaining_sec < delay_sec
202
+ sleep(delay_sec) if delay_sec.positive?
203
+ end
204
+
179
205
  # Raise a KmsError that wraps the KMS status message (which describes the
180
206
  # retry exhaustion) with the error from the last attempt.
181
207
  #
@@ -40,6 +40,10 @@ module Mongo
40
40
  # @param [ String ] key_vault_namespace The key vault namespace in the format
41
41
  # db_name.collection_name.
42
42
  # @param [ Hash ] mongocryptd_options Options related to mongocryptd.
43
+ # @param [ Proc | nil ] kms_connect_callback Optional callable that
44
+ # establishes the TCP connection to a KMS provider. It is invoked with
45
+ # the host, port, and operation timeout in milliseconds (or nil), and
46
+ # must return an IO connected to the host.
43
47
  #
44
48
  # @option mongocryptd_options [ Boolean ] :mongocryptd_bypass_spawn
45
49
  # @option mongocryptd_options [ String ] :mongocryptd_spawn_path
@@ -52,10 +56,13 @@ module Mongo
52
56
  # @note This class expects that the key_vault_client and key_vault_namespace
53
57
  # options are not nil and are in the correct format.
54
58
  def initialize(
55
- key_vault_namespace:, key_vault_client:, metadata_client:, client: nil, mongocryptd_client: nil, mongocryptd_options: {}
59
+ key_vault_namespace:, key_vault_client:, metadata_client:, client: nil, mongocryptd_client: nil, mongocryptd_options: {}, kms_connect_callback: nil
56
60
  )
57
61
  validate_key_vault_client!(key_vault_client)
58
62
  validate_key_vault_namespace!(key_vault_namespace)
63
+ if kms_connect_callback && !kms_connect_callback.respond_to?(:call)
64
+ raise ArgumentError, 'kms_connect_callback must respond to :call'
65
+ end
59
66
 
60
67
  @client = client
61
68
  @mongocryptd_client = mongocryptd_client
@@ -63,6 +70,7 @@ module Mongo
63
70
  @key_vault_client = key_vault_client
64
71
  @metadata_client = metadata_client
65
72
  @options = mongocryptd_options
73
+ @kms_connect_callback = kms_connect_callback
66
74
  end
67
75
 
68
76
  # Query for keys in the key vault collection using the provided
@@ -163,15 +171,25 @@ module Mongo
163
171
  # Must be a non-negative integer. An explicit value of 0 means infinite.
164
172
  # The default value is unset which means the feature is not enabled.
165
173
  def feed_kms(kms_context, tls_options, timeout_ms: nil)
166
- with_ssl_socket(kms_context.endpoint, tls_options) do |ssl_socket|
167
- Timeout.timeout(timeout_ms || SOCKET_TIMEOUT, Error::SocketTimeoutError,
174
+ # When a budget is in effect the TLS handshake, the request write, and
175
+ # every read chunk share a single deadline, so a slow, chunked response
176
+ # cannot run for a multiple of the budget. Without a budget each phase
177
+ # keeps the fixed SOCKET_TIMEOUT fallback. Timeout.timeout takes
178
+ # seconds, but timeout_ms is in milliseconds.
179
+ deadline = Utils.monotonic_time + (timeout_ms / 1_000.0) if timeout_ms
180
+ # Use the CSOT-appropriate error class when a timeout budget is
181
+ # in effect, otherwise preserve the historical SocketTimeoutError.
182
+ timeout_error = timeout_ms ? Error::TimeoutError : Error::SocketTimeoutError
183
+
184
+ with_ssl_socket(kms_context.endpoint, tls_options, timeout_ms: timeout_ms) do |ssl_socket|
185
+ Timeout.timeout(remaining_timeout(deadline), timeout_error,
168
186
  'Socket write operation timed out') do
169
187
  ssl_socket.syswrite(kms_context.message)
170
188
  end
171
189
 
172
190
  bytes_needed = kms_context.bytes_needed
173
191
  while bytes_needed > 0
174
- bytes = Timeout.timeout(timeout_ms || SOCKET_TIMEOUT, Error::SocketTimeoutError,
192
+ bytes = Timeout.timeout(remaining_timeout(deadline), timeout_error,
175
193
  'Socket read operation timed out') do
176
194
  ssl_socket.sysread(bytes_needed)
177
195
  end
@@ -252,6 +270,38 @@ module Mongo
252
270
 
253
271
  private
254
272
 
273
+ # The time left, in seconds, before the shared KMS exchange deadline.
274
+ # When no operation budget is in effect there is no deadline, so each
275
+ # phase falls back to the fixed SOCKET_TIMEOUT.
276
+ #
277
+ # @param [ Float, nil ] deadline The monotonic time the exchange must
278
+ # finish by, or nil when no budget is set.
279
+ #
280
+ # @return [ Float ] The number of seconds left before the deadline.
281
+ #
282
+ # @raise [ Error::TimeoutError ] If the deadline has already passed.
283
+ def remaining_timeout(deadline)
284
+ return SOCKET_TIMEOUT if deadline.nil?
285
+
286
+ remaining = deadline - Utils.monotonic_time
287
+ raise Error::TimeoutError, 'KMS request timed out' if remaining <= 0
288
+
289
+ remaining
290
+ end
291
+
292
+ # The budget for the connect phase, in seconds: the remaining operation
293
+ # timeout when a CSOT budget is in effect, otherwise the driver's fixed
294
+ # connect timeout. The connect callback and the TLS handshake that
295
+ # follows it share this budget, so neither can run past the deadline.
296
+ #
297
+ # @param [ Integer, nil ] timeout_ms The remaining operation timeout in
298
+ # milliseconds, or nil when no budget is set.
299
+ #
300
+ # @return [ Float ] The connect budget in seconds.
301
+ def connect_budget(timeout_ms)
302
+ timeout_ms ? timeout_ms / 1_000.0 : Server::CONNECT_TIMEOUT
303
+ end
304
+
255
305
  def validate_key_vault_client!(key_vault_client)
256
306
  raise ArgumentError.new('The :key_vault_client option cannot be nil') unless key_vault_client
257
307
 
@@ -345,24 +395,60 @@ module Mongo
345
395
  # executing
346
396
  def with_ssl_socket(endpoint, tls_options, timeout_ms: nil)
347
397
  csot = !timeout_ms.nil?
348
- address = begin
349
- host, port = endpoint.split(':')
350
- port ||= 443 # All supported KMS APIs use this port by default.
351
- Address.new([ host, port ].join(':'))
352
- end
353
- socket_options = { ssl: true, csot: csot }.tap do |opts|
354
- opts[:connect_timeout] = (timeout_ms / 1_000.0) if csot
355
- end
356
- mongo_socket = address.socket(
357
- SOCKET_TIMEOUT,
358
- tls_options.merge(socket_options)
359
- )
398
+ host, port = endpoint.split(':')
399
+ port = (port || 443).to_i
400
+
401
+ mongo_socket =
402
+ if @kms_connect_callback
403
+ # The callback runs before any socket exists, so it cannot inherit
404
+ # the connect timeout the socket gets below; bound it explicitly by
405
+ # the connect budget so a callback that blocks cannot outlive the
406
+ # operation deadline. A well-behaved callback should still honor
407
+ # timeout_ms itself, so it can fail cleanly and close its socket.
408
+ connect_budget_sec = connect_budget(timeout_ms)
409
+ connect_deadline = Utils.monotonic_time + connect_budget_sec
410
+ connect_error = csot ? Error::TimeoutError : Error::SocketTimeoutError
411
+ connected_socket =
412
+ Timeout.timeout(connect_budget_sec, connect_error,
413
+ 'KMS connect callback timed out') do
414
+ @kms_connect_callback.call(host, port, timeout_ms)
415
+ end
416
+ unless connected_socket.is_a?(IO)
417
+ raise Error::KmsError.new(
418
+ 'kms_connect_callback must return an IO connected to the KMS provider ' +
419
+ "at #{host}:#{port}, but it returned #{connected_socket.inspect}"
420
+ )
421
+ end
422
+
423
+ # The callback and the handshake share one connect budget: give the
424
+ # handshake only the time the callback left, so together they cannot
425
+ # run past the deadline.
426
+ remaining_connect = connect_deadline - Utils.monotonic_time
427
+ raise connect_error, 'KMS connect timed out' if remaining_connect <= 0
428
+
429
+ socket_options = { ssl: true, csot: csot, connected_socket: connected_socket }
430
+ socket_options[:connect_timeout] = remaining_connect
431
+ Mongo::Socket::SSL.new(
432
+ host, port, host, SOCKET_TIMEOUT, ::Socket::AF_UNSPEC,
433
+ tls_options.merge(socket_options)
434
+ )
435
+ else
436
+ address = Address.new([ host, port ].join(':'))
437
+ socket_options = { ssl: true, csot: csot }.tap do |opts|
438
+ opts[:connect_timeout] = (timeout_ms / 1_000.0) if csot
439
+ end
440
+ address.socket(SOCKET_TIMEOUT, tls_options.merge(socket_options))
441
+ end
442
+
360
443
  yield(mongo_socket.socket)
361
444
  rescue Error::KmsError
362
445
  raise
363
446
  rescue StandardError => e
447
+ # A timeout is not a transient network failure: retrying it only spends
448
+ # more of the operation budget, and under CSOT the deadline has already
449
+ # passed, so let it surface instead of letting feed_kms retry.
364
450
  raise Error::KmsError.new("Error when connecting to KMS provider: #{e.class}: #{e.message}",
365
- network_error: true)
451
+ network_error: !e.is_a?(Error::TimeoutError))
366
452
  ensure
367
453
  mongo_socket&.close
368
454
  end
@@ -40,9 +40,12 @@ module Mongo
40
40
  # @param [ Integer | nil ] key_expiration_ms The lifetime of the data
41
41
  # encryption key cache, in milliseconds. A value of 0 means the cache
42
42
  # never expires. When nil, libmongocrypt's default of 60000 is used.
43
+ # @param [ Proc | Method | #call | nil ] kms_connect_callback A callable
44
+ # invoked as +call(host, port, timeout_ms)+ when the driver needs to
45
+ # reach a KMS host. See Mongo::ClientEncryption for details.
43
46
  def initialize(
44
47
  key_vault_client, key_vault_namespace, kms_providers, kms_tls_options,
45
- timeout_ms = nil, key_expiration_ms = nil
48
+ timeout_ms = nil, key_expiration_ms = nil, kms_connect_callback = nil
46
49
  )
47
50
  Crypt.validate_ffi!
48
51
  @crypt_handle = Handle.new(
@@ -54,7 +57,8 @@ module Mongo
54
57
  @encryption_io = EncryptionIO.new(
55
58
  key_vault_client: key_vault_client,
56
59
  metadata_client: nil,
57
- key_vault_namespace: key_vault_namespace
60
+ key_vault_namespace: key_vault_namespace,
61
+ kms_connect_callback: kms_connect_callback
58
62
  )
59
63
  @timeout_ms = timeout_ms
60
64
  end
@@ -54,12 +54,15 @@ module Mongo
54
54
 
55
55
  # @return [ Integer | nil ] Returns the remaining milliseconds of the timeout
56
56
  # set for the operation; if no timeout is set, or the timeout is 0
57
- # (means unlimited) returns nil.
57
+ # (means unlimited) returns nil. A finite budget never rounds down to 0,
58
+ # since 0 means unlimited to callers: the last sub-millisecond before the
59
+ # deadline is reported as 1 ms instead.
58
60
  def remaining_timeout_ms
59
61
  seconds = remaining_timeout_sec
60
62
  return nil if seconds.nil?
61
63
 
62
- (seconds * 1_000).to_i
64
+ ms = (seconds * 1_000).to_i
65
+ ms.zero? ? 1 : ms
63
66
  end
64
67
 
65
68
  def remaining_timeout_ms!
@@ -23,12 +23,19 @@ module Mongo
23
23
  class InvalidReadOption < Error
24
24
  # Instantiate the new exception.
25
25
  #
26
+ # The value is not included in the message: it may come from the
27
+ # connection string and can contain text the user intended as a
28
+ # credential.
29
+ #
26
30
  # @example Instantiate the exception.
27
31
  # Mongo::Error::InvalidReadOption.new({:mode => 'bogus'})
28
32
  #
33
+ # @param [ Object ] _read_option The provided read option.
34
+ # @param [ String ] msg Description of the problem.
35
+ #
29
36
  # @since 2.6.0
30
- def initialize(read_option, msg)
31
- super("Invalid read preference value: #{read_option.inspect}: #{msg}")
37
+ def initialize(_read_option, msg)
38
+ super("Invalid read preference value: #{msg}")
32
39
  end
33
40
  end
34
41
  end