upstream commit

Now that we no longer support SSHv1, replace the contents
of this file with a pointer to
https://tools.ietf.org/html/draft-miller-ssh-agent-00 It's better edited,
doesn't need to document stuff we no longer implement and does document stuff
that we do implement (RSA SHA256/512 signature flags)

Upstream-ID: da8cdc46bbcc266efabd565ddddd0d8e556f846e

1 files changed, 3 insertions, 582 deletions

diff --git a/PROTOCOL.agent b/PROTOCOL.agent
index 60d36f912..54cf2be4d 100644
--- a/PROTOCOL.agent
+++ b/PROTOCOL.agent
@@ -1,582 +1,3 @@
-This describes the protocol used by OpenSSH's ssh-agent.
-
-OpenSSH's agent supports managing keys for the standard SSH protocol
-2 as well as the legacy SSH protocol 1. Support for these key types
-is almost completely disjoint - in all but a few cases, operations on
-protocol 2 keys cannot see or affect protocol 1 keys and vice-versa.
-
-Protocol 1 and protocol 2 keys are separated because of the differing
-cryptographic usage: protocol 1 private RSA keys are used to decrypt
-challenges that were encrypted with the corresponding public key,
-whereas protocol 2 RSA private keys are used to sign challenges with
-a private key for verification with the corresponding public key. It
-is considered unsound practice to use the same key for signing and
-encryption.
-
-With a couple of exceptions, the protocol message names used in this
-document indicate which type of key the message relates to. SSH_*
-messages refer to protocol 1 keys only. SSH2_* messages refer to
-protocol 2 keys. Furthermore, the names also indicate whether the
-message is a request to the agent (*_AGENTC_*) or a reply from the
-agent (*_AGENT_*). Section 3 below contains the mapping of the
-protocol message names to their integer values.
-
-1. Data types
-
-Because of support for legacy SSH protocol 1 keys, OpenSSH's agent
-protocol makes use of some data types not defined in RFC 4251.
-
-1.1 uint16
-
-The "uint16" data type is a simple MSB-first 16 bit unsigned integer
-encoded in two bytes.
-
-1.2 mpint1
-
-The "mpint1" type represents an arbitrary precision integer (bignum).
-Its format is as follows:
-
-	uint16			bits
-	byte[(bits + 7) / 8]	bignum
-
-"bignum" contains an unsigned arbitrary precision integer encoded as
-eight bits per byte in big-endian (MSB first) format.
-
-Note the difference between the "mpint1" encoding and the "mpint"
-encoding defined in RFC 4251. Also note that the length of the encoded
-integer is specified in bits, not bytes and that the byte length of
-the integer must be calculated by rounding up the number of bits to the
-nearest eight.
-
-2. Protocol Messages
-
-All protocol messages are prefixed with their length in bytes, encoded
-as a 32 bit unsigned integer. Specifically:
-
-	uint32			message_length
-	byte[message_length]	message
-
-The following message descriptions refer only to the content the
-"message" field.
-
-2.1 Generic server responses
-
-The following generic messages may be sent by the server in response to
-requests from the client. On success the agent may reply either with:
-
-	byte			SSH_AGENT_SUCCESS
-
-or a request-specific success message.
-
-On failure, the agent may reply with:
-
-	byte			SSH_AGENT_FAILURE
-
-SSH_AGENT_FAILURE messages are also sent in reply to unknown request
-types.
-
-2.2 Adding keys to the agent
-
-Keys are added to the agent using the SSH_AGENTC_ADD_RSA_IDENTITY and
-SSH2_AGENTC_ADD_IDENTITY requests for protocol 1 and protocol 2 keys
-respectively.
-
-Two variants of these requests are SSH_AGENTC_ADD_RSA_ID_CONSTRAINED
-and SSH2_AGENTC_ADD_ID_CONSTRAINED - these add keys with optional
-"constraints" on their usage.
-
-OpenSSH may be built with support for keys hosted on a smartcard
-or other hardware security module. These keys may be added
-to the agent using the SSH_AGENTC_ADD_SMARTCARD_KEY and
-SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED requests.
-
-2.2.1 Key constraints
-
-The OpenSSH agent supports some basic optional constraints on key usage.
-At present there are two constraints defined.
-
-The first constraint limits the validity duration of a key. It is
-encoded as:
-
-	byte			SSH_AGENT_CONSTRAIN_LIFETIME
-	uint32			seconds
-
-Where "seconds" contains the number of seconds that the key shall remain
-valid measured from the moment that the agent receives it. After the
-validity period has expired, OpenSSH's agent will erase these keys from
-memory.
-
-The second constraint requires the agent to seek explicit user
-confirmation before performing private key operations with the loaded
-key. This constraint is encoded as:
-
-	byte			SSH_AGENT_CONSTRAIN_CONFIRM
-
-Zero or more constraints may be specified when adding a key with one
-of the *_CONSTRAINED requests. Multiple constraints are appended
-consecutively to the end of the request:
-
-	byte			constraint1_type
-	....			constraint1_data
-	byte			constraint2_type
-	....			constraint2_data
-	....
-	byte			constraintN_type
-	....			constraintN_data
-
-Such a sequence of zero or more constraints will be referred to below
-as "constraint[]". Agents may determine whether there are constraints
-by checking whether additional data exists in the "add key" request
-after the key data itself. OpenSSH will refuse to add a key if it
-contains unknown constraints.
-
-2.2.2 Add protocol 1 key
-
-A client may add a protocol 1 key to an agent with the following
-request:
-
-	byte			SSH_AGENTC_ADD_RSA_IDENTITY or
-				SSH_AGENTC_ADD_RSA_ID_CONSTRAINED
-	uint32			ignored
-	mpint1			rsa_n
-	mpint1			rsa_e
-	mpint1			rsa_d
-	mpint1			rsa_iqmp
-	mpint1			rsa_q
-	mpint1			rsa_p
-	string			key_comment
-	constraint[]		key_constraints
-
-Note that there is some redundancy in the key parameters; a key could be
-fully specified using just rsa_q, rsa_p and rsa_e at the cost of extra
-computation.
-
-"key_constraints" may only be present if the request type is
-SSH_AGENTC_ADD_RSA_ID_CONSTRAINED.
-
-The agent will reply with a SSH_AGENT_SUCCESS if the key has been
-successfully added or a SSH_AGENT_FAILURE if an error occurred.
-
-2.2.3 Add protocol 2 key
-
-The OpenSSH agent supports DSA, ECDSA and RSA keys for protocol 2. DSA
-keys may be added using the following request
-
-	byte			SSH2_AGENTC_ADD_IDENTITY or
-				SSH2_AGENTC_ADD_ID_CONSTRAINED
-	string			"ssh-dss"
-	mpint			dsa_p
-	mpint			dsa_q
-	mpint			dsa_g
-	mpint			dsa_public_key
-	mpint			dsa_private_key
-	string			key_comment
-	constraint[]		key_constraints
-
-DSA certificates may be added with:
-	byte			SSH2_AGENTC_ADD_IDENTITY or
-				SSH2_AGENTC_ADD_ID_CONSTRAINED
-	string			"ssh-dss-cert-v00@openssh.com"
-	string			certificate
-	mpint			dsa_private_key
-	string			key_comment
-	constraint[]		key_constraints
-
-ECDSA keys may be added using the following request
-
-	byte			SSH2_AGENTC_ADD_IDENTITY or
-				SSH2_AGENTC_ADD_ID_CONSTRAINED
-	string			"ecdsa-sha2-nistp256" |
-				"ecdsa-sha2-nistp384" |
-				"ecdsa-sha2-nistp521"
-	string			ecdsa_curve_name
-	string			ecdsa_public_key
-	mpint			ecdsa_private
-	string			key_comment
-	constraint[]		key_constraints
-
-ECDSA certificates may be added with:
-	byte			SSH2_AGENTC_ADD_IDENTITY or
-				SSH2_AGENTC_ADD_ID_CONSTRAINED
-	string			"ecdsa-sha2-nistp256-cert-v01@openssh.com" |
-				"ecdsa-sha2-nistp384-cert-v01@openssh.com" |
-				"ecdsa-sha2-nistp521-cert-v01@openssh.com"
-	string			certificate
-	mpint			ecdsa_private_key
-	string			key_comment
-	constraint[]		key_constraints
-
-ED25519 keys may be added using the following request
-	byte			SSH2_AGENTC_ADD_IDENTITY or
-				SSH2_AGENTC_ADD_ID_CONSTRAINED
-	string			"ssh-ed25519"
-	string			ed25519_public_key
-	string			ed25519_private_key || ed25519_public_key
-	string			key_comment
-	constraint[]		key_constraints
-
-ED25519 certificates may be added with:
-	byte			SSH2_AGENTC_ADD_IDENTITY or
-				SSH2_AGENTC_ADD_ID_CONSTRAINED
-	string			"ssh-ed25519-cert-v01@openssh.com"
-	string			certificate
-	string			ed25519_public_key
-	string			ed25519_private_key || ed25519_public_key
-	string			key_comment
-	constraint[]		key_constraints
-
-For both ssh-ed25519 and ssh-ed25519-cert-v01@openssh.com keys, the private
-key has the public key appended (for historical reasons).
-
-RSA keys may be added with this request:
-
-	byte			SSH2_AGENTC_ADD_IDENTITY or
-				SSH2_AGENTC_ADD_ID_CONSTRAINED
-	string			"ssh-rsa"
-	mpint			rsa_n
-	mpint			rsa_e
-	mpint			rsa_d
-	mpint			rsa_iqmp
-	mpint			rsa_p
-	mpint			rsa_q
-	string			key_comment
-	constraint[]		key_constraints
-
-RSA certificates may be added with this request:
-
-	byte			SSH2_AGENTC_ADD_IDENTITY or
-				SSH2_AGENTC_ADD_ID_CONSTRAINED
-	string			"ssh-rsa-cert-v00@openssh.com"
-	string			certificate
-	mpint			rsa_d
-	mpint			rsa_iqmp
-	mpint			rsa_p
-	mpint			rsa_q
-	string			key_comment
-	constraint[]		key_constraints
-
-Note that the 'rsa_p' and 'rsa_q' parameters are sent in the reverse
-order to the protocol 1 add keys message. As with the corresponding
-protocol 1 "add key" request, the private key is overspecified to avoid
-redundant processing.
-
-For DSA, ECDSA and RSA key add requests, "key_constraints" may only be
-present if the request type is SSH2_AGENTC_ADD_ID_CONSTRAINED.
-
-The agent will reply with a SSH_AGENT_SUCCESS if the key has been
-successfully added or a SSH_AGENT_FAILURE if an error occurred.
-
-2.2.4 Loading keys from a smartcard
-
-The OpenSSH agent may have optional smartcard support built in to it. If
-so, it supports an operation to load keys from a smartcard. Technically,
-only the public components of the keys are loaded into the agent so
-this operation really arranges for future private key operations to be
-delegated to the smartcard.
-
-	byte			SSH_AGENTC_ADD_SMARTCARD_KEY or
-				SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED
-	string			reader_id
-	string			pin
-	constraint[]		key_constraints
-
-"reader_id" is an identifier to a smartcard reader and "pin"
-is a PIN or passphrase used to unlock the private key(s) on the
-device. "key_constraints" may only be present if the request type is
-SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED.
-
-This operation may load all SSH keys that are unlocked using the
-"pin" on the specified reader. The type of key loaded (protocol 1
-or protocol 2) will be specified by the smartcard itself, it is not
-client-specified.
-
-The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have
-been successfully loaded or a SSH_AGENT_FAILURE if an error occurred.
-The agent will also return SSH_AGENT_FAILURE if it does not support
-smartcards.
-
-2.3 Removing multiple keys
-
-A client may request that an agent delete all protocol 1 keys using the
-following request:
-
-	byte			SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES
-
-This message requests the deletion of all protocol 2 keys:
-
-	byte			SSH2_AGENTC_REMOVE_ALL_IDENTITIES
-
-On success, the agent will delete all keys of the requested type and
-reply with a SSH_AGENT_SUCCESS message. If an error occurred, the agent
-will reply with SSH_AGENT_FAILURE.
-
-Note that, to delete all keys (both protocol 1 and 2), a client
-must send both a SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES and a
-SSH2_AGENTC_REMOVE_ALL_IDENTITIES request.
-
-2.4 Removing specific keys
-
-2.4.1 Removing a protocol 1 key
-
-Removal of a protocol 1 key may be requested with the following message:
-
-	byte 			SSH_AGENTC_REMOVE_RSA_IDENTITY
-	uint32			key_bits
-	mpint1			rsa_e
-	mpint1			rsa_n
-
-Note that key_bits is strictly redundant, as it may be inferred by the
-length of rsa_n.
-
-The agent will delete any private key matching the specified public key
-and return SSH_AGENT_SUCCESS. If no such key was found, the agent will
-return SSH_AGENT_FAILURE.
-
-2.4.2 Removing a protocol 2 key
-
-Protocol 2 keys may be removed with the following request:
-
-	byte			SSH2_AGENTC_REMOVE_IDENTITY
-	string			key_blob
-
-Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
-Algorithms" for any of the supported protocol 2 key types.
-
-The agent will delete any private key matching the specified public key
-and return SSH_AGENT_SUCCESS. If no such key was found, the agent will
-return SSH_AGENT_FAILURE.
-
-2.4.3 Removing keys loaded from a smartcard
-
-A client may request that a server remove one or more smartcard-hosted
-keys using this message:
-
-	byte			SSH_AGENTC_REMOVE_SMARTCARD_KEY
-	string			reader_id
-	string			pin
-
-"reader_id" the an identifier to a smartcard reader and "pin" is a PIN
-or passphrase used to unlock the private key(s) on the device.
-
-When this message is received, and if the agent supports
-smartcard-hosted keys, it will delete all keys that are hosted on the
-specified smartcard that may be accessed with the given "pin".
-
-The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have
-been successfully removed or a SSH_AGENT_FAILURE if an error occurred.
-The agent will also return SSH_AGENT_FAILURE if it does not support
-smartcards.
-
-2.5 Requesting a list of known keys
-
-An agent may be requested to list which keys it holds. Different
-requests exist for protocol 1 and protocol 2 keys.
-
-2.5.1 Requesting a list of protocol 1 keys
-
-To request a list of protocol 1 keys that are held in the agent, a
-client may send the following message:
-
-	byte			SSH_AGENTC_REQUEST_RSA_IDENTITIES
-
-The agent will reply with the following message:
-
-	byte			SSH_AGENT_RSA_IDENTITIES_ANSWER
-	uint32			num_keys
-
-Followed by zero or more consecutive keys, encoded as:
-
-	uint32			bits
-	mpint1			rsa_e
-	mpint1			rsa_n
-	string			key_comment
-
-2.5.2 Requesting a list of protocol 2 keys
-
-A client may send the following message to request a list of
-protocol 2 keys that are stored in the agent:
-
-	byte			SSH2_AGENTC_REQUEST_IDENTITIES
-
-The agent will reply with the following message header:
-
-	byte			SSH2_AGENT_IDENTITIES_ANSWER
-	uint32			num_keys
-
-Followed by zero or more consecutive keys, encoded as:
-
-	string			key_blob
-	string			key_comment
-
-Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
-Algorithms" for any of the supported protocol 2 key types.
-
-2.6 Private key operations
-
-The purpose of the agent is to perform private key operations, such as
-signing and encryption without requiring a passphrase to unlock the
-key and without allowing the private key itself to be exposed. There
-are separate requests for the protocol 1 and protocol 2 private key
-operations.
-
-2.6.1 Protocol 1 private key challenge
-
-The private key operation used in version 1 of the SSH protocol is
-decrypting a challenge that has been encrypted with a public key.
-It may be requested using this message:
-
-	byte			SSH_AGENTC_RSA_CHALLENGE
-	uint32			ignored
-	mpint1			rsa_e
-	mpint1			rsa_n
-	mpint1			encrypted_challenge
-	byte[16]		session_id
-	uint32			response_type /* must be 1 */
-
-"rsa_e" and "rsa_n" are used to identify which private key to use.
-"encrypted_challenge" is a challenge blob that has (presumably)
-been encrypted with the public key and must be in the range
-1 <= encrypted_challenge < 2^256. "session_id" is the SSH protocol 1
-session ID (computed from the server host key, the server semi-ephemeral
-key and the session cookie).
-
-"ignored" and "response_type" exist for compatibility with legacy
-implementations. "response_type" must be equal to 1; other response
-types are not supported.
-
-On receiving this request, the server decrypts the "encrypted_challenge"
-using the private key matching the supplied (rsa_e, rsa_n) values. For
-the response derivation, the decrypted challenge is represented as an
-unsigned, big-endian integer encoded in a 32 byte buffer (i.e. values
-smaller than 2^248 will have leading 0 bytes).
-
-The response value is then calculated as:
-
-	response = MD5(decrypted_challenge || session_id)
-
-and returned in the following message
-
-	byte			SSH_AGENT_RSA_RESPONSE
-	byte[16]		response
-
-If the agent cannot find the key specified by the supplied (rsa_e,
-rsa_n) then it will return SSH_AGENT_FAILURE.
-
-2.6.2 Protocol 2 private key signature request
-
-A client may use the following message to request signing of data using
-a protocol 2 key:
-
-	byte			SSH2_AGENTC_SIGN_REQUEST
-	string			key_blob
-	string			data
-	uint32			flags
-
-Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
-Algorithms" for any of the supported protocol 2 key types. "flags" is
-a bit-mask, but at present only one possible value is defined (see below
-for its meaning):
-
-	SSH_AGENT_OLD_SIGNATURE		1
-
-Upon receiving this request, the agent will look up the private key that
-corresponds to the public key contained in key_blob. It will use this
-private key to sign the "data" and produce a signature blob using the
-key type-specific method described in RFC 4253 section 6.6 "Public Key
-Algorithms".
-
-An exception to this is for "ssh-dss" keys where the "flags" word
-contains the value SSH_AGENT_OLD_SIGNATURE. In this case, a legacy
-signature encoding is used in lieu of the standard one. In this case,
-the DSA signature blob is encoded as:
-
-	byte[40]		signature
-
-The signature will be returned in the response message:
-
-	byte			SSH2_AGENT_SIGN_RESPONSE
-	string			signature_blob
-
-If the agent cannot find the key specified by the supplied key_blob then
-it will return SSH_AGENT_FAILURE.
-
-2.7 Locking or unlocking an agent
-
-The agent supports temporary locking with a passphrase to suspend
-processing of sensitive operations until it has been unlocked with the
-same passphrase. To lock an agent, a client send the following request:
-
-	byte			SSH_AGENTC_LOCK
-	string			passphrase
-
-Upon receipt of this message and if the agent is not already locked,
-it will suspend processing requests and return a SSH_AGENT_SUCCESS
-reply. If the agent is already locked, it will return SSH_AGENT_FAILURE.
-
-While locked, the agent will refuse all requests except
-SSH_AGENTC_UNLOCK, SSH_AGENTC_REQUEST_RSA_IDENTITIES and
-SSH2_AGENTC_REQUEST_IDENTITIES. The "request identities" requests are
-treated specially by a locked agent: it will always return an empty list
-of keys.
-
-To unlock an agent, a client may request:
-
-	byte			SSH_AGENTC_UNLOCK
-	string			passphrase
-
-If the passphrase matches and the agent is locked, then it will resume
-processing all requests and return SSH_AGENT_SUCCESS. If the agent
-is not locked or the passphrase does not match then it will return
-SSH_AGENT_FAILURE.
-
-Locking and unlocking affects both protocol 1 and protocol 2 keys.
-
-3. Protocol message numbers
-
-3.1 Requests from client to agent for protocol 1 key operations
-
-	SSH_AGENTC_REQUEST_RSA_IDENTITIES		1
-	SSH_AGENTC_RSA_CHALLENGE			3
-	SSH_AGENTC_ADD_RSA_IDENTITY			7
-	SSH_AGENTC_REMOVE_RSA_IDENTITY			8
-	SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES		9
-	SSH_AGENTC_ADD_RSA_ID_CONSTRAINED		24
-
-3.2 Requests from client to agent for protocol 2 key operations
-
-	SSH2_AGENTC_REQUEST_IDENTITIES			11
-	SSH2_AGENTC_SIGN_REQUEST			13
-	SSH2_AGENTC_ADD_IDENTITY			17
-	SSH2_AGENTC_REMOVE_IDENTITY			18
-	SSH2_AGENTC_REMOVE_ALL_IDENTITIES		19
-	SSH2_AGENTC_ADD_ID_CONSTRAINED			25
-
-3.3 Key-type independent requests from client to agent
-
-	SSH_AGENTC_ADD_SMARTCARD_KEY			20
-	SSH_AGENTC_REMOVE_SMARTCARD_KEY			21
-	SSH_AGENTC_LOCK					22
-	SSH_AGENTC_UNLOCK				23
-	SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED	26
-
-3.4 Generic replies from agent to client
-
-	SSH_AGENT_FAILURE				5
-	SSH_AGENT_SUCCESS				6
-
-3.5 Replies from agent to client for protocol 1 key operations
-
-	SSH_AGENT_RSA_IDENTITIES_ANSWER			2
-	SSH_AGENT_RSA_RESPONSE				4
-
-3.6 Replies from agent to client for protocol 2 key operations
-
-	SSH2_AGENT_IDENTITIES_ANSWER			12
-	SSH2_AGENT_SIGN_RESPONSE			14
-
-3.7 Key constraint identifiers
-
-	SSH_AGENT_CONSTRAIN_LIFETIME			1
-	SSH_AGENT_CONSTRAIN_CONFIRM			2
-
-$OpenBSD: PROTOCOL.agent,v 1.11 2016/05/19 07:45:32 djm Exp $
+This file used to contain a description of the SSH agent protocol
+implemented by OpenSSH. It has since been superseded by
+https://tools.ietf.org/html/draft-miller-ssh-agent-00