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

See AnonymousAuthenticator.

Allows the user to gain access to public services or resources without authenticating or disclosing an identity.

EXTERNAL

See ExternalAuthenticator.

Authenticates using already established credentials, such as a TLS certificate or IPSec.

OAUTHBEARER

See OAuthBearerAuthenticator.

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 and SCRAM-SHA-256 are directly supported by Net::IMAP::SASL. New authenticators can easily be added for any other SCRAM-* 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 see DigestMD5Authenticator.

For LOGIN, see LoginAuthenticator.

For CRAM-MD5, see CramMD5Authenticator.

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 or NO in IMAP.

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

add_authenticator(...) click to toggle source

Delegates to ::authenticators. See Authenticators#add_authenticator.

# File net-imap-0.5.1/lib/net/imap/sasl.rb, line 171
def self.add_authenticator(...) authenticators.add_authenticator(...) end
authenticator(*args, registry: authenticators, **kwargs, &block) click to toggle source

Creates a new SASL authenticator, using SASL::Authenticators#new.

registry defaults to SASL.authenticators. All other arguments are forwarded to to registry.new.

# File net-imap-0.5.1/lib/net/imap/sasl.rb, line 166
def self.authenticator(*args, registry: authenticators, **kwargs, &block)
  registry.new(*args, **kwargs, &block)
end
authenticators() click to toggle source

Returns the default global SASL::Authenticators instance.

# File net-imap-0.5.1/lib/net/imap/sasl.rb, line 160
def self.authenticators; @authenticators ||= Authenticators.new end

Public Instance Methods

saslprep(string, **opts) click to toggle source

See Net::IMAP::StringPrep::SASLprep#saslprep.

# File net-imap-0.5.1/lib/net/imap/sasl.rb, line 176
def saslprep(string, **opts)
  Net::IMAP::StringPrep::SASLprep.saslprep(string, **opts)
end