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