net-smtp 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbf12984985ffef0271f09805060b2cfa5e72eb3955c8ce51ee8076b427e1a02
-  data.tar.gz: 17c6420b495abe8b17446b1e667681b2680b02d894b3ce1e4ef6cffaa26ad1df
+  metadata.gz: 1fcccbe34b29672c33aa7515de88e88dba31882e26a4b6c0a5fc30c5a4eb697d
+  data.tar.gz: 5c47e6453d2cb69365edc7b4e31b17106b73e254e1bc10258f4b14ea780ba889
 SHA512:
-  metadata.gz: 4d9372a9673256cc280600a1367a0c92bed91250209736b4b54c7219c115b1006e9fc66d465367729f53ef393b9a8077b33f11f7578365d9cb84051e44b86976
-  data.tar.gz: 0f7da80c1d40216684ff0927637b14dfb5597638913a0aa3a8f2ca68a3fc89724926736c719715171b7bcab915a9504016f10356b2622bc6da9e5f51238f8e52
+  metadata.gz: 6576c5b7dc21982576fa6c3a6e08641e973136148d5d5bcb27fe1e17b4e5fdd802c5f5a6f9f116dd15bf4f2a0e5f95f071ca19d47119cf60c7da9230a64d3a4c
+  data.tar.gz: 9b1c54b2d9a48e384d3b1a67f1aa8b8a2614a383dc31b83d49170f3ed93d69a2058f3c310f72d443f54a0947c1066249105087a1a3addc92965c289354c8156a

data/NEWS.md

@@ -0,0 +1,133 @@
+# NEWS
+
+## Version 0.5.0 (2024-03-27)
+
+### Improvements
+
+* Allow case-insensitive strings for SASL mechanism <https://github.com/ruby/net-smtp/pull/64>
+* Make #auth_capable? public <https://github.com/ruby/net-smtp/pull/63>
+* Add XOAUTH2 authenticator <https://github.com/ruby/net-smtp/pull/80>
+
+### Others
+
+* Remove unused private auth_method <https://github.com/ruby/net-smtp/pull/67>
+* Delegate checking auth args to the authenticator <https://github.com/ruby/net-smtp/pull/73>
+* Updated docs, especially TLS and SASL-related <https://github.com/ruby/net-smtp/pull/66>
+* Renew test certificates <https://github.com/ruby/net-smtp/pull/75>
+* Fix version extraction to work with non ASCII characters with any LANG <https://github.com/ruby/net-smtp/pull/76>
+* Replace non-ASCII EM DASH (U+2014) with ASCII hyphen (U+002D) <https://github.com/ruby/net-smtp/pull/78>
+* Use reusing workflow for Ruby versions <https://github.com/ruby/net-smtp/pull/79>
+* Make the test suite compatible with --enable-frozen-string-literal <https://github.com/ruby/net-smtp/pull/81>
+
+## Version 0.4.0 (2023-09-20)
+
+### Improvements
+
+* add Net::SMTP::Authenticator class and auth_* methods are separated from the Net::SMTP class. <https://github.com/ruby/net-smtp/pull/53>
+      This allows you to add a new authentication method to Net::SMTP.
+      Create a class with an `auth` method that inherits Net::SMTP::Authenticator.
+      The `auth` method has two arguments, `user` and `secret`.
+      Send an instruction to the SMTP server by using the `continue` or `finish` method.
+      For more information, see lib/net/smtp/auto _*.rb.
+* Add SMTPUTF8 support <https://github.com/ruby/net-smtp/pull/49>
+
+### Fixes
+
+* Revert "Replace Timeout.timeout with socket timeout" <https://github.com/ruby/net-smtp/pull/51>
+* Fixed issue sending emails to unaffected recipients on 53x error <https://github.com/ruby/net-smtp/pull/56>
+
+### Others
+
+* Removed unnecessary Subversion keywords <https://github.com/ruby/net-smtp/pull/57>
+
+## Version 0.3.3 (2022-10-29)
+
+* No timeout library required <https://github.com/ruby/net-smtp/pull/44>
+* Make the digest library optional <https://github.com/ruby/net-smtp/pull/45>
+
+## Version 0.3.2 (2022-09-28)
+
+* Make exception API compatible with what Ruby expects <https://github.com/ruby/net-smtp/pull/42>
+
+## Version 0.3.1 (2021-12-12)
+
+### Improvements
+
+* add Net::SMTP::Address.
+* add Net::SMTP#capable? and Net::SMTP#capabilities.
+* add Net::SMTP#tls_verify, Net::SMTP#tls_hostname, Net::SMTP#ssl_context_params
+
+## Version 0.3.0 (2021-10-14)
+
+### Improvements
+
+* Add `tls`, `starttls` keyword arguments.
+    ```ruby
+    # always use TLS connection for port 465.
+    Net::SMTP.start(hostname, 465, tls: true)
+
+    # do not use starttls for localhost
+    Net::SMTP.start('localhost', starttls: false)
+    ```
+
+### Incompatible changes
+
+* The tls_* paramter has been moved from start() to initialize().
+
+## Version 0.2.2 (2021-10-09)
+
+* Add `response` to SMTPError exceptions.
+* `Net::SMTP.start()` and `#start()` accepts `ssl_context_params` keyword argument.
+* Replace `Timeout.timeout` with socket timeout.
+* Remove needless files from gem.
+* Add dependency on digest, timeout.
+
+## Version 0.2.1 (2020-11-18)
+
+### Fixes
+
+* Update the license for the default gems to dual licenses.
+* Add dependency for net-protocol.
+
+## Version 0.2.0 (2020-11-15)
+
+### Incompatible changes
+
+* Verify the server's certificate by default.
+  If you don't want verification, specify `start(tls_verify: false)`.
+  <https://github.com/ruby/net-smtp/pull/12>
+
+* Use STARTTLS by default if possible.
+  If you don't want starttls, specify:
+      ```
+      smtp = Net::SMTP.new(hostname, port)
+      smtp.disable_starttls
+      smtp.start do |s|
+        s.send_message ....
+      end
+      ```
+  <https://github.com/ruby/net-smtp/pull/9>
+
+### Improvements
+
+* Net::SMTP.start and Net::SMTP#start arguments are keyword arguments.
+      ```
+      start(address, port = nil, helo: 'localhost', user: nil, secret: nil, authtype: nil) { |smtp| ... }
+      ```
+  `password` is an alias of `secret`.
+  <https://github.com/ruby/net-smtp/pull/7>
+
+* Add `tls_hostname` parameter to `start()`.
+  If you want to use a different hostname than the certificate for the connection, you can specify the certificate hostname with `tls_hostname`.
+  <https://github.com/ruby/net-smtp/pull/14>
+
+* Add SNI support to net/smtp <https://github.com/ruby/net-smtp/pull/4>
+
+### Fixes
+
+* enable_starttls before disable_tls causes an error. <https://github.com/ruby/net-smtp/pull/10>
+* TLS should not check the hostname when verify_mode is disabled. <https://github.com/ruby/net-smtp/pull/6>
+
+## Version 0.1.0 (2019-12-03)
+
+This is the first release of net-smtp gem.

data/README.md

@@ -0,0 +1,97 @@
+# Net::SMTP
+
+This library provides functionality to send internet mail via SMTP, the Simple Mail Transfer Protocol.
+
+For details of SMTP itself, see [RFC2821](http://www.ietf.org/rfc/rfc2821.txt).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'net-smtp'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install net-smtp
+
+## Usage
+
+### Sending Messages
+
+You must open a connection to an SMTP server before sending messages.
+The first argument is the address of your SMTP server, and the second
+argument is the port number. Using SMTP.start with a block is the simplest
+way to do this. This way, the SMTP connection is closed automatically
+after the block is executed.
+
+```ruby
+require 'net/smtp'
+Net::SMTP.start('your.smtp.server', 25) do |smtp|
+  # Use the SMTP object smtp only in this block.
+end
+```
+
+Replace 'your.smtp.server' with your SMTP server. Normally
+your system manager or internet provider supplies a server
+for you.
+
+Then you can send messages.
+
+```ruby
+msgstr = <<END_OF_MESSAGE
+From: Your Name <your@mail.address>
+To: Destination Address <someone@example.com>
+Subject: test message
+Date: Sat, 23 Jun 2001 16:26:43 +0900
+Message-Id: <unique.message.id.string@example.com>
+
+This is a test message.
+END_OF_MESSAGE
+
+require 'net/smtp'
+Net::SMTP.start('your.smtp.server', 25) do |smtp|
+  smtp.send_message msgstr,
+                    'your@mail.address',
+                    'his_address@example.com'
+end
+```
+
+### Closing the Session
+
+You MUST close the SMTP session after sending messages, by calling
+the #finish method:
+
+```ruby
+# using SMTP#finish
+smtp = Net::SMTP.start('your.smtp.server', 25)
+smtp.send_message msgstr, 'from@address', 'to@address'
+smtp.finish
+```
+
+You can also use the block form of SMTP.start/SMTP#start.  This closes
+the SMTP session automatically:
+
+```ruby
+# using block form of SMTP.start
+Net::SMTP.start('your.smtp.server', 25) do |smtp|
+  smtp.send_message msgstr, 'from@address', 'to@address'
+end
+```
+
+I strongly recommend this scheme.  This form is simpler and more robust.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/net-smtp.

data/lib/net/smtp/auth_cram_md5.rb

@@ -0,0 +1,48 @@
+unless defined? OpenSSL
+  begin
+    require 'digest/md5'
+  rescue LoadError
+  end
+end
+
+class Net::SMTP
+  class AuthCramMD5 < Net::SMTP::Authenticator
+    auth_type :cram_md5
+
+    def auth(user, secret)
+      challenge = continue('AUTH CRAM-MD5')
+      crammed = cram_md5_response(secret, challenge.unpack1('m'))
+      finish(base64_encode("#{user} #{crammed}"))
+    end
+
+    IMASK = 0x36
+    OMASK = 0x5c
+
+    # CRAM-MD5: [RFC2195]
+    def cram_md5_response(secret, challenge)
+      tmp = digest_class::MD5.digest(cram_secret(secret, IMASK) + challenge)
+      digest_class::MD5.hexdigest(cram_secret(secret, OMASK) + tmp)
+    end
+
+    CRAM_BUFSIZE = 64
+
+    def cram_secret(secret, mask)
+      secret = digest_class::MD5.digest(secret) if secret.size > CRAM_BUFSIZE
+      buf = secret.ljust(CRAM_BUFSIZE, "\0")
+      0.upto(buf.size - 1) do |i|
+        buf[i] = (buf[i].ord ^ mask).chr
+      end
+      buf
+    end
+
+    def digest_class
+      @digest_class ||= if defined?(OpenSSL::Digest)
+                          OpenSSL::Digest
+                        elsif defined?(::Digest)
+                          ::Digest
+                        else
+                          raise '"openssl" or "digest" library is required'
+                        end
+    end
+  end
+end

data/lib/net/smtp/auth_login.rb

@@ -0,0 +1,11 @@
+class Net::SMTP
+  class AuthLogin < Net::SMTP::Authenticator
+    auth_type :login
+
+    def auth(user, secret)
+      continue('AUTH LOGIN')
+      continue(base64_encode(user))
+      finish(base64_encode(secret))
+    end
+  end
+end

data/lib/net/smtp/auth_plain.rb

@@ -0,0 +1,9 @@
+class Net::SMTP
+  class AuthPlain < Net::SMTP::Authenticator
+    auth_type :plain
+
+    def auth(user, secret)
+      finish('AUTH PLAIN ' + base64_encode("\0#{user}\0#{secret}"))
+    end
+  end
+end

data/lib/net/smtp/auth_xoauth2.rb

@@ -0,0 +1,17 @@
+class Net::SMTP
+  class AuthXoauth2 < Net::SMTP::Authenticator
+    auth_type :xoauth2
+
+    def auth(user, secret)
+      token = xoauth2_string(user, secret)
+
+      finish("AUTH XOAUTH2 #{base64_encode(token)}")
+    end
+
+    private
+
+    def xoauth2_string(user, secret)
+      "user=#{user}\1auth=Bearer #{secret}\1\1"
+    end
+  end
+end

data/lib/net/smtp/authenticator.rb

@@ -0,0 +1,57 @@
+module Net
+  class SMTP
+    class Authenticator
+      def self.auth_classes
+        @classes ||= {}
+      end
+
+      def self.auth_type(type)
+        type = type.to_s.upcase.tr(?_, ?-).to_sym
+        Authenticator.auth_classes[type] = self
+      end
+
+      def self.auth_class(type)
+        type = type.to_s.upcase.tr(?_, ?-).to_sym
+        Authenticator.auth_classes[type]
+      end
+
+      def self.check_args(user_arg = nil, secret_arg = nil, *, **)
+        unless user_arg
+          raise ArgumentError, 'SMTP-AUTH requested but missing user name'
+        end
+        unless secret_arg
+          raise ArgumentError, 'SMTP-AUTH requested but missing secret phrase'
+        end
+      end
+
+      attr_reader :smtp
+
+      def initialize(smtp)
+        @smtp = smtp
+      end
+
+      # @param arg [String] message to server
+      # @return [String] message from server
+      def continue(arg)
+        res = smtp.get_response arg
+        raise res.exception_class.new(res) unless res.continue?
+        res.string.split[1]
+      end
+
+      # @param arg [String] message to server
+      # @return [Net::SMTP::Response] response from server
+      def finish(arg)
+        res = smtp.get_response arg
+        raise SMTPAuthenticationError.new(res) unless res.success?
+        res
+      end
+
+      # @param str [String]
+      # @return [String] Base64 encoded string
+      def base64_encode(str)
+        # expects "str" may not become too long
+        [str].pack('m0')
+      end
+    end
+  end
+end

data/lib/net/smtp.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 # = net/smtp.rb
 #
 # Copyright (c) 1999-2007 Yukihiro Matsumoto.
@@ -12,21 +13,16 @@
 # This program is free software. You can re-distribute and/or
 # modify this program under the same terms as Ruby itself.
 #
-# $Id$
-#
 # See Net::SMTP for documentation.
 #
 
 require 'net/protocol'
-require 'digest/md5'
-require 'timeout'
 begin
   require 'openssl'
 rescue LoadError
 end
 
 module Net
-
   # Module mixed in to all SMTP error classes
   module SMTPError
     # This *class* is a module for backward compatibility.
@@ -35,8 +31,13 @@ module Net
     attr_reader :response
 
     def initialize(response, message: nil)
-      @response = response
-      @message = message
+      if response.is_a?(::Net::SMTP::Response)
+        @response = response
+        @message = message
+      else
+        @response = nil
+        @message = message || response
+      end
     end
 
     def message
@@ -78,25 +79,34 @@ module Net
   # == What is This Library?
   #
   # This library provides functionality to send internet
-  # mail via SMTP, the Simple Mail Transfer Protocol. For details of
-  # SMTP itself, see [RFC2821] (http://www.ietf.org/rfc/rfc2821.txt).
+  # mail via \SMTP, the Simple Mail Transfer Protocol. For details of
+  # \SMTP itself, see [RFC5321[https://www.rfc-editor.org/rfc/rfc5321.txt]].
+  # This library also implements \SMTP authentication, which is often
+  # necessary for message composers to submit messages to their
+  # outgoing \SMTP server, see
+  # [RFC6409[https://www.rfc-editor.org/rfc/rfc6409.html]],
+  # and [SMTPUTF8[https://www.rfc-editor.org/rfc/rfc6531.txt]], which is
+  # necessary to send messages to/from addresses containing characters
+  # outside the ASCII range.
   #
   # == What is This Library NOT?
   #
   # This library does NOT provide functions to compose internet mails.
   # You must create them by yourself. If you want better mail support,
-  # try RubyMail or TMail or search for alternatives in
+  # try the mail[https://rubygems.org/gems/mail] or
+  # rmail[https://rubygems.org/gems/rmail] gems, or search for alternatives in
   # {RubyGems.org}[https://rubygems.org/] or {The Ruby
   # Toolbox}[https://www.ruby-toolbox.com/].
   #
-  # FYI: the official documentation on internet mail is: [RFC2822] (http://www.ietf.org/rfc/rfc2822.txt).
+  # FYI: the official specification on internet mail is:
+  # [RFC5322[https://www.rfc-editor.org/rfc/rfc5322.txt]].
   #
   # == Examples
   #
   # === Sending Messages
   #
-  # You must open a connection to an SMTP server before sending messages.
-  # The first argument is the address of your SMTP server, and the second
+  # You must open a connection to an \SMTP server before sending messages.
+  # The first argument is the address of your \SMTP server, and the second
   # argument is the port number. Using SMTP.start with a block is the simplest
   # way to do this. This way, the SMTP connection is closed automatically
   # after the block is executed.
@@ -106,7 +116,7 @@ module Net
   #       # Use the SMTP object smtp only in this block.
   #     end
   #
-  # Replace 'your.smtp.server' with your SMTP server. Normally
+  # Replace 'your.smtp.server' with your \SMTP server. Normally
   # your system manager or internet provider supplies a server
   # for you.
   #
@@ -139,7 +149,7 @@ module Net
   #     smtp.send_message msgstr, 'from@address', 'to@address'
   #     smtp.finish
   #
-  # You can also use the block form of SMTP.start/SMTP#start.  This closes
+  # You can also use the block form of SMTP.start or SMTP#start.  This closes
   # the SMTP session automatically:
   #
   #     # using block form of SMTP.start
@@ -152,36 +162,37 @@ module Net
   # === HELO domain
   #
   # In almost all situations, you must provide a third argument
-  # to SMTP.start/SMTP#start. This is the domain name which you are on
+  # to SMTP.start or SMTP#start. This is the domain name which you are on
   # (the host to send mail from). It is called the "HELO domain".
-  # The SMTP server will judge whether it should send or reject
+  # The \SMTP server will judge whether it should send or reject
   # the SMTP session by inspecting the HELO domain.
   #
-  #     Net::SMTP.start('your.smtp.server', 25
-  #                     helo: 'mail.from.domain') { |smtp| ... }
+  #     Net::SMTP.start('your.smtp.server', 25, helo: 'mail.from.domain') do |smtp|
+  #       smtp.send_message msgstr, 'from@address', 'to@address'
+  #     end
+  #
+  # === \SMTP Authentication
   #
-  # === SMTP Authentication
+  # The Net::SMTP class supports the \SMTP extension for SASL Authentication
+  # [RFC4954[https://www.rfc-editor.org/rfc/rfc4954.html]] and the following
+  # SASL mechanisms: +PLAIN+, +LOGIN+ _(deprecated)_, and +CRAM-MD5+
+  # _(deprecated)_.
   #
-  # The Net::SMTP class supports three authentication schemes;
-  # PLAIN, LOGIN and CRAM MD5.  (SMTP Authentication: [RFC2554])
-  # To use SMTP authentication, pass extra arguments to
-  # SMTP.start/SMTP#start.
+  # To use \SMTP authentication, pass extra arguments to
+  # SMTP.start or SMTP#start.
   #
   #     # PLAIN
-  #     Net::SMTP.start('your.smtp.server', 25
+  #     Net::SMTP.start('your.smtp.server', 25,
   #                     user: 'Your Account', secret: 'Your Password', authtype: :plain)
-  #     # LOGIN
-  #     Net::SMTP.start('your.smtp.server', 25
-  #                     user: 'Your Account', secret: 'Your Password', authtype: :login)
   #
-  #     # CRAM MD5
-  #     Net::SMTP.start('your.smtp.server', 25
-  #                     user: 'Your Account', secret: 'Your Password', authtype: :cram_md5)
+  # Support for other SASL mechanisms-such as +EXTERNAL+, +OAUTHBEARER+,
+  # +SCRAM-SHA-256+, and +XOAUTH2+-will be added in a future release.
+  #
+  # The +LOGIN+ and +CRAM-MD5+ mechanisms are still available for backwards
+  # compatibility, but are deprecated and should be avoided.
   #
   class SMTP < Protocol
-    VERSION = "0.3.1"
-
-    Revision = %q$Revision$.split[1]
+    VERSION = "0.5.0"
 
     # The default SMTP port number, 25.
     def SMTP.default_port
@@ -204,7 +215,7 @@ module Net
 
     def SMTP.default_ssl_context(ssl_context_params = nil)
       context = OpenSSL::SSL::SSLContext.new
-      context.set_params(ssl_context_params ? ssl_context_params : {})
+      context.set_params(ssl_context_params || {})
       context
     end
 
@@ -223,10 +234,13 @@ module Net
     # If the hostname in the server certificate is different from +address+,
     # it can be specified with +tls_hostname+.
     #
-    # Additional SSLContext params can be added to +ssl_context_params+ hash argument and are passed to
-    # +OpenSSL::SSL::SSLContext#set_params+
+    # Additional SSLContext[https://ruby.github.io/openssl/OpenSSL/SSL/SSLContext.html]
+    # params can be added to the +ssl_context_params+ hash argument and are
+    # passed to {OpenSSL::SSL::SSLContext#set_params}[https://ruby.github.io/openssl/OpenSSL/SSL/SSLContext.html#method-i-set_params].
+    #
+    # <tt>tls_verify: true</tt> is equivalent to <tt>ssl_context_params: {
+    # verify_mode: OpenSSL::SSL::VERIFY_PEER }</tt>.
     #
-    # +tls_verify: true+ is equivalent to +ssl_context_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER }+.
     # This method does not open the TCP connection.  You can use
     # SMTP.start instead of SMTP.new if you want to do everything
     # at once.  Otherwise, follow SMTP.new with SMTP#start.
@@ -275,7 +289,7 @@ module Net
     attr_accessor :esmtp
 
     # +true+ if the SMTP object uses ESMTP (which it does by default).
-    alias :esmtp? :esmtp
+    alias esmtp? esmtp
 
     # true if server advertises STARTTLS.
     # You cannot get valid value before opening SMTP session.
@@ -310,12 +324,13 @@ module Net
       auth_capable?('CRAM-MD5')
     end
 
+    # Returns whether the server advertises support for the authentication type.
+    # You cannot get valid result before opening SMTP session.
     def auth_capable?(type)
       return nil unless @capabilities
       return false unless @capabilities['AUTH']
       @capabilities['AUTH'].include?(type)
     end
-    private :auth_capable?
 
     # Returns supported authentication methods on this server.
     # You cannot get valid value before opening SMTP session.
@@ -332,7 +347,7 @@ module Net
 
     alias ssl? tls?
 
-    # Enables SMTP/TLS (SMTPS: SMTP over direct TLS connection) for
+    # Enables SMTP/TLS (SMTPS: \SMTP over direct TLS connection) for
     # this object.  Must be called before the connection is established
     # to have any effect.  +context+ is a OpenSSL::SSL::SSLContext object.
     def enable_tls(context = nil)
@@ -451,7 +466,10 @@ module Net
     #
     # This method is equivalent to:
     #
-    #   Net::SMTP.new(address, port).start(helo: helo_domain, user: account, secret: password, authtype: authtype, tls_verify: flag, tls_hostname: hostname, ssl_context_params: nil)
+    #   Net::SMTP.new(address, port, tls_verify: flag, tls_hostname: hostname, ssl_context_params: nil)
+    #     .start(helo: helo_domain, user: account, secret: password, authtype: authtype)
+    #
+    # See also: Net::SMTP.new, #start
     #
     # === Example
     #
@@ -476,12 +494,6 @@ module Net
     # +helo+ is the _HELO_ _domain_ provided by the client to the
     # server (see overview comments); it defaults to 'localhost'.
     #
-    # The remaining arguments are used for SMTP authentication, if required
-    # or desired.  +user+ is the account name; +secret+ is your password
-    # or other authentication token; and +authtype+ is the authentication
-    # type, one of :plain, :login, or :cram_md5.  See the discussion of
-    # SMTP Authentication in the overview notes.
-    #
     # If +tls+ is true, enable TLS. The default is false.
     # If +starttls+ is :always, enable STARTTLS, if +:auto+, use STARTTLS when the server supports it,
     # if false, disable STARTTLS.
@@ -490,10 +502,26 @@ module Net
     # If the hostname in the server certificate is different from +address+,
     # it can be specified with +tls_hostname+.
     #
-    # Additional SSLContext params can be added to +ssl_context_params+ hash argument and are passed to
-    # +OpenSSL::SSL::SSLContext#set_params+
+    # Additional SSLContext[https://ruby.github.io/openssl/OpenSSL/SSL/SSLContext.html]
+    # params can be added to the +ssl_context_params+ hash argument and are
+    # passed to {OpenSSL::SSL::SSLContext#set_params}[https://ruby.github.io/openssl/OpenSSL/SSL/SSLContext.html#method-i-set_params].
+    #
+    # <tt>tls_verify: true</tt> is equivalent to <tt>ssl_context_params: {
+    # verify_mode: OpenSSL::SSL::VERIFY_PEER }</tt>.
+    #
+    # The remaining arguments are used for \SMTP authentication, if required or
+    # desired.
+    #
+    # +authtype+ is the SASL authentication mechanism.
+    #
+    # +user+ is the authentication or authorization identity.
+    #
+    # +secret+ or +password+ is your password or other authentication token.
     #
-    # +tls_verify: true+ is equivalent to +ssl_context_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER }+.
+    # These will be sent to #authenticate as positional arguments-the exact
+    # semantics are dependent on the +authtype+.
+    #
+    # See the discussion of Net::SMTP@SMTP+Authentication in the overview notes.
     #
     # === Errors
     #
@@ -521,7 +549,7 @@ module Net
       new(address, port, tls: tls, starttls: starttls, tls_verify: tls_verify, tls_hostname: tls_hostname, ssl_context_params: ssl_context_params).start(helo: helo, user: user, secret: secret, authtype: authtype, &block)
     end
 
-    # +true+ if the SMTP session has been started.
+    # +true+ if the \SMTP session has been started.
     def started?
       @started
     end
@@ -538,11 +566,21 @@ module Net
     # +helo+ is the _HELO_ _domain_ that you'll dispatch mails from; see
     # the discussion in the overview notes.
     #
-    # If both of +user+ and +secret+ are given, SMTP authentication
-    # will be attempted using the AUTH command.  +authtype+ specifies
-    # the type of authentication to attempt; it must be one of
-    # :login, :plain, and :cram_md5.  See the notes on SMTP Authentication
-    # in the overview.
+    # The remaining arguments are used for \SMTP authentication, if required or
+    # desired.
+    #
+    # +authtype+ is the SASL authentication mechanism.
+    #
+    # +user+ is the authentication or authorization identity.
+    #
+    # +secret+ or +password+ is your password or other authentication token.
+    #
+    # These will be sent to #authenticate as positional arguments-the exact
+    # semantics are dependent on the +authtype+.
+    #
+    # See the discussion of Net::SMTP@SMTP+Authentication in the overview notes.
+    #
+    # See also: Net::SMTP.start
     #
     # === Block Usage
     #
@@ -622,28 +660,24 @@ module Net
     private
 
     def tcp_socket(address, port)
-      begin
-        Socket.tcp address, port, nil, nil, connect_timeout: @open_timeout
-      rescue Errno::ETIMEDOUT #raise Net:OpenTimeout instead for compatibility with previous versions
-        raise Net::OpenTimeout, "Timeout to open TCP connection to "\
-          "#{address}:#{port} (exceeds #{@open_timeout} seconds)"
-      end
+      TCPSocket.open address, port
     end
 
     def do_start(helo_domain, user, secret, authtype)
       raise IOError, 'SMTP session already started' if @started
-      if user or secret
-        check_auth_method(authtype || DEFAULT_AUTH_TYPE)
-        check_auth_args user, secret
+      if user || secret || authtype
+        check_auth_args authtype, user, secret
+      end
+      s = Timeout.timeout(@open_timeout, Net::OpenTimeout) do
+        tcp_socket(@address, @port)
       end
-      s = tcp_socket(@address, @port)
       logging "Connection opened: #{@address}:#{@port}"
       @socket = new_internet_message_io(tls? ? tlsconnect(s, @ssl_context_tls) : s)
       check_response critical { recv_response() }
       do_helo helo_domain
       if ! tls? and (starttls_always? or (capable_starttls? and starttls_auto?))
         unless capable_starttls?
-          raise SMTPUnsupportedCommand.new(nil, message: "STARTTLS is not supported on this server")
+          raise SMTPUnsupportedCommand, "STARTTLS is not supported on this server"
         end
         starttls
         @socket = new_internet_message_io(tlsconnect(s, @ssl_context_starttls))
@@ -703,6 +737,18 @@ module Net
       @socket = nil
     end
 
+    def requires_smtputf8(address)
+      if address.kind_of? Address
+        !address.address.ascii_only?
+      else
+        !address.ascii_only?
+      end
+    end
+
+    def any_require_smtputf8(addresses)
+      addresses.any?{ |a| requires_smtputf8(a) }
+    end
+
     #
     # Message Sending
     #
@@ -746,7 +792,9 @@ module Net
     # * IOError
     #
     def send_message(msgstr, from_addr, *to_addrs)
+      to_addrs.flatten!
       raise IOError, 'closed session' unless @socket
+      from_addr = Address.new(from_addr, 'SMTPUTF8') if any_require_smtputf8(to_addrs) && capable?('SMTPUTF8')
       mailfrom from_addr
       rcptto_list(to_addrs) {data msgstr}
     end
@@ -799,7 +847,9 @@ module Net
     # * IOError
     #
     def open_message_stream(from_addr, *to_addrs, &block)   # :yield: stream
+      to_addrs.flatten!
       raise IOError, 'closed session' unless @socket
+      from_addr = Address.new(from_addr, 'SMTPUTF8') if any_require_smtputf8(to_addrs) && capable?('SMTPUTF8')
       mailfrom from_addr
       rcptto_list(to_addrs) {data(&block)}
     end
@@ -810,92 +860,28 @@ module Net
     # Authentication
     #
 
-    public
-
     DEFAULT_AUTH_TYPE = :plain
 
+    # Authenticates with the server, using the "AUTH" command.
+    #
+    # +authtype+ is the name of a SASL authentication mechanism.
+    #
+    # All arguments-other than +authtype+-are forwarded to the authenticator.
+    # Different authenticators may interpret the +user+ and +secret+
+    # arguments differently.
     def authenticate(user, secret, authtype = DEFAULT_AUTH_TYPE)
-      check_auth_method authtype
-      check_auth_args user, secret
-      public_send auth_method(authtype), user, secret
-    end
-
-    def auth_plain(user, secret)
-      check_auth_args user, secret
-      res = critical {
-        get_response('AUTH PLAIN ' + base64_encode("\0#{user}\0#{secret}"))
-      }
-      check_auth_response res
-      res
-    end
-
-    def auth_login(user, secret)
-      check_auth_args user, secret
-      res = critical {
-        check_auth_continue get_response('AUTH LOGIN')
-        check_auth_continue get_response(base64_encode(user))
-        get_response(base64_encode(secret))
-      }
-      check_auth_response res
-      res
-    end
-
-    def auth_cram_md5(user, secret)
-      check_auth_args user, secret
-      res = critical {
-        res0 = get_response('AUTH CRAM-MD5')
-        check_auth_continue res0
-        crammed = cram_md5_response(secret, res0.cram_md5_challenge)
-        get_response(base64_encode("#{user} #{crammed}"))
-      }
-      check_auth_response res
-      res
+      check_auth_args authtype, user, secret
+      authenticator = Authenticator.auth_class(authtype).new(self)
+      authenticator.auth(user, secret)
     end
 
     private
 
-    def check_auth_method(type)
-      unless respond_to?(auth_method(type), true)
+    def check_auth_args(type, *args, **kwargs)
+      type ||= DEFAULT_AUTH_TYPE
+      klass = Authenticator.auth_class(type) or
         raise ArgumentError, "wrong authentication type #{type}"
-      end
-    end
-
-    def auth_method(type)
-      "auth_#{type.to_s.downcase}".intern
-    end
-
-    def check_auth_args(user, secret, authtype = DEFAULT_AUTH_TYPE)
-      unless user
-        raise ArgumentError, 'SMTP-AUTH requested but missing user name'
-      end
-      unless secret
-        raise ArgumentError, 'SMTP-AUTH requested but missing secret phrase'
-      end
-    end
-
-    def base64_encode(str)
-      # expects "str" may not become too long
-      [str].pack('m0')
-    end
-
-    IMASK = 0x36
-    OMASK = 0x5c
-
-    # CRAM-MD5: [RFC2195]
-    def cram_md5_response(secret, challenge)
-      tmp = Digest::MD5.digest(cram_secret(secret, IMASK) + challenge)
-      Digest::MD5.hexdigest(cram_secret(secret, OMASK) + tmp)
-    end
-
-    CRAM_BUFSIZE = 64
-
-    def cram_secret(secret, mask)
-      secret = Digest::MD5.digest(secret) if secret.size > CRAM_BUFSIZE
-      buf = secret.ljust(CRAM_BUFSIZE, "\0")
-      0.upto(buf.size - 1) do |i|
-        buf[i] = (buf[i].ord ^ mask).chr
-      end
-      buf
+      klass.check_args(*args, **kwargs)
     end
 
     #
@@ -924,29 +910,20 @@ module Net
 
     # +from_addr+ is +String+ or +Net::SMTP::Address+
     def mailfrom(from_addr)
-      addr = Address.new(from_addr)
+      addr = if requires_smtputf8(from_addr) && capable?("SMTPUTF8")
+               Address.new(from_addr, "SMTPUTF8")
+             else
+               Address.new(from_addr)
+             end
       getok((["MAIL FROM:<#{addr.address}>"] + addr.parameters).join(' '))
     end
 
     def rcptto_list(to_addrs)
       raise ArgumentError, 'mail destination not given' if to_addrs.empty?
-      ok_users = []
-      unknown_users = []
       to_addrs.flatten.each do |addr|
-        begin
-          rcptto addr
-        rescue SMTPAuthenticationError
-          unknown_users << addr.to_s.dump
-        else
-          ok_users << addr
-        end
+        rcptto addr
       end
-      raise ArgumentError, 'mail destination not given' if ok_users.empty?
-      ret = yield
-      unless unknown_users.empty?
-        raise SMTPAuthenticationError, "failed to deliver for #{unknown_users.join(', ')}"
-      end
-      ret
+      yield
     end
 
     # +to_addr+ is +String+ or +Net::SMTP::Address+
@@ -1009,6 +986,12 @@ module Net
       getok('QUIT')
     end
 
+    def get_response(reqline)
+      validate_line reqline
+      @socket.writeline reqline
+      recv_response()
+    end
+
     private
 
     def validate_line(line)
@@ -1028,12 +1011,6 @@ module Net
       res
     end
 
-    def get_response(reqline)
-      validate_line reqline
-      @socket.writeline reqline
-      recv_response()
-    end
-
     def recv_response
       buf = ''.dup
       while true
@@ -1066,18 +1043,6 @@ module Net
       end
     end
 
-    def check_auth_response(res)
-      unless res.success?
-        raise SMTPAuthenticationError.new(res)
-      end
-    end
-
-    def check_auth_continue(res)
-      unless res.continue?
-        raise res.exception_class.new(res)
-      end
-    end
-
     # This class represents a response received by the SMTP server. Instances
     # of this class are created by the SMTP class; they should not be directly
     # created by the user. For more information on SMTP responses, view
@@ -1165,7 +1130,7 @@ module Net
     class Address
       # mail address [String]
       attr_reader :address
-      # paramters [Array<String>]
+      # parameters [Array<String>]
       attr_reader :parameters
 
       # :call-seq:
@@ -1179,17 +1144,21 @@ module Net
           @parameters = address.parameters
         else
           @address = address
-          @parameters = (args + [kw_args]).map{|param| Array(param)}.flatten(1).map{|param| Array(param).compact.join('=')}
+          @parameters = []
         end
+        @parameters = (parameters + args + [kw_args]).map{|param| Array(param)}.flatten(1).map{|param| Array(param).compact.join('=')}.uniq
       end
 
       def to_s
         @address
       end
     end
-
   end   # class SMTP
 
   SMTPSession = SMTP # :nodoc:
+end
 
+require_relative 'smtp/authenticator'
+Dir.glob("#{__dir__}/smtp/auth_*.rb") do |r|
+  require_relative r
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: net-smtp
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Yukihiro Matsumoto
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-12 00:00:00.000000000 Z
+date: 2024-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -24,34 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: digest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: timeout
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: Simple Mail Transfer Protocol client library for Ruby.
 email:
 - matz@ruby-lang.org
@@ -60,8 +32,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE.txt
+- NEWS.md
+- README.md
 - lib/net/smtp.rb
-- net-smtp.gemspec
+- lib/net/smtp/auth_cram_md5.rb
+- lib/net/smtp/auth_login.rb
+- lib/net/smtp/auth_plain.rb
+- lib/net/smtp/auth_xoauth2.rb
+- lib/net/smtp/authenticator.rb
 homepage: https://github.com/ruby/net-smtp
 licenses:
 - Ruby
@@ -84,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.0.dev
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Simple Mail Transfer Protocol client library for Ruby.

data/net-smtp.gemspec

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-name = File.basename(__FILE__, ".gemspec")
-version = ["lib", Array.new(name.count("-"), "..").join("/")].find do |dir|
-  break File.foreach(File.join(__dir__, dir, "#{name.tr('-', '/')}.rb")) do |line|
-    /^\s*VERSION\s*=\s*"(.*)"/ =~ line and break $1
-  end rescue nil
-end
-
-Gem::Specification.new do |spec|
-  spec.name          = name
-  spec.version       = version
-  spec.authors       = ["Yukihiro Matsumoto"]
-  spec.email         = ["matz@ruby-lang.org"]
-
-  spec.summary       = %q{Simple Mail Transfer Protocol client library for Ruby.}
-  spec.description   = %q{Simple Mail Transfer Protocol client library for Ruby.}
-  spec.homepage      = "https://github.com/ruby/net-smtp"
-  spec.licenses      = ["Ruby", "BSD-2-Clause"]
-  spec.required_ruby_version = ">= 2.6.0"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage
-
-  spec.files         = %w[
-    LICENSE.txt
-    lib/net/smtp.rb
-    net-smtp.gemspec
-  ]
-  spec.require_paths = ["lib"]
-
-  spec.add_dependency "net-protocol"
-  spec.add_dependency "digest"
-  spec.add_dependency "timeout"
-end