|
| 1 | +# frozen_string_literal: true |
| 2 | + |
| 3 | +module Net |
| 4 | + class IMAP |
| 5 | + module SASL |
| 6 | + |
| 7 | + # This API is *experimental*, and may change. |
| 8 | + # |
| 9 | + # TODO: catch exceptions in #process and send #cancel_response. |
| 10 | + # TODO: raise an error if the command succeeds after being canceled. |
| 11 | + # TODO: use with more clients, to verify the API can accommodate them. |
| 12 | + # |
| 13 | + # Create an AuthenticationExchange from a client adapter and a mechanism |
| 14 | + # authenticator: |
| 15 | + # def authenticate(mechanism, ...) |
| 16 | + # authenticator = SASL.authenticator(mechanism, ...) |
| 17 | + # SASL::AuthenticationExchange.new( |
| 18 | + # sasl_adapter, mechanism, authenticator |
| 19 | + # ).authenticate |
| 20 | + # end |
| 21 | + # |
| 22 | + # private |
| 23 | + # |
| 24 | + # def sasl_adapter = MyClientAdapter.new(self, &method(:send_command)) |
| 25 | + # |
| 26 | + # Or delegate creation of the authenticator to ::build: |
| 27 | + # def authenticate(...) |
| 28 | + # SASL::AuthenticationExchange.build(sasl_adapter, ...) |
| 29 | + # .authenticate |
| 30 | + # end |
| 31 | + # |
| 32 | + # As a convenience, ::authenticate combines ::build and #authenticate: |
| 33 | + # def authenticate(...) |
| 34 | + # SASL::AuthenticationExchange.authenticate(sasl_adapter, ...) |
| 35 | + # end |
| 36 | + # |
| 37 | + # Likewise, ClientAdapter#authenticate delegates to #authenticate: |
| 38 | + # def authenticate(...) = sasl_adapter.authenticate(...) |
| 39 | + # |
| 40 | + class AuthenticationExchange |
| 41 | + # Convenience method for <tt>build(...).authenticate</tt> |
| 42 | + def self.authenticate(...) build(...).authenticate end |
| 43 | + |
| 44 | + # Use +registry+ to override the global Authenticators registry. |
| 45 | + def self.build(client, mechanism, *args, sasl_ir: true, **kwargs, &block) |
| 46 | + authenticator = SASL.authenticator(mechanism, *args, **kwargs, &block) |
| 47 | + new(client, mechanism, authenticator, sasl_ir: sasl_ir) |
| 48 | + end |
| 49 | + |
| 50 | + attr_reader :mechanism, :authenticator |
| 51 | + |
| 52 | + def initialize(client, mechanism, authenticator, sasl_ir: true) |
| 53 | + @client = client |
| 54 | + @mechanism = -mechanism.to_s.upcase.tr(?_, ?-) |
| 55 | + @authenticator = authenticator |
| 56 | + @sasl_ir = sasl_ir |
| 57 | + @processed = false |
| 58 | + end |
| 59 | + |
| 60 | + # Call #authenticate to execute an authentication exchange for #client |
| 61 | + # using #authenticator. Authentication failures will raise an |
| 62 | + # exception. Any exceptions other than those in RESPONSE_ERRORS will |
| 63 | + # drop the connection. |
| 64 | + def authenticate |
| 65 | + client.run_command(mechanism, initial_response) { process _1 } |
| 66 | + .tap { raise AuthenticationIncomplete, _1 unless done? } |
| 67 | + rescue *client.response_errors |
| 68 | + raise # but don't drop the connection |
| 69 | + rescue |
| 70 | + client.drop_connection |
| 71 | + raise |
| 72 | + rescue Exception # rubocop:disable Lint/RescueException |
| 73 | + client.drop_connection! |
| 74 | + raise |
| 75 | + end |
| 76 | + |
| 77 | + def send_initial_response? |
| 78 | + @sasl_ir && |
| 79 | + authenticator.respond_to?(:initial_response?) && |
| 80 | + authenticator.initial_response? && |
| 81 | + client.sasl_ir_capable? && |
| 82 | + client.auth_capable?(mechanism) |
| 83 | + end |
| 84 | + |
| 85 | + def done? |
| 86 | + authenticator.respond_to?(:done?) ? authenticator.done? : @processed |
| 87 | + end |
| 88 | + |
| 89 | + private |
| 90 | + |
| 91 | + attr_reader :client |
| 92 | + |
| 93 | + def initial_response |
| 94 | + return unless send_initial_response? |
| 95 | + client.encode_ir authenticator.process nil |
| 96 | + end |
| 97 | + |
| 98 | + def process(challenge) |
| 99 | + client.encode authenticator.process client.decode challenge |
| 100 | + ensure |
| 101 | + @processed = true |
| 102 | + end |
| 103 | + |
| 104 | + end |
| 105 | + end |
| 106 | + end |
| 107 | +end |
0 commit comments