golang/crypto

Use NewClient to create an ExtendedAgent that communicates with an ssh-agent process.

If the provided io.ReadWriter also implements io.Closer (such as a *net.UnixConn), the client will use a pipelined connection. This allows multiple goroutines to issue concurrent requests (like Sign or List) without waiting for previous responses to complete, improving performance.

If the transport does not implement io.Closer, the client falls back to a fully serialized mode where only one request can be in flight at a time.

The ClientConfig struct defines the parameters for an SSH connection.

Key fields:

• User: The username for authentication.
• Auth: A slice of AuthMethod to attempt.
• HostKeyCallback: Required. A function to validate the server's host key. If omitted, connection will fail.
• BannerCallback: A hook to handle the server's identification banner.
• AuthCallback: A hook for dynamic authentication selection.
• Timeout: Maximum time for the TCP connection establishment.

Use NewClientConn when you need fine-grained control over the connection, specifically when you need access to the incomingChannels and incomingRequests channels. This is useful for handling multiplexed traffic sent from the remote server to the client.

Note: The returned NewChannel and Request channels must be serviced (read from), otherwise the connection will hang.

If an authentication callback needs to signal that further steps are required (e.g., multi-factor authentication), it can return a *PartialSuccessError.

This error contains a Next field of type ServerAuthCallbacks, which defines the next set of authentication methods available to the client. This allows the server to dynamically transition between different authentication requirements.

The ClientAuthCallback allows you to dynamically choose an authentication method based on the current state of the handshake.

Return values:

• (AuthMethod, nil): Attempt this specific method next. Use ClientAuthContext.TriedMethods to avoid loops.
• (nil, nil): Automatically pick the next available method from ClientConfig.Auth.
• (nil, error): Abort the handshake with the returned error.

To add a key to the agent, use the Add method with an AddedKey struct. You can specify constraints like lifetime, confirmation requirements, or custom extensions.

Supported PrivateKey types: *rsa.PrivateKey, *dsa.PrivateKey, ed25519.PrivateKey, or *ecdsa.PrivateKey.

The Agent interface defines the standard operations for interacting with an SSH agent:

• List() ([]*Key, error): Returns a list of identities (public keys) known to the agent.
• Sign(key ssh.PublicKey, data []byte) (*ssh.Signature, error): Requests the agent to sign the provided data using the specified key.
• Add(key AddedKey) error: Adds a private key to the agent.
• Remove(key ssh.PublicKey) error: Removes all identities associated with the given public key.
• RemoveAll() error: Removes all identities from the agent.
• Lock(passphrase []byte) error: Locks the agent. Subsequent Sign and Remove calls will fail.
• Unlock(passphrase []byte) error: Unlocks the agent.
• Signers() ([]ssh.Signer, error): Returns a slice of ssh.Signer objects for all known keys, which can be used directly in ssh.ClientConfig for authentication.

Use NewControlClientConn to establish an SSH connection over an existing OpenSSH ControlMaster socket in proxy mode.

WARNING: This bypasses the standard cryptographic handshake. The provided net.Conn must be a local, secure connection (such as a Unix domain socket) connected to a running OpenSSH process. Passing a standard network connection (like TCP) will result in plaintext data leakage.