Annotation of src/usr.bin/ssh/PROTOCOL.agent, Revision 1.21
1.15 djm 1: The SSH agent protocol is described in
1.20 djm 2: https://tools.ietf.org/html/draft-miller-ssh-agent
1.13 djm 3:
1.17 dtucker 4: This file documents OpenSSH's extensions to the agent protocol.
1.15 djm 5:
6: 1. session-bind@openssh.com extension
7:
8: This extension allows a ssh client to bind an agent connection to a
9: particular SSH session identifier as derived from the initial key
10: exchange (as per RFC4253 section 7.2) and the host key used for that
11: exchange. This binding is verifiable at the agent by including the
12: initial KEX signature made by the host key.
13:
14: The message format is:
15:
16: byte SSH_AGENTC_EXTENSION (0x1b)
17: string session-bind@openssh.com
18: string hostkey
19: string session identifier
20: string signature
21: bool is_forwarding
22:
23: Where 'hostkey' is the encoded server host public key, 'session
1.16 jsg 24: identifier' is the exchange hash derived from the initial key
1.15 djm 25: exchange, 'signature' is the server's signature of the session
26: identifier using the private hostkey, as sent in the final
27: SSH2_MSG_KEXDH_REPLY/SSH2_MSG_KEXECDH_REPLY message of the initial key
28: exchange. 'is_forwarding' is a flag indicating whether this connection
29: should be bound for user authentication or forwarding.
30:
31: When an agent received this message, it will verify the signature and
32: check the consistency of its contents, including refusing to accept
33: a duplicate session identifier, or any attempt to bind a connection
1.19 jsg 34: previously bound for authentication. It will then record the
1.15 djm 35: binding for the life of the connection for use later in testing per-key
36: destination constraints.
37:
38: 2. restrict-destination-v00@openssh.com key constraint extension
39:
40: The key constraint extension supports destination- and forwarding path-
41: restricted keys. It may be attached as a constraint when keys or
42: smartcard keys are added to an agent.
43:
44: byte SSH_AGENT_CONSTRAIN_EXTENSION (0xff)
45: string restrict-destination-v00@openssh.com
46: constraint[] constraints
47:
48: Where a constraint consists of:
49:
50: string from_username (must be empty)
51: string from_hostname
52: keyspec[] from_hostkeys
53: string to_username
54: string to_hostname
55: keyspec[] to_hostkeys
56:
1.18 dtucker 57: And a keyspec consists of:
1.15 djm 58:
59: string keyblob
60: bool is_ca
61:
62: When receiving this message, the agent will ensure that the
63: 'from_username' field is empty, and that 'to_hostname' and 'to_hostkeys'
64: have been supplied (empty 'from_hostname' and 'from_hostkeys' are valid
1.16 jsg 65: and signify the initial hop from the host running ssh-agent). The agent
1.15 djm 66: will then record the constraint against the key.
67:
68: Subsequent operations on this key including add/remove/request
69: identities and, in particular, signature requests will check the key
1.16 jsg 70: constraints against the session-bind@openssh.com bindings recorded for
1.15 djm 71: the agent connection over which they were received.
72:
73: 3. SSH_AGENT_CONSTRAIN_MAXSIGN key constraint
74:
75: This key constraint allows communication to an agent of the maximum
76: number of signatures that may be made with an XMSS key. The format of
77: the constraint is:
78:
79: byte SSH_AGENT_CONSTRAIN_MAXSIGN (0x03)
80: uint32 max_signatures
81:
82: This option is only valid for XMSS keys.
83:
1.21 ! djm 84: 3. associated-certs-v00@openssh.com key constraint extension
! 85:
! 86: The key constraint extension allows certificates to be associated
! 87: with private keys as they are loaded from a PKCS#11 token.
! 88:
! 89: byte SSH_AGENT_CONSTRAIN_EXTENSION (0xff)
! 90: string associated-certs-v00@openssh.com
! 91: bool certs_only
! 92: string certsblob
! 93:
! 94: Where "certsblob" constists of one or more certificates encoded as public
! 95: key blobs:
! 96:
! 97: string[] certificates
! 98:
! 99: This extension is only valid for SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED
! 100: requests. When an agent receives this extension, it will attempt to match
! 101: each certificate in the request with a corresponding private key loaded
! 102: from the requested PKCS#11 token. When a matching key is found, the
! 103: agent will graft the certificate contents to the token-hosted private key
! 104: and store the result for subsequent use by regular agent operations.
! 105:
! 106: If the "certs_only" flag is set, then this extension will cause ONLY
! 107: the resultant certificates to be loaded to the agent. The default
! 108: behaviour is to load the PKCS#11-hosted private key as well as the
! 109: resultant certificate.
! 110:
! 111: A SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED will return SSH_AGENT_SUCCESS
! 112: if any key (plain private or certificate) was successfully loaded, or
! 113: SSH_AGENT_FAILURE if no key was loaded.
! 114:
! 115: $OpenBSD: PROTOCOL.agent,v 1.20 2023/10/03 23:56:10 djm Exp $