module Net::IMAP::SASL - net-imap: Ruby Standard Library Documentation

# 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.4/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.4/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.4/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.4/lib/net/imap/sasl.rb, line 176
    def saslprep(string, **opts)
      Net::IMAP::StringPrep::SASLprep.saslprep(string, **opts)
    end