From 56459e1f73cf299b447c7a51f6a03e0f27c5fd97 Mon Sep 17 00:00:00 2001 From: nick evans Date: Mon, 2 Oct 2023 22:57:26 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=A7=20username=20vs=20authzid=20vs=20a?= =?UTF-8?q?uthcid?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- lib/net/imap/sasl/anonymous_authenticator.rb | 7 +- lib/net/imap/sasl/digest_md5_authenticator.rb | 37 ++++-- lib/net/imap/sasl/external_authenticator.rb | 40 ++++-- .../imap/sasl/oauthbearer_authenticator.rb | 115 ++++++++++++------ lib/net/imap/sasl/plain_authenticator.rb | 42 ++++--- lib/net/imap/sasl/scram_authenticator.rb | 36 +++--- lib/net/imap/sasl/xoauth2_authenticator.rb | 32 +++-- test/net/imap/test_imap_authenticators.rb | 26 +++- 8 files changed, 227 insertions(+), 108 deletions(-) diff --git a/lib/net/imap/sasl/anonymous_authenticator.rb b/lib/net/imap/sasl/anonymous_authenticator.rb index ed7a46ef..74ba363b 100644 --- a/lib/net/imap/sasl/anonymous_authenticator.rb +++ b/lib/net/imap/sasl/anonymous_authenticator.rb @@ -21,16 +21,17 @@ class AnonymousAuthenticator attr_reader :anonymous_message # :call-seq: - # new(anonymous_message = "", **) -> authenticator # new(anonymous_message: "", **) -> authenticator + # new(anonymous_message = "", **) -> authenticator # # Creates an Authenticator for the "+ANONYMOUS+" SASL mechanism, as # specified in RFC-4505[https://tools.ietf.org/html/rfc4505]. To use # this, see Net::IMAP#authenticate or your client's authentication # method. # - # #anonymous_message is an optional message which is sent to the server. - # It may be sent as a positional argument or as a keyword argument. + # ==== Parameters + # + # * _optional_ #anonymous_message — a message to send to the server. # # Any other keyword arguments are silently ignored. def initialize(anon_msg = nil, anonymous_message: nil, **) diff --git a/lib/net/imap/sasl/digest_md5_authenticator.rb b/lib/net/imap/sasl/digest_md5_authenticator.rb index dcc6fc59..2d759b5e 100644 --- a/lib/net/imap/sasl/digest_md5_authenticator.rb +++ b/lib/net/imap/sasl/digest_md5_authenticator.rb @@ -20,8 +20,9 @@ class Net::IMAP::SASL::DigestMD5Authenticator # "Authentication identity" is the generic term used by # RFC-4422[https://tools.ietf.org/html/rfc4422]. # RFC-4616[https://tools.ietf.org/html/rfc4616] and many later RFCs abbreviate - # that to +authcid+. So +authcid+ is available as an alias for #username. + # this to +authcid+. attr_reader :username + alias authcid username # A password or passphrase that matches the #username. # @@ -42,8 +43,9 @@ class Net::IMAP::SASL::DigestMD5Authenticator attr_reader :authzid # :call-seq: - # new(username, password, authzid = nil, **options) -> authenticator + # new(authcid:, password:, authzid: nil, **options) -> authenticator # new(username:, password:, authzid: nil, **options) -> authenticator + # new(username, password, authzid = nil, **options) -> authenticator # # Creates an Authenticator for the "+DIGEST-MD5+" SASL mechanism. # @@ -51,25 +53,36 @@ class Net::IMAP::SASL::DigestMD5Authenticator # # ==== Parameters # - # * #username — Identity whose #password is used. - # * #password — A password or passphrase associated with this #username. - # * #authzid ― Alternate identity to act as or on behalf of. Optional. - # * +warn_deprecation+ — Set to +false+ to silence the warning. + # * #username ― Authentication identity that is associated with #password. + # * #authcid ― An alias for +username+. + # * #password ― A password or passphrase associated with this #username. + # * _optional_ #authzid ― Authorization identity to act as or on behalf of. + # * _optional_ +warn_deprecation+ — Set to +false+ to silence the warning. + # + # Any other keyword arguments are silently ignored. + # + # When +authzid+ is not set, the server should derive the authorization + # identity from the authentication identity. # # See the documentation for each attribute for more details. def initialize(user = nil, pass = nil, authz = nil, - username: nil, password: nil, authzid: nil, - warn_deprecation: true, **) - username ||= user or raise ArgumentError, "missing username" - password ||= pass or raise ArgumentError, "missing password" - authzid ||= authz + authcid: nil, username: nil, + authzid: nil, + password: nil, + warn_deprecation: true, + **) + @username = authcid || username || user + @password = password || pass + @authzid = authzid || authz + @username or raise ArgumentError, "missing username (authcid)" + @password or raise ArgumentError, "missing password" + if warn_deprecation warn "WARNING: DIGEST-MD5 SASL mechanism was deprecated by RFC6331." # TODO: recommend SCRAM instead. end require "digest/md5" require "strscan" - @username, @password, @authzid = username, password, authzid @nc, @stage = {}, STAGE_ONE end diff --git a/lib/net/imap/sasl/external_authenticator.rb b/lib/net/imap/sasl/external_authenticator.rb index f229c63d..f32e5eea 100644 --- a/lib/net/imap/sasl/external_authenticator.rb +++ b/lib/net/imap/sasl/external_authenticator.rb @@ -12,28 +12,48 @@ module SASL # established external to SASL, for example by TLS certificate or IPsec. class ExternalAuthenticator - # Authorization identity: an identity to act as or on behalf of. + # Authorization identity: an identity to act as or on behalf of. The + # identity form is application protocol specific. If not provided or + # left blank, the server derives an authorization identity from the + # authentication identity. The server is responsible for verifying the + # client's credentials and verifying that the identity it associates + # with the client's authentication identity is allowed to act as (or on + # behalf of) the authorization identity. + # + # For example, an administrator or superuser might take on another role: + # + # imap.authenticate "PLAIN", "root", passwd, authzid: "user" # - # If not explicitly provided, the server defaults to using the identity - # that was authenticated by the external credentials. attr_reader :authzid + # An alias for #authzid. + alias username authzid + # :call-seq: - # new(authzid: nil, **) -> authenticator + # new(authzid: nil, **) -> authenticator + # new(username: nil, **) -> authenticator + # new(username = nil, **) -> authenticator # # Creates an Authenticator for the "+EXTERNAL+" SASL mechanism, as # specified in RFC-4422[https://tools.ietf.org/html/rfc4422]. To use # this, see Net::IMAP#authenticate or your client's authentication # method. # - # #authzid is an optional identity to act as or on behalf of. + # ==== Parameters + # + # * _optional_ #authzid ― Authorization identity to act as or on behalf of. + # * _optional_ #username ― An alias for #authzid. + # + # Note that, unlike some other authenticators, the +username+ keyword + # parameter sets the authorization identity and not the authentication + # identity. The authenticated identity is established for the client + # with the OAuth credential. # # Any other keyword parameters are quietly ignored. - def initialize(authzid: nil, **) - @authzid = authzid&.to_str&.encode "UTF-8" - if @authzid&.match?(/\u0000/u) # also validates UTF8 encoding - raise ArgumentError, "contains NULL" - end + def initialize(user = nil, authzid: nil, username: nil, **) + @authzid = authzid || username || user + @authzid &&= @authzid.to_str.encode "UTF-8" + raise ArgumentError, "contains NULL" if @authzid&.match?(/\u0000/u) @done = false end diff --git a/lib/net/imap/sasl/oauthbearer_authenticator.rb b/lib/net/imap/sasl/oauthbearer_authenticator.rb index c23c35f9..240c9c60 100644 --- a/lib/net/imap/sasl/oauthbearer_authenticator.rb +++ b/lib/net/imap/sasl/oauthbearer_authenticator.rb @@ -14,13 +14,20 @@ module SASL class OAuthAuthenticator include GS2Header - # Authorization identity: an identity to act as or on behalf of. + # Authorization identity: an identity to act as or on behalf of. The + # identity form is application protocol specific. If not provided or + # left blank, the server derives an authorization identity from the + # authentication identity. The server is responsible for verifying the + # client's credentials and verifying that the identity it associates + # with the client's authentication identity is allowed to act as (or on + # behalf of) the authorization identity. + # + # For example, an administrator or superuser might take on another role: + # + # imap.authenticate "PLAIN", "root", passwd, authzid: "user" # - # If no explicit authorization identity is provided, it is usually - # derived from the authentication identity. For the OAuth-based - # mechanisms, the authentication identity is the identity established by - # the OAuth credential. attr_reader :authzid + alias username authzid # Hostname to which the client connected. attr_reader :host @@ -39,6 +46,7 @@ class OAuthAuthenticator # The query string. (optional) attr_reader :qs + alias query qs # Stores the most recent server "challenge". When authentication fails, # this may hold information about the failure reason, as JSON. @@ -47,29 +55,44 @@ class OAuthAuthenticator # Creates an RFC7628[https://tools.ietf.org/html/rfc7628] OAuth # authenticator. # - # === Options + # ==== Parameters + # + # See child classes for required parameter(s). The following parameters + # are all optional, but it is worth noting that application protocols + # are allowed to require #authzid (or other parameters, such as + # #host or #port) as are specific server implementations. # - # See child classes for required configuration parameter(s). The - # following parameters are all optional, but protocols or servers may - # add requirements for #authzid, #host, #port, or any other parameter. + # * _optional_ #authzid ― Authorization identity to act as or on behalf of. + # * _optional_ #username — An alias for #authzid. # - # * #authzid ― Identity to act as or on behalf of. - # * #host — Hostname to which the client connected. - # * #port — Service port to which the client connected. - # * #mthd — HTTP method - # * #path — HTTP path data - # * #post — HTTP post data - # * #qs — HTTP query string + # Note that, unlike some other authenticators, the +username+ keyword + # parameter sets the authorization identity and not the authentication + # identity. The authenticated identity is established for the client + # with the #oauth2_token. + # * _optional_ #host — Hostname to which the client connected. + # * _optional_ #port — Service port to which the client connected. + # * _optional_ #mthd — HTTP method + # * _optional_ #path — HTTP path data + # * _optional_ #post — HTTP post data + # * _optional_ #qs — HTTP query string + # * _optional_ #query — An alias for #qs # + # Any other keyword parameters are quietly ignored. + # + # Note that, unlike some other authenticators, the +username+ keyword + # parameter sets the authorization identity and not the authentication + # identity. The authenticated identity is established for the client + # with the OAuth credential. def initialize(authzid: nil, host: nil, port: nil, + username: nil, query: nil, mthd: nil, path: nil, post: nil, qs: nil, **) - @authzid = authzid + @authzid = authzid || username @host = host @port = port @mthd = mthd @path = path @post = post - @qs = qs + @qs = qs || query @done = false end @@ -116,36 +139,48 @@ def authorization; raise "must be implemented by subclass" end # the bearer token. class OAuthBearerAuthenticator < OAuthAuthenticator - # An OAuth2 bearer token, generally the access token. + # An OAuth 2.0 bearer token. See {RFC-6750}[https://www.rfc-editor.org/rfc/rfc6750] attr_reader :oauth2_token # :call-seq: - # new(oauth2_token, **options) -> authenticator - # new(oauth2_token:, **options) -> authenticator + # new(oauth2_token:, authzid: nil, host: nil, port: nil, **options) -> authenticator + # new(oauth2_token:, username: nil, host: nil, port: nil, **options) -> authenticator + # new(oauth2_token, authzid: nil, host: nil, port: nil, **options) -> authenticator + # new(authzid, oauth2_token, host: nil, port: nil, **options) -> authenticator # # Creates an Authenticator for the "+OAUTHBEARER+" SASL mechanism. # # Called by Net::IMAP#authenticate and similar methods on other clients. # - # === Options - # - # Only +oauth2_token+ is required by the mechanism, however protocols - # and servers may add requirements for #authzid, #host, #port, or any - # other parameter. - # - # * #oauth2_token — An OAuth2 bearer token or access token. *Required.* - # May be provided as either regular or keyword argument. - # * #authzid ― Identity to act as or on behalf of. - # * #host — Hostname to which the client connected. - # * #port — Service port to which the client connected. - # * See OAuthAuthenticator documentation for less common parameters. - # - def initialize(oauth2_token_arg = nil, oauth2_token: nil, **args, &blk) - super(**args, &blk) # handles authzid, host, port, etc - oauth2_token && oauth2_token_arg and - raise ArgumentError, "conflicting values for oauth2_token" - @oauth2_token = oauth2_token || oauth2_token_arg or - raise ArgumentError, "missing oauth2_token" + # ==== Parameters + # + # * #oauth2_token — An OAuth2 bearer token + # + # All other keyword parameters are passed to + # {super}[rdoc-ref:OAuthAuthenticator::new]. The most common ones are: + # + # * _optional_ #authzid ― Authorization identity to act as or on behalf of. + # * _optional_ #username — An alias for #authzid. + # + # Note that, unlike some other authenticators, the +username+ keyword + # parameter sets the authorization identity and not the authentication + # identity. The authenticated identity is established for the client + # with the #oauth2_token. + # * _optional_ #host — Hostname to which the client connected. + # * _optional_ #port — Service port to which the client connected. + # + # Only +oauth2_token+ is required by this mechanism, but it is worth + # noting that application protocols are allowed to require + # #authzid (or other parameters, such as #host or #port) as are + # specific server implementations. At the time this was written, + # Gmail and Yahoo Mail both required +authzid+. + # + # See OAuthAuthenticator documentation for other parameters. + def initialize(arg1 = nil, arg2 = nil, oauth2_token: nil, **args, &blk) + username, oauth2_token_arg = arg2.nil? ? [nil, arg1] : [arg1, arg2] + super(username: username, **args, &blk) + @oauth2_token = oauth2_token || oauth2_token_arg + @oauth2_token or raise ArgumentError, "missing oauth2_token" end # :call-seq: diff --git a/lib/net/imap/sasl/plain_authenticator.rb b/lib/net/imap/sasl/plain_authenticator.rb index c8539282..c1b98946 100644 --- a/lib/net/imap/sasl/plain_authenticator.rb +++ b/lib/net/imap/sasl/plain_authenticator.rb @@ -22,6 +22,7 @@ class Net::IMAP::SASL::PlainAuthenticator # RFC-4616[https://tools.ietf.org/html/rfc4616] and many later RFCs abbreviate # this to +authcid+. attr_reader :username + alias authcid username # A password or passphrase that matches the #username. attr_reader :password @@ -40,34 +41,41 @@ class Net::IMAP::SASL::PlainAuthenticator attr_reader :authzid # :call-seq: - # new(username, password, authzid: nil, **) -> authenticator + # new(authcid:, password:, authzid: nil, **) -> authenticator # new(username:, password:, authzid: nil, **) -> authenticator + # new(username, password, authzid: nil, **) -> authenticator # # Creates an Authenticator for the "+PLAIN+" SASL mechanism. # # Called by Net::IMAP#authenticate and similar methods on other clients. # - # === Parameters + # ==== Parameters + # + # * #username ― Authentication identity that is associated with #password. + # * #authcid ― An alias for #username. + # * #password ― A password or passphrase associated with #username. + # * _optional_ #authzid ― Authorization identity to act as or on behalf of. # - # * #username ― Identity whose +password+ is used. - # * #password ― Password or passphrase associated with this username+. - # * #authzid ― Alternate identity to act as or on behalf of. Optional. + # Any other keyword parameters are quietly ignored. + # + # When +authzid+ is not set, the server should derive the authorization + # identity from the authentication identity. # # See attribute documentation for more details. def initialize(user = nil, pass = nil, - username: nil, password: nil, authzid: nil, **) - [username, user].compact.count == 1 or - raise ArgumentError, "conflicting values for username" - [password, pass].compact.count == 1 or - raise ArgumentError, "conflicting values for password" - username ||= user or raise ArgumentError, "missing username" - password ||= pass or raise ArgumentError, "missing password" - raise ArgumentError, "username contains NULL" if username.include?(NULL) - raise ArgumentError, "password contains NULL" if password.include?(NULL) - raise ArgumentError, "authzid contains NULL" if authzid&.include?(NULL) - @username = username - @password = password + authcid: nil, username: nil, + authzid: nil, + password: nil, + **) + @username = authcid || username || user + @password = password || pass @authzid = authzid + @username or raise ArgumentError, "missing username (authcid)" + @password or raise ArgumentError, "missing password" + raise ArgumentError, "username contains NULL" if @username.include?(NULL) + raise ArgumentError, "password contains NULL" if @password.include?(NULL) + raise ArgumentError, "authzid contains NULL" if @authzid&.include?(NULL) + @done = false end diff --git a/lib/net/imap/sasl/scram_authenticator.rb b/lib/net/imap/sasl/scram_authenticator.rb index d8d36947..cecfbe2e 100644 --- a/lib/net/imap/sasl/scram_authenticator.rb +++ b/lib/net/imap/sasl/scram_authenticator.rb @@ -58,8 +58,9 @@ class ScramAuthenticator include ScramAlgorithm # :call-seq: - # new(username, password, **options) -> auth_ctx + # new(authzid:, password:, **options) -> auth_ctx # new(username:, password:, **options) -> auth_ctx + # new(username, password, **options) -> auth_ctx # # Creates an authenticator for one of the "+SCRAM-*+" SASL mechanisms. # Each subclass defines #digest to match a specific mechanism. @@ -68,34 +69,39 @@ class ScramAuthenticator # # === Parameters # - # * #username ― Identity whose #password is used. Aliased as #authcid. + # * #username ― Identity whose #password is used. + # * #authcid - An alias for #username. # * #password ― Password or passphrase associated with this #username. # * #authzid ― Alternate identity to act as or on behalf of. Optional. # * #min_iterations - Overrides the default value (4096). Optional. # # See the documentation on the corresponding attributes for more. def initialize(username_arg = nil, password_arg = nil, - username: nil, password: nil, authcid: nil, authzid: nil, + authcid: nil, username: nil, + authzid: nil, + password: nil, min_iterations: 4096, # see both RFC5802 and RFC7677 cnonce: nil, # must only be set in tests - **options) - @username = username || username_arg || authcid or - raise ArgumentError, "missing username (authcid)" - [username, username_arg, authcid].compact.count == 1 or - raise ArgumentError, "conflicting values for username (authcid)" - @password = password || password_arg or - raise ArgumentError, "missing password" - [password, password_arg].compact.count == 1 or - raise ArgumentError, "conflicting values for password" - @authzid = authzid + **) + @username = authcid || username || username_arg + @password = password || password_arg + @authzid = authzid + @username or raise ArgumentError, "missing username (authcid)" + @password or raise ArgumentError, "missing password" @min_iterations = Integer min_iterations - @min_iterations.positive? or - raise ArgumentError, "min_iterations must be positive" + @min_iterations.positive? or raise ArgumentError, "min_iterations must be positive" + @cnonce = cnonce || SecureRandom.base64(32) end # Authentication identity: the identity that matches the #password. + # + # RFC-2831[https://tools.ietf.org/html/rfc2831] uses the term +username+. + # "Authentication identity" is the generic term used by + # RFC-4422[https://tools.ietf.org/html/rfc4422]. + # RFC-4616[https://tools.ietf.org/html/rfc4616] and many later RFCs abbreviate + # this to +authcid+. attr_reader :username alias authcid username diff --git a/lib/net/imap/sasl/xoauth2_authenticator.rb b/lib/net/imap/sasl/xoauth2_authenticator.rb index 164afa0d..53f7830c 100644 --- a/lib/net/imap/sasl/xoauth2_authenticator.rb +++ b/lib/net/imap/sasl/xoauth2_authenticator.rb @@ -27,13 +27,19 @@ class Net::IMAP::SASL::XOAuth2Authenticator # authorization identity. attr_reader :username + # Note that, unlike most other authenticators, #username is an alias for the + # authorization identity and not the authentication identity. The + # authenticated identity is established for the client by the #oauth2_token. + alias authzid username + # An OAuth2 access token which has been authorized with the appropriate OAuth2 # scopes to use the service for #username. attr_reader :oauth2_token # :call-seq: - # new(username, oauth2_token, **) -> authenticator + # new(authzid:, oauth2_token:, **) -> authenticator # new(username:, oauth2_token:, **) -> authenticator + # new(username, oauth2_token, **) -> authenticator # # Creates an Authenticator for the "+XOAUTH2+" SASL mechanism, as specified by # Google[https://developers.google.com/gmail/imap/xoauth2-protocol], @@ -43,19 +49,25 @@ class Net::IMAP::SASL::XOAuth2Authenticator # === Properties # # * #username --- the username for the account being accessed. + # * #authzid --- an alias for #username. # * #oauth2_token --- An OAuth2.0 access token which is authorized to access # the service for #username. # + # Note that, unlike most other authenticators, the +username+ keyword + # parameter sets the authorization identity and not the authentication + # identity. The authenticated identity is established for the client with the + # OAuth credential. + # # See the documentation for each attribute for more details. - def initialize(user = nil, token = nil, username: nil, oauth2_token: nil, **) - @username = username || user or - raise ArgumentError, "missing username" - @oauth2_token = oauth2_token || token or - raise ArgumentError, "missing oauth2_token" - [username, user].compact.count == 1 or - raise ArgumentError, "conflicting values for username" - [oauth2_token, token].compact.count == 1 or - raise ArgumentError, "conflicting values for oauth2_token" + def initialize(user = nil, token = nil, + authzid: nil, username: nil, + oauth2_token: nil, + **) + @username = username || authzid || user + @oauth2_token = oauth2_token || token + @username or raise ArgumentError, "missing username (authcid)" + @oauth2_token or raise ArgumentError, "missing oauth2_token" + @done = false end diff --git a/test/net/imap/test_imap_authenticators.rb b/test/net/imap/test_imap_authenticators.rb index 38773a29..38afb1fc 100644 --- a/test/net/imap/test_imap_authenticators.rb +++ b/test/net/imap/test_imap_authenticators.rb @@ -45,13 +45,34 @@ def test_plain_supports_initial_response def test_plain_response assert_equal("\0authc\0passwd", plain("authc", "passwd").process(nil)) + end + + def test_plain_authzid assert_equal("authz\0user\0pass", plain("user", "pass", authzid: "authz").process(nil)) end + def test_plain_kw_params + assert_equal( + "zid\0cid\0p", + plain(authcid: "cid", password: "p", authzid: "zid").process(nil) + ) + end + + def test_plain_username_kw_sets_both_authcid_and_authzid + assert_equal( + "\0uname\0passwd", + plain(username: "uname", password: "passwd").process(nil) + ) + end + def test_plain_no_null_chars assert_raise(ArgumentError) { plain("bad\0user", "pass") } assert_raise(ArgumentError) { plain("user", "bad\0pass") } + assert_raise(ArgumentError) { plain(authcid: "bad\0user", password: "p") } + assert_raise(ArgumentError) { plain(username: "bad\0user", password: "p") } + assert_raise(ArgumentError) { plain(username: "u", password: "bad\0pass") } + assert_raise(ArgumentError) { plain("u", "p", authzid: "bad\0authz") } assert_raise(ArgumentError) { plain("u", "p", authzid: "bad\0authz") } end @@ -244,7 +265,11 @@ def test_external_matches_mechanism def test_external_response assert_equal("", external.process(nil)) + assert_equal("", external.process("")) assert_equal("kwarg", external(authzid: "kwarg").process(nil)) + assert_equal("username", external(username: "username").process(nil)) + assert_equal("z", external("p", authzid: "z", username: "u").process(nil)) + assert_equal("positional", external("positional").process(nil)) end def test_external_utf8 @@ -256,7 +281,6 @@ def test_external_utf8 def test_external_invalid assert_raise(ArgumentError) { external(authzid: "bad\0contains NULL") } assert_raise(ArgumentError) { external(authzid: "invalid utf8\x80") } - assert_raise(ArgumentError) { external("invalid positional argument") } end # ----------------------