RFC 9987: Secure Shell (SSH) Agent Protocol
RFC 9987<br>SSH Agent Protocol<br>May 2026
Miller<br>Standards Track<br>[Page]
Stream:<br>Internet Engineering Task Force (IETF)<br>RFC:<br>9987<br>Category:<br>Standards Track<br>Published:
May 2026
ISSN:<br>2070-1721<br>Author:
D. Miller
OpenSSH
RFC 9987
Secure Shell (SSH) Agent Protocol
Abstract
This document specifies a key agent protocol for use in<br>the Secure Shell (SSH) protocol.¶
Status of This Memo
This is an Internet Standards Track document.¶
This document is a product of the Internet Engineering Task Force<br>(IETF). It represents the consensus of the IETF community. It has<br>received public review and has been approved for publication by<br>the Internet Engineering Steering Group (IESG). Further<br>information on Internet Standards is available in Section 2 of<br>RFC 7841.¶
Information about the current status of this document, any<br>errata, and how to provide feedback on it may be obtained at<br>https://www.rfc-editor.org/info/rfc9987.¶
Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the<br>document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal<br>Provisions Relating to IETF Documents<br>(https://trustee.ietf.org/license-info) in effect on the date of<br>publication of this document. Please review these documents<br>carefully, as they describe your rights and restrictions with<br>respect to this document. Code Components extracted from this<br>document must include Revised BSD License text as described in<br>Section 4.e of the Trust Legal Provisions and are provided without<br>warranty as described in the Revised BSD License.¶
Table of Contents
1. Introduction
Secure Shell (SSH)<br>[RFC4251]<br>is a protocol for secure remote connections<br>[RFC4253]<br>and login<br>[RFC4254]<br>over untrusted networks.<br>It supports multiple authentication mechanisms<br>[RFC4252]<br>including public key authentication. This document<br>specifies the protocol for interacting with a key<br>management component, usually referred to as "an agent",<br>that holds private keys. SSH clients (and possibly<br>SSH servers) can invoke the agent via this protocol<br>to perform operations using public and private keys<br>held in the agent.¶
Holding keys in an agent offers usability and security<br>advantages to loading and unwrapping them at each use, as<br>each key unwrapping may require entry of a passphrase.<br>Access to an agent may optionally be forwarded across an SSH connection,<br>thereby allowing remote systems to use stored keys without directly<br>exposing the key material to the remote system.<br>Finally, the agent may be implemented as a dedicated component that<br>presents a smaller attack surface than a key loaded into<br>a full SSH server or client and that may be subject to special<br>protection from the wider system.¶
2. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",<br>"MAY", and "OPTIONAL" in this document are to be interpreted as<br>described in BCP 14 [RFC2119] [RFC8174]<br>when, and only when, they appear in all capitals, as shown here.¶
3. Protocol Overview
The agent protocol is a packetised request-response protocol that is<br>solely driven by the client. It consists of a number of<br>requests sent from a client to an agent and a set of reply<br>messages that are sent in response. At no time does the agent<br>send messages except in response to a client request. Replies<br>are sent in order.¶
These requests include the ability to load keys into an agent,<br>remove some or all keys from an agent, and perform signature<br>operations using previously loaded keys.¶
Agents MAY implement support for only a subset of available key types<br>and MAY additionally refuse some operations in particular contexts.<br>For example, an agent may allow only clients local to itself to<br>add keys or may make particular subsets of keys available to a<br>given client.<br>For this reason, clients of the agent SHOULD be prepared to<br>fail gracefully if any operation is refused.¶
4. Terminology and Units
Henceforth, in this document, "agent" will be used to refer to a<br>key management component that implements the responder side of<br>this protocol. "Client" will refer to a tool that implements<br>the requester side of the protocol to communicate with an agent.<br>If it is pertinent that the client in question is a<br>Secure Shell client as described in [RFC4251], then the client will be<br>explicitly referred to as an "SSH client".<br>Similarly, "SSH server" will be used to refer to Secure Shell<br>servers.¶
All encoding data types ("byte", "uint32", "string", etc.) are<br>as specified in Section 5 of [RFC4251].<br>Additionally, the type "byte[]" without a specified length<br>within the square brackets indicates an unadorned sequence of<br>zero or more bytes where the length is determined by context.¶
All length units are given in bytes unless otherwise specified.¶
5. Protocol Messages
Messages consist of a "length", "type", and "contents".¶
uint32 length<br>byte type<br>byte[length - 1] contents¶
In the...