123456789_123456789_123456789_123456789_123456789_

Module: Net::IMAP::SASL

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 #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.

Constant Summary

Class Method Summary

Class Method Details

.add_authenticator

Delegates to .authenticators. See Authenticators#add_authenticator.

[ GitHub ] 

  


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



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


  








  

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



  

    

Creates a new SASL authenticator, using Authenticators#new.



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


  



  [ GitHub ]


  

  


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



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


  








  

    .authenticators  
  



  

    

Returns the default global SASL::Authenticators instance.


  



  [ GitHub ]


  

  


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



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


  








  

    .saslprep(string, **opts)   (mod_func)
  



  

    

See StringPrep::SASLprep#saslprep.


  



  [ GitHub ]


  

  


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



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