Module: Net::IMAP::SASL

Defined in:
lib/net/imap/sasl.rb,
lib/net/imap/sasl/gs2_header.rb,
lib/net/imap/sasl/stringprep.rb,
lib/net/imap/sasl/authenticators.rb,
lib/net/imap/sasl/client_adapter.rb,
lib/net/imap/sasl/scram_algorithm.rb,
lib/net/imap/sasl/protocol_adapters.rb,
lib/net/imap/sasl/scram_authenticator.rb,
lib/net/imap/sasl/external_authenticator.rb,
lib/net/imap/sasl/anonymous_authenticator.rb,
lib/net/imap/sasl/authentication_exchange.rb,
lib/net/imap/sasl/oauthbearer_authenticator.rb

Overview

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.

Defined Under Namespace

Modules: GS2Header, ProtocolAdapters, ScramAlgorithm Classes: AnonymousAuthenticator, AuthenticationExchange, AuthenticationIncomplete, Authenticators, ClientAdapter, CramMD5Authenticator, DigestMD5Authenticator, ExternalAuthenticator, LoginAuthenticator, OAuthAuthenticator, OAuthBearerAuthenticator, PlainAuthenticator, ScramAuthenticator, ScramSHA1Authenticator, ScramSHA256Authenticator, XOAuth2Authenticator

Constant Summary collapse

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.

Class.new(StandardError)
AuthenticationCanceled =

Indicates an authentication exchange that will be or has been canceled by the client, not due to any error or failure during processing.

Class.new(Error)
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.

Class.new(Error)
AuthenticationFailed =

Indicates that authentication cannot proceed because one of the server’s messages has not passed integrity checks.

Class.new(Error)
SASLprep =

Alias for Net::IMAP::StringPrep::SASLprep.

Net::IMAP::StringPrep::SASLprep
StringPrep =

:nodoc:

Net::IMAP::StringPrep
BidiStringError =

:nodoc:

Net::IMAP::StringPrep::BidiStringError
ProhibitedCodepoint =

:nodoc:

Net::IMAP::StringPrep::ProhibitedCodepoint
StringPrepError =

:nodoc:

Net::IMAP::StringPrep::StringPrepError

Class Method Summary collapse

Class Method Details

.add_authenticator ⇒ Object

Delegates to ::authenticators. See Authenticators#add_authenticator.



171
 
# File 'lib/net/imap/sasl.rb', line 171

def self.add_authenticator(...) authenticators.add_authenticator(...) end

.authenticator(*args, registry: authenticators, **kwargs, &block) ⇒ Object

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

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



166
167
168
 
# File 'lib/net/imap/sasl.rb', line 166

def self.authenticator(*args, registry: authenticators, **kwargs, &block)
  registry.new(*args, **kwargs, &block)
end

.authenticators ⇒ Object

Returns the default global SASL::Authenticators instance.



160
 
# File 'lib/net/imap/sasl.rb', line 160

def self.authenticators; @authenticators ||= Authenticators.new end

.saslprep(string, **opts) ⇒ Object

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



176
177
178
 
# File 'lib/net/imap/sasl.rb', line 176

def saslprep(string, **opts)
  Net::IMAP::StringPrep::SASLprep.saslprep(string, **opts)
end