rfc9987.original   rfc9987.txt 
Internet Engineering Task Force D. Miller Internet Engineering Task Force (IETF) D. Miller
Internet-Draft OpenSSH Request for Comments: 9987 OpenSSH
Intended status: Standards Track 19 February 2026 Category: Standards Track May 2026
Expires: 23 August 2026 ISSN: 2070-1721
SSH Agent Protocol Secure Shell (SSH) Agent Protocol
draft-ietf-sshm-ssh-agent-16
Abstract Abstract
This document specifies a key agent protocol for use in the Secure This document specifies a key agent protocol for use in the Secure
Shell (SSH) protocol. Shell (SSH) protocol.
Note
This note is to be removed before publishing as an RFC.
In the IANA considerations section, please replace "thisRFC" with
"RFC" and the assigned number, when known.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on 23 August 2026. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9987.
Copyright Notice Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Revised BSD License text as to this document. Code Components extracted from this document must
described in Section 4.e of the Trust Legal Provisions and are include Revised BSD License text as described in Section 4.e of the
provided without warranty as described in the Revised BSD License. Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction
1.1. Background . . . . . . . . . . . . . . . . . . . . . . . 3 2. Requirements Language
1.2. Requirements Language . . . . . . . . . . . . . . . . . . 3 3. Protocol Overview
2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 4 4. Terminology and Units
2.1. Background . . . . . . . . . . . . . . . . . . . . . . . 4 5. Protocol Messages
2.2. Terminology and units . . . . . . . . . . . . . . . . . . 4 5.1. Generic Agent Responses
3. Protocol Messages . . . . . . . . . . . . . . . . . . . . . . 5 5.2. Adding Keys to the Agent
3.1. Generic agent responses . . . . . . . . . . . . . . . . . 5 5.2.1. DSA Keys
3.2. Adding keys to the agent . . . . . . . . . . . . . . . . 5 5.2.2. ECDSA Keys
3.2.1. DSA keys . . . . . . . . . . . . . . . . . . . . . . 6 5.2.3. EdDSA Keys
3.2.2. ECDSA keys . . . . . . . . . . . . . . . . . . . . . 7 5.2.4. RSA Keys
3.2.3. EDDSA keys . . . . . . . . . . . . . . . . . . . . . 7 5.2.5. Other Keys
3.2.4. RSA keys . . . . . . . . . . . . . . . . . . . . . . 8 5.2.6. Adding Keys from a Token
3.2.5. Other keys . . . . . . . . . . . . . . . . . . . . . 8 5.2.7. Key Constraints
3.2.6. Adding keys from a token . . . . . . . . . . . . . . 8 5.3. Public Key Encoding
3.2.7. Key Constraints . . . . . . . . . . . . . . . . . . . 9 5.4. Removing Keys from the Agent
3.3. Public key encoding . . . . . . . . . . . . . . . . . . . 10 5.5. Requesting a List of Keys
3.4. Removing keys from the agent . . . . . . . . . . . . . . 11 5.6. Private Key Operations
3.5. Requesting a list of keys . . . . . . . . . . . . . . . . 11 5.6.1. Signature Flags
3.6. Private key operations . . . . . . . . . . . . . . . . . 12 5.7. Locking and Unlocking an Agent
3.6.1. Signature flags . . . . . . . . . . . . . . . . . . . 13 5.8. Extension Mechanism
3.7. Locking and unlocking an agent . . . . . . . . . . . . . 13 5.8.1. Query Extension
3.8. Extension mechanism . . . . . . . . . . . . . . . . . . . 13 6. Connecting to an Agent
3.8.1. Query extension . . . . . . . . . . . . . . . . . . . 14 7. Forwarding Access to an Agent
4. Connecting to an agent . . . . . . . . . . . . . . . . . . . 15 7.1. Advertising Agent Forwarding Support
5. Forwarding access to an agent . . . . . . . . . . . . . . . . 15 7.2. Requesting Agent Forwarding
5.1. Advertising agent forwarding support . . . . . . . . . . 15 7.3. Agent Connection Requests
5.2. Requesting agent forwarding . . . . . . . . . . . . . . . 16 8. Protocol Numbers
5.3. Agent connection requests . . . . . . . . . . . . . . . . 16 8.1. Message Type Numbers
6. Protocol numbers . . . . . . . . . . . . . . . . . . . . . . 17 8.1.1. Reserved Message Type Numbers
6.1. Message type numbers . . . . . . . . . . . . . . . . . . 17 8.2. Constraint Identifiers
6.1.1. Reserved message type numbers . . . . . . . . . . . . 18 8.3. Signature Flags
6.2. Constraint identifiers . . . . . . . . . . . . . . . . . 18 9. IANA Considerations
6.3. Signature flags . . . . . . . . . . . . . . . . . . . . . 18 9.1. Guidance for Designated Experts
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 9.2. "SSH Agent Protocol Message Type Numbers" Registry
7.1. Guidance for Designated Experts . . . . . . . . . . . . . 19 9.3. "SSH Agent Key Constraint Numbers" Registry
7.2. New registry: SSH agent protocol message type numbers . . 19 9.4. "SSH Agent Key Constraint Extension Names" Registry
7.3. New registry: SSH agent key constraint numbers . . . . . 23 9.5. "SSH Agent Signature Flags" Registry
7.4. New registry: SSH agent key constraint extension names . 23 9.6. "SSH Agent Extension Request Names" Registry
7.5. New registry: SSH agent signature flags . . . . . . . . . 23 9.7. Additions to the "Extension Names" Registry
7.6. New registry: SSH agent extension request names . . . . . 24 9.8. Additions to the "Connection Protocol Channel Request
7.7. Additions to SSH Extension Names . . . . . . . . . . . . 24 Names" Registry
7.8. Additions to SSH Connection Protocol Channel Request 9.9. Additions to the "Connection Protocol Channel Types"
Names . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Registry
7.9. Additions to SSH Connection Protocol Channel Types . . . 25 10. Security Considerations
8. Security Considerations . . . . . . . . . . . . . . . . . . . 25 11. References
9. Implementation Status . . . . . . . . . . . . . . . . . . . . 27 11.1. Normative References
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 11.2. Informative References
10.1. Normative References . . . . . . . . . . . . . . . . . . 28 Acknowledgments
10.2. Informative References . . . . . . . . . . . . . . . . . 29 Author's Address
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 30
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 31
1. Introduction 1. Introduction
Secure Shell (SSH) [RFC4251] is a protocol for secure remote Secure Shell (SSH) [RFC4251] is a protocol for secure remote
connections [RFC4253] and login [RFC4254] over untrusted networks. connections [RFC4253] and login [RFC4254] over untrusted networks.
It supports multiple authentication mechanisms [RFC4252], including It supports multiple authentication mechanisms [RFC4252] including
public key authentication. This document specifies the protocol for public key authentication. This document specifies the protocol for
interacting with a key management component, usually referred to as interacting with a key management component, usually referred to as
"an agent", that holds private keys. SSH clients (and possibly SSH "an agent", that holds private keys. SSH clients (and possibly SSH
servers) can invoke the agent via this protocol to perform operations servers) can invoke the agent via this protocol to perform operations
using public and private keys held in the agent. using public and private keys held in the agent.
Holding keys in an agent offers usability and security advantages to Holding keys in an agent offers usability and security advantages to
loading and unwrapping them at each use, as each key unwrapping may loading and unwrapping them at each use, as each key unwrapping may
require entry of a pass-phrase. Access to an agent may optionally be require entry of a passphrase. Access to an agent may optionally be
forwarded across an SSH connection, thereby allowing remote systems forwarded across an SSH connection, thereby allowing remote systems
to use stored keys without directly exposing the key material to the to use stored keys without directly exposing the key material to the
remote system. Finally, the agent may be implemented as a dedicated remote system. Finally, the agent may be implemented as a dedicated
component that presents a smaller attack surface than a key loaded component that presents a smaller attack surface than a key loaded
into a full SSH server or client, and which may be subject to special into a full SSH server or client and that may be subject to special
protection from the wider system. protection from the wider system.
1.1. Background 2. Requirements Language
This section is to be removed before publishing as an RFC.
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.
1.2. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
2. Protocol Overview 3. Protocol Overview
The agent protocol is a packetised request-response protocol, solely The agent protocol is a packetised request-response protocol that is
driven by the client. It consists of a number of requests sent from solely driven by the client. It consists of a number of requests
a client to an agent and a set of reply messages that are sent in sent from a client to an agent and a set of reply messages that are
response. At no time does the agent send messages except in response sent in response. At no time does the agent send messages except in
to a client request. Replies are sent in order. response to a client request. Replies are sent in order.
These requests include the ability to load keys into an agent, remove These requests include the ability to load keys into an agent, remove
some or all keys from an agent and to perform signature operations some or all keys from an agent, and perform signature operations
using previously-loaded keys. using previously loaded keys.
Agents MAY implement support for only a subset of available key type Agents MAY implement support for only a subset of available key types
and MAY additionally refuse some operations in particular contexts. and MAY additionally refuse some operations in particular contexts.
For example, an agent may allow only clients local to itself to add For example, an agent may allow only clients local to itself to add
keys, or may make particular subsets of keys available to a given keys or may make particular subsets of keys available to a given
client. For this reason, clients of the agent SHOULD be prepared to client. For this reason, clients of the agent SHOULD be prepared to
fail gracefully if any operation is refused. fail gracefully if any operation is refused.
2.1. Background 4. Terminology and Units
This section is to be removed before publishing as an RFC.
Note that this protocol is separate to and incompatible with the one
described in the similarly-named [draft-ietf-secsh-agent-02] which
expired in 2004.
2.2. Terminology and units
Henceforth in this document, "agent" will be used to refer to a key Henceforth, in this document, "agent" will be used to refer to a key
management component that implements the responder side of this management component that implements the responder side of this
protocol. "Client" will refer to a tool that implements the protocol. "Client" will refer to a tool that implements the
requester side of the protocol to communicate with an agent. If it requester side of the protocol to communicate with an agent. If it
is pertinent that the client in question is a [RFC4251] Secure Shell is pertinent that the client in question is a Secure Shell client as
client, then it will be explicitly referred to as an "SSH client". described in [RFC4251], then the client will be explicitly referred
Similarly, "SSH server" will be used to refer to Secure Shell to as an "SSH client". Similarly, "SSH server" will be used to refer
servers. to Secure Shell servers.
All encoding data types ("byte", "uint32", "string", etc.) are as All encoding data types ("byte", "uint32", "string", etc.) are as
specified in Section 5 of [RFC4251]. Additionally, the type "byte[]" specified in Section 5 of [RFC4251]. Additionally, the type "byte[]"
without a specified length within the square brackets indicates an without a specified length within the square brackets indicates an
unadorned sequence of zero or more bytes where the length is unadorned sequence of zero or more bytes where the length is
determined by context. determined by context.
All length units are given in bytes unless otherwise specified. All length units are given in bytes unless otherwise specified.
3. Protocol Messages 5. Protocol Messages
Messages consist of a length, type and contents. Messages consist of a "length", "type", and "contents".
uint32 length uint32 length
byte type byte type
byte[length - 1] contents byte[length - 1] contents
In the sections below, the "length" field is omitted. For clarity, In the sections below, the "length" field is omitted. For clarity,
the symbolic names of the message types are shown; their numeric the symbolic names of the message types are shown; their numeric
values are listed in Section 6.1 below. values are listed in Section 8.1.
3.1. Generic agent responses 5.1. Generic Agent Responses
The following generic messages may be sent by the agent in response The following generic messages may be sent by the agent in response
to requests from the client. On success the agent MUST reply either to requests from the client. On success, the agent MUST reply either
with the single-byte response: with the single-byte response:
byte SSH_AGENT_SUCCESS byte SSH_AGENT_SUCCESS
or a request-specific success message that may contain additional or with a request-specific success message that may contain
fields. On failure, the agent MUST reply with the single-byte additional fields. On failure, the agent MUST reply with the single-
response: byte response:
byte SSH_AGENT_FAILURE byte SSH_AGENT_FAILURE
or a request-specific failure message that may contain additional or with a request-specific failure message that may contain
fields. SSH_AGENT_FAILURE messages MUST also be sent in reply to additional fields. SSH_AGENT_FAILURE messages MUST also be sent in
requests with unknown or unsupported types. reply to requests with unknown or unsupported types.
3.2. Adding keys to the agent 5.2. Adding Keys to the Agent
Keys may be added to the agent using the SSH_AGENTC_ADD_IDENTITY or Keys may be added to the agent using the SSH_AGENTC_ADD_IDENTITY or
SSH_AGENTC_ADD_ID_CONSTRAINED messages. The latter variant allows SSH_AGENTC_ADD_ID_CONSTRAINED messages. The latter variant allows
adding keys with optional constraints on their usage. adding keys with optional constraints on their usage.
The generic format for the SSH_AGENTC_ADD_IDENTITY message is: The generic format for the SSH_AGENTC_ADD_IDENTITY message is:
byte SSH_AGENTC_ADD_IDENTITY byte SSH_AGENTC_ADD_IDENTITY
string key type string key type
byte[] key data byte[] key data
string comment string comment
Here "key type" is the specified key type name, for example "ssh-rsa" Here "key type" is the specified key type name, for example, "ssh-
for an RSA key as defined by [RFC4253]. "key data" consists of the rsa" for an RSA key as defined by [RFC4253]. The "key data" consists
public and private components of the key and varies by key type, as of the public and private components of the key and varies by key
specified in subsections 3.2.1 through 3.2.4 for commonly used key type, as specified in Sections 5.2.1 through 5.2.4 for commonly used
types. "comment" is a human-readable key name or comment as a UTF-8 key types. A "comment" is a human-readable key name or comment as a
string that may serve to identify the key in user-visible messages. UTF-8 string that may serve to identify the key in user-visible
This string may be of zero length. messages. This string may be of zero length.
The SSH_AGENTC_ADD_ID_CONSTRAINED message is similar, but adds an The SSH_AGENTC_ADD_ID_CONSTRAINED message is similar but adds an
extra field: extra field:
byte SSH_AGENTC_ADD_ID_CONSTRAINED byte SSH_AGENTC_ADD_ID_CONSTRAINED
string key type string key type
byte[] key data byte[] key data
string comment string comment
constraint[] constraints constraint[] constraints
Constraints are used to place limits on the validity or use of keys. Constraints are used to place limits on the validity or use of keys.
Section 3.2.7 details constraint types and their format. Clients Section 5.2.7 details constraint types and their formats. Clients
SHOULD prefer the SSH_AGENTC_ADD_IDENTITY message over sending an SHOULD prefer the SSH_AGENTC_ADD_IDENTITY message over sending an
SSH_AGENTC_ADD_ID_CONSTRAINED with an empty constraints field, though SSH_AGENTC_ADD_ID_CONSTRAINED message with an empty "constraints"
both are valid and equivalent. field, though both are valid and equivalent.
An agent MUST reply with SSH_AGENT_SUCCESS if the key was An agent MUST reply with SSH_AGENT_SUCCESS if the key was
successfully loaded as a result of one of these messages, or successfully loaded as a result of one of these messages or
SSH_AGENT_FAILURE otherwise. SSH_AGENT_FAILURE otherwise.
Adding a key that is already present in an agent SHOULD replace any Adding a key that is already present in an agent SHOULD replace any
constraints it was previously loaded with those (if any) present in constraints it was previously loaded with those (if any) that are
the subsequent add request, as this ensures that security-relevant present in the subsequent add request, as this ensures that security-
constraints on a loaded key best match user expectations. Otherwise relevant constraints on a loaded key best match user expectations.
an agent MAY refuse to load a key that has already been loaded. Otherwise, an agent MAY refuse to load a key that has already been
loaded.
An agent MAY support only a subset of the key types defined here and 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 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 does not recognise the type name in a request to add a key, then it
MUST respond with an SSH_AGENT_FAILURE reply. MUST respond with an SSH_AGENT_FAILURE reply.
3.2.1. DSA keys 5.2.1. DSA Keys
DSA keys have key type "ssh-dss" and are defined in [RFC4253]. They Digital Signature Algorithm (DSA) keys have key type "ssh-dss" and
may be added to the agent using the following message. The are defined in [RFC4253]. They may be added to the agent using the
"constraints" field is only present for the following message. The "constraints" field is only present for the
SSH_AGENTC_ADD_ID_CONSTRAINED message. SSH_AGENTC_ADD_ID_CONSTRAINED message.
byte SSH_AGENTC_ADD_IDENTITY or byte SSH_AGENTC_ADD_IDENTITY or
SSH_AGENTC_ADD_ID_CONSTRAINED SSH_AGENTC_ADD_ID_CONSTRAINED
string "ssh-dss" string "ssh-dss"
mpint p mpint p
mpint q mpint q
mpint g mpint g
mpint y mpint y
mpint x mpint x
string comment string comment
constraint[] constraints constraint[] constraints
The "p", "q", "g" values are the DSA domain parameters. "y" and "x" The "p", "q", and "g" values are the DSA domain parameters. The "y"
are the public and private keys respectively. These values are as and "x" values are the public and private keys, respectively. These
defined by Section 4.1 of [FIPS.186-4]. values are as defined by Section 4.1 of [FIPS.186-4].
3.2.2. ECDSA keys 5.2.2. ECDSA Keys
ECDSA keys have key types starting with "ecdsa-sha2-" and are defined Elliptic Curve Digital Signature Algorithm (ECDSA) keys have key
in [RFC5656]. They may be added to the agent using the following types starting with "ecdsa-sha2-" and are defined in [RFC5656]. They
message. The "constraints" field is only present for the may be added to the agent using the following message. The
"constraints" field is only present for the
SSH_AGENTC_ADD_ID_CONSTRAINED message. SSH_AGENTC_ADD_ID_CONSTRAINED message.
byte SSH_AGENTC_ADD_IDENTITY or byte SSH_AGENTC_ADD_IDENTITY or
SSH_AGENTC_ADD_ID_CONSTRAINED SSH_AGENTC_ADD_ID_CONSTRAINED
string key type string key type
string ecdsa_curve_name string ecdsa_curve_name
string Q string Q
mpint d mpint d
string comment string comment
constraint[] constraints constraint[] constraints
The values "Q" and "d" are the ECDSA public and private values The values "Q" and "d" are the ECDSA public and private values
respectively. Both are defined by Section 6.2 of [FIPS.186-5]. respectively. Both are defined by Section 6.2 of [FIPS.186-5].
3.2.3. EDDSA keys 5.2.3. EdDSA Keys
[RFC8709] defines Ed25519 and Ed448 with key type names "ssh-ed25519" [RFC8709] defines Edwards-curve Digital Signature Algorithm (EdDSA)
and "ssh-ed448" respectively. These may be added to the agent using keys (see [RFC8032]) Ed25519 and Ed448 with key type names "ssh-
the following message. The "constraints" field is only present for ed25519" and "ssh-ed448", respectively. These may be added to the
the SSH_AGENTC_ADD_ID_CONSTRAINED message. 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 byte SSH_AGENTC_ADD_IDENTITY or
SSH_AGENTC_ADD_ID_CONSTRAINED SSH_AGENTC_ADD_ID_CONSTRAINED
string "ssh-ed25519" or "ssh-ed448" string "ssh-ed25519" or "ssh-ed448"
string ENC(A) string ENC(A)
string k || ENC(A) string k || ENC(A)
string comment string comment
constraint[] constraints constraint[] constraints
The first value is the EDDSA public key ENC(A). The second value is 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 (this a concatenation of the private key k and the public ENC(A) key (this
redundant repetition of the public key is to maintain compatibility redundant repetition of the public key is to maintain compatibility
with widely deployed implementations). The contents and with widely deployed implementations). The contents and
interpretation of the ENC(A) and k values are defined by Section 3.2 interpretation of the ENC(A) and k values are defined by Section 3.2
of [RFC8032]. of [RFC8032].
3.2.4. RSA keys 5.2.4. RSA Keys
RSA keys have key type "ssh-rsa" and are defined in [RFC4253]. They RSA keys have key type "ssh-rsa" and are defined in [RFC4253]. They
may be added to the agent using the following message. The may be added to the agent using the following message. The
"constraints" field is only present for the "constraints" field is only present for the
SSH_AGENTC_ADD_ID_CONSTRAINED message. SSH_AGENTC_ADD_ID_CONSTRAINED message.
byte SSH_AGENTC_ADD_IDENTITY or byte SSH_AGENTC_ADD_IDENTITY or
SSH_AGENTC_ADD_ID_CONSTRAINED SSH_AGENTC_ADD_ID_CONSTRAINED
string "ssh-rsa" string "ssh-rsa"
mpint n mpint n
mpint e mpint e
mpint d mpint d
mpint iqmp mpint iqmp
mpint p mpint p
mpint q mpint q
string comment string comment
constraint[] constraints constraint[] constraints
"n" is the public composite modulus. "e" is the public exponent. "n" is the public composite modulus. "e" is the public exponent.
"d" is the private exponent. "p" and "q" are its constituent private "d" is the private exponent. "p" and "q" are its constituent private
prime factors. "iqmp" is the inverse of "q" modulo "p". All these prime factors. "iqmp" is the inverse of "q" modulo "p". All of
values except "iqmp" (which can be calculated from the others) are these values, except "iqmp" (which can be calculated from the
defined by Section 5.1 of [FIPS.186-5]. others), are defined by Section 5.1 of [FIPS.186-5].
3.2.5. Other keys 5.2.5. Other Keys
Agents and their clients MAY support additional key types not Agents and their clients MAY support additional key types not
documented here. Vendor-specific key types MUST use the domain- documented here. Vendor-specific key types MUST use the domain-
qualified naming convention defined in Section 6 of [RFC4251] until qualified naming convention defined in Section 6 of [RFC4251] until
code-points are allocated by IANA [IANA-PUBKEYS]. codepoints are allocated by IANA [IANA-PUBKEYS].
3.2.6. Adding keys from a token 5.2.6. Adding Keys from a Token
Keys hosted on smart-cards or other hardware tokens may be added Keys hosted on smart-cards or other hardware tokens may be added
using the SSH_AGENTC_ADD_SMARTCARD_KEY and using the SSH_AGENTC_ADD_SMARTCARD_KEY and
SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED requests. Note that SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED requests. Note that the
"constraints" field is only included for the "constraints" field is only included for the
SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED variant of this message. SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED variant of this message.
byte SSH_AGENTC_ADD_SMARTCARD_KEY or byte SSH_AGENTC_ADD_SMARTCARD_KEY or
SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED
string token id string token id
string PIN string PIN
constraint[] constraints constraint[] constraints
Here "token id" is an opaque identifier for the hardware token and Here "token id" is an opaque identifier for the hardware token and
"PIN" is an optional password or PIN to unlock the key. The "PIN" is an optional password or PIN to unlock the key. The
interpretation of "token id" is not defined by the protocol but is interpretation of "token id" is not defined by the protocol: it is
left solely up to the agent. left solely up to the agent.
Typically, only the public components of any keys supported on a Typically, only the public components of any keys supported on a
hardware token will be loaded into an agent so, strictly speaking, hardware token will be loaded into an agent; thus, strictly speaking,
this message really arranges future private key operations to be this message really arranges for future private key operations to be
delegated to the hardware token in question. delegated to the hardware token in question.
An agent MUST reply with SSH_AGENT_SUCCESS if one or more keys were An agent MUST reply with SSH_AGENT_SUCCESS if one or more keys were
successfully loaded as a result of one of these messages, or successfully loaded as a result of one of these messages or with
SSH_AGENT_FAILURE if no keys were found. The agent MUST also return SSH_AGENT_FAILURE if no keys were found. The agent MUST also return
SSH_AGENT_FAILURE if the "token id" was not recognised, if the SSH_AGENT_FAILURE if the "token id" was not recognised, if the
request was against agent policy, or if the agent doesn't support request was against agent policy, or if the agent doesn't support
token-hosted keys at all. token-hosted keys at all.
3.2.7. Key Constraints 5.2.7. Key Constraints
A number of constraints may be used in the constrained variants of A number of constraints may be used in the constrained variants of
the key add messages. Each constraint is represented by a type byte the key add messages. Each constraint is represented by a type byte
followed by zero or more value bytes. followed by zero or more value bytes.
Zero or more constraints may be specified when adding a key with one Zero or more constraints may be specified when adding a key with one
of the *_CONSTRAINED requests. Multiple constraints are appended of the *_CONSTRAINED requests. Multiple constraints are appended
consecutively to the end of the request: consecutively to the end of the request:
byte constraint1_type byte constraint1_type
byte[] constraint1_data byte[] constraint1_data
byte constraint2_type byte constraint2_type
byte[] constraint2_data byte[] constraint2_data
.... ....
byte constraintN_type byte constraintN_type
byte[] constraintN_data byte[] constraintN_data
To fully parse a constraint, it is necessary to know its structure To fully parse a constraint, it is necessary to know its structure
beforehand and it is not possible to safely recover when an beforehand; it is not possible to safely recover when an unrecognised
unrecognised constraint is encountered. Given this, if an agent does constraint is encountered. Given this, if an agent does not
not recognise or support a requested constraint it MUST abort recognise or support a requested constraint, it MUST abort parsing,
parsing, refuse the request and return an SSH_AGENT_FAILURE message refuse the request, and return an SSH_AGENT_FAILURE message to the
to the client. client.
The following constraints are defined. The following subsections describe the constraints that have been
defined.
3.2.7.1. Key lifetime constraint 5.2.7.1. Key Lifetime Constraint
This constraint requests that the agent limit the key's lifetime by This constraint requests that the agent limit the key's lifetime by
deleting it after the specified duration (in seconds) has elapsed deleting it after the specified duration (in seconds) has elapsed
from the time the key was added to the agent. from the time the key was added to the agent.
byte SSH_AGENT_CONSTRAIN_LIFETIME byte SSH_AGENT_CONSTRAIN_LIFETIME
uint32 seconds uint32 seconds
3.2.7.2. Key confirmation constraint 5.2.7.2. Key Confirmation Constraint
This constraint requests that the agent require explicit user This constraint requests that the agent require explicit user
confirmation for each private key operation using the key. For confirmation for each private key operation using the key. For
example, the agent could present a confirmation dialog before example, the agent could present a confirmation dialog before
completing a signature operation. completing a signature operation.
byte SSH_AGENT_CONSTRAIN_CONFIRM byte SSH_AGENT_CONSTRAIN_CONFIRM
3.2.7.3. Constraint extensions 5.2.7.3. Constraint Extensions
Agents may implement experimental or private-use constraints through Agents may implement experimental or private-use constraints through
an extension constraint that supports named constraints. an extension constraint that supports named constraints.
byte SSH_AGENT_CONSTRAIN_EXTENSION byte SSH_AGENT_CONSTRAIN_EXTENSION
string extension name string extension name
byte[] extension-specific details byte[] extension-specific details
The extension name MUST consist of a UTF-8 string. Vendor extensions The "extension name" MUST consist of a UTF-8 string. Vendor
MUST be suffixed by the implementation domain following the naming extensions MUST be suffixed by the implementation domain following
scheme defined in Section 6 of [RFC4251], e.g. "foo@example.com". the naming scheme defined in Section 6 of [RFC4251], e.g.,
"foo@example.com".
Note, given the above requirement to reject keys with unsupported Note, given the above requirement to reject keys with unsupported
constraints, a constraint extension is only usable when both client constraints, a constraint extension is only usable when both the
and agent support it. Otherwise, the agent will be required to client and agent support it. Otherwise, the agent will be required
reject the key. This is desirable, as the constraint extension may to reject the key. This is desirable, as the constraint extension
specify limits on the key that, if ignored, may result in the key may specify limits on the key that, if ignored, may result in the key
being available in situations the user did not intend (i.e. the agent being available in situations the user did not intend (i.e., the
will fail safely). agent will fail safely).
3.3. Public key encoding 5.3. Public Key Encoding
Keys previously loaded into an agent are referred to by their public Keys previously loaded into an agent are referred to by their public
key blob, which is the standard SSH wire encoding for public keys. key blob, which is the standard SSH wire encoding for public keys.
SSH protocol key encodings are defined in [RFC4253] for "ssh-rsa" and SSH protocol key encodings are defined in [RFC4253] for "ssh-rsa" and
"ssh-dss" keys, in [RFC5656] for "ecdsa-sha2-*" keys and in [RFC8709] "ssh-dss" keys, in [RFC5656] for "ecdsa-sha2-*" keys, and in
for "ssh-ed25519" and "ssh-ed448" keys. [RFC8709] for "ssh-ed25519" and "ssh-ed448" keys.
3.4. Removing keys from the agent 5.4. Removing Keys from the Agent
A client may request that an agent remove all keys that it stores: A client may request that an agent remove all keys that it stores:
byte SSH_AGENTC_REMOVE_ALL_IDENTITIES byte SSH_AGENTC_REMOVE_ALL_IDENTITIES
On receipt of such a message, an agent SHOULD delete all keys that it On receipt of such a message, an agent SHOULD delete all keys that it
is holding and reply with SSH_AGENT_SUCCESS, otherwise it MUST reply is holding and reply with SSH_AGENT_SUCCESS; otherwise, it MUST reply
with SSH_AGENT_FAILURE if the request was refused. with SSH_AGENT_FAILURE if the request was refused.
This request SHOULD be honoured regardless of any agent policy that This request SHOULD be honoured regardless of any agent policy that
limits actions that a given client may take, as otherwise a user limits actions that a given client may take; otherwise, a user would
would be unable to quickly and completely remove their keys in an be unable to quickly and completely remove their keys in an urgent
urgent situation. situation.
Specific keys may also be removed: Specific keys may also be removed:
byte SSH_AGENTC_REMOVE_IDENTITY byte SSH_AGENTC_REMOVE_IDENTITY
string key blob string key blob
Where "key blob" is the standard public key encoding of the key to be Where "key blob" is the standard public key encoding of the key to be
removed (Section 3.3). removed (Section 5.3).
An agent MUST reply with SSH_AGENT_SUCCESS if the key was deleted or An agent MUST reply with SSH_AGENT_SUCCESS if the key was deleted or
SSH_AGENT_FAILURE if it was not found. SSH_AGENT_FAILURE if it was not found.
Token-hosted keys may be removed from an agent using: Token-hosted keys may be removed from an agent using:
byte SSH_AGENTC_REMOVE_SMARTCARD_KEY byte SSH_AGENTC_REMOVE_SMARTCARD_KEY
string token id string token id
string PIN string PIN
Where "token id" is an opaque identifier for the hardware token and Where "token id" is an opaque identifier for the hardware token and
"PIN" is an optional password or PIN (not typically used), both "PIN" is an optional password or PIN (not typically used), both
encoded using UTF-8. Requesting deletion of token-hosted keys SHOULD encoded using UTF-8. Requesting deletion of token-hosted keys SHOULD
cause the agent to remove all keys it loaded from the device matching cause the agent to remove all keys it loaded from the device matching
"token id". Similarly to SSH_AGENTC_REMOVE_ALL_IDENTITIES, agents "token id". Similarly to SSH_AGENTC_REMOVE_ALL_IDENTITIES, agents
SHOULD honour this request regardless of local policy to allow fast SHOULD honour this request regardless of local policy to allow fast
and complete removal of keys. Note: this operation affects the agent and complete removal of keys. Note: this operation affects the agent
only, it SHOULD NOT cause the keys be deleted from the token itself. only; it SHOULD NOT cause the keys be deleted from the token itself.
An agent MUST reply with SSH_AGENT_SUCCESS keys were deleted or An agent MUST reply with SSH_AGENT_SUCCESS if the keys were deleted
SSH_AGENT_FAILURE if none were found. or SSH_AGENT_FAILURE if none were found.
3.5. Requesting a list of keys 5.5. Requesting a List of Keys
A client may request a list of keys from an agent using the following A client may request a list of keys from an agent using the following
message: message:
byte SSH_AGENTC_REQUEST_IDENTITIES byte SSH_AGENTC_REQUEST_IDENTITIES
The agent MUST reply with a message with the following preamble. The agent MUST reply with a message with the following preamble:
byte SSH_AGENT_IDENTITIES_ANSWER byte SSH_AGENT_IDENTITIES_ANSWER
uint32 nkeys uint32 nkeys
Where "nkeys" indicates the number of keys to follow. Following the Where "nkeys" indicates the number of keys to follow. Following the
preamble are zero or more keys, representing the keys the agent makes preamble are zero or more keys, representing the keys the agent makes
available to the client with each encoded as: available to the client with each encoded as:
string key blob string key blob
string comment string comment
Where "key blob" is the standard public key encoding of the key Where "key blob" is the standard public key encoding of the key
(Section 3.3) and "comment" is a human-readable comment encoded as a (Section 5.3) and "comment" is a human-readable comment encoded as a
UTF-8 string. UTF-8 string.
3.6. Private key operations 5.6. Private Key Operations
A client may request the agent perform a private key signature A client may request that the agent perform a private key signature
operation using the following message: operation using the following message:
byte SSH_AGENTC_SIGN_REQUEST byte SSH_AGENTC_SIGN_REQUEST
string key blob string key blob
string data string data
uint32 flags uint32 flags
Where "key blob" is the key requested to perform the signature Where "key blob" is the key requested to perform the signature
(encoded as per Section 3.3), "data" is the data to be signed and (encoded as per Section 5.3), "data" is the data to be signed, and
"flags" is a bitfield containing the bitwise OR of zero or more "flags" is a bitfield containing the bitwise OR of zero or more
signature flags (see below). signature flags (see below).
If the agent does not support the requested flags, or is otherwise If the agent does not support the requested flags, or is otherwise
unable or unwilling to generate the signature (for example, because unable or unwilling to generate the signature (for example, because
it doesn't have the specified key, or the user refused confirmation it doesn't have the specified key or the user refused confirmation of
of a constrained key), it MUST reply with an SSH_AGENT_FAILURE a constrained key), it MUST reply with an SSH_AGENT_FAILURE message.
message.
On success, the agent MUST reply with: On success, the agent MUST reply with:
byte SSH_AGENT_SIGN_RESPONSE byte SSH_AGENT_SIGN_RESPONSE
string signature string signature
The signature format is specific to the algorithm of the key type in The signature format is specific to the algorithm of the key type in
use. SSH protocol signature formats are defined in [RFC4253] for use. SSH protocol signature formats are defined in [RFC4253] for
"ssh-rsa" and "ssh-dss" keys, in [RFC5656] for "ecdsa-sha2-*" keys "ssh-rsa" and "ssh-dss" keys, in [RFC5656] for "ecdsa-sha2-*" keys,
and in [RFC8709] for "ssh-ed25519" and "ssh-ed448" keys. and in [RFC8709] for "ssh-ed25519" and "ssh-ed448" keys.
3.6.1. Signature flags 5.6.1. Signature Flags
Two flags are currently defined for signature request messages: Two flags are currently defined for signature request messages:
SSH_AGENT_RSA_SHA2_256 and SSH_AGENT_RSA_SHA2_512 (defined in SSH_AGENT_RSA_SHA2_256 and SSH_AGENT_RSA_SHA2_512 (defined in
Section 6.3). These two flags are only valid for "ssh-rsa" keys and Section 8.3). These two flags are only valid for "ssh-rsa" keys and
request that the agent return a signature using the "rsa-sha2-256" or request that the agent return a signature using the "rsa-sha2-256" or
"rsa-sha2-512" signature methods respectively. These signature "rsa-sha2-512" signature methods, respectively. These signature
schemes are defined in [RFC8332]. schemes are defined in [RFC8332].
3.7. Locking and unlocking an agent 5.7. Locking and Unlocking an Agent
The agent protocol supports instructing an agent to temporarily lock The agent protocol supports instructing an agent to temporarily lock
itself with a pass-phrase. When locked, an agent MUST suspend itself with a passphrase. When locked, an agent MUST suspend
processing of sensitive operations (private key signature operations processing of sensitive operations (private key signature operations
at the very least) until it has been unlocked with the same pass- at the very least) until it has been unlocked with the same
phrase. passphrase.
The following message instructs an agent to lock itself: The following message instructs an agent to lock itself:
byte SSH_AGENTC_LOCK byte SSH_AGENTC_LOCK
string passphrase string passphrase
The agent MUST reply with SSH_AGENT_SUCCESS if locked successfully or The agent MUST reply with SSH_AGENT_SUCCESS if locked successfully or
SSH_AGENT_FAILURE otherwise (e.g. if the agent was already locked). SSH_AGENT_FAILURE otherwise (e.g., if the agent was already locked).
The following message requests unlocking an agent: The following message requests unlocking an agent:
byte SSH_AGENTC_UNLOCK byte SSH_AGENTC_UNLOCK
string passphrase string passphrase
If the agent is already locked and the pass-phrase matches the one If the agent is already locked and the passphrase matches the one
used to lock it then it MUST unlock and reply with SSH_AGENT_SUCCESS. used to lock it, then it MUST unlock and reply with
If the agent is already unlocked or if the pass-phrase does not match SSH_AGENT_SUCCESS. If the agent is already unlocked or if the
it MUST reply with SSH_AGENT_FAILURE. passphrase does not match, it MUST reply with SSH_AGENT_FAILURE.
3.8. Extension mechanism 5.8. Extension Mechanism
The agent protocol includes an optional extension mechanism that The agent protocol includes an optional extension mechanism that
allows vendor-specific and experimental messages to be sent via the allows vendor-specific and experimental messages to be sent via the
agent protocol. Extension requests from the client consist of: agent protocol. Extension requests from the client consist of:
byte SSH_AGENTC_EXTENSION byte SSH_AGENTC_EXTENSION
string extension type string extension type
byte[] extension request-specific contents byte[] extension request-specific contents
The extension type indicates the type of the extension message as a The "extension type" indicates the type of the extension message as a
UTF-8 string. Implementation-specific extensions MUST be suffixed by UTF-8 string. Implementation-specific extensions MUST be suffixed by
the implementation domain following the extension naming scheme the implementation domain following the extension naming scheme
defined in Section 6 of [RFC4251], e.g. "foo@example.com". defined in Section 6 of [RFC4251], e.g., "foo@example.com".
An agent that does not support extensions of the supplied type MUST An agent that does not support extensions of the supplied type MUST
reply with an empty SSH_AGENT_FAILURE message. This reply is also reply with an empty SSH_AGENT_FAILURE message. This reply is also
sent by agents that do not support the extension mechanism at all. sent by agents that do not support the extension mechanism at all.
The contents of successful extension reply messages are specific to The contents of successful extension reply messages are specific to
the extension type. Successful extension requests MUST return either the "extension type". Successful extension requests MUST return
SSH_AGENT_SUCCESS on success or an extension-specific response either SSH_AGENT_SUCCESS on success or an extension-specific response
message: message:
byte SSH_AGENT_EXTENSION_RESPONSE byte SSH_AGENT_EXTENSION_RESPONSE
string extension type string extension type
byte[] extension response-specific contents byte[] extension response-specific contents
Where the extension type is the same as that in the request. Where the "extension type" is the same as that in the request.
Extension failure SHOULD be signaled using an Extension failure SHOULD be signaled using an
SSH_AGENT_EXTENSION_FAILURE message: SSH_AGENT_EXTENSION_FAILURE message:
byte SSH_AGENT_EXTENSION_FAILURE byte SSH_AGENT_EXTENSION_FAILURE
Extensions SHOULD NOT use the standard SSH_AGENT_FAILURE message. Extensions SHOULD NOT use the standard SSH_AGENT_FAILURE message.
This allows failed requests to be distinguished from the extension This allows failed requests to be distinguished from the extension
not being supported. not being supported.
3.8.1. Query extension 5.8.1. Query Extension
A single, optional extension request "query" is defined to allow a A single optional extension request "query" is defined to allow a
client to query which, if any, extensions are supported by an agent. client to query which, if any, extensions are supported by an agent.
byte SSH_AGENTC_EXTENSION byte SSH_AGENTC_EXTENSION
string "query" string "query"
If an agent supports the query extension it SHOULD reply with a list If an agent supports the query extension, it SHOULD reply with a list
of supported extension names. of supported extension names.
byte SSH_AGENT_EXTENSION_RESPONSE byte SSH_AGENT_EXTENSION_RESPONSE
string "query" string "query"
string[] supported extension types string[] supported extension types
4. Connecting to an agent 6. Connecting to an Agent
Agents are exposed to the local system using a connection-oriented Agents are exposed to the local system using a connection-oriented
endpoint. On Unix-like systems, it is typical to arrange for the endpoint. On Unix-like systems, it is typical to arrange for the
agent to listen on a filesystem-based Unix domain socket. On agent to listen on a filesystem-based Unix domain socket. On
Microsoft Windows, it is usual to use a Windows Named Pipe. Access Microsoft Windows, it is usual to use a Windows Named Pipe. Access
to these endpoints SHOULD be controlled as discussed in Section 8. to these endpoints SHOULD be controlled as discussed in Section 10.
Multiple clients may access a single agent by making connections to Multiple clients may access a single agent by making connections to
these sockets. these sockets.
In both cases, it is common to expose the name or address of the In both cases, it is common to expose the name or address of the
listening endpoint via an environment variable named "SSH_AUTH_SOCK". listening endpoint via an environment variable named "SSH_AUTH_SOCK".
Clients of an agent will use this variable to locate and connect to Clients of an agent will use this variable to locate and connect to
the listening agent. Agents alternately MAY use an implicit the listening agent. Alternatively, agents MAY use an implicit
mechanism for clients to locate their endpoint, such as a default mechanism for clients to locate their endpoint, such as a default
per-user location. per-user location.
5. Forwarding access to an agent 7. Forwarding Access to an Agent
The agent protocol may be forwarded over an SSH connection, using the The agent protocol may be forwarded over an SSH connection, using the
[RFC4254] connection protocol, allowing agent forwarding to be [RFC4254] connection protocol, allowing agent forwarding to be
requested for any session channel, using a model that is similar to requested for any session channel, using a model that is similar to
the connection protocol's support for X11 Forwarding (Section 6.3 of the connection protocol's support for X11 Forwarding (Section 6.3 of
[RFC4254]). This feature is OPTIONAL for SSH protocol and agent [RFC4254]). This feature is OPTIONAL for the SSH protocol and agent
implementations. implementations.
5.1. Advertising agent forwarding support 7.1. Advertising Agent Forwarding Support
Support for agent forwarding may be advertised by an SSH server using Support for agent forwarding may be advertised by an SSH server using
the [RFC8308] extension mechanism using the name "agent-forward" in the extension mechanism described in [RFC8308] using the name "agent-
the SSH_MSG_EXT_INFO message. forward" in the SSH_MSG_EXT_INFO message.
string "agent-forward" string "agent-forward"
string "0" (version) string "0" (version)
Note that this protocol substantially predates the existence of the Note that this protocol substantially predates the existence of the
[RFC8308] extension mechanism and several widely-deployed SSH extension mechanism described in [RFC8308]. Further note that
implementations that support agent forwarding do not advertise their several widely deployed SSH implementations that support agent
ability to do so. SSH Clients MAY opportunistically attempt to forwarding do not advertise their ability to do so. SSH clients MAY
request agent forwarding in the absence of an [RFC8308] advertisement opportunistically attempt to request agent forwarding in the absence
using the vendor-specific names mentioned below. Likewise, SSH of an advertisement (see [RFC8308]) using the vendor-specific names
servers MAY implement the vendor-specific names in addition to the mentioned below. Likewise, SSH servers MAY implement the vendor-
one described here. specific names in addition to the one described here.
5.2. Requesting agent forwarding 7.2. Requesting Agent Forwarding
An SSH client may request agent forwarding for a previously-opened An SSH client may request agent forwarding for a previously opened
session (Section 6.1 of [RFC4254]) using the following channel session (see Section 6.1 of [RFC4254]) using the following channel
request. This request is sent after the channel has been opened, but request. This request is sent after the channel has been opened, but
before a shell, command or subsystem has been executed. before a shell, command, or subsystem has been executed.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 channel_id uint32 channel_id
string "agent-req" or "auth-agent-req@openssh.com" string "agent-req" or "auth-agent-req@openssh.com"
boolean want_reply boolean want_reply
Where channel_id is the identifier for an established session channel Where "channel_id" is the identifier for an established session
(as returned from a previous SSH_MSG_CHANNEL_OPEN request, and the channel (as returned from a previous SSH_MSG_CHANNEL_OPEN request)
want_reply flag indicates whether the SSH server should respond with and the "want_reply" flag indicates whether the SSH server should
a confirmation of whether the request was successful (as specified in respond with a confirmation of whether the request was successful (as
Section 5.4 of [RFC4254]) specified in Section 5.4 of [RFC4254]).
If an SSH server accepts this request, typically it will arrange to If an SSH server accepts this request, typically it will arrange to
make an endpoint (e.g. a listening socket) available and advertise make an endpoint (e.g., a listening socket) available and advertise
this fact to the subordinate session. Most implementations on Unix- this fact to the subordinate session. Most implementations on Unix-
like systems do this by providing a user-private listening Unix like systems do this by providing a user-private listening Unix
domain socket and recording its location in an environment variable domain socket and recording its location in an environment variable
SSH_AUTH_SOCK. "SSH_AUTH_SOCK".
As mentioned previously, many deployed implementations only support As mentioned previously, many deployed implementations only support
the pre-standardisation "auth-agent-req@openssh.com" request name. the pre-standardisation "auth-agent-req@openssh.com" request name.
The "agent-req" name SHOULD only be used if support was explicitly The "agent-req" name SHOULD only be used if support was explicitly
advertised as per Section 5.1. advertised as per Section 7.1.
5.3. Agent connection requests 7.3. Agent Connection Requests
After an SSH client has requested that a session have agent After an SSH client has requested that a session have agent
forwarding enabled, the SSH server later may request a connection to forwarding enabled, the SSH server may request a connection to the
the forwarded agent. The SSH server does this by requesting a forwarded agent. The SSH server does this by requesting a dedicated
dedicated channel to communicate with the SSH client's agent. channel to communicate with the SSH client's agent.
byte SSH_MSG_CHANNEL_OPEN byte SSH_MSG_CHANNEL_OPEN
string "agent-connect" or "auth-agent@openssh.com" string "agent-connect" or "auth-agent@openssh.com"
uint32 channel_id uint32 channel_id
uint32 local_window uint32 local_window
uint32 local_maxpacket uint32 local_maxpacket
The channel_id, local_window and local_maxpacket fields should be The "channel_id", "local_window", and "local_maxpacket" fields should
interpreted as specified by Section 5.1 of [RFC4254]. be interpreted as specified by Section 5.1 of [RFC4254].
As above, the "agent-connect" open type name SHOULD only be used if As above, the "agent-connect" open type name SHOULD only be used if
support was explicitly advertised as per Section 5.1. support was explicitly advertised as per Section 7.1.
An SSH client SHOULD be prepared to handle multiple concurrent An SSH client SHOULD be prepared to handle multiple concurrent
forwarded connections to a client-side agent, otherwise requests to forwarded connections to a client-side agent; otherwise, requests to
access the agent from the remote side that happen to overlap prior access the agent from the remote side that happen to overlap prior
requests may fail. Overlapping requests may occur because the SSH requests may fail. Overlapping requests may occur because the SSH
connection protocol [RFC4254] allows multiple user sessions over a connection protocol [RFC4254] allows multiple user sessions over a
single [RFC4253] transport, which may each request use of the agentcw single transport (see [RFC4253]), which may each request use of the
independently and potentially concurrently. agentcw independently and potentially concurrently.
An SSH client MAY accept agent connection requests (subject to An SSH client MAY accept agent connection requests (subject to
authorisation) without a prior agent forwarding request having been authorisation) without a prior agent forwarding request having been
made to support the situation where agent forwarding without opening made to support the situation where agent forwarding without opening
a session is desired. Similarly, an SSH client MAY continue to a session is desired. Similarly, an SSH client MAY continue to
accept agent connection requests after the session for which agent accept agent connection requests after the session for which agent
forwarding was requested has closed. forwarding was requested has closed.
An SSH client MUST refuse unauthorised agent connection requests, An SSH client MUST refuse unauthorised agent connection requests,
when agent forwarding is neither requested nor desired by the SSH when agent forwarding is neither requested nor desired by the SSH
client but an SSH server sends an agent connection request anyway. client but an SSH server sends an agent connection request anyway.
Because the "agent-connect" request contains no identifier to Because the "agent-connect" request contains no identifier to
distinguish which session channel originated the connection request, distinguish which session channel originated the connection request,
an SSH connection can effectively forward access to only a single SSH an SSH connection can effectively forward access to only a single SSH
client-side agent using this protocol (although there may be multiple client-side agent using this protocol (although there may be multiple
concurrent connections to that single agent). concurrent connections to that single agent).
6. Protocol numbers 8. Protocol Numbers
6.1. Message type numbers 8.1. Message Type Numbers
The following numbers are used as message types for requests from the The following numbers are used as message types for requests from the
client to the agent. client to the agent.
SSH_AGENTC_REQUEST_IDENTITIES 11 SSH_AGENTC_REQUEST_IDENTITIES 11
SSH_AGENTC_SIGN_REQUEST 13 SSH_AGENTC_SIGN_REQUEST 13
SSH_AGENTC_ADD_IDENTITY 17 SSH_AGENTC_ADD_IDENTITY 17
SSH_AGENTC_REMOVE_IDENTITY 18 SSH_AGENTC_REMOVE_IDENTITY 18
SSH_AGENTC_REMOVE_ALL_IDENTITIES 19 SSH_AGENTC_REMOVE_ALL_IDENTITIES 19
SSH_AGENTC_ADD_SMARTCARD_KEY 20 SSH_AGENTC_ADD_SMARTCARD_KEY 20
skipping to change at page 18, line 12 skipping to change at line 783
The following numbers are used as message types for replies from the The following numbers are used as message types for replies from the
agent to the client. agent to the client.
SSH_AGENT_FAILURE 5 SSH_AGENT_FAILURE 5
SSH_AGENT_SUCCESS 6 SSH_AGENT_SUCCESS 6
SSH_AGENT_IDENTITIES_ANSWER 12 SSH_AGENT_IDENTITIES_ANSWER 12
SSH_AGENT_SIGN_RESPONSE 14 SSH_AGENT_SIGN_RESPONSE 14
SSH_AGENT_EXTENSION_FAILURE 28 SSH_AGENT_EXTENSION_FAILURE 28
SSH_AGENT_EXTENSION_RESPONSE 29 SSH_AGENT_EXTENSION_RESPONSE 29
6.1.1. Reserved message type numbers 8.1.1. Reserved Message Type Numbers
The following message type numbers are reserved for implementations The following message type numbers are reserved for implementations
that implement support for the legacy SSH protocol version 1: 1-4, that implement support for the legacy SSH protocol version 1: 1-4,
7-10, 15-16 and 24 (inclusive). These message numbers MAY be used by 7-10, 15-16, and 24 (inclusive). These message numbers MAY be used
an implementation supporting the legacy protocol but MUST NOT be by an implementation supporting the legacy protocol but MUST NOT be
reused otherwise. reused otherwise.
Message number 0 is also reserved and MUST NOT be used. Message number 0 is also reserved and MUST NOT be used.
The range of message numbers 240-255 are reserved for Private Use The range of message numbers 240-255 is reserved for Private Use
extensions to the agent protocol and MUST NOT be used by generic extensions to the agent protocol and MUST NOT be used by generic
implementations. implementations (see [RFC8126] for more information on Private Use).
6.2. Constraint identifiers 8.2. Constraint Identifiers
The following numbers are used to identify key constraints. These The following numbers are used to identify key constraints. These
are only used in key constraints and are not sent as message numbers. are only used in key constraints and are not sent as message numbers.
SSH_AGENT_CONSTRAIN_LIFETIME 1 SSH_AGENT_CONSTRAIN_LIFETIME 1
SSH_AGENT_CONSTRAIN_CONFIRM 2 SSH_AGENT_CONSTRAIN_CONFIRM 2
SSH_AGENT_CONSTRAIN_EXTENSION 255 SSH_AGENT_CONSTRAIN_EXTENSION 255
The constraint identifier 0 is reserved. The constraint identifier 0 is reserved.
6.3. Signature flags 8.3. Signature Flags
The following numbers may be present in signature request The following numbers may be present in signature request
(SSH_AGENTC_SIGN_REQUEST) messages. These flags form a bit field by (SSH_AGENTC_SIGN_REQUEST) messages. These flags form a bit field by
taking the logical OR of zero or more flags. taking the logical OR of zero or more flags.
SSH_AGENT_RSA_SHA2_256 0x00000002 SSH_AGENT_RSA_SHA2_256 0x00000002
SSH_AGENT_RSA_SHA2_512 0x00000004 SSH_AGENT_RSA_SHA2_512 0x00000004
The flag value 1 is reserved for historical implementations. The flag value 1 is reserved for historical implementations.
7. IANA Considerations 9. IANA Considerations
This protocol requires five registries be established, one for This protocol describes the establishment of five registries: one for
message type numbers, one for constraint numbers, one for signature message type numbers, one for constraint numbers, one for signature
request flags, one for constraint extension names and one for request flags, one for constraint extension names, and one for
extension request names. Additionally, new codepoints are requested extension request names. Additionally, new codepoints are requested
in three existing registries. in three existing registries.
7.1. Guidance for Designated Experts 9.1. Guidance for Designated Experts
When a Designated Expert (DE) is asked to review additions to the new When a Designated Expert (DE) is asked to review additions to the new
registries described above (Section 7.2, Section 7.3, Section 7.5 and registries described in this document (Section 9.2, Section 9.3,
Section 7.6), they are requested to verify that suitable Section 9.5, and Section 9.6), they are requested to verify that
documentation as described in [RFC8126] exists and is permanently and suitable documentation as described in [RFC8126] exists and is
publicly available. The DE is also requested to check the clarity of permanently and publicly available. The DE is also requested to
purpose and use of the requested code points. The DE should also check the clarity of purpose and use of the requested codepoints.
verify that specifications produced in the IETF that request code The DE should also verify that specifications produced in the IETF
points in these registries have been made available to the SSHM that request codepoints in these registries have been made available
working group and the ssh@ietf.org mailing list for review. Requests to the SSHM Working Group and the ssh@ietf.org mailing list for
for code points made for specifications produced outside the IETF review. Requests for codepoints made for specifications produced
should not conflict with active IETF work or prior IETF outside the IETF should not conflict with active IETF work or prior
specifications. IETF specifications.
The available number of code points in the SSH agent protocol numbers The available number of codepoints in the SSH agent protocol numbers
(Section 7.2), constraint numbers (Section 7.3) and SSH agent (Section 9.2), constraint numbers (Section 9.3), and SSH agent
signature flags (Section 7.5) registries are limited, so the DE is signature flags (Section 9.5) registries are limited, so the DE is
requested to ensure the use of code points is very well justified. requested to ensure the use of codepoints is very well justified.
For the SSH agent protocol message numbers, named extension requests For the SSH agent protocol message numbers, named extension requests
(Section 7.6) provide an alternative for most uses with no practical (Section 9.6) provide an alternative for most uses with no practical
limitation on the number of available code points. For key limitation on the number of available codepoints. For key constraint
constraint numbers, the constraint extension mechanism numbers, the constraint extension mechanism (Section 5.2.7.3)
(Section 3.2.7.3) provides a similar alternative that is not limited provides a similar alternative that is not limited by available
by available code points. codepoints.
7.2. New registry: SSH agent protocol message type numbers 9.2. "SSH Agent Protocol Message Type Numbers" Registry
This registry, titled "SSH agent protocol message type numbers" The "SSH Agent Protocol Message Type Numbers" registry records the
records the message type numbers for client requests and agent message type numbers for client requests and agent responses. It is
responses. It should be created in the Secure Shell (SSH) Protocol located in the "Secure Shell (SSH) Protocol Parameters" registry
Parameters registry group [IANA-SSH]. Its initial state should group [IANA-SSH]. Its initial state consists of the following
consist of the following numbers and reservations. Future message numbers and reservations. Future message number allocations shall
number allocations shall occur via Expert Review as per [RFC8126]. occur via Expert Review as per [RFC8126].
+===========+==========================================+===========+ +=========+==========================================+=============+
| Number(s) | Identifier | Reference | | Number | Identifier | Reference |
+===========+==========================================+===========+ +=========+==========================================+=============+
| 0 | reserved | thisrfc, | | 0 | Reserved | RFC 9987, |
| | | Section | | | | Section |
| | | 6.1.1 | | | | 8.1.1 |
+-----------+------------------------------------------+-----------+ +---------+------------------------------------------+-------------+
| 1 | reserved | thisrfc, | | 1 | Reserved | RFC 9987, |
| | | Section | | | | Section |
| | | 6.1.1 | | | | 8.1.1 |
+-----------+------------------------------------------+-----------+ +---------+------------------------------------------+-------------+
| 2 | reserved | thisrfc, | | 2 | Reserved | RFC 9987, |
| | | Section | | | | Section |
| | | 6.1.1 | | | | 8.1.1 |
+-----------+------------------------------------------+-----------+ +---------+------------------------------------------+-------------+
| 3 | reserved | thisrfc, | | 3 | Reserved | RFC 9987, |
| | | Section | | | | Section |
| | | 6.1.1 | | | | 8.1.1 |
+-----------+------------------------------------------+-----------+ +---------+------------------------------------------+-------------+
| 4 | reserved | thisrfc, | | 4 | Reserved | RFC 9987, |
| | | Section | | | | Section |
| | | 6.1.1 | | | | 8.1.1 |
+-----------+------------------------------------------+-----------+ +---------+------------------------------------------+-------------+
| 5 | SSH_AGENT_FAILURE | thisrfc, | | 5 | SSH_AGENT_FAILURE | RFC 9987, |
| | | Sections | | | | Sections |
| | | 3.1 and | | | | 5.1 and 8.1 |
| | | 6.1 | +---------+------------------------------------------+-------------+
+-----------+------------------------------------------+-----------+ | 6 | SSH_AGENT_SUCCESS | RFC 9987, |
| 6 | SSH_AGENT_SUCCESS | thisrfc, | | | | Sections |
| | | Sections | | | | 5.1 and 8.1 |
| | | 3.1 and | +---------+------------------------------------------+-------------+
| | | 6.1 | | 7 | Reserved | RFC 9987, |
+-----------+------------------------------------------+-----------+ | | | Section |
| 7 | reserved | thisrfc, | | | | 8.1.1 |
| | | Section | +---------+------------------------------------------+-------------+
| | | 6.1.1 | | 8 | Reserved | RFC 9987, |
+-----------+------------------------------------------+-----------+ | | | Section |
| 8 | reserved | thisrfc, | | | | 8.1.1 |
| | | Section | +---------+------------------------------------------+-------------+
| | | 6.1.1 | | 9 | Reserved | RFC 9987, |
+-----------+------------------------------------------+-----------+ | | | Section |
| 9 | reserved | thisrfc, | | | | 8.1.1 |
| | | Section | +---------+------------------------------------------+-------------+
| | | 6.1.1 | | 10 | Reserved | RFC 9987, |
+-----------+------------------------------------------+-----------+ | | | Section |
| 10 | reserved | thisrfc, | | | | 8.1.1 |
| | | Section | +---------+------------------------------------------+-------------+
| | | 6.1.1 | | 11 | SSH_AGENTC_REQUEST_IDENTITIES | RFC 9987, |
+-----------+------------------------------------------+-----------+ | | | Sections |
| 11 | SSH_AGENTC_REQUEST_IDENTITIES | thisrfc, | | | | 5.5 and 8.1 |
| | | Sections | +---------+------------------------------------------+-------------+
| | | 3.5 and | | 12 | SSH_AGENT_IDENTITIES_ANSWER | RFC 9987, |
| | | 6.1 | | | | Sections |
+-----------+------------------------------------------+-----------+ | | | 5.5 and 8.1 |
| 12 | SSH_AGENT_IDENTITIES_ANSWER | thisrfc, | +---------+------------------------------------------+-------------+
| | | Sections | | 13 | SSH_AGENTC_SIGN_REQUEST | RFC 9987, |
| | | 3.5 and | | | | Sections |
| | | 6.1 | | | | 5.6 and 8.1 |
+-----------+------------------------------------------+-----------+ +---------+------------------------------------------+-------------+
| 13 | SSH_AGENTC_SIGN_REQUEST | thisrfc, | | 14 | SSH_AGENT_SIGN_RESPONSE | RFC 9987, |
| | | Sections | | | | Sections |
| | | 3.6 and | | | | 5.6 and 8.1 |
| | | 6.1 | +---------+------------------------------------------+-------------+
+-----------+------------------------------------------+-----------+ | 15 | Reserved | RFC 9987, |
| 14 | SSH_AGENT_SIGN_RESPONSE | thisrfc, | | | | Section |
| | | Sections | | | | 8.1.1 |
| | | 3.6 and | +---------+------------------------------------------+-------------+
| | | 6.1 | | 16 | Reserved | RFC 9987, |
+-----------+------------------------------------------+-----------+ | | | Section |
| 15 | reserved | thisrfc, | | | | 8.1.1 |
| | | Section | +---------+------------------------------------------+-------------+
| | | 6.1.1 | | 17 | SSH_AGENTC_ADD_IDENTITY | RFC 9987, |
+-----------+------------------------------------------+-----------+ | | | Sections |
| 16 | reserved | thisrfc, | | | | 5.2 and 8.1 |
| | | Section | +---------+------------------------------------------+-------------+
| | | 6.1.1 | | 18 | SSH_AGENTC_REMOVE_IDENTITY | RFC 9987, |
+-----------+------------------------------------------+-----------+ | | | Sections |
| 17 | SSH_AGENTC_ADD_IDENTITY | thisrfc, | | | | 5.4 and 8.1 |
| | | Sections | +---------+------------------------------------------+-------------+
| | | 3.2 and | | 19 | SSH_AGENTC_REMOVE_ALL_IDENTITIES | RFC 9987, |
| | | 6.1 | | | | Sections |
+-----------+------------------------------------------+-----------+ | | | 5.4 and 8.1 |
| 18 | SSH_AGENTC_REMOVE_IDENTITY | thisrfc, | +---------+------------------------------------------+-------------+
| | | Sections | | 20 | SSH_AGENTC_ADD_SMARTCARD_KEY | RFC 9987, |
| | | 3.4 and | | | | Sections |
| | | 6.1 | | | | 5.2.6 and |
+-----------+------------------------------------------+-----------+ | | | 8.1 |
| 19 | SSH_AGENTC_REMOVE_ALL_IDENTITIES | thisrfc, | +---------+------------------------------------------+-------------+
| | | Sections | | 21 | SSH_AGENTC_REMOVE_SMARTCARD_KEY | RFC 9987, |
| | | 3.4 and | | | | Sections |
| | | 6.1 | | | | 5.4 and 8.1 |
+-----------+------------------------------------------+-----------+ +---------+------------------------------------------+-------------+
| 20 | SSH_AGENTC_ADD_SMARTCARD_KEY | thisrfc, | | 22 | SSH_AGENTC_LOCK | RFC 9987, |
| | | Sections | | | | Sections |
| | | 3.2.6 and | | | | 5.7 and 8.1 |
| | | 6.1 | +---------+------------------------------------------+-------------+
+-----------+------------------------------------------+-----------+ | 23 | SSH_AGENTC_UNLOCK | RFC 9987, |
| 21 | SSH_AGENTC_REMOVE_SMARTCARD_KEY | thisrfc, | | | | Sections |
| | | Sections | | | | 5.7 and 8.1 |
| | | 3.4 and | +---------+------------------------------------------+-------------+
| | | 6.1 | | 24 | Reserved | RFC 9987, |
+-----------+------------------------------------------+-----------+ | | | Section |
| 22 | SSH_AGENTC_LOCK | thisrfc, | | | | 8.1.1 |
| | | Sections | +---------+------------------------------------------+-------------+
| | | 3.7 and | | 25 | SSH_AGENTC_ADD_ID_CONSTRAINED | RFC 9987, |
| | | 6.1 | | | | Sections |
+-----------+------------------------------------------+-----------+ | | | 5.2 and 8.1 |
| 23 | SSH_AGENTC_UNLOCK | thisrfc, | +---------+------------------------------------------+-------------+
| | | Sections | | 26 | SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED | RFC 9987, |
| | | 3.7 and | | | | Sections |
| | | 6.1 | | | | 5.2.6 and |
+-----------+------------------------------------------+-----------+ | | | 8.1 |
| 24 | reserved | thisrfc, | +---------+------------------------------------------+-------------+
| | | Section | | 27 | SSH_AGENTC_EXTENSION | RFC 9987, |
| | | 6.1.1 | | | | Sections |
+-----------+------------------------------------------+-----------+ | | | 5.8 and 8.1 |
| 25 | SSH_AGENTC_ADD_ID_CONSTRAINED | thisrfc, | +---------+------------------------------------------+-------------+
| | | Sections | | 28 | SSH_AGENT_EXTENSION_FAILURE | RFC 9987, |
| | | 3.2 and | | | | Sections |
| | | 6.1 | | | | 5.8 and 8.1 |
+-----------+------------------------------------------+-----------+ +---------+------------------------------------------+-------------+
| 26 | SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED | thisrfc, | | 29 | SSH_AGENT_EXTENSION_RESPONSE | RFC 9987, |
| | | Sections | | | | Sections |
| | | 3.2.6 and | | | | 5.8 and 8.1 |
| | | 6.1 | +---------+------------------------------------------+-------------+
+-----------+------------------------------------------+-----------+ | 240-255 | Private Use | RFC 9987, |
| 27 | SSH_AGENTC_EXTENSION | thisrfc, | | | | Section 8.1 |
| | | Sections | +---------+------------------------------------------+-------------+
| | | 3.8 and |
| | | 6.1 |
+-----------+------------------------------------------+-----------+
| 28 | SSH_AGENT_EXTENSION_FAILURE | thisrfc, |
| | | Sections |
| | | 3.8 and |
| | | 6.1 |
+-----------+------------------------------------------+-----------+
| 29 | SSH_AGENT_EXTENSION_RESPONSE | thisrfc, |
| | | Sections |
| | | 3.8 and |
| | | 6.1 |
+-----------+------------------------------------------+-----------+
| 240-255 | Private Use | thisrfc, |
| | | Section |
| | | 6.1 |
+-----------+------------------------------------------+-----------+
Table 1 Table 1
7.3. New registry: SSH agent key constraint numbers 9.3. "SSH Agent Key Constraint Numbers" Registry
This registry, titled "SSH agent key constraint numbers" records the The "SSH Agent Key Constraint Numbers" registry records the message
message numbers for key use constraints. It should be created in the numbers for key use constraints. It is located in the "Secure Shell
Secure Shell (SSH) Protocol Parameters registry group [IANA-SSH]. (SSH) Protocol Parameters" registry group [IANA-SSH]. Its initial
Its initial state should consist of the following numbers. Future state is as follows. Future key constraint number allocations shall
key constraint number allocations shall occur via Expert Review as occur via Expert Review as per [RFC8126].
per [RFC8126].
+========+===============================+======================+ +========+===============================+=======================+
| Number | Identifier | Reference | | Number | Identifier | Reference |
+========+===============================+======================+ +========+===============================+=======================+
| 0 | reserved | thisrfc, Section 6.2 | | 0 | Reserved | RFC 9987, Section 8.2 |
+--------+-------------------------------+----------------------+ +--------+-------------------------------+-----------------------+
| 1 | SSH_AGENT_CONSTRAIN_LIFETIME | thisrfc, Section 6.2 | | 1 | SSH_AGENT_CONSTRAIN_LIFETIME | RFC 9987, Section 8.2 |
+--------+-------------------------------+----------------------+ +--------+-------------------------------+-----------------------+
| 2 | SSH_AGENT_CONSTRAIN_CONFIRM | thisrfc, Section 6.2 | | 2 | SSH_AGENT_CONSTRAIN_CONFIRM | RFC 9987, Section 8.2 |
+--------+-------------------------------+----------------------+ +--------+-------------------------------+-----------------------+
| 255 | SSH_AGENT_CONSTRAIN_EXTENSION | thisrfc, Section 6.2 | | 255 | SSH_AGENT_CONSTRAIN_EXTENSION | RFC 9987, Section 8.2 |
+--------+-------------------------------+----------------------+ +--------+-------------------------------+-----------------------+
Table 2 Table 2
7.4. New registry: SSH agent key constraint extension names 9.4. "SSH Agent Key Constraint Extension Names" Registry
This registry, titled "SSH agent key constraint extension names" The "SSH Agent Key Constraint Extension Names" registry records the
records the names used in the SSH_AGENT_CONSTRAIN_EXTENSION names used in the SSH_AGENT_CONSTRAIN_EXTENSION constraint extension
constraint extension type (Section 3.2.7.3). It should be created in type (Section 5.2.7.3). It is located in the "Secure Shell (SSH)
the Secure Shell (SSH) Protocol Parameters registry group [IANA-SSH]. Protocol Parameters" registry group [IANA-SSH]. Its initial state is
Its initial state should be empty. Future key constraint extension empty. Future key constraint extension name allocations shall occur
name allocations shall occur via Expert Review as per [RFC8126]. via Expert Review as per [RFC8126].
7.5. New registry: SSH agent signature flags 9.5. "SSH Agent Signature Flags" Registry
This registry, titled "SSH agent signature flags" records the values The "SSH Agent Signature Flags" registry records the values for
for signature request (SSH_AGENTC_SIGN_REQUEST) flag values. It signature request (SSH_AGENTC_SIGN_REQUEST) flag values. It is
should be created in the Secure Shell (SSH) Protocol Parameters located in the "Secure Shell (SSH) Protocol Parameters" registry
registry group [IANA-SSH]. Its initial state should consist of the group [IANA-SSH]. Its initial state consists of the following
following numbers. Note that as the flags are combined by bitwise numbers. Note that as the flags are combined by bitwise OR, all flag
OR, all flag values must be powers of two and the maximum available values must be powers of two and the maximum available flag value is
flag value is 0x80000000. 0x80000000.
Future signature flag allocations shall occur via Expert Review as Future signature flag allocations shall occur via Expert Review as
per [RFC8126]. per [RFC8126].
+========+========================+======================+ +========+========================+=======================+
| Number | Identifier | Reference | | Number | Identifier | Reference |
+========+========================+======================+ +========+========================+=======================+
| 0x01 | reserved | thisrfc, Section 6.3 | | 0x01 | Reserved | RFC 9987, Section 8.3 |
+--------+------------------------+----------------------+ +--------+------------------------+-----------------------+
| 0x02 | SSH_AGENT_RSA_SHA2_256 | thisrfc, Section 6.3 | | 0x02 | SSH_AGENT_RSA_SHA2_256 | RFC 9987, Section 8.3 |
+--------+------------------------+----------------------+ +--------+------------------------+-----------------------+
| 0x04 | SSH_AGENT_RSA_SHA2_512 | thisrfc, Section 6.3 | | 0x04 | SSH_AGENT_RSA_SHA2_512 | RFC 9987, Section 8.3 |
+--------+------------------------+----------------------+ +--------+------------------------+-----------------------+
Table 3 Table 3
7.6. New registry: SSH agent extension request names 9.6. "SSH Agent Extension Request Names" Registry
This registry, titled "SSH agent extension request names" records the The "SSH Agent Extension Request Names" registry records the names
names used in the generic extension request message used in the generic extension request message (SSH_AGENTC_EXTENSION).
(SSH_AGENTC_EXTENSION). It should be created in the Secure Shell It is located in the "Secure Shell (SSH) Protocol Parameters"
(SSH) Protocol Parameters registry group [IANA-SSH]. Its initial registry group [IANA-SSH]. Its initial state consists of the
state should consist of the following names. following names.
Future name allocations shall occur via Expert Review as per Future name allocations shall occur via Expert Review as per
[RFC8126]. [RFC8126].
+================+========================+ +================+=========================+
| Extension Name | Reference | | Extension Name | Reference |
+================+========================+ +================+=========================+
| query | thisrfc, Section 3.8.1 | | query | RFC 9987, Section 5.8.1 |
+----------------+------------------------+ +----------------+-------------------------+
Table 4 Table 4
7.7. Additions to SSH Extension Names 9.7. Additions to the "Extension Names" Registry
IANA is requested to insert the following entries into the table IANA has added the following entries to the "Extension Names"
Extension Names [IANA-SSH-EXT] in the Secure Shell (SSH) Protocol registry [IANA-SSH-EXT] in the "Secure Shell (SSH) Protocol
Parameters registry group [IANA-SSH]. Parameters" registry group [IANA-SSH].
+================+======================+ +================+=======================+
| Extension Name | Reference | | Extension Name | Reference |
+================+======================+ +================+=======================+
| agent-forward | thisrfc, Section 5.1 | | agent-forward | RFC 9987, Section 7.1 |
+----------------+----------------------+ +----------------+-----------------------+
Table 5 Table 5
7.8. Additions to SSH Connection Protocol Channel Request Names 9.8. Additions to the "Connection Protocol Channel Request Names"
Registry
IANA is requested to insert the following entries into the table IANA has added the following entries to the "Connection Protocol
Connection Protocol Channel Request Names [IANA-SSH-CHANREQ] in the Channel Request Names" registry [IANA-SSH-CHANREQ] in the "Secure
Secure Shell (SSH) Protocol Parameters registry group [IANA-SSH]. Shell (SSH) Protocol Parameters" registry group [IANA-SSH].
+==============+======================+ +==============+=======================+
| Request Type | Reference | | Request Type | Reference |
+==============+======================+ +==============+=======================+
| agent-req | thisrfc, Section 5.2 | | agent-req | RFC 9987, Section 7.2 |
+--------------+----------------------+ +--------------+-----------------------+
Table 6 Table 6
7.9. Additions to SSH Connection Protocol Channel Types 9.9. Additions to the "Connection Protocol Channel Types" Registry
IANA is requested to insert the following entries into the table IANA has added the following entries to the "Connection Protocol
Connection Protocol Channel Types [IANA-SSH-CHANTYPE] under Secure Channel Types" registry [IANA-SSH-CHANTYPE] under the "Secure Shell
Shell (SSH) Protocol Parameters [IANA-SSH]. (SSH) Protocol Parameters" registry group [IANA-SSH].
+===============+======================+ +===============+=======================+
| Request Type | Reference | | Channel Type | Reference |
+===============+======================+ +===============+=======================+
| agent-connect | thisrfc, Section 5.3 | | agent-connect | RFC 9987, Section 7.3 |
+---------------+----------------------+ +---------------+-----------------------+
Table 7 Table 7
8. Security Considerations 10. Security Considerations
The agent is a service that is tasked with retaining and providing The agent is a service that is tasked with retaining and providing
controlled access to what are typically long-lived login controlled access to what are typically long-lived login
authentication credentials. It is by nature a sensitive and trusted authentication credentials. It is, by nature, a sensitive and
software component. Moreover, the agent protocol itself does not trusted software component. Moreover, the agent protocol itself does
include any authentication or transport security; ability to not include any authentication or transport security; ability to
communicate with an agent is usually sufficient to invoke it to communicate with an agent is usually sufficient to invoke it to
perform private key operations. perform private key operations.
Since being able to access an agent is usually sufficient to perform Since being able to access an agent is usually sufficient to perform
private key operations, it is critically important that the agent private key operations, it is critically important that the agent
only be exposed to its owner and their authorised delegates. On only be exposed to its owner and their authorised delegates. On
Unix-like systems this may be achieved via filesystem permissions on Unix-like systems, this may be achieved via filesystem permissions on
the agent socket and/or identity checks on the client connected to a the agent socket and/or identity checks on the client connected to a
socket (e.g. SO_PEERCRED on some Unix-like systems). On Windows, socket (e.g., SO_PEERCRED on some Unix-like systems). On Windows,
access to a named pipe may be controlled by attaching a security access to a named pipe may be controlled by attaching a security
descriptor at the time of its creation. descriptor at the time of its creation.
The primary design intention of an agent is that an attacker with The primary design intention of an agent is that an attacker with
unprivileged access to their victim's agent should be prevented from 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 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 not preclude the attacker from stealing use of those keys (e.g., if
they have been loaded without a confirmation constraint). they have been loaded without a confirmation constraint).
Given this, the agent should, as far as possible, prevent its memory Given this, the agent should, as far as possible, prevent its memory
being read by other processes to prevent theft of loaded keys. This from being read by other processes to prevent theft of loaded keys.
typically includes disabling debugging interfaces and preventing Typically, this includes disabling debugging interfaces and
process memory dumps on abnormal termination. preventing process memory dumps on abnormal termination.
Another, more subtle, means by which keys may be stolen are via Another, more subtle, means by which keys may be stolen is via
cryptographic side-channels. Private key operations may leak cryptographic side-channels. Private key operations may leak
information about the contents of keys via differences in timing, information about the contents of keys via differences in timing,
power use or by side effects in the memory subsystems (e.g. CPU 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 caches) of the host running the agent. For the case of a local
attacker and an agent holding unconstrained keys, the only limit on attacker and an agent holding unconstrained keys, the only limit on
the number of private key operations the attacker may be able to the number of private key operations the attacker may be able to
observe is the rate at which the CPU can perform signatures. This observe is the rate at which the CPU can perform signatures. This
grants the attacker an almost ideal oracle for side-channel attacks. grants the attacker an almost ideal oracle for side-channel attacks.
While a full treatment of side-channel attacks is beyond the scope of While a full treatment of side-channel attacks is beyond the scope of
this specification, agents SHOULD use cryptographic implementations this specification, agents SHOULD use cryptographic implementations
that are resistant to side-channel attacks and MAY take additional that are resistant to side-channel attacks and MAY take additional
measures to hide the actual time spent processing private key measures to hide the actual time spent processing private key
operations. Failure to do so may expose keys to recovery through operations. Failure to do so may expose keys to recovery through
these side-channels. these side-channels.
Forwarding access to a local agent over an SSH connection (Section 5) Forwarding access to a local agent over an SSH connection (Section 7)
inherently creates a transitive trust relationship. SSH inherently creates a transitive trust relationship. SSH
implementations SHOULD NOT forward use of an agent by default and implementations SHOULD NOT forward use of an agent by default, and
users SHOULD NOT forward use of an agent to hosts that are not fully users SHOULD NOT forward use of an agent to hosts that are not fully
trusted, as doing so could expose access to the user's keys to trusted, as doing so could expose access to the user's keys to
attackers on remote hosts. Agents SHOULD implement additional attackers on remote hosts. Agents SHOULD implement additional
controls over key visibility and use for forwarded agent connections, controls over key visibility and use for forwarded agent connections;
otherwise the user has only an all-or-nothing choice over whether to otherwise, the user has only an all-or-nothing choice about whether
forward an agent. to forward an agent.
Implementation of token/smartcard-hosted keys requires some care too. Implementation of token/smartcard-hosted keys requires some care,
On some systems, tokens may invoked by providing a path to shared too. On some systems, tokens may be invoked by providing a path to a
library that must be loaded to make use of keys hosted on the device shared library that must be loaded to make use of keys hosted on the
(a path to a library for a particular PKCS#11 module, for example). device (a path to a library for a particular PKCS#11 module, for
Loading a shared library on most platforms implies automatic example). Loading a shared library on most platforms implies
execution of code in that library in the address space of the process automatic execution of code in that library in the address space of
that loads it. To avoid loading of potentially-hostile code, agents the process that loads it. To avoid the loading of potentially
that support loading token-hosted keys via library path SHOULD ensure hostile code, agents that support loading token-hosted keys via a
that only trusted token provider libraries are loadable. library path SHOULD ensure that only trusted token provider libraries
Additionally agents SHOULD ensure that loaded token library code are loadable. Additionally, agents SHOULD ensure that loaded token
cannot gain access to other keys loaded in the agent and MAY disallow library code cannot gain access to other keys loaded in the agent and
remote clients from loading token keys entirely. Protection for MAY disallow remote clients from loading token keys entirely.
existing keys from tokey library code may be achieved by loading the Protection for existing keys from a token library code may be
token library into a separate process to the agent and arranging for achieved by loading the token library into a separate process to the
the agent to invoke token operations to this process via IPC. agent and arranging for the agent to invoke token operations to this
process via IPC.
Finally, with respect to the agent locking functionality in Finally, with respect to the agent locking functionality in
Section 3.7, an agent SHOULD take countermeasures against brute-force Section 5.7, an agent SHOULD take countermeasures against brute-force
guessing attacks against the pass-phrase. This may take the form of guessing attacks on the passphrase. This may take the form of
enforced delays when an unlock attempt is made with an incorrect enforced delays when an unlock attempt is made with an incorrect
password (potentially increasing for subsequent failures), a lockout password (potentially increasing for subsequent failures), a lockout
period where the agent refuses to accept further requests after some period where the agent refuses to accept further requests after some
threshold of failed unlock attempts has been made and/or deletion of threshold of failed unlock attempts has been made, and/or deletion of
all keys held by the agent after a threshold of failed unlock all keys held by the agent after a threshold of failed unlock
attempts. attempts.
9. Implementation Status 11. References
This section is to be removed before publishing as an RFC.
Note to editor: please also remove the orphaned reference to RFC7942.
This section records the status of known implementations of the
protocol defined by this specification at the time of posting of this
Internet-Draft, and is based on a proposal described in [RFC7942].
The description of implementations in this section is intended to
assist the IETF in its decision processes in progressing drafts to
RFCs. Please note that the listing of any individual implementation
here does not imply endorsement by the IETF. Furthermore, no effort
has been spent to verify the information presented here that was
supplied by IETF contributors. This is not intended as, and must not
be construed to be, a catalog of available implementations or their
features. Readers are advised to note that other implementations may
exist.
According to [RFC7942], "this will allow reviewers and working groups
to assign due consideration to documents that have the benefit of
running code, which may serve as evidence of valuable experimentation
and feedback that have made the implemented protocols more mature.
It is up to the individual working groups to use this information as
they see fit".
The following projects maintain an implementation of this protocol:
OpenSSH OpenSSH is the originating implementation of this protocol
and has supported it since 2000.
Website: https://www.openssh.com/
PuTTY PuTTY is a popular SSH client implementation for multiple
platforms that has included a compatible agent client since 2001.
Website: https://www.chiark.greenend.org.uk/~sgtatham/putty/
Dropbear Dropbear is an SSH client and server implementation for
Unix-like systems. It has supported the agent protocol since
2005.
Website: https://matt.ucc.asn.au/dropbear/dropbear.html
Paramiko Paramiko is an SSH client and server implementation in the
Python programming language. It has supported an agent protocol
implementation since 2005.
Website: https://www.paramiko.org/
Golang x/crypto/ssh/agent The Go programming language project has
supported an implementation of this protocol in its external "x"
repository since 2015.
Website: https://pkg.go.dev/golang.org/x/crypto/ssh/agent
This list is not exhaustive.
10. References
10.1. Normative References 11.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC4251] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) [RFC4251] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
Protocol Architecture", RFC 4251, DOI 10.17487/RFC4251, Protocol Architecture", RFC 4251, DOI 10.17487/RFC4251,
January 2006, <https://www.rfc-editor.org/info/rfc4251>. January 2006, <https://www.rfc-editor.org/info/rfc4251>.
skipping to change at page 29, line 34 skipping to change at line 1244
the Secure Shell (SSH) Protocol", RFC 8332, the Secure Shell (SSH) Protocol", RFC 8332,
DOI 10.17487/RFC8332, March 2018, DOI 10.17487/RFC8332, March 2018,
<https://www.rfc-editor.org/info/rfc8332>. <https://www.rfc-editor.org/info/rfc8332>.
[RFC8709] Harris, B. and L. Velvindron, "Ed25519 and Ed448 Public [RFC8709] Harris, B. and L. Velvindron, "Ed25519 and Ed448 Public
Key Algorithms for the Secure Shell (SSH) Protocol", Key Algorithms for the Secure Shell (SSH) Protocol",
RFC 8709, DOI 10.17487/RFC8709, February 2020, RFC 8709, DOI 10.17487/RFC8709, February 2020,
<https://www.rfc-editor.org/info/rfc8709>. <https://www.rfc-editor.org/info/rfc8709>.
[FIPS.186-4] [FIPS.186-4]
National Institute of Standards and Technology, "Digital NIST, "Digital Signature Standard (DSS)", NIST FIPS 186-4,
Signature Standard (DSS)", FIPS PUB 186-4, DOI 10.6028/NIST.FIPS.186-4, June 2013,
DOI 10.6028/NIST.FIPS.186-4, July 2013,
<https://doi.org/10.6028/NIST.FIPS.186-4>. <https://doi.org/10.6028/NIST.FIPS.186-4>.
[FIPS.186-5] [FIPS.186-5]
National Institute of Standards and Technology, "Digital NIST, "Digital Signature Standard (DSS)", NIST FIPS 186-5,
Signature Standard (DSS)", FIPS PUB 186-5,
DOI 10.6028/NIST.FIPS.186-5, February 2023, DOI 10.6028/NIST.FIPS.186-5, February 2023,
<https://doi.org/10.6028/NIST.FIPS.186-5>. <https://doi.org/10.6028/NIST.FIPS.186-5>.
10.2. Informative References 11.2. Informative References
[RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252,
January 2006, <https://www.rfc-editor.org/info/rfc4252>. January 2006, <https://www.rfc-editor.org/info/rfc4252>.
[RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running
Code: The Implementation Status Section", BCP 205,
RFC 7942, DOI 10.17487/RFC7942, July 2016,
<https://www.rfc-editor.org/info/rfc7942>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
[IANA-SSH-CHANREQ] [IANA-SSH-CHANREQ]
IANA, "Connection Protocol Channel Types", IANA, "Connection Protocol Channel Types",
<https://www.iana.org/assignments/ssh-parameters/>. <https://www.iana.org/assignments/ssh-parameters/>.
[IANA-SSH] IANA, "Secure Shell (SSH) Protocol Parameters", [IANA-SSH] IANA, "Secure Shell (SSH) Protocol Parameters",
<https://www.iana.org/assignments/ssh-parameters/ssh- <https://www.iana.org/assignments/ssh-parameters/>.
parameters.xhtml>.
[IANA-SSH-CHANTYPE] [IANA-SSH-CHANTYPE]
IANA, "Extension Names", IANA, "Extension Names",
<https://www.iana.org/assignments/ssh-parameters/>. <https://www.iana.org/assignments/ssh-parameters/>.
[IANA-SSH-EXT] [IANA-SSH-EXT]
IANA, "Connection Protocol Channel Request Names", IANA, "Connection Protocol Channel Request Names",
<https://www.iana.org/assignments/ssh-parameters/>. <https://www.iana.org/assignments/ssh-parameters/>.
[IANA-PUBKEYS] [IANA-PUBKEYS]
IANA, "Public Key Algorithm Names", IANA, "Public Key Algorithm Names",
<https://www.iana.org/assignments/ssh-parameters/>. <https://www.iana.org/assignments/ssh-parameters/>.
[draft-ietf-secsh-agent-02]
Ylonen, T., Rinne, T. J., and S. Lehtinen, "Secure Shell
Authentication Agent Protocol", January 2004,
<https://datatracker.ietf.org/doc/html/draft-ietf-secsh-
agent-02>.
Acknowledgments Acknowledgments
This protocol was designed and first implemented by Markus Friedl, This protocol was designed and first implemented by Markus Friedl,
based on a similar protocol for an agent to support the legacy SSH based on a similar protocol for an agent to support the legacy SSH
version 1 by Tatu Ylonen. version 1 by Tatu Ylonen.
Thanks to Simon Tatham, Niels Möller, James Spencer, Simon Josefsson, Thanks to Simon Tatham, Niels Möller, James Spencer, Simon Josefsson,
Matt Johnston, Jakub Jelen, Rich Salz, Caspar Schutijser, Florian Matt Johnston, Jakub Jelen, Rich Salz, Caspar Schutijser, Florian
Obser, Martin Thomson, Deb Cooley and Tero Kivinen who reviewed and Obser, Martin Thomson, Deb Cooley, and Tero Kivinen who reviewed and
helped improve this document. helped improve this document.
Author's Address Author's Address
Damien Miller Damien Miller
OpenSSH OpenSSH
Email: djm@openssh.com Email: djm@openssh.com
URI: https://www.openssh.com/ URI: https://www.openssh.com/
 End of changes. 180 change blocks. 
665 lines changed or deleted 552 lines changed or added

This html diff was produced by rfcdiff 1.48.