openbsd-src / usr.bin / ssh / PROTOCOL.agent

The SSH agent protocol is described in
https://datatracker.ietf.org/doc/draft-ietf-sshm-ssh-agent/

This file documents OpenSSH's extensions to the agent protocol.

1. [e-mail] extension

This extension allows a ssh client to bind an agent connection to a
particular SSH session identifier as derived from the initial key
exchange (as per RFC4253 section 7.2) and the host key used for that
exchange. This binding is verifiable at the agent by including the
initial KEX signature made by the host key.

The message format is:

	byte		SSH_AGENTC_EXTENSION (0x1b)
	string		[e-mail]
	string		hostkey
	string		session identifier
	string		signature
	bool		is_forwarding

Where 'hostkey' is the encoded server host public key, 'session
identifier' is the exchange hash derived from the initial key
exchange, 'signature' is the server's signature of the session
identifier using the private hostkey, as sent in the final
SSH2_MSG_KEXDH_REPLY/SSH2_MSG_KEXECDH_REPLY message of the initial key
exchange. 'is_forwarding' is a flag indicating whether this connection
should be bound for user authentication or forwarding.

When an agent received this message, it will verify the signature and
check the consistency of its contents, including refusing to accept
a duplicate session identifier, or any attempt to bind a connection
previously bound for authentication. It will then record the
binding for the life of the connection for use later in testing per-key
destination constraints.

2. [e-mail] key constraint extension

The key constraint extension supports destination- and forwarding path-
restricted keys. It may be attached as a constraint when keys or
smartcard keys are added to an agent.

	byte		SSH_AGENT_CONSTRAIN_EXTENSION (0xff)
	string		[e-mail]
	constraint[]	constraints

Where a constraint consists of:

	string		from_username (must be empty)
	string		from_hostname
	string		reserved
	keyspec[]	from_hostkeys
	string		to_username
	string		to_hostname
	string		reserved
	keyspec[]	to_hostkeys
	string		reserved

And a keyspec consists of:

	string		keyblob
	bool		is_ca

When receiving this message, the agent will ensure that the
'from_username' field is empty, and that 'to_hostname' and 'to_hostkeys'
have been supplied (empty 'from_hostname' and 'from_hostkeys' are valid
and signify the initial hop from the host running ssh-agent). The agent
will then record the constraint against the key.

Subsequent operations on this key including add/remove/request
identities and, in particular, signature requests will check the key
constraints against the [e-mail] bindings recorded for
the agent connection over which they were received.

3. [e-mail] key constraint extension

The key constraint extension allows certificates to be associated
with private keys as they are loaded from a PKCS#11 token.

	byte		SSH_AGENT_CONSTRAIN_EXTENSION (0xff)
	string		[e-mail]
	bool		certs_only
	string		certsblob

Where "certsblob" consists of one or more certificates encoded as public
key blobs:

	string[]	certificates

This extension is only valid for SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED
requests. When an agent receives this extension, it will attempt to match
each certificate in the request with a corresponding private key loaded
from the requested PKCS#11 token. When a matching key is found, the
agent will graft the certificate contents to the token-hosted private key
and store the result for subsequent use by regular agent operations.

If the "certs_only" flag is set, then this extension will cause ONLY
the resultant certificates to be loaded to the agent. The default
behaviour is to load the PKCS#11-hosted private key as well as the
resultant certificate.

A SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED will return SSH_AGENT_SUCCESS
if any key (plain private or certificate) was successfully loaded, or
SSH_AGENT_FAILURE if no key was loaded.

$OpenBSD: PROTOCOL.agent,v 1.25 2025/08/29 03:50:38 djm Exp $