module Net::IMAP::SASL
Pluggable authentication mechanisms for protocols which support SASL
(Simple Authentication and Security Layer), such as IMAP4, SMTP, LDAP, and XMPP. RFC-4422 specifies the common SASL framework:
SASL
is conceptually a framework that provides an abstraction layer between protocols and mechanisms as illustrated in the following diagram.SMTP LDAP XMPP Other protocols ... \ | | / \ | | / SASL abstraction layer / | | \ / | | \ EXTERNAL GSSAPI PLAIN Other mechanisms ...
Net::IMAP
uses SASL
via the Net::IMAP#authenticate
method.
Mechanisms¶ ↑
Each mechanism has different properties and requirements. Please consult the documentation for the specific mechanisms you are using:
ANONYMOUS
-
Allows the user to gain access to public services or resources without authenticating or disclosing an identity.
EXTERNAL
-
Authenticates using already established credentials, such as a TLS certificate or IPsec.
OAUTHBEARER
-
Login using an OAuth2 Bearer token. This is the standard mechanism for using OAuth2 with SASL, but it is not yet deployed as widely as
XOAUTH2
. PLAIN
-
See
PlainAuthenticator
.Login using clear-text username and password.
SCRAM-SHA-1
SCRAM-SHA-256
-
See
ScramAuthenticator
.Login by username and password. The password is not sent to the server but is used in a salted challenge/response exchange.
SCRAM-SHA-1
andSCRAM-SHA-256
are directly supported byNet::IMAP::SASL
. New authenticators can easily be added for any otherSCRAM-*
mechanism if the digest algorithm is supported by OpenSSL::Digest. XOAUTH2
-
See
XOAuth2Authenticator
.Login using a username and an OAuth2 access token. Non-standard and obsoleted by
OAUTHBEARER
, but widely supported.
See the SASL mechanism registry for a list of all SASL
mechanisms and their specifications. To register new authenticators, see Authenticators
.
Deprecated mechanisms¶ ↑
Obsolete mechanisms should be avoided, but are still available for backwards compatibility.
For
DIGEST-MD5
seeDigestMD5Authenticator
.For
LOGIN
, seeLoginAuthenticator
.For
CRAM-MD5
, seeCramMD5Authenticator
.
Using a deprecated mechanism will print a warning.
Constants
- AuthenticationCanceled
Indicates an authentication exchange that will be or has been canceled by the client, not due to any error or failure during processing.
- AuthenticationError
Indicates an error when processing a server challenge, e.g: an invalid or unparsable challenge. An underlying exception may be available as the exception’s cause.
- AuthenticationFailed
Indicates that authentication cannot proceed because one of the server’s messages has not passed integrity checks.
- Error
Exception class for any client error detected during the authentication exchange.
When the server reports an authentication failure, it will respond with a protocol specific error instead, e.g:
BAD
orNO
inIMAP
.When the client encounters any error, it must consider the authentication exchange to be unsuccessful and it might need to drop the connection. For example, if the server reports that the authentication exchange was successful or the protocol does not allow additional authentication attempts.
- SASLprep
Alias for
Net::IMAP::StringPrep::SASLprep
.
Public Class Methods
Delegates to ::authenticators
. See Authenticators#add_authenticator
.
# File net-imap-0.4.11/lib/net/imap/sasl.rb, line 168 def self.add_authenticator(...) authenticators.add_authenticator(...) end
Delegates to registry.new
See Authenticators#new
.
# File net-imap-0.4.11/lib/net/imap/sasl.rb, line 163 def self.authenticator(*args, registry: authenticators, **kwargs, &block) registry.new(*args, **kwargs, &block) end
Returns the default global SASL::Authenticators
instance.
# File net-imap-0.4.11/lib/net/imap/sasl.rb, line 160 def self.authenticators; @authenticators ||= Authenticators.new end
Public Instance Methods
See Net::IMAP::StringPrep::SASLprep#saslprep
.
# File net-imap-0.4.11/lib/net/imap/sasl.rb, line 173 def saslprep(string, **opts) Net::IMAP::StringPrep::SASLprep.saslprep(string, **opts) end