From 2cfc961b80bf85f752cabcedad532e8ee4b59a58 Mon Sep 17 00:00:00 2001 From: nick evans Date: Thu, 28 Sep 2023 16:31:04 -0400 Subject: [PATCH] Updated docs, especially TLS and SASL-related * Escaped SMTP in many places where it refers to the protocol, not the class. * Fixed some ruby example syntax, so rdoc syntax highlighting works. * Separated `SMTP.start or SMTP#start`, so rdoc can link both methods. * Updated the RFC links. Fixed link to RFC6409 (not 6503!). * Linked to the `mail` (previously TMail) and `rmail` (previously RubyMail) gems. * Fixed `` formatting issues. * "See also" links from `start` methods. * Removed detailed documentation for deprecated `LOGIN` and `CRAM-MD5`. * Clarified authentication arg docs to Net::SMTP.start and #start. * Linked directly to Net::SMTP@SMTP+Authentication. --- lib/net/smtp.rb | 137 +++++++++++++++++++++++++++++++----------------- 1 file changed, 89 insertions(+), 48 deletions(-) diff --git a/lib/net/smtp.rb b/lib/net/smtp.rb index 145f897..81fe806 100644 --- a/lib/net/smtp.rb +++ b/lib/net/smtp.rb @@ -79,13 +79,13 @@ class SMTPUnsupportedCommand < ProtocolError # == 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 [RFC5321] (http://www.ietf.org/rfc/rfc5321.txt). - # This library also implements SMTP authentication, which is often + # 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](http://www.ietf.org/rfc/rfc6503.txt), - # and [SMTPUTF8](http://www.ietf.org/rfc/rfc6531.txt), which is + # 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. # @@ -93,18 +93,20 @@ class SMTPUnsupportedCommand < ProtocolError # # 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 specification on internet mail is: [RFC5322] (http://www.ietf.org/rfc/rfc5322.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. @@ -114,7 +116,7 @@ class SMTPUnsupportedCommand < ProtocolError # # 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. # @@ -147,7 +149,7 @@ class SMTPUnsupportedCommand < ProtocolError # 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 @@ -160,31 +162,34 @@ class SMTPUnsupportedCommand < ProtocolError # === 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.4.0" @@ -229,10 +234,13 @@ def SMTP.default_ssl_context(ssl_context_params = nil) # 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]. + # + # tls_verify: true is equivalent to ssl_context_params: { + # verify_mode: OpenSSL::SSL::VERIFY_PEER }. # - # +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. @@ -338,7 +346,7 @@ def tls? 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) @@ -457,7 +465,10 @@ def debug_output=(arg) # # 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 # @@ -482,12 +493,6 @@ def debug_output=(arg) # +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. @@ -496,10 +501,26 @@ def debug_output=(arg) # 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]. + # + # tls_verify: true is equivalent to ssl_context_params: { + # verify_mode: OpenSSL::SSL::VERIFY_PEER }. + # + # 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. # - # +tls_verify: true+ is equivalent to +ssl_context_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER }+. + # +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. # # === Errors # @@ -527,7 +548,7 @@ def SMTP.start(address, port = nil, *args, helo: nil, 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 @@ -544,11 +565,21 @@ def started? # +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 # @@ -831,6 +862,16 @@ def open_message_stream(from_addr, *to_addrs, &block) # :yield: stream DEFAULT_AUTH_TYPE = :plain + # call-seq: + # authenticate(username, secret, type = DEFAULT_AUTH_TYPE, **, &) + # + # Authenticates with the server, using the "AUTH" command. + # + # +type+ is the name of a SASL authentication mechanism. + # + # All arguments—other than +type+—are forwarded to the authenticator. + # Different authenticators may interpret the +username+ and +secret+ + # arguments differently. def authenticate(user, secret, authtype = DEFAULT_AUTH_TYPE) check_auth_method authtype check_auth_args user, secret