x/crypto/ssh: add a specific error for algorithm negotiation issues/errors

[drakkan]

A common requirement for applications using x/crypto/ssh is to report some errors differently than others.
We currently have ServerAuthError and ErrNoAuth which are useful for authentication related errors.

If the client and the server cannot negotiate a common algorithm for host key, KEX, cipher, MAC we have a generic error and can only search for the error string.
New algorithms are added over time and old algorithms are deprecated and disabled by default, so a well defined error allows applications using the library to better report errors to end users and allow them to fix the issue (e.g by enabling an old algorithm).

An algorithm negotiation error is typically returned in the findCommon method, but the same error should also be returned in other places, for example if pickHostKey fails or in enterKeyExchange so searching for an error string is quite fragile.

We can add something very simple like this

// ErrAlgorithmNegotiation is the error returned if the client and the server cannot agree
// on an algorithm for host key, KEX, cipher, MAC or if an unsupported algorithm 
// is configured.
var ErrAlgorithmNegotiation = errors.New("ssh: algorithm negotiation error")

and wrap this error when needed, for example in findCommon we could use

return "", fmt.Errorf("%w: ssh: no common algorithm for %s; client offered: %v, server offered: %v", ErrAlgorithm, what, client, server)

instead of

return "", fmt.Errorf("ssh: no common algorithm for %s; client offered: %v, server offered: %v", what, client, server)

and the same in other places where there is an algorithm error.

If you see CL 508398, this error may also be returned if NewSignerWithAlgorithms fails for example.

We could also evaluate something more complex, such as an error structure with an exported error code for each error category.
This way we could, for example, have specific error codes for MAC, KEX or cipher negotiation errors, I'm not sure if it's worth the effort to implement and maintain, but if you prefer this approach I can try to propose an API for that as well.

cc @golang/security

[FiloSottile]

This sounds good. Two notes: it should be possible to make this play well with #58523, at least to expose the remote’s supported algorithms, which might be useful to track in metrics for applications; and we can make the final error string the same as before so we don’t break current string matching applications.ErrAlgorithms feels a bit generic as a name. ErrAlgorithmNegotiation or ErrNoCommonAlgorithms?

[drakkan]

@FiloSottile do you mean something like this?

// ErrAlgorithmNegotiation is the error returned if the client and the server cannot agree
// on an algorithm for host key, KEX, cipher, MAC or if an unsupported algorithm
// is configured.
var ErrAlgorithmNegotiation = &AlgorithmNegotiationError{}

type AlgorithmNegotiationError struct {
	err                 error
	SupportedAlgorithms []string
}

func (e *AlgorithmNegotiationError) Error() string {
	return e.err.Error()
}

func (e *AlgorithmNegotiationError) Is(target error) bool {
	_, ok := target.(*AlgorithmNegotiationError)
	return ok
}

func (e *AlgorithmNegotiationError) Unwrap() error {
	return e.err
}

so we can use

errors.Is(err, ErrAlgorithmNegotiation)

var algoNegotiationErr *AlgorithmNegotiationError
errors.As(err, &algoNegotiationErr)

[FiloSottile]

I mean that if in #58523 we come up with an Algorithms type, we should maybe expose it as part of AlgorithmNegotiationError. (No need to have ErrAlgorithmNegotiation if we have AlgorithmNegotiationError, applications can just use errors.As.)

[drakkan]

ok thanks.

So the struct approach should be fine

// AlgorithmNegotiationError defines the error returned if the client and the
// server cannot agree on an algorithm for host key, KEX, cipher, MAC or if an
// unsupported algorithm is configured.
type AlgorithmNegotiationError struct {
	err                 error
	SupportedAlgorithms []string
}

func (e *AlgorithmNegotiationError) Error() string {
	return e.err.Error()
}

func (e *AlgorithmNegotiationError) Is(target error) bool {
	_, ok := target.(*AlgorithmNegotiationError)
	return ok
}

func (e *AlgorithmNegotiationError) Unwrap() error {
	return e.err
}

for now the algorithms are strings. If this changes in the future, we can use of the Algorithm type instead of strings.

However, it's probably better to wait for an accepted proposal for #58523 before proceeding here

[hanwen]

for now the algorithms are strings. If this changes in the future, we can use of the Algorithm type instead of strings.

we can't change the type for things like "aes128-ctr" from string to something else. That would break backward compatibility.

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[hanwen]

it should be possible to make this play well with #58523, at least to expose the remote’s supported algorithms,

not sure: that bug is about exposing algorithms in a successful connection setup (single algorithm for hostkey, kex, mac & cipher), where this issue is about unsuccessful connection setup (list of algorithms for one of {kex,mac,cipher,hostkey}). For backward compat reasons, the algorithms have to be string, so I don't think you can do much better than a proposal of struct AlgorithmError { What string; Algorithms []string }

[drakkan]

@hanwen if we want to add What string perhaps we should also consider exposing these constants.

Other than that, what do you think about this?

// AlgorithmNegotiationError defines the error returned if the client and the
// server cannot agree on an algorithm for host key, KEX, cipher, MAC or if an
// unsupported algorithm is configured.
type AlgorithmNegotiationError struct {
	err                 error
	What                string
	RequestedAlgorithms []string
	SupportedAlgorithms []string
}