]> SSH Agent Protocol OpenSSH
djm@openssh.com https://www.openssh.com/
General Internet Engineering Task Force ssh agent ssh-agent This document describes a key agent protocol for use in the Secure Shell (SSH) protocol.
Introduction Secure Shell (SSH) is a protocol for secure remote connections and login over untrusted networks. It supports multiple authentication mechanisms, including public key authentication. This document describes the protocol for interacting with an agent that holds private keys. Clients (and possibly servers) can invoke the agent via this protocol to perform operations using public and private keys held in the agent. Holding keys in an agent offers usability and security advantages to loading and unwrapping them at each use. Moreover, the agent implements a simple protocol and presents a smaller attack surface than a key loaded into a full SSH server or client. This agent protocol is already widely used and a de-facto standard, having been implemented by a number of popular SSH clients and servers for many years. The purpose of this document is to describe the protocol as it has been implemented.
Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.
Protocol Overview The agent protocol is a packetised request-response protocol, solely driven by the client. It consists of a number of requests sent from the client to the server and a set of reply messages that are sent in response. At no time does the server send messages except in response to a client request. Replies are sent in order. Agents MAY implement support for only a subset of operations or available key types, and MAY additionally refuse abitrary operations in particular contexts. For example, an agent may allow only local clients of an agent to add or remove keys, or make particular subsets of keys available to a given client. For this reason, clients of the agent SHOULD be prepared to fail gracefully if any operation is refused. Note that this protocol is separate to and incompatible with the one described in the similarly-named .
Protocol Messages All values in the agent protocol are encoded using the SSH wire representations specified by . Messages consist of a length, type and contents. uint32 length byte type byte[length - 1] contents
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 requests with unknown types.
Adding keys to the agent Keys may be added to the agent using the SSH_AGENTC_ADD_IDENTITY or SSH_AGENTC_ADD_ID_CONSTRAINED messages. The latter variant allows adding keys with optional constraints on their usage. The generic format for the key SSH_AGENTC_ADD_IDENTITY message is: byte SSH_AGENTC_ADD_IDENTITY string key type byte[] key contents string key comment Here "type" is the specified key type name, for example "ssh-rsa" for a RSA key as defined by . "contents" consists of the public and private components of the key and vary by key type, they are listed below for standard and commonly used key types. "comment" is an optional human-readable key name or comment as a UTF-8 string that may serve to identify the key in user-visible messages. The SSH_AGENTC_ADD_ID_CONSTRAINED is similar, but adds a extra field: byte SSH_AGENTC_ADD_ID_CONSTRAINED string type byte[] contents string comment constraint[] constraints Constraints are used to place limits on the validity or use of keys. details constraint types and their format. An agent should reply with SSH_AGENT_SUCCESS if the key was successfully loaded as a result of one of these messages, or SSH_AGENT_FAILURE otherwise. An agent MAY support only a subset of the key types defined here and may support additional key types as described below. If an agent does not recognise the type name in a request to add a key, then it MUST fail gracefully and respond with a SSH_AGENT_FAILURE reply.
DSA keys DSA keys have key type "ssh-dss" and are defined in . They may be added to the agent using the following message. The "constraints" field is only present for the SSH_AGENTC_ADD_ID_CONSTRAINED message. byte SSH_AGENTC_ADD_IDENTITY or SSH_AGENTC_ADD_ID_CONSTRAINED string "ssh-dss" mpint p mpint q mpint g mpint y mpint x string comment constraint[] constraints The "p", "q", "g" values are the DSA domain parameters. "y" and "x" are the public and private keys respectively. These values are as defined by .
ECDSA keys ECDSA keys have key types starting with "ecdsa-sha2-" and are defined in . They may be added to the agent using the following message. The "constraints" field is only present for the SSH_AGENTC_ADD_ID_CONSTRAINED message. byte SSH_AGENTC_ADD_IDENTITY or SSH_AGENTC_ADD_ID_CONSTRAINED string key type string ecdsa_curve_name string Q mpint d string comment constraint[] constraints The values "Q" and "d" are the ECDSA public and private values respectively. Both are defined by .
EDDSA keys defines Ed25519 and Ed448 with key type names "ssh-ed25519" and "ssh-ed448" respectively. These may be added to the agent using the following message. The "key constraints" field is only present for the SSH_AGENTC_ADD_ID_CONSTRAINED message. byte SSH_AGENTC_ADD_IDENTITY or SSH_AGENTC_ADD_ID_CONSTRAINED string "ssh-ed25519" or "ssh-ed448" string ENC(A) string k || ENC(A) string comment constraint[] constraints The first value is the EDDSA public key ENC(A). The second value is a concatenation of the private key k and the public ENC(A) key. The contents and interpretation of the ENC(A) and k values are defined by .
RSA keys RSA keys have key type "ssh-rsa" and are defined in . They may be added to the agent using the following message. The "key constraints" field is only present for the SSH_AGENTC_ADD_ID_CONSTRAINED message. byte SSH_AGENTC_ADD_IDENTITY or SSH_AGENTC_ADD_ID_CONSTRAINED string "ssh-rsa" mpint n mpint e mpint d mpint iqmp mpint p mpint q string comment constraint[] constraints "n" is the public composite modulus. "p" and "q" are its constituent private prime factors. "e" is the public exponent. "iqmp" is the inverse of "q" modulo "p". All these values except "iqmp" (which can be calculated from the others) are defined by .
Other keys Agents and their clients MAY support additional key types not documented here. Vendor-specific key types should use the domain-qualified naming convention defined in .
Adding keys from a token Keys hosted on smart-cards or other hardware tokens may be added using the SSH_AGENTC_ADD_SMARTCARD_KEY and SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED requests. Note that "constraints" field is only included for the SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED variant of this message. byte SSH_AGENTC_ADD_SMARTCARD_KEY or SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED string id string PIN constraint[] constraints Here "id" is an opaque identifier for the hardware token and "PIN" is an optional password or PIN to unlock the key. The interpretation of "id" is not defined by the protocol but is left solely up to the agent. Typically only the public components of any keys supported on a hardware token will be loaded into an agent so, strictly speaking, this message really arranges future private key operations to be delegated to the hardware token in question. An agent should reply with SSH_AGENT_SUCCESS if one or more keys were successfully loaded as a result of one of these messages, or SSH_AGENT_FAILURE if no keys were found. The agent should also return SSH_AGENT_FAILURE if the token "id" was not recognised or if the agent doesn't support token-hosted keys at all.
A number of constraints and may be used in the constrained variants of the key add messages. Each constraint is represented by a type byte followed by zero or more value bytes. 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 byte[] constraint1_data byte constraint2_type byte[] constraint2_data .... byte constraintN_type byte[] constraintN_data If an agent does not recognise or support a requested constraint it MUST refuse the request and return a SSH_AGENT_FAILURE message to the client. The following constraints are defined.
Key lifetime constraint This constraint requests that the agent limit the key's lifetime by deleting it after the specified duration (in seconds) has elapsed from the time the key was added to the agent. byte SSH_AGENT_CONSTRAIN_LIFETIME uint32 seconds
Key confirmation constraint This constraint requests that the agent require explicit user confirmation for each private key operation using the key. For example, the agent could present a confirmation dialog before completing a signature operation. byte SSH_AGENT_CONSTRAIN_CONFIRM
Constraint extensions Agents may implement experimental or private-use constraints through a extension constraint that supports named constraints. byte SSH_AGENT_CONSTRAIN_EXTENSION string extension name byte[] extension-specific details The extension name MUST consist of a UTF-8 string suffixed by the implementation domain following the naming scheme defined in , e.g. "foo@example.com".
Public key encoding Keys previously loaded into an agent are referred to by their public key blob, which is the standard SSH wire encoding for public keys. SSH protocol key encodings are defined in for "ssh-rsa" and "ssh-dss" keys, in for "ecdsa-sha2-*" keys and in for "ssh-ed25519" and "ssh-ed448" keys.
Removing keys from the agent A client may request that an agent remove all keys that it stores: byte SSH_AGENTC_REMOVE_ALL_IDENTITIES On receipt of such a message, an agent shall delete all keys that it is holding and reply with SSH_AGENT_SUCCESS. Specific keys may also be removed: byte SSH_AGENTC_REMOVE_IDENTITY string key blob Where "key blob" is the standard public key encoding of the key to be removed (). An agent shall reply with SSH_AGENT_SUCCESS if the key was deleted or SSH_AGENT_FAILURE if it was not found. Smartcard keys may be removed using: byte SSH_AGENTC_REMOVE_SMARTCARD_KEY string reader id string PIN Where "reader id" is an opaque identifier for the smartcard reader and "PIN" is an optional password or PIN (not typically used). Requesting deletion of smartcard-hosted keys SHOULD cause the agent to remove all keys loaded from that smartcard. An agent shall reply with SSH_AGENT_SUCCESS if the key was deleted or SSH_AGENT_FAILURE if it was not found.
Requesting a list of keys A client may request a list of keys from an agent using the following message: byte SSH_AGENTC_REQUEST_IDENTITIES The agent shall reply with a message with the following preamble. byte SSH_AGENT_IDENTITIES_ANSWER uint32 nkeys Where "nkeys" indicates the number of keys to follow. Following the preamble are zero or more keys, each encoded as: string key blob string comment Where "key blob" is the standard public key encoding of the key () and "comment" is a human-readable comment encoded as a UTF-8 string.
Private key operations A client may request the agent perform a private key signature operation using the following message: byte SSH_AGENTC_SIGN_REQUEST string key blob string data uint32 flags Where "key blob" is the key requested to perform the signature (encoded as per ), "data" is the data to be signed and "flags" is a bitfield containing the bitwise OR of zero or more signature flags (see below). If the agent does not support the requested flags, or is otherwise unable or unwilling to generate the signature (e.g. because it doesn't have the specified key, or the user refused confirmation of a constrained key), it must reply with a SSH_AGENT_FAILURE message. On success, the agent shall reply with: byte SSH_AGENT_SIGN_RESPONSE string signature The signature format is specific to the algorithm of the key type in use. SSH protocol signature formats are defined in for "ssh-rsa" and "ssh-dss" keys, in for "ecdsa-sha2-*" keys and in for "ssh-ed25519" and "ssh-ed448" keys.
Signature flags Two flags are currently defined for signature request messages: SSH_AGENT_RSA_SHA2_256 and SSH_AGENT_RSA_SHA2_512. These two flags are only valid for "ssh-rsa" keys and request that the agent return a signature using the "rsa-sha2-256" or "rsa-sha2-512" signature methods respectively. These signature schemes are defined in .
Locking and unlocking an agent The agent protocol supports requesting that an agent temporarily lock itself with a pass-phrase. When locked an agent should suspend processing of sensitive operations (private key signature operations at the very least) until it has been unlocked with the same pass-phrase. The following message requests agent locking byte SSH_AGENTC_LOCK string passphrase The agent shall reply with SSH_AGENT_SUCCESS if locked successfully or SSH_AGENT_FAILURE otherwise (e.g. if the agent was already locked). The following message requests unlocking an agent: byte SSH_AGENTC_UNLOCK string passphrase If the agent is already locked and the pass-phrase matches the one used to lock it then it should unlock and reply with SSH_AGENT_SUCCESS. If the agent is unlocked or if the the pass-phrase does not match it should reply with SSH_AGENT_FAILURE. An agent SHOULD take countermeasures against brute-force guessing attacks against the pass-phrase.
Extension mechanism The agent protocol includes an optional extension mechanism that allows vendor-specific and experimental messages to be sent via the agent protocol. Extension requests from the client consist of: byte SSH_AGENTC_EXTENSION string extension type byte[] extension request-specific contents The extension type indicates the type of the extension message as a UTF-8 string. Implementation-specific extensions should be suffixed by the implementation domain following the extension naming scheme defined in , e.g. "foo@example.com". An agent that does not support extensions of the supplied type MUST reply with an empty SSH_AGENT_FAILURE message. This reply is also sent by agents that do not support the extension mechanism at all. The contents of successful extension reply messages are specific to the extension type. Extension requests may return SSH_AGENT_SUCCESS on success or the extension-specific response message: byte SSH_AGENT_EXTENSION_RESPONSE string extension type byte[] extension response-specific contents Where the extension type is the same as that in the request. Extension failure should be signaled using the SSH_AGENT_EXTENSION_FAILURE code - extensions should not use the standard SSH_AGENT_FAILURE message. This allows failed requests to be distinguished from the extension not being supported.
Query extension A single, optional extension request "query" is defined to allow a client to query which, if any, extensions are supported by an agent. byte SSH_AGENTC_EXTENSION string "query" If an agent supports the query extension is should reply with a list of supported extension names. byte SSH_AGENT_EXTENSION_RESPONSE string "query" string[] supported extension types
Forwarding access to an agent The agent protocol may be forwarded over a SSH connection, using the connection protocol, allowing agent forwarding to be requested for any session channel, using a model that is similar to the connection protocol's support for X11 Forwarding (). This feature is OPTIONAL for SSH protocol and agent implementations. Note that the deployed integration with the SSH protocol uses vendor-specific names.
Support for agent forwarding may be advertised by a SSH protocol server using the extension mechanism using the name "agent-forward" in the SSH_MSG_EXT_INFO message. string "agent-forward" string "0" (version) Note that this protocol substantially predates the existence of the extension mechanism and several widely-deployed SSH implementations that support agent forwarding do not advertise their ability to do so. Clients MAY opportunitically attempt to request agent forwarding in the absence of an advertisment using the vendor-specific names mentioned below. Likewise, servers MAY implement the vendor-specific names in addition to the one described here.
Requesting agent forwarding A client may request agent forwarding for a previously-opened session () using the following channel request. This request is sent after the channel has been opened, but before a shell, command or subsystem has been executed. byte SSH_MSG_CHANNEL_REQUEST string channel_id string "agent-req" or "auth-agent-req@openssh.com" boolean want_reply Where channel_id is the identifier for an established session channel (as returned from a previous SSH_MSG_CHANNEL_OPEN request, and the want_reply flag indicates whether the server should respond with a confirmation of whether the request was successful (as specified in ) If a SSH server accepts this request, typically it will arrange to make a endpoint (e.g. a listening socket) available and advertise this fact to the subordinate session. Most implementations on Unix-like systems do this by providing a user-private listening Unix domain socket and recording its location in an environment variable $SSH_AUTH_SOCK. As mentioned previously, many deployed implementations only support the former, pre-standardisation "auth-agent-req@openssh.com" request name. The latter "agent-req" name SHOULD only be used if support was explicitly advertised as per .
Agent connection requests After a client has requested that a session have agent forwarding enabled, the server later may request a connection to the forwarded agent. The server does this by requesting a dedicated channel to communicate with the client's agent. byte SSH_MSG_CHANNEL_OPEN string "agent-connect" or "auth-agent@openssh.com" uint32 channel_id uint32 local_window uint32 local_maxpacket The channel_id, local_window and local_maxpacket fields should be interpreted as specified by . As above, the latter "agent-connect" open type name SHOULD only be used if support was explicitly advertised as per . A client SHOULD be prepared to handle multiple concurrent active agent connections. A client MAY accept agent connection requests (subject to authorisation) without a prior agent forwarding request having been made to support the situation where agent forwarding without opening a session is desired. Similarly, a client MAY continue to accept agent connection requests after the session for which agent forwarding was requested has closed. A client MUST refuse unauthorised agent connection requests, i.e. when agent forwarding was not desired or requested but a server sends an agent connection request anyway. Note the connection request provides no way to identify which session channel a given agent connection request relates to. This implies that a SSH connection can functionally forward access to only a single client-side agent concurrently using this protocol.
Protocol numbers
The following numbers are used for requests from the client to the agent. SSH_AGENTC_REQUEST_IDENTITIES 11 SSH_AGENTC_SIGN_REQUEST 13 SSH_AGENTC_ADD_IDENTITY 17 SSH_AGENTC_REMOVE_IDENTITY 18 SSH_AGENTC_REMOVE_ALL_IDENTITIES 19 SSH_AGENTC_ADD_SMARTCARD_KEY 20 SSH_AGENTC_REMOVE_SMARTCARD_KEY 21 SSH_AGENTC_LOCK 22 SSH_AGENTC_UNLOCK 23 SSH_AGENTC_ADD_ID_CONSTRAINED 25 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED 26 SSH_AGENTC_EXTENSION 27 The following numbers are used for replies from the agent to the client. SSH_AGENT_FAILURE 5 SSH_AGENT_SUCCESS 6 SSH_AGENT_IDENTITIES_ANSWER 12 SSH_AGENT_SIGN_RESPONSE 14 SSH_AGENT_EXTENSION_FAILURE 28 SSH_AGENT_EXTENSION_RESPONSE 29
Reserved message numbers The following message numbers are reserved for implementations that implement support for the legacy SSH protocol version 1: 1-4, 7-9 and 24 (inclusive). These message numbers MAY be used by an implementation supporting the legacy protocol but MUST NOT be reused otherwise. The range of message numbers 240-255 are reserved for organization-local extensions to the agent protocol and MUST NOT be used by generic implementations.
The following numbers are used to identify key constraints. These are only used in key constraints and are not sent as message numbers. SSH_AGENT_CONSTRAIN_LIFETIME 1 SSH_AGENT_CONSTRAIN_CONFIRM 2 SSH_AGENT_CONSTRAIN_EXTENSION 255
The following numbers may be present in signature request (SSH_AGENTC_SIGN_REQUEST) messages. These flags form a bit field by taking the logical OR of zero or more flags. SSH_AGENT_RSA_SHA2_256 2 SSH_AGENT_RSA_SHA2_512 4 The flag value 1 is reserved for historical implementations.
IANA Considerations This protocol requires three registries be established, one for message numbers, one for constraints and one for signature request flags.
New registry: SSH agent protocol numbers This registry, titled "SSH agent protocol numbers" records the message numbers for client requests and agent responses. Its initial state should consist of the following numbers and reservations. Future message number allocations shall require specification in the form of an RFC (EXPERT REVIEW as per ).
Number(s)IdentifierReference
1reserved
2reserved
3reserved
4reserved
5SSH_AGENT_FAILURE
6SSH_AGENT_SUCCESS
7reserved
8reserved
9reserved
10reserved
11SSH_AGENTC_REQUEST_IDENTITIES
12SSH_AGENT_IDENTITIES_ANSWER
13SSH_AGENTC_SIGN_REQUEST
14SSH_AGENT_SIGN_RESPONSE
15reserved
16reserved
17SSH_AGENTC_ADD_IDENTITY
18SSH_AGENTC_REMOVE_IDENTITY
19SSH_AGENTC_REMOVE_ALL_IDENTITIES
20SSH_AGENTC_ADD_SMARTCARD_KEY
21SSH_AGENTC_REMOVE_SMARTCARD_KEY
22SSH_AGENTC_LOCK
23SSH_AGENTC_UNLOCK
24reserved
25SSH_AGENTC_ADD_ID_CONSTRAINED
26SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED
27SSH_AGENTC_EXTENSION
28SSH_AGENT_EXTENSION_FAILURE
29SSH_AGENT_EXTENSION_RESPONSE
240-255Reserved for organizational use
New registry: SSH agent key constraint numbers This registry, titled "SSH agent key constraint numbers" records the message numbers for key use constraints. Its initial state should consist of the following numbers. Future constraint number allocations shall require specification in the form of an RFC (EXPERT REVIEW as per ).
NumberIdentifierReference
1SSH_AGENT_CONSTRAIN_LIFETIME
2SSH_AGENT_CONSTRAIN_CONFIRM
255SSH_AGENT_CONSTRAIN_EXTENSION
New registry: SSH agent signature flags This registry, titled "SSH agent signature flags records the values for signature request (SSH_AGENTC_SIGN_REQUEST) flag values. Its initial state should consist of the following numbers. Note that as the flags are combined by bitwise OR, all flag values must be powers of two and the maximum available flag value is 0x80000000. Future constraint number allocations shall require specification in the form of an RFC (EXPERT REVIEW as per ).
NumberIdentifierReference
0x01reserved
0x02SSH_AGENT_RSA_SHA2_256
0x04SSH_AGENT_RSA_SHA2_512
New registry: SSH agent extension request names This registry, titled "SSH agent extension request names" records the names used in the generic extension request message (SSH_AGENTC_EXTENSION). Its initial state should consist of the following names. Future constraint number allocations shall require specification in the form of an RFC (EXPERT REVIEW as per ).
Extension NameReference
query
IANA is requested to insert the following entries into the table Extension Names under Secure Shell (SSH) Protocol Parameters .
Extension NameReference
agent-forward
IANA is requested to insert the following entries into the table Connection Protocol Channel Request Names under Secure Shell (SSH) Protocol Parameters .
Extension NameReference
agent-forward
IANA is requested to insert the following entries into the table Connection Protocol Channel Types under Secure Shell (SSH) Protocol Parameters .
Extension NameReference
agent-connect
Security Considerations The agent is a service that is tasked with retaining and providing controlled access to what are typically long-lived login authentication credentials. It is by nature a sensitive and trusted software component. Moreover, the agent protocol itself does not include any authentication or transport security; ability to communicate with an agent is usually sufficient to invoke it to perform private key operations. Since being able to access an agent is usually sufficient to perform private key operations, it is critically important that the agent only be exposed to its owner and their authorised delegates. The primary design intention of an agent is that an attacker with unprivileged access to their victim's agent should be prevented from gaining a copy of any keys that have been loaded into it. This may not preclude the attacker from stealing use of those keys (e.g. if they have been loaded without a confirmation constraint). Given this, the agent should, as far as possible, prevent its memory being read by other processes to direct theft of loaded keys. This typically include disabling debugging interfaces and preventing process memory dumps on abnormal termination. Another, more subtle, means by which keys may be stolen are via cryptographic side-channels. Private key operations may leak information about the contents of keys via differences in timing, power use or by side-effects in the memory subsystems (e.g. CPU caches) of the host running the agent. For the case of a local attacker and an agent holding unconstrained keys, the only limit on the number of private key operations the attacker may be able to observe is the rate at which the CPU can perform signatures. This grants the attacker an almost ideal oracle for side-channel attacks. While a full treatment of side-channel attacks is beyond the scope of this specification, agents SHOULD use cryptographic implementations that are resistant to side-channel attacks and MAY take additional measures to hide the actual time spent processing private key operations. Forwarding access to a local agent over a SSH connection () inherently creates a transitive trust relationship. SSH implementations SHOULD NOT forward use of an agent by default and MAY implement additional controls over key visibility and use for forwarded agent connections.
References Normative References Digital Signature Standard (DSS) National Institute of Standards and Technology Informative References Connection Protocol Channel Types IANA Extension Names IANA Connection Protocol Channel Request Names IANA Secure Shell Authentication Agent Protocol This document describes the Secure Shell authentication agent protocol (i.e., the protocol used between a client requesting authentication and the authentication agent). This protocol usually runs in a machine-spe- cific local channel or over a forwarded authentication channel. It is assumed that the channel is trusted, so no protection for the communica- tions channel is provided by this protocol.
Acknowledgements This protocol was designed and first implemented by Markus Friedl, based on a similar protocol for an agent to support the legacy SSH version 1 by Tatu Ylonen. Thanks to Simon Tatham, Niels Möller and James Spencer who reviewed and helped improve this document.