8000 📚 Update SASL-related rdoc · ruby/net-imap@9c8c90f · GitHub
[go: up one dir, main page]
Skip to content

Commit 9c8c90f

Browse files
nevansnevans
committed
📚 Update SASL-related rdoc
* Update that not all methods ignore capabilities. * Separate paragraphs for #authenticate args. * Simplify #authenticate call-seq * Reword #authenticate capabilities rdoc... again. * remove obsolete `DIGEST-MD5` from example. * Update the mechanisms listing and copy to SASL module rdoc. * Provide citation for preferring authenticate over login.
1 parent acbc64f commit 9c8c90f

File tree

3 files changed

+98
-77
lines changed

3 files changed

+98
-77
lines changed

‎lib/net/imap.rb

Lines changed: 50 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -768,13 +768,12 @@ def disconnected?
768768
# cached #capabilities are used without sending a new #capability command to
769769
# the server.
770770
#
771-
# <em>*NOTE:* Net::IMAP does not</em> currently <em>modify its behaviour
772-
# according to the server's advertised capabilities.</em>
771+
# <em>*NOTE:* Most Net::IMAP methods do not _currently_ modify their
772+
# behaviour according to the server's advertised #capabilities.</em>
773773
#
774774
# See Net::IMAP@Capabilities for more about \IMAP capabilities.
775775
#
776776
# Related: #auth_capable?, #capabilities, #capability, #enable
777-
#
778777
def capable?(capability) capabilities.include? capability.to_s.upcase end
779778
alias capability? capable?
780779

@@ -783,12 +782,12 @@ def capable?(capability) capabilities.include? capability.to_s.upcase end
783782
#
784783
# To ensure a case-insensitive comparison, #capable? can be used instead.
785784
#
786-
# <em>*NOTE:* Net::IMAP does not</em> currently <em>modify its behaviour
787-
# according to the server's advertised capabilities.</em>
785+
# <em>*NOTE:* Most Net::IMAP methods do not _currently_ modify their
786+
# behaviour according to the server's advertised #capabilities.</em>
788787
#
789788
# See Net::IMAP@Capabilities for more about \IMAP capabilities.
790789
#
791-
# Related: #capable?, #auth_capable?, #capability
790+
# Related: #capable?, #auth_capable?, #auth_mechanisms, #capability, #enable
792791
def capabilities
793792
@capabilities || capability
794793
end
@@ -812,13 +811,7 @@ def capabilities
812811
# imap.authenticate("XOAUTH2", username, oauth2_access_token)
813812
# imap.auth_mechanisms # => []
814813
#
815-
# <em>*NOTE:* Net::IMAP does not</em> currently <em>modify its behaviour
816-
# according to the server's advertised capabilities.</em>
817-
#
818-
# See Net::IMAP@Capabilities for more about \IMAP capabilities.
819-
#
820-
# Related: #auth_capable?, #capabilities
821-
#
814+
# Related: #authenticate, #auth_capable?, #capabilities
822815
def auth_mechanisms
823816
capabilities
824817
.grep(/\AAUTH=/i)
@@ -835,12 +828,7 @@ def auth_mechanisms
835828
# imap.auth_capable? "PLAIN" # => true
836829
# imap.auth_capable? "blurdybloop" # => false
837830
#
838-
# <em>*NOTE:* Net::IMAP does not</em> currently <em>modify its behaviour
839-
# according to the server's advertised capabilities.</em>
840-
#
841-
# See Net::IMAP@Capabilities for more about \IMAP capabilities.
842-
#
843-
# Related: #authenticate, #capable?, #capabilities
831+
# Related: #authenticate, #auth_mechanisms, #capable?, #capabilities
844832
def auth_capable?(mechanism)
845833
capable? "AUTH=#{mechanism}"
846834
end
@@ -875,8 +863,8 @@ def clear_cached_capabilities
875863
# and returns an array of capabilities that are supported by the server.
876864
# The result is stored for use by #capable? and #capabilities.
877865
#
878-
# <em>*NOTE:* Net::IMAP does not</em> currently <em>modify its behaviour
879-
# according to the server's advertised capabilities.</em>
866+
# <em>*NOTE:* Most Net::IMAP methods do not _currently_ modify their
867+
# behaviour according to the server's advertised #capabilities.</em>
880868
#
881869
# Net::IMAP automatically stores and discards capability data according to
882870
# the requirements and recommendations in
@@ -992,82 +980,76 @@ def starttls(options = {}, verify = true)
992980
end
993981

994982
# :call-seq:
995-
# authenticate(mechanism, ...) -> ok_resp
996-
# authenticate(mech, *creds, sasl_ir: true, **attrs, &callback) -> ok_resp
983+
# authenticate(mechanism, *, sasl_ir: true, **, &) -> ok_resp
997984
#
998985
# Sends an {AUTHENTICATE command [IMAP4rev1 §6.2.2]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.2]
999986
# to authenticate the client. If successful, the connection enters the
1000987
# "_authenticated_" state.
1001988
#
1002989
# +mechanism+ is the name of the \SASL authentication mechanism to be used.
990+
#
1003991
# +sasl_ir+ allows or disallows sending an "initial response" (see the
1004-
# +SASL-IR+ capability, below). All other arguments are forwarded to the
1005-
# registered SASL authenticator for the requested mechanism. <em>The
1006-
# documentation for each individual mechanism must be consulted for its
1007-
# specific parameters.</em>
992+
# +SASL-IR+ capability, below).
1008993
#
1009-
# An exception Net::IMAP::NoResponseError is raised if authentication fails.
994+
# All other arguments are forwarded to the registered SASL authenticator for
995+
# the requested mechanism. <em>The documentation for each individual
996+
# mechanism must be consulted for its specific parameters.</em>
1010997
#
1011998
# Related: #login, #starttls, #auth_capable?, #auth_mechanisms
1012999
#
1013-
# ==== Supported SASL Mechanisms
1000+
# ==== Mechanisms
10141001
#
1015-
# +PLAIN+:: See PlainAuthenticator.
1016-
# Login using clear-text username and password.
1002+
# Each mechanism has different properties and requirements. Please consult
1003+
# the documentation for the specific mechanisms you are using:
10171004
#
1018-
# +XOAUTH2+:: See XOAuth2Authenticator.
1019-
# Login using a username and OAuth2 access token.
1020-
# Non-standard and obsoleted by +OAUTHBEARER+, but widely
1021-
# supported.
1005+
# +PLAIN+::
1006+
# See PlainAuthenticator[Net::IMAP::SASL::PlainAuthenticator].
10221007
#
1023-
# >>>
1024-
# *Deprecated:* <em>Obsolete mechanisms are available for backwards
1025-
# compatibility.</em>
1008+
# Login using clear-text username and password.
10261009
#
1027-
# For +DIGEST-MD5+ see DigestMD5Authenticator.
1010+
# +XOAUTH2+::
1011+
# See XOAuth2Authenticator[Net::IMAP::SASL::XOAuth2Authenticator].
10281012
#
1029-
# For +LOGIN+, see LoginAuthenticator.
1013+
# Login using a username and an OAuth2 access token. Non-standard and
1014+
# obsoleted by +OAUTHBEARER+, but widely supported.
10301015
#
1031-
# For +CRAM-MD5+, see CramMD5Authenticator.
1016+
# See the {SASL mechanism
1017+
# registry}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
1018+
# for a list of all SASL mechanisms and their specifications. To register
1019+
# new authenticators, see Authenticators.
10321020
#
1033-
# <em>Using a deprecated mechanism will print a warning.</em>
1021+
# ===== Deprecated mechanisms
10341022
#
1035-
# See Net::IMAP::Authenticators for information on plugging in
1036-
# authenticators for other mechanisms. See the {SASL mechanism
1037-
# registry}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
1038-
# for information on these and other SASL mechanisms.
1023+
# <em>Obsolete mechanisms should be avoided, but are still available for
1024+
# backwards compatibility. See</em> Net::IMAP::SASL@Deprecated+mechanisms.
1025+
# <em>Using a deprecated mechanism will print a warning.</em>
10391026
#
1040-
# ===== Capabilities
1027+
# ==== Capabilities
10411028
#
1042-
# The server should list <tt>"AUTH=#{mechanism}"</tt> capabilities for
1043-
# supported mechanisms. Check #auth_capable? or #auth_mechanisms before
1044-
# using a particular mechanism.
1029+
# <tt>"AUTH=#{mechanism}"</tt> capabilities indicate server support for
1030+
# mechanisms. Use #auth_capable? or #auth_mechanisms to check for support
1031+
# before using a particular mechanism.
10451032
#
10461033
# if imap.auth_capable? "XOAUTH2"
10471034
# imap.authenticate "XOAUTH2", username, oauth2_access_token
10481035
# elsif imap.auth_capable? "PLAIN"
10491036
# imap.authenticate "PLAIN", username, password
1050-
# elsif imap.auth_capable? "DIGEST-MD5"
1051-
# imap.authenticate "DIGEST-MD5", username, password
10521037
# elsif !imap.capability? "LOGINDISABLED"
10531038
# imap.login username, password
10541039
# else
10551040
# raise "No acceptable authentication mechanism is available"
10561041
# end
10571042
#
1058-
# The SASL exchange provides a method for server challenges and client
1059-
# responses, but many mechanisms expect the client to "respond" first. When
1060-
# the server's capabilities include +SASL-IR+
1061-
# [RFC4959[https://tools.ietf.org/html/rfc4959]], this "initial response"
1062-
# may be sent as an argument to the +AUTHENTICATE+ command, saving a
1063-
# round-trip. The initial response will _only_ be sent when it is supported
1064-
# by both the mechanism and the server. Set +sasl_ir+ to +false+ to prevent
1065-
# sending an initial response, even when it is supported.
1043+
# Although servers should list all supported \SASL mechanisms, they may
1044+
# allow authentication with an unlisted +mechanism+.
10661045
#
1067-
# Although servers _should_ advertise all supported auth mechanisms, it is
1068-
# possible to attempt to authenticate with a +mechanism+ that isn't listed.
1069-
# However the initial response will not be sent unless the appropriate
1070-
# <tt>"AUTH=#{mechanism}"</tt> capability is also present.
1046+
# If [SASL-IR[https://www.rfc-editor.org/rfc/rfc4959.html]] is supported
1047+
# and the appropriate <tt>"AUTH=#{mechanism}"</tt> capability is present,
1048+
# an "initial response" may be sent as an argument to the +AUTHENTICATE+
1049+
# command, saving a round-trip. The SASL exchange allows for server
1050+
# challenges and client responses, but many mechanisms expect the client to
1051+
# "respond" first. The initial response will only be sent for
1052+
# "client-first" mechanisms.
10711053
#
10721054
# Server capabilities may change after #starttls, #login, and #authenticate.
10731055
# Previously cached #capabilities will be cleared when this method
@@ -1098,8 +1080,10 @@ def authenticate(mechanism, *creds, sasl_ir: true, **props, &callback)
10981080
# this +user+. If successful, the connection enters the "_authenticated_"
10991081
# state.
11001082
#
1101-
# Using #authenticate is generally preferred over #login. The LOGIN command
1102-
# is not the same as #authenticate with the "LOGIN" +mechanism+.
1083+
# Using #authenticate {should be
1084+
# preferred}[https://www.rfc-editor.org/rfc/rfc9051.html#name-login-command]
1085+
# over #login. The LOGIN command is not the same as #authenticate with the
1086+
# "LOGIN" +mechanism+.
11031087
#
11041088
# A Net::IMAP::NoResponseError is raised if authentication fails.
11051089
#

‎lib/net/imap/sasl.rb

Lines changed: 47 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,11 @@ class IMAP
66
# Pluggable authentication mechanisms for protocols which support SASL
77
# (Simple Authentication and Security Layer), such as IMAP4, SMTP, LDAP, and
88
# XMPP. {RFC-4422}[https://tools.ietf.org/html/rfc4422] specifies the
9-
# common SASL framework and the +EXTERNAL+ mechanism, and the
10-
# {SASL mechanism registry}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
11-
# lists the specification for others.
12-
#
13-
# "SASL is conceptually a framework that provides an abstraction layer
14-
# between protocols and mechanisms as illustrated in the following diagram."
9+
# common \SASL framework:
10+
# >>>
11+
# SASL is conceptually a framework that provides an abstraction layer
12+
# between protocols and mechanisms as illustrated in the following
13+
# diagram.
1514
#
1615
# SMTP LDAP XMPP Other protocols ...
1716
# \ | | /
@@ -21,10 +20,46 @@ class IMAP
2120
# / | | \
2221
# EXTERNAL GSSAPI PLAIN Other mechanisms ...
2322
#
23+
# Net::IMAP uses SASL via the Net::IMAP#authenticate method.
24+
#
25+
# == Mechanisms
26+
#
27+
# Each mechanism has different properties and requirements. Please consult
28+
# the documentation for the specific mechanisms you are using:
29+
#
30+
# +PLAIN+::
31+
# See PlainAuthenticator[Net::IMAP::SASL::PlainAuthenticator].
32+
#
33+
# Login using clear-text username and password.
34+
#
35+
# +XOAUTH2+::
36+
# See XOAuth2Authenticator[Net::IMAP::SASL::XOAuth2Authenticator].
37+
#
38+
# Login using a username and an OAuth2 access token. Non-standard and
39+
# obsoleted by +OAUTHBEARER+, but widely supported.
40+
#
41+
# See the {SASL mechanism
42+
# registry}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
43+
# for a list of all SASL mechanisms and their specifications. To register
44+
# new authenticators, see Authenticators.
45+
#
46+
# === Deprecated mechanisms
47+
#
48+
# <em>Obsolete mechanisms should be avoided, but are still available for
49+
# backwards compatibility.</em>
50+
#
51+
# >>>
52+
# For +DIGEST-MD5+ see DigestMD5Authenticator.
53+
#
54+
# For +LOGIN+, see LoginAuthenticator.
55+
#
56+
# For +CRAM-MD5+, see CramMD5Authenticator.
57+
#
58+
# <em>Using a deprecated mechanism will print a warning.</em>
59+
#
2460
module SASL
2561

2662
# autoloading to avoid loading all of the regexps when they aren't used.
27-
2863
sasl_stringprep_rb = File.expand_path("sasl/stringprep", __dir__)
2964
autoload :StringPrep, sasl_stringprep_rb
3065
autoload :SASLprep, sasl_stringprep_rb
@@ -60,11 +95,13 @@ def saslprep(string, **opts)
6095
Net::IMAP::StringPrep::SASLprep.saslprep(string, **opts)
6196
end
6297

63-
def initial_response?(mechanism)
64-
mechanism.respond_to?(:initial_response?) && mechanism.initial_response?
98+
# Returns whether the authenticator is client-first and supports sending
99+
# an "initial response".
100+
def initial_response?(authenticator)
101+
authenticator.respond_to?(:initial_response?) &&
102+
authenticator.initial_response?
65103
end
66104

67105
end
68106
end
69-
70107
end

‎lib/net/imap/sasl/stringprep.rb

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
module Net::IMAP::SASL
44

5-
# Alias for Net::IMAP::StringPrep::SASLPrep.
5+
# Alias for Net::IMAP::StringPrep::SASLprep.
66
SASLprep = Net::IMAP::StringPrep::SASLprep
77
StringPrep = Net::IMAP::StringPrep # :nodoc:
88
BidiStringError = Net::IMAP::StringPrep::BidiStringError # :nodoc:

0 commit comments

Comments
 (0)
0