Skip to content

x/crypto/ssh: add ServerConfig.PreAuthConnCallback, ServerPreAuthConn (banner) interface #68688

Closed

Description

@awly

Proposal Details

SSH server has 2 methods of sending banners (SSH_MSG_USERAUTH_BANNER) back to the client:

  1. BannerCallback, which runs before any auth handlers
  2. BannerError return, which can be returned from any auth handler

However, the SSH spec allows banners to be sent at any point in the connection until authentication is complete, not bound to auth attempts. While we could add a new method on ssh.ConnMetadata (which is passed to auth handlers) or ssh.Conn (which can be type-asserted from ssh.ConnMetadata), this would break backwards-compatibility for custom implementations of those interfaces.

I propose we add a new single-purpose interface:

// BannerSender sends banner messages from the server to the client. Banners
// can only be sent before authentication is complete, from callbacks in
// ServerConfig. Calls to SendBanner after authentication always fail. Callers
// can access a BannerSender using a checked type assertion on the ConnMetadata
// value passed to the callbacks in ServerConfig. 
type BannerSender interface {
    SendBanner(message string) error
}

This new method would be implemented on the unexported *x/crypto/ssh.connection type, which is passed as ConnMetadata in authentication handlers. This is not very discoverable, but is the least disruptive API change I could think of.

In #64962 (comment) I claimed that this was sufficient for Tailscale's use case, but turns out it was not, that's my bad.
For example, a server can print a custom prompt or instruction to the user while an authentication attempt is pending, which is required for the user to finish that attempt.

cc @drakkan @oxtoacart @bradfitz

Activity

  1. added this to the Proposal milestone on Jul 31, 2024
  2. gabyhelp commented on Jul 31, 2024

    @gabyhelp

    Related Issues and Documentation

    (Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)

  3. moved this to Incoming in Proposalson Aug 7, 2024
  4. ianlancetaylor commented on Aug 7, 2024

    @ianlancetaylor
    Contributor

    CC @golang/security

  5. gopherbot commented on Sep 17, 2024

    @gopherbot
    Contributor

    Change https://go.dev/cl/613856 mentions this issue: ssh: add ServerConfig.GetPreAuthConn, ServerPreAuthConn (banner) interface

  6. gopherbot commented on Sep 22, 2024

    @gopherbot
    Contributor

    Change https://go.dev/cl/614416 mentions this issue: ssh: add BannerSender interface

  7. drakkan commented on Sep 29, 2024

    @drakkan
    Member

    I would like to discuss also the proposal implemented by @bradfitz in CL 613856.

    Here is the proposal, I just change the name of the callback to make it more similar to the existing ones:

    // ServerPreAuthConn is the interface available on an incoming server
    // connection before authentication has completed.
    type ServerPreAuthConn interface {
    	unexportedMethodForFutureProofing() // permits growing ServerPreAuthConn safely later, ala testing.TB
    
    	ConnMetadata
    
    	// SendAuthBanner sends a banner message to the client.
    	// It returns an error once the authentication phase has ended.
    	SendAuthBanner(string) error
    }
    
    // ServerConfig holds server specific configuration data.
    type ServerConfig struct {
         .....
         // PreAuthConnCallback, if non-nil, is called upon receiving a new connection
         // before any authentication has started. The provided ServerPreAuthConn
         // can be used before authentication is complete.
         PreAuthConnCallback func(ServerPreAuthConn)
    }
    

    The main difference with the other proposal is that here we add interface extension of the ConnMetadata that allows to send banners and we can obtain it by adding a PreAuthConnCallback to ServerConfig.

    The other approach allows to send banners using the ConnMetadata interface received in the authentication callbacks.

    PreAuthConnCallback seems more flexible, in the future we may consider reusing it to expose other methods or properties as well

  8. oxtoacart commented on Oct 29, 2024

    @oxtoacart
    Contributor

    @FiloSottile @drakkan Is there anything I can do to help move this forward?

  9. bradfitz commented on Oct 30, 2024

    @bradfitz
    Contributor

    I dusted off my CL above, did the rename, and added some tests: https://go-review.googlesource.com/c/crypto/+/613856

  10. added a commit that references this issue on Nov 1, 2024
    4e86b1d
  11. changed the title [-]proposal: x/crypto/ssh: add BannerSender interface[/-] [+]proposal: x/crypto/ssh: add ServerConfig.PreAuthConnCallback, ServerPreAuthConn (banner) interface[/+] on Nov 5, 2024
  12. bradfitz commented on Nov 5, 2024

    @bradfitz
    Contributor

    @FiloSottile, @drakkan, https://go-review.googlesource.com/c/crypto/+/613856 contains the latest proposal (with @drakkan's renames from above) and the approved implementation, on Hold for approval here.

    When does Crypto Proposal Committee meet? :)

  13. 10 remaining items

  14. moved this from Likely Accept to Accepted in Proposalson Jan 16, 2025
  15. aclements commented on Jan 16, 2025

    @aclements
    Member

    No change in consensus, so accepted. 🎉
    This issue now tracks the work of implementing the proposal.

    The proposal is to add the following interface type and configurable callback to golang.org/x/crypto/ssh

    // ServerPreAuthConn is the interface available on an incoming server
    // connection before authentication has completed.
    type ServerPreAuthConn interface {
    	unexportedMethodForFutureProofing() // permits growing ServerPreAuthConn safely later, ala testing.TB
    
    	ConnMetadata
    
    	// SendAuthBanner sends a banner message to the client.
    	// It returns an error if the authentication phase has ended.
    	SendAuthBanner(string) error
    }
    
    type ServerConfig struct {
    	...
    
    	// PreAuthConnCallback, if non-nil, is called upon receiving a new connection
    	// before any authentication has started. The provided ServerPreAuthConn
    	// can be used at any time before authentication is complete, including
    	// after this callback has returned.
    	PreAuthConnCallback func(ServerPreAuthConn)
    
    	...
    }
  16. changed the title [-]proposal: x/crypto/ssh: add ServerConfig.PreAuthConnCallback, ServerPreAuthConn (banner) interface[/-] [+]x/crypto/ssh: add ServerConfig.PreAuthConnCallback, ServerPreAuthConn (banner) interface[/+] on Jan 16, 2025
  17. modified the milestones: Proposal, Backlog on Jan 16, 2025
  18. bradfitz commented on Jan 16, 2025

    @bradfitz
    Contributor

    https://go.dev/cl/613856 is updated & ready.

  19. modified the milestones: Backlog, Unreleased on Jan 18, 2025
  20. added a commit that references this issue on Jan 18, 2025
    a8ea4be
  21. locked and limited conversation to collaborators on Jan 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions