Honoring server-reported and client-enabled capabilities #49
Description
- Depends on:
- Subtasks:
- Security related (authentication, TLS, etc)
- Related:
- refuse LOGIN for cleartext connections
- refuse AUTHENTICATE for cleartext connections, configurable per authenticator
Using capabilities information
The client should track whenever it is knowingly violating capabilitied, either server reported or client enabled. At the very least, this should include checking capabilities before sending specific commands or command arguments.
Client-enabled capabilties
There will be no API to work around client.enable(capability). Users who are determined to evade this limitation can figure out how cheat with client.instance_variable_set(...).
Server reported capabilities
The server capabilties cache will always be kept up-to-date when capabilities are checked. If the server hasn't sent its capabilities unsolicited, the client will request capabilties whenever capabilities are checked.
If the capabilities check fails:
- For new commands or new arguments to existing commands.
- A
CapabilityErrorwill be raised without issuing any command to the server,
- A
- Where there is a security risk.
- A
CapabilityErrorwill be raised without issuing any command to the server, - This is backwards incompatible!
- A
- For other existing commands with existing command arguments.
- A warning will be printed to
$stderrbut the command will still be sent
- A warning will be printed to
In some future version of Net::IMAP (perhaps the version released with ruby 3.2 or 3.3), the default for existing commands should change to match the behavior for new commands.
Configuration
To opt-out of the new behavior or to opt-in to more strict behavior:
Net::IMAP#enforce_capabilities=nil-- Uses the current default behavior, which can change in future releases.true-- Always raise an exception for any failed capabilities checks. Never knowingly sends unsupported commands or command arguments to the server.:warn-- Prints a warning to$stderrfor non-security-related capabilities, regardless of the command or the currentNet::IMAPdefault. Still raises for security-related capabilities checks.false-- Restores old default behavior: client doesn't care about server capabilities. Still warns for security-related capabilities checks.def []: (CapabilityError, Net::IMAP) -> (nil | true | false | :warn), eg. aProc. May change security-related capabilities handling.. The command, command args, required capabilities, etc will all be available on CapabilityError.
Net::IMAP#initialize(*args, **kwargs, enforce_capabilities: cfg)- Shorthand for
Net::IMAP.new(...).tap {|client| client.enforce_capabilities = cfg }
- Shorthand for
Net::IMAP#cmdname(..., enforce_capabilities: cfg)#cmdnamerepresents any command which might check server capability.- This kwarg also changes security-related capabilities handling for
#starttls,#authenticate,#login.
opting out of security errors
enforce_capabilities: false will still raise a warning for security related violations. These warnings can only be disabled with a proc.
client.authenticate("PLAIN", username, password, enforce_capabilities: false)
# $stderr << "warning: Ignoring server capability \"AUTH=PLAIN\"" unless capability?("AUTH=PLAIN")
# The server might respond with a tagged `NO` => `NoResponseError`
client.login(username, password, enforce_capabilities: false)
# $stderr << "warning: Ignoring server capability \"LOGINDISABLED\"" if capability?("LOGINDISABLED")
# The server might respond with a tagged `NO` => `NoResponseError`
# Always ignore server capabilities. Please don't do this!
client = Net::IMAP.new(..., enforce_capabilities: -> _ { false })
client.enforce_capabilities = -> _ { false }Allow fine-grained configuration with a Proc
The arguments will be a CapabilityError exception (which can be raised) and the Net::IMAP client object (in case the proc is shared between multiple clients). CapabilityError should have at least one sub-class, SecurityCapabilityError, to represent LOGINDISABLED, AUTH=, STARTTLS capabilities, etc. CapabilityError and its subclasses should allow pattern matching via #deconstruct and/or #deconstruct_keys
This could be used to:
- add support for capabilities which haven't been added to
net-imapyet - log unexpectedly missing security related capabilities errors.
- log all capabilities errors.
client.enforce_capabilities = proc do |error|
case error
in AuthCapabilityError{sasl_mechanism: "FOOBAR"}
raise "Server doesn't support our pretend SASL mechanism"
in SecurityCapabilityError{command: "AUTHENTICATE" | "STARTTLS"}
raise SecureAuthUnsupportedError
in SecurityCapabilityError
raise error
in command: "SELECT" | "EXAMINE", capability: "QRESYNC"
error.run_alternate_commands do
# a theoretical API for gracefully degrading
end
in capability: "X_PLEASE_WARN"
logger.warn { "X_WARNING: error.warning" }
in capability: "X_PLEASE_WARN_2"
# let Net::IMAP handle warning via $stderr
# just like client.enforce_capabilities = :warn
:warn
in capability: "BINARY"
# let Net::IMAP raise the error
# just like client.enforce_capabilities = true
true
in capability: "X_THIS_CLIENT_ALLOWS_IT"
# ignore the missing capability
# just like client.enforce_capabilities = false
false
else
# use the default behavior for this version of Net::IMAP, i.e. warn now, raise later
# just like client.enforce_capabilities = nil
nil
end
end