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