RFC 9987 Secure Shell (SSH) Agent Protocol

Опубликовано 07.05.2026 автором Nikolai Malykh 
Internet Engineering Task Force (IETF)                         D. Miller
Request for Comments: 9987                                       OpenSSH
Category: Standards Track                                       May 2026
ISSN: 2070-1721

Secure Shell (SSH) Agent Protocol

Протокол агента SSH

PDF

Аннотация

В этом документе определён протокол агента ключей для использования с протоколом Secure Shell (SSH).

Статус документа

Документ содержит проект стандарта Internet (Standards Track).

Документ является результатом работы IETF1 и представляет согласованный взгляд сообщества IETF. Документ прошёл открытое обсуждение и был одобрен для публикации IESG2. Дополнительную информацию о стандартах Internet можно найти в разделе 2 в RFC 7841.

Информацию о текущем статусе документа, ошибках и способах обратной связи можно найти по ссылке https://www.rfc-editor.org/info/rfc9987.

Авторские права

Copyright (c) 2026. Авторские права принадлежат IETF Trust и лицам, указанным в качестве авторов документа. Все права защищены.

К этому документу применимы права и ограничения, перечисленные в BCP 78 и IETF Trust Legal Provisions и относящиеся к документам IETF (http://trustee.ietf.org/license-info), на момент публикации данного документа. Прочтите упомянутые документы внимательно. Фрагменты программного кода, включённые в этот документ, распространяются в соответствии с пересмотренной лицензией BSD, как указано в параграфе 4.e документа IETF Trust Legal Provisions, без каких-либо гарантий (как указано в Revised BSD License).

1. Введение

Протокол Secure Shell (SSH) [RFC4251] предназначен для защищённых соединений [RFC4253] и входа в систему (login) [RFC4254] через незащищённые сети. Он поддерживает множество механизмов проверки подлинности [RFC4252], включая аутентификацию с открытым ключом. Этот документ задаёт протокол взаимодействия с компонентом управления ключами (обычно называемым агентом), который хранит секретные ключи. Клиенты SSH (возможно, и серверы) могут обращаться к агенту по этому протоколу для выполнения операций с использованием открытого ключа и секретного ключа, хранящегося у агента.

Сохранение ключей в агенте обеспечивает удобство и безопасность их загрузки и извлечения при использовании, поскольку при каждом извлечении ключа может требоваться ввод пароля. Доступ к агенту может перенаправляться через соединение SSH, что позволяет удаленным системам использовать сохранённые ключи без прямого раскрытия ключевого материала удалённой системе. Агент можно реализовать как выделенный компонент, который менее подвержен атакам, нежели ключ, загруженный на полный сервер SSH, или клиент, и которому может быть обеспечена специальная защита со стороны более широкой системы.

2. Уровни требований

Ключевые слова должно (MUST), недопустимо (MUST NOT), требуется (REQUIRED), нужно (SHALL), не следует (SHALL NOT), следует (SHOULD), не нужно (SHOULD NOT), рекомендуется (RECOMMENDED), не рекомендуется (NOT RECOMMENDED), возможно (MAY), необязательно (OPTIONAL) в данном документе интерпретируются в соответствии с BCP 14 [RFC2119] [RFC8174] тогда и только тогда, когда они выделены шрифтом, как показано здесь.

3. Обзор протокола

Протокол агента основан на пакетах запросов и откликов, которыми единолично управляет клиент. Протокол включает ряд запросов клиента к агенту и набор откликов, передаваемых в ответ. Агент передаёт сообщения лишь в ответ на запросы клиентов, соблюдая порядок отправки.

Запросы включают возможность загрузки ключей в агент, удаления всех или некоторых ключей и выполнение операций подписи с использованием загруженных ранее ключей.

Агент может поддерживать лишь подмножество доступных типов ключей, а также может отклонять (отвергать) некоторые операции в определённом контексте. Например, агент может разрешать добавление ключей только локальным клиентам или предоставлять данному клиенту лишь определённый набор ключей. Поэтому клиенту следует быть готовым к аккуратному отказу, если какая-либо операция будет отклонена.

4. Термины и обозначения

Далее в документе термин «агент» применяется для обозначения компонента управления ключами, реализующего отвечающую сторону протокола, а термин «клиент» — запрашивающую сторону, которая взаимодействует с агентом протокола. Если рассматриваемый клиент является клиентом Secure Shell [RFC4251], он называется явно «клиентом SSH, а термин «сервер SSH» обозначает сервер Secure Shell.

Кодируемые типы данных (byte, uint32, string и т. д.) описаны в разделе 5 [RFC4251]. Тип byte[] без указания размера внутри квадратных скобок указывает последовательность байтов (возможно, пустую), размер которой определяется контекстом. Все размеры указываются в байтах, если явно не указано иное.

5. Сообщения протокола

Сообщение включает элементы (поля) length, type и contents.

       uint32            length
       byte              type
       byte[length - 1]  contents

В последующих параграфах элемент length не указывается. Для наглядности приводятся символьные имена типов сообщений, а номера (численные значения) указаны в параграфе 8.1.

5.1. Базовые отклики агента

Агент может передавать в ответ на запрос клиента показанные ниже базовые сообщения. В случае успеха агент должен ответить однобайтовым сообщением

       byte              SSH_AGENT_SUCCESS

или зависящим от запроса сообщением об успехе, которое может включать дополнительные поля.

В случае отказа агент должен отвечать однобайтовым сообщением

       byte              SSH_AGENT_FAILURE

или зависящим от запроса сообщением об отказе, которое может включать дополнительные поля. Сообщения SSH_AGENT_FAILURE должны также передаваться в ответ на непонятные или неподдерживаемые типы запросов.

5.2. Добавление ключей в агент

Ключи могут добавляться в агент с помощью сообщений SSH_AGENTC_ADD_IDENTITY или SSH_AGENTC_ADD_ID_CONSTRAINED. Базовый формат SSH_AGENTC_ADD_IDENTITY имеет вид

       byte             SSH_AGENTC_ADD_IDENTITY
       string           key type
       byte[]           key data
       string           comment

Поле key type указывает тип ключа, например, ssh-rsa для ключей RSA, определённых в [RFC4253]. Поле key data содержит открытую и секретную часть ключа и зависит от типа ключа, как описано в параграфах 5.2.1 — 5.2.4 для наиболее распространённых ключей. Поле comment содержит понятное человеку имя ключа или комментарий в форме строки символов UTF-8 и может служить для идентификации ключа в видимых пользователю сообщениях. Эта строка может быть пустой. Сообщение SSH_AGENTC_ADD_ID_CONSTRAINED имеет похожий формат с одним добавочным полем

       byte             SSH_AGENTC_ADD_ID_CONSTRAINED
       string           key type
       byte[]           key data
       string           comment
       constraint[]     constraints

Поле constraints служит для задания ограничений пригодности или использования ключа. Типы и формат ограничений описаны в параграфе 5.2.7. Клиентам следует применять сообщение SSH_AGENTC_ADD_IDENTITY, вместо SSH_AGENTC_ADD_ID_CONSTRAINED с пустым полем constraints, хотя пригодны (и эквивалентны) оба варианта.

Агент должен отвечать сообщением SSH_AGENT_SUCCESS, если ключ был успешно загружен в результате одного или нескольких таких сообщений. В иных случаях передаётся сообщение SSH_AGENT_FAILURE.

При добавлении ключа, уже имеющегося в агенте, новый ключ и ограничения (при наличии) следует помещать взамен имеющихся, поскольку это обеспечит наилучшее соответствие связанных с безопасностью ограничений ожиданиям пользователя. В иных случаях агент может отклонить загрузку уже имеющегося у него ключа.

Агент может поддерживать лишь часть заданных здесь типов ключей и может поддерживать дополнительные типы, как описано ниже. Если агент не распознаёт тип указанного в запросе на добавление ключа, он должен ответить сообщением SSH_AGENT_FAILURE.

5.2.1. Ключи DSA

Ключи DSA (Digital Signature Algorithm), указываемые как ssh-dss, определены в [RFC4253]. Эти ключи могут добавляться с использованием показанного ниже сообщения. Поле constraints присутствует только в сообщениях SSH_AGENTC_ADD_ID_CONSTRAINED.

       byte             SSH_AGENTC_ADD_IDENTITY или
                        SSH_AGENTC_ADD_ID_CONSTRAINED
       string           ssh-dss
       mpint            p
       mpint            q
       mpint            g
       mpint            y
       mpint            x
       string           comment
       constraint[]     constraints

Значения p, q, g являются параметрами домена DSA, y и x указывают открытый и секретный ключ, соответственно. Значения определены в параграфе 4.1 [FIPS.186-4].

5.2.2. Ключи ECDSA

Ключи ECDSA (Elliptic Curve Digital Signature Algorithm) имеют тип ecdsa-sha2- и определены в [RFC5656]. Эти ключи могут добавляться с использованием указанного ниже сообщения. Поле constraints присутствует только в сообщениях SSH_AGENTC_ADD_ID_CONSTRAINED.

       byte             SSH_AGENTC_ADD_IDENTITY или
                        SSH_AGENTC_ADD_ID_CONSTRAINED
       string           key type
       string           ecdsa_curve_name
       string           Q
       mpint            d
       string           comment
       constraint[]     constraints

Q и d указывают открытую и секретную часть, соответственно. Значения определены в параграфе 6.2 [FIPS.186-5].

5.2.3. Ключи EdDSA

В [RFC8709] определены ключи EdDSA (Edwards-curve Digital Signature Algorithm) (см. [RFC8032]) Ed25519 и Ed448 с именами ssh-ed25519 и ssh-ed448, соответственно. Эти ключи могут добавляться с использованием указанного ниже сообщения. Поле constraints присутствует только в сообщениях SSH_AGENTC_ADD_ID_CONSTRAINED.

       byte             SSH_AGENTC_ADD_IDENTITY или
                        SSH_AGENTC_ADD_ID_CONSTRAINED
       string           ssh-ed25519 или ssh-ed448
       string           ENC(A)
       string           k || ENC(A)
       string           comment
       constraint[]     constraints

Первое значение является открытым ключом EdDSA — ENC(A), а второе — конкатенацией секретного ключа k и открытого ключа ENC(A) (повтор открытого ключа служит для совместимости с широко распространёнными реализациями). Содержимое и интерпретация значений ENC(A) и k определены в параграфе 3.2 [RFC8032].

5.2.4. Ключи RSA

Ключи RSA, именуемые как ssh-rsa, определены в [RFC4253]. Эти ключи могут добавляться с использованием указанного ниже сообщения. Поле constraints присутствует лишь в сообщениях SSH_AGENTC_ADD_ID_CONSTRAINED.

       byte             SSH_AGENTC_ADD_IDENTITY или
                        SSH_AGENTC_ADD_ID_CONSTRAINED
       string           "ssh-rsa"
       mpint            n
       mpint            e
       mpint            d
       mpint            iqmp
       mpint            p
       mpint            q
       string           comment
       constraint[]     constraints

Поле n указывает открытый композитный модуль, e — секретный, а d — открытый показатель степени. Поля p и q — секретные простые сомножители, значение iqmp — обратно q по модулю p. Все значения, кроме iqmp (которое может быть рассчитано по другим значениям), определены в параграфе 5.1 [FIPS.186-5].

5.2.5. Другие ключи

Агенты и их клиенты могут поддерживать не указанные в этом документе типы ключей. Фирменные типы ключей должны использовать связанное с доменом именование, как указано в разделе 6 [RFC4251], пока коды не будут выделены IANA [IANA-PUBKEYS].

5.2.6. Добавление ключей из токенов

Ключи, хранящиеся на смарт-картах и других носителях (token), могут добавляться с помощью запросов SSH_AGENTC_ADD_SMARTCARD_KEY и SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED. Поле constraints включается лишь в вариант SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED.

       byte             SSH_AGENTC_ADD_SMARTCARD_KEY или
                        SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED
       string           token id
       string           PIN
       constraint[]     constraints

Поле token id содержит неанализируемый (opaque) идентификатор носителя, а PIN — необязательный пароль или код PIN для разблокировки ключа. Протокол не задаёт интерпретацию token id, полностью отдавая её агенту.

Как правило, в агент загружаются лишь открытые компоненты ключей, поддерживаемых носителем, и, строго говоря, эти сообщения предназначены для будущих операций с секретным ключом, делегируемых данному носителю.

Агент должен отвечать сообщением SSH_AGENT_SUCCESS, если хотя бы 1 ключ был успешно загружен в результате одного или нескольких таких сообщений. Если ключей не найдено, поле token id не распознано, запрос не соответствует правилам агента или агент не поддерживает ключи на аппаратных носителях, агент должен возвращать сообщение SSH_AGENT_FAILURE.

5.2.7. Ограничения ключей

В запросах добавления ключа с ограничениями может передаваться множество типов ограничений, каждое из которых сопровождается байтом типа, за которым могут следовать байты данных ограничения. Ограничения могут включаться в любые сообщения *_CONSTRAINED, как показано ниже.

       byte             constraint1_type
       byte[]           constraint1_data
       byte             constraint2_type
       byte[]           constraint2_data
       ....
       byte             constraintN_type
       byte[]           constraintN_data

Для полного разбора ограничений нужно заранее знать их структуру, а восстановление нераспознанного ограничения может оказаться небезопасным. Поэтому агент, не распознавший или не поддерживающий указанное в запросе ограничение, должен прервать разбор, отклонить запрос и возвратить клиенту сообщение SSH_AGENT_FAILURE.

В последующих параграфах описываются ограничения, определённые к настоящему моменту.

5.2.7.1. Ограничение срока действия ключей

По таким запросам агент ограничивает срок действия ключей, удаляя их по истечении заданного числа секунд с момента добавления ключа в агент.

       byte             SSH_AGENT_CONSTRAIN_LIFETIME
       uint32           seconds
5.2.7.2. Требование подтверждения ключа

По таким запросам агент будет требовать явного подтверждения пользователя для каждой операции с использованием секретного ключа. Например, агент может представлять диалог подтверждения перед завершением операции подписи.

       byte             SSH_AGENT_CONSTRAIN_CONFIRM
5.2.7.3. Расширения для ограничений

Агенты могут реализовать экспериментальные или приватные ограничения с помощью расширений, поддерживающих именованные ограничения.

       byte             SSH_AGENT_CONSTRAIN_EXTENSION
       string           extension name
       byte[]           extension-specific details

Поле extension name должно содержать строку UTF-8. В фирменных расширениях должен применяться суффикс домена реализации (например, foo@example.com), определяемый схемой именования из раздела 6 в [RFC4251].

Отметим, что с учётом приведённого выше требования отклонять ключи с неподдерживаемыми ограничениями, расширения для ограничений применимы лишь в случае их поддержки как клиентом, так и агентом. В противном случае агент должен будет отклонить ключ. Это желательно, поскольку расширения для ограничений могут задавать пределы, игнорирование которых может создавать ситуации, когда ключ будет доступен там, где это не предусмотрено (например, при безопасном завершении агента в случае отказа).

5.3. Кодирование открытых ключей

Загруженные в агент ключи указываются блобами открытых ключей, которые представляют собой стандартное кодирование открытых ключей SSH для передачи в линию, заданное в [RFC4253] для ключей ssh-rsa и ssh-dss, в [RFC5656] — для ecdsa-sha2-* и в [RFC8709] — для ssh-ed25519и ssh-ed448.

5.4. Удаление ключей из агента

Клиент может запросить у агента удаление всех хранящихся в нем ключей с помощью сообщения

       byte             SSH_AGENTC_REMOVE_ALL_IDENTITIES

При получении такого запроса агенту следует удалить все сохранённые ключи и возвратить сообщение SSH_AGENT_SUCCESS. В случае отклонения запроса он должен передать сообщение SSH_AGENT_FAILURE. Такие запросы следует выполнять независимо от правил агента, ограничивающих действия для данного клиента, поскольку в ином случае пользователь не сможет быстро и полностью удалить свои ключи в экстренной ситуации.

Конкретный ключ можно удалить с помощью сообщения

       byte             SSH_AGENTC_REMOVE_IDENTITY
       string           key blob

где key blob — стандартное кодирование удаляемого ключа (параграф 5.3). Агент должен возвращать отклик SSH_AGENT_SUCCESS при удалении ключа и SSH_AGENT_FAILURE, если ключ не найден.

Хранящиеся в носителях ключи можно удалить с помощью сообщения

       byte             SSH_AGENTC_REMOVE_SMARTCARD_KEY
       string           token id
       string           PIN

Поле token id — это неанализируемый (opaque) идентификатор носителя ключа, а PIN — необязательный пароль или PIN (обычно не применяется) в кодировке UTF-8. По запросу на удаление хранящегося в носителе ключа агенту следует удалять все ключи, загруженные с устройства, соответствующего token id. По запросу SSH_AGENTC_REMOVE_ALL_IDENTITIES агентам следует быстро и полностью удалять все ключи независимо от локальной политики. Удаление хранящегося на носителе ключа происходит только в агенте, а хранящийся на носителе ключ удалять не следует.

Агент должен отвечать сообщением SSH_AGENT_SUCCESS после удаления ключа и SSH_AGENT_FAILURE, если ключ не найден.

5.5. Запрос списка ключей

Клиент может запросить у агента список ключей с помощью сообщения

       byte             SSH_AGENTC_REQUEST_IDENTITIES

Агент должен отвечать сообщением

       byte             SSH_AGENT_IDENTITIES_ANSWER
       uint32           nkeys

где nkeys указывает число ключей, за которым могут следовать предоставляемые клиенту ключи в формате

       string           key blob
       string           comment

Поле key blob содержит стандартное кодирование открытого ключа (параграф 5.3), comment — понятную человеку строку комментария в кодировке UTF-8.

5.6. Операции с секретным ключом

Клиент может запросить у агента операцию подписи с секретным ключом, используя сообщение

       byte             SSH_AGENTC_SIGN_REQUEST
       string           key blob
       string           data
       uint32           flags

Поле key blob указывает запрошенный для подписи ключ (кодирование в соответствии с параграфом 5.3), data — данные для подписания, а flags — битовое поле с побитовым объединением (OR) флагов подписи (см. ниже). Если агент не поддерживает запрошенные флаги или по иной причине не может создать подпись (например, заданного ключа нет или пользователь не подтвердил ключ с ограничением), он должен ответить сообщением SSH_AGENT_FAILURE. При успешном подписании агент должен передать сообщение

       byte             SSH_AGENT_SIGN_RESPONSE
       string           signature

Формат подписи (signature) зависит от алгоритма используемого ключа. Форматы подписей протокола SSH заданы в [RFC4253] для ключей ssh-rsa и ssh-dss, в [RFC5656] — для ecdsa-sha2-* и в [RFC8709] — для ssh-ed25519и ssh-ed448.

5.6.1. Флаги подписи

В настоящее время для запросов подписи заданы флаги SSH_AGENT_RSA_SHA2_256 и SSH_AGENT_RSA_SHA2_512 (см. параграф 8.3). Оба эти флага пригодны лишь для ключей ssh-rsa и запрашивают у агента подпись с использованием метода rsa-sha2-256 или rsa-sha2-512, соответственно. Схемы подписи заданы в [RFC8332].

5.7. Установка и снятие блокировки агента

Протокол агента поддерживает возможность временной блокировки агентом самого себя с помощью пароля. Заблокированный агент должен приостановить выполнение конфиденциальных операций (по меньшей мере, операций подписи с секретным ключом) до момента снятия блокировки с тем же паролем. Для блокировки служит сообщение

       byte             SSH_AGENTC_LOCK
       string           passphrase

Агент должен возвращать сообщение SSH_AGENT_SUCCESS после установки блокирования и SSH_AGENT_FAILURE в иных случаях (например, когда агент уже заблокирован).

Для снятия блокировки служит сообщение

       byte             SSH_AGENTC_UNLOCK
       string           passphrase

Если агент заблокирован и пароль совпадает с заданным при блокировке, агент должен снять блокировку и ответить сообщением SSH_AGENT_SUCCESS. Если агент не заблокирован или пароль не совпадает, агент должен ответить сообщением SSH_AGENT_FAILURE.

5.8. Механизм расширения

Протокол агента включает необязательный механизм расширения, позволяющий передавать через протокол фирменные и экспериментальные сообщения. Запрос расширения имеет вид

       byte             SSH_AGENTC_EXTENSION
       string           extension type
       byte[]           зависящее от запроса содержимое

Поле extension type указывает тип сообщения с расширением в форме строки UTF-8. Зависящие от реализации расширения должны иметь суффикс, соответствующий схеме из раздела 6 [RFC4251] (например, foo@example.com).

Агент, не поддерживающий предложенный тип расширения, должен отвечать сообщением SSH_AGENT_FAILURE. Такое же сообщение передаёт агент, не поддерживающий механизм расширения.

Содержимое отклика об успешном расширении зависит от extension type. В случае успеха агент должен возвращать SSH_AGENT_SUCCESS или зависящее от расширения сообщение вида

       byte             SSH_AGENT_EXTENSION_RESPONSE
       string           extension type
       byte[]           зависящее от отклика содержимое

где поле extension type совпадает с полученным в запросе.

Отказы при расширении следует передавать в сообщении SSH_AGENT_EXTENSION_FAILURE

       byte             SSH_AGENT_EXTENSION_FAILURE

Расширениям не следует применять стандартное сообщение SSH_AGENT_FAILURE. Это позволит отличать запросы с отказом от неподдерживаемых расширений.

5.8.1. Расширение Query

Необязательный запрос query определён для того, чтобы узнать набор поддерживаемых агентом расширений.

       byte             SSH_AGENTC_EXTENSION
       string           "query"

Если агент поддерживает расширение query, ему следует отвечать списком имён поддерживаемых расширений.

       byte             SSH_AGENT_EXTENSION_RESPONSE
       string           "query"
       string[]         поддерживаемые типы расширений

6. Соединение с агентом

Агенты раскрываются локальным системам через ориентированные на соединения конечные точки. В системах класса Unix агент обычно прослушивает связанный с файловой системой сокет домена Unix, в Microsoft Windows обычно используется Windows Named Pipe. Доступ к конечным точкам следует контролировать в соответствии с разделом 10. Через такие сокеты к одному агенту может подключаться множество клиентов. В обоих случаях имя или адрес прослушивающей конечной точки обычно раскрывается через переменную окружения SSH_AUTH_SOCK, которую клиенты используют для поиска и подключения к прослушивающему агенту. Как вариант, агенты могут использовать неявные механизмы обнаружения их конечной точки, например, заданное по умолчанию расположение для каждого пользователя.

7. Перенаправление доступа к агенту

С помощью протокола соединений, описанного в [RFC4254], можно пересылать протокол агента через соединение SSH. Это позволяет запрашивать перенаправление к агенту для любого канала сессии с использованием модели, похожей на перенаправление X11 Forwarding (параграф 6.3 в [RFC4254]). Это свойство является необязательным для реализаций протокола SSH и клиентов.

7.1. Анонсирование поддержки перенаправления

Сервер SSH может анонсировать перенаправление к агенту с помощью расширения, описанного в [RFC8308], используя имя agent-forward в сообщении SSH_MSG_EXT_INFO.

       string           "agent-forward"
       string           "0" (version)

Отметим, что этот протокол появился существенно раньше механизма расширения, описанного в [RFC8308]. Также следует отметить, что несколько широко распространённых реализаций SSH с поддержкой перенаправления к агенту не анонсируют эту поддержку. Клиенты SSH могут пытаться в отсутствие анонсов (см. [RFC8308]) запрашивать перенаправление с помощью фирменных имён, указанных ниже. Серверы SSH могут реализовать фирменные имена в дополнение к описанным здесь.

7.2. Запрос перенаправления

Клиент SSH может запросить перенаправление к агенту для ранее созданной сессии (см. параграф 6.1 в [RFC4254]), используя показанный ниже запрос, который передаётся после создания канала, но до вызова оболочки, команды или подсистемы.

       byte             SSH_MSG_CHANNEL_REQUEST
       uint32           channel_id
       string           "agent-req" или "auth-agent-req@openssh.com"
       boolean          want_reply

Поле channel_id содержит идентификатор канала созданной сессии (возвращённый из предыдущего запроса SSH_MSG_CHANNEL_OPEN), а флаг want_reply указывает, следует ли серверу SSH подтверждать успешность запроса (как указано в параграфе 5.4 [RFC4254]). Если сервер SSH воспринимает запрос, он обычно предоставляет конечную точку (например, прослушивающий сокет) и анонсирует это в подчинённую сессию. Большинство реализаций в Unix-подобных системах деляют это, предоставляя приватный пользовательский прослушивающий сокет домена Unix и записывая его местоположение в переменную среды SSH_AUTH_SOCK.

Многие развёрнутые реализации поддерживают лишь предстандартное имя запроса auth-agent-req@openssh.com. Имя agent-req следует применять лишь при явном анонсировании поддержки, как указано в параграфе 7.1.

7.3. Запрос соединения с агентом

После запроса клиентом SSH включения в сессии перенаправления к агенту сервер SSH может запросить соединение с этим агентом для связи с агентом клиента SSH по выделенному каналу путём отправки приведённого ниже сообщения.

       byte             SSH_MSG_CHANNEL_OPEN
       string           "agent-connect" или "auth-agent@openssh.com"
       uint32           channel_id
       uint32           local_window
       uint32           local_maxpacket

Поля channel_id, local_window и local_maxpacket следует интерпретировать в соответствии с параграфом 5.1 [RFC4254]. Тип agent-connect следует применять лишь при явном анонсировании поддержки, как указано в параграфе 7.1.

Клиенту SSH следует быть готовым к обработке одновременно нескольких соединений, пересылаемых к агенту клиентской стороны, иначе запросы на доступ к агенту с удалённой стороны, перекрывающие прежние запросы, могут столкнуться с отказом. Перекрытие запросов может возникать из-за того, что протокол соединения SSH [RFC4254] допускает множество пользовательских сессий через один транспорт (см. [RFC4253]) и каждая сессия может запрашивать использование агента (возможно, одновременно).

Клиент SSH может воспринимать запросы соединения с агентом (по результату проверки полномочий) без предварительного запроса на перенаправление к агенту для случаев, когда желательно перенаправление без организации сессии. Клиент SSH может продолжать восприятие запросов соединения с агентом после завершения сессии, для которой было запрошено перенаправление. Клиент SSH должен отвергать несанкционированные запросы на соединение с агентом, когда перенаправление к агенту не запрашивалось и нежелательно для клиента, но сервер SSH всё равно передаёт запрос на соединение с агентом.

Поскольку запрос agent-connect не включает идентификатора, позволяющего отличать канал сессии, передавший запрос на соединение, SSH-соединение фактически может перенаправлять доступ лишь к одному клиентскому агенту SSH с использованием этого протокола (хотя агент допускает множество одновременных соединений).

8. Протокольные номера

8.1. Типы сообщений

В таблице 1 приведены номера, используемые для типов сообщений в запросах от клиента к агенту.

Таблица 1.

 

SSH_AGENTC_REQUEST_IDENTITIES

11

SSH_AGENTC_SIGN_REQUEST

13

SSH_AGENTC_ADD_IDENTITY

17

SSH_AGENTC_REMOVE_IDENTITY

18

SSH_AGENTC_REMOVE_ALL_IDENTITIES

19

SSH_AGENTC_ADD_SMARTCARD_KEY

20

SSH_AGENTC_REMOVE_SMARTCARD_KEY

21

SSH_AGENTC_LOCK

22

SSH_AGENTC_UNLOCK

23

SSH_AGENTC_ADD_ID_CONSTRAINED

25

SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED

26

SSH_AGENTC_EXTENSION

27

 

В таблице 2 приведены номера, используемые для типов сообщений в откликах клиенту со стороны агента.

Таблица 2.

 

SSH_AGENT_FAILURE

5

SSH_AGENT_SUCCESS

6

SSH_AGENT_IDENTITIES_ANSWER

12

SSH_AGENT_SIGN_RESPONSE

14

SSH_AGENT_EXTENSION_FAILURE

28

SSH_AGENT_EXTENSION_RESPONSE

29

 

8.1.1. Резервные номера сообщений

Для реализаций с поддержкой устаревшей версии протокола SSH v1 зарезервированы номера сообщений 1-4, 7-10, 15-16, 24. Эти номера могут применяться реализациями с поддержкой устаревшей версии протокола, но в иных случаях их использование недопустимо.

Сообщение с номером 0 также является резервным и применять его недопустимо.

Сообщения с номерами 240-255 зарезервированы для приватного использования (Private Use) в расширениях протокола агента и их недопустимо применять в реализациях общего назначения (см. [RFC8126]).

8.2. Идентификаторы с ограничениями

В таблице 3 указаны номера для ограничений. Они применяются лишь в ограничениях для ключей и не передаются как номера сообщений. Ограничение с номером 0 является резервным.

Таблица 3.

 

SSH_AGENT_CONSTRAIN_LIFETIME

1

SSH_AGENT_CONSTRAIN_CONFIRM

2

SSH_AGENT_CONSTRAIN_EXTENSION

255

 

8.3. Флаги подписи

В таблице 4 указаны номера, которые могут присутствовать в запросах подписи (SSH_AGENTC_SIGN_REQUEST). Эти флаги формируют битовое поле (возможно, пустое) с помощью операции OR (или). Значение флага 1 зарезервировано для старых (historical) реализаций.

Таблица 4.

 

SSH_AGENT_RSA_SHA2_256

0x00000002

SSH_AGENT_RSA_SHA2_512

0x00000004

 

9. Взаимодействие с IANA

Для этого протокола создаётся 5 реестров: номера типов сообщений, номера ограничений, флаги запросов подписи, имена расширений для ограничений и имена запросов на расширение. Кроме того, добавляются значения в три существующих реестра.

9.1. Рекомендации назначенным экспертам

Когда назначенного эксперта (Designated Expert или DE) просят прорецензировать добавления в новые реестры, описанные здесь (параграфы 9.2, 9.3, 9.5, 9.6), это означает запрос на проверку наличия и общедоступности соответствующих документов, как описано в [RFC8126]. DE также предлагается проверить ясность назначения и использования запрошенных кодов. DE также следует убедиться, что созданные в IETF спецификации, которые запрашивают коды в этих реестрах, доступны для ознакомления рабочей группе SSHM (почтовая конференция ssh@ietf.org). Запросы для кодов из спецификаций, выполненных вне IETF, не должны конфликтовать с активными работами IETF или прежними спецификациями IETF.

Доступное число кодов в реестрах номеров протокола агента SSH (параграф 9.2), номеров ограничений (параграф 9.3) и флагов подписи агента SSH (параграф 9.5) ограничено, поэтому DE должен убедиться, что использование кодов должным образом обосновано. Для номеров сообщений протокола агента SSH именованные запросы на расширения (параграф 9.6) предоставляют для большинства применений практически неограниченное число доступных кодов. Для номеров ограничений для ключей механизм расширения ограничений (параграф 5.2.7.3) также обеспечивает неограниченное число вариантов.

9.2. Реестр SSH Agent Protocol Message Type Numbers

Реестр SSH Agent Protocol Message Type Numbers содержит номера типов сообщений для запросов клиента и откликов агента. Реестр размещается в разделе Secure Shell (SSH) Protocol Parameters [IANA-SSH]. Исходное содержимое реестра привадено в таблице 5, а выделение значений нужно выполнять по процедуре Expert Review [RFC8126].

Таблица 5.

 

Номер

Идентификатор

Документ

0

Резерв

Параграф 8.1.1 в RFC 9987

1

Резерв

Параграф 8.1.1 в RFC 9987

2

Резерв

Параграф 8.1.1 в RFC 9987

3

Резерв

Параграф 8.1.1 в RFC 9987

4

Резерв

Параграф 8.1.1 в RFC 9987

5

SSH_AGENT_FAILURE

Параграфы 5.1 и 8.1 в RFC 9987

6

SSH_AGENT_SUCCESS

Параграфы 5.1 и 8.1 в RFC 9987

7

Резерв

Параграф 8.1.1 в RFC 9987

8

Резерв

Параграф 8.1.1 в RFC 9987

9

Резерв

Параграф 8.1.1 в RFC 9987

10

Резерв

Параграф 8.1.1 в RFC 9987

11

SSH_AGENTC_REQUEST_IDENTITIES

Параграфы 5.5 и 8.1 в RFC 9987

12

SSH_AGENT_IDENTITIES_ANSWER

Параграфы 5.5 и 8.1 в RFC 9987

13

SSH_AGENTC_SIGN_REQUEST

Параграфы 5.6 и 8.1 в RFC 9987

14

SSH_AGENT_SIGN_RESPONSE

Параграфы 5.6 и 8.1 в RFC 9987

15

Резерв

Параграф 8.1.1 в RFC 9987

16

Резерв

Параграф 8.1.1 в RFC 9987

17

SSH_AGENTC_ADD_IDENTITY

Параграфы 5.2 и 8.1 в RFC 9987

18

SSH_AGENTC_REMOVE_IDENTITY

Параграфы 5.4 и 8.1 в RFC 9987

19

SSH_AGENTC_REMOVE_ALL_IDENTITIES

Параграфы 5.4 и 8.1 в RFC 9987

20

SSH_AGENTC_ADD_SMARTCARD_KEY

Параграфы 5.2.6 и 8.1 в RFC 9987

21

SSH_AGENTC_REMOVE_SMARTCARD_KEY

Параграфы 5.4 и 8.1 в RFC 9987

22

SSH_AGENTC_LOCK

Параграфы 5.7 и 8.1 в RFC 9987

23

SSH_AGENTC_UNLOCK

Параграфы 5.7 и 8.1 в RFC 9987

24

Резерв

Параграф 8.1.1 в RFC 9987

25

SSH_AGENTC_ADD_ID_CONSTRAINED

Параграфы 5.2 и 8.1 в RFC 9987

26

SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED

Параграфы 5.2.6 и 8.1 в RFC 9987

27

SSH_AGENTC_EXTENSION

Параграфы 5.8 и 8.1 в RFC 9987

28

SSH_AGENT_EXTENSION_FAILURE

Параграфы 5.8 и 8.1 в RFC 9987

29

SSH_AGENT_EXTENSION_RESPONSE

Параграфы 5.8 и 8.1 в RFC 9987

240-255

Приватное использование

Параграф 8.1.1 в RFC 9987

 

9.3. Реестр SSH Agent Key Constraint Numbers

Реестр SSH Agent Key Constraint Numbers содержит номера ограничений на использование ключей и размещается в разделе Secure Shell (SSH) Protocol Parameters [IANA-SSH]. Исходное содержимое реестра приведено в таблице 6, а выделение значений нужно выполнять по процедуре Expert Review [RFC8126].

Таблица 6.

 

Номер

Идентификатор

Документ

0

Резерв

Параграф 8.2 в RFC 9987

1

SSH_AGENT_CONSTRAIN_LIFETIME

Параграф 8.2 в RFC 9987

2

SSH_AGENT_CONSTRAIN_CONFIRM

Параграф 8.2 в RFC 9987

255

SSH_AGENT_CONSTRAIN_EXTENSION

Параграф 8.2 в RFC 9987

 

9.4. Реестр SSH Agent Key Constraint Extension Names

Реестр SSH Agent Key Constraint Extension Names содержит имена, применяемые в типе расширения ограничений SSH_AGENT_CONSTRAIN_EXTENSION (параграф 5.2.7.3), и размещается в разделе Secure Shell (SSH) Protocol Parameters [IANA-SSH]. Исходно реестр пуст, а выделение значений нужно выполнять по процедуре Expert Review [RFC8126].

9.5. Реестр SSH Agent Signature Flags

Реестр SSH Agent Signature Flags содержит значения флагов запроса подписи (SSH_AGENTC_SIGN_REQUEST) и размещается в разделе Secure Shell (SSH) Protocol Parameters [IANA-SSH]. Исходное содержимое реестра приведено в таблице 7. Отметим, что флаги объединяются побитово операцией OR, все значения флагов должны быть степенями 2, а максимальное значение флага составляет 0x80000000. Новые флаги подписей нужно выделять по процедуре Expert Review [RFC8126].

Таблица 7.

 

Номер

Идентификатор

Документ

0x01

Резерв

Параграф 8.3 в RFC 9987

0x02

SSH_AGENT_RSA_SHA2_256

Параграф 8.3 в RFC 9987

0x04

SSH_AGENT_RSA_SHA2_512

Параграф 8.3 в RFC 9987

 

9.6. Реестр SSH Agent Extension Request Names

Реестр SSH Agent Extension Request Names содержит имена, используемые в базовых сообщениях запроса расширений (SSH_AGENTC_EXTENSION), и размещается в разделе Secure Shell (SSH) Protocol Parameters [IANA-SSH]. Исходное содержимое реестра приведено в таблице 8. Новые имена нужно выделять по процедуре Expert Review [RFC8126].

Таблица 8.

 

Имя расширения

Документ

query

Параграф 5.8.1 в RFC 9987

 

9.7. Дополнение в реестр Extension Names

Агентство IANA добавило в реестр Extension Names [IANA-SSH-EXT] раздела Secure Shell (SSH) Protocol Parameters [IANA-SSH] значение, приведённое в таблице 9.

Таблица 9.

 

Имя расширения

Документ

agent-forward

Параграф 7.1 в RFC 9987

 

9.8. Дополнение в реестр Connection Protocol Channel Request Names

Агентство IANA добавило в реестр Connection Protocol Channel Request Names [IANA-SSH-CHANREQ] раздела Secure Shell (SSH) Protocol Parameters [IANA-SSH] значение, приведённое в таблице 10.

Таблица 10.

 

Тип запроса

Документ

agent-req

Параграф 7.2 в RFC 9987

 

9.9. Дополнение в реестр Connection Protocol Channel Types

Агентство IANA добавило в реестр Connection Protocol Channel Types [IANA-SSH-CHANTYPE] раздела Secure Shell (SSH) Protocol Parameters [IANA-SSH] значение, приведённое в таблице 11.

Таблица 11.

 

Тип канала

Документ

agent-connect

Параграф 7.3 в RFC 9987

 

10. Вопросы безопасности

Агент — это служба, задачей которой является хранение и предоставление учётных данных (обычно долгосрочных) для аутентификации при входе в систему. По своей природе агент является конфиденциальным и доверенным компонентом. Сам протокол агента не включает какой-либо проверки подлинности или транспортной защиты. Возможности взаимодействовать с агентом обычно достаточно, чтобы вызвать агент для выполнения операций с секретным ключом. Поэтому очень важно раскрывать агент только владельцу и его полномочным представителям. В Unix-подобных системах это может обеспечиваться на основе прав доступа к файловой системе для сокета агента и/или проверки подлинности клиента, подключаемого к сокету (например, SO_PEERCRED в некоторых Unix-подобных системах). В Windows доступ к именованным каналам может контролироваться через дескриптор защиты, присваиваемый в момент создания канала.

Задачей агентов является предотвращение злоумышленникам с непривилегированным доступом к агенту жертвы возможности скопировать какой-либо из загруженных в агент ключей. Это может не предотвратить возможность злоумышленника захватывать использование этих ключей (например, при загрузке ключей без ограничения на подтверждение). С учётом этого агенту следует, насколько это возможно, препятствовать считыванию своей памяти другими процессами для предотвращения кражи загруженных ключей. Обычно это включает запрет отладочных интерфейсов и обработки дампов памяти, создаваемых при аварийном завершении.

Более изощренным способом кражи ключей является использование побочных криптографических каналов. При операциях с секретными ключами может происходить утечка этих ключей из-за различий во времени, энергопотреблении или побочных эффектов в подсистеме памяти (например, кэш CPU) на хосте, где работает агент. В случае локального злоумышленника и агента, хранящего ключи без ограничений, единственным ограничением числа операций с секретными ключами, которые атакующий может наблюдать, является скорость выполнения подписей процессором (CPU). Это даёт атакующему почти идеальное предсказание для атак по побочным каналам. Хотя полное рассмотрение атак по побочным каналам выходит за рамки этой спецификации, агентам следует использовать криптографические реализации, стойкие к атакам по побочным каналам, и можно принимать дополнительные меры для сокрытия фактического времени выполнения операций с секретными ключами. Неисполнение этих требований может раскрывать ключи через побочные каналы.

Перенаправление доступа к локальному агенту через соединение SSH (раздел 7) по своей сути создаёт транзитивные отношения доверия. Реализациям SSH не следует перенаправлять использование агента по умолчанию, а пользователям не следует перенаправлять использование агента на хост, к которому нет полного доверия, поскольку это может приводить к тому, что злоумышленники на удалённых хостах получат доступ к ключам пользователя. Агентам следует реализовать дополнительные средства контроля за видимостью ключей и их использованием для перенаправленных к агенту соединений, иначе у пользователя будет лишь один вариант для перенаправления к агенту — «всё или ничего».

Реализации ключей в токенах и смарт-картах также требуют осторожности. В некоторых системах к токенам можно обращаться по пути к общей библиотеке (например, библиотеке конкретного модуля PKCS#11), которую нужно загрузить для использования размещенных на устройстве ключей. Загрузка общей библиотеки на большинстве платформ предполагает автоматическое исполнение кода этой библиотеки в адресном пространстве загрузившего её процесса. Для предотвращения загрузки потенциально вредоносного кода агентам с поддержкой ключей из токенов через путь к библиотеке следует убедиться, что загружаться могут лишь библиотеки доверенных поставщиков токенов. Кроме того, агентам следует гарантировать, что загруженный код библиотеки токенов не получит доступа к другим ключам, загруженным в агент, и можно полностью запрещать удаленным клиентам загрузку ключей из токена. Защиту имеющихся ключей от кода библиотеки токенов можно обеспечить путём загрузки этой библиотеки в отдельный процесс для агента и организации вызова агентом операций с токеном для этого процесса через IPC1.

В части функциональности блокировки (параграф 5.7) агенту следует принимать меры против подбора парольной фразы (brute-force). Это можно сделать путём внесения задержки при вводе некорректного пароля (возможно, увеличивающейся после каждой попытки), временной блокировки ввода, когда агент отвергает дальнейшие запросы после некого числа неудачных попыток и/или удаления всей ключей после определённого числа неудачных попыток.

11. Литература

11.1. Нормативные документы

[FIPS.186-4] NIST, «Digital Signature Standard (DSS)», NIST FIPS 186-4, DOI 10.6028/NIST.FIPS.186-4, June 2013, <https://doi.org/10.6028/NIST.FIPS.186-4>.

[FIPS.186-5] NIST, «Digital Signature Standard (DSS)», NIST FIPS 186-5, DOI 10.6028/NIST.FIPS.186-5, February 2023, <https://doi.org/10.6028/NIST.FIPS.186-5>.

[RFC2119] Bradner, S., «Key words for use in RFCs to Indicate Requirement Levels», BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.

[RFC4251] Ylonen, T. and C. Lonvick, Ed., «The Secure Shell (SSH) Protocol Architecture», RFC 4251, DOI 10.17487/RFC4251, January 2006, <https://www.rfc-editor.org/info/rfc4251>.

[RFC4253] Ylonen, T. and C. Lonvick, Ed., «The Secure Shell (SSH) Transport Layer Protocol», RFC 4253, DOI 10.17487/RFC4253, January 2006, <https://www.rfc-editor.org/info/rfc4253>.

[RFC4254] Ylonen, T. and C. Lonvick, Ed., «The Secure Shell (SSH) Connection Protocol», RFC 4254, DOI 10.17487/RFC4254, January 2006, <https://www.rfc-editor.org/info/rfc4254>.

[RFC5656] Stebila, D. and J. Green, «Elliptic Curve Algorithm Integration in the Secure Shell Transport Layer», RFC 5656, DOI 10.17487/RFC5656, December 2009, <https://www.rfc-editor.org/info/rfc5656>.

[RFC8032] Josefsson, S. and I. Liusvaara, «Edwards-Curve Digital Signature Algorithm (EdDSA)», RFC 8032, DOI 10.17487/RFC8032, January 2017, <https://www.rfc-editor.org/info/rfc8032>.

[RFC8174] Leiba, B., «Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words», BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC8308] Bider, D., «Extension Negotiation in the Secure Shell (SSH) Protocol», RFC 8308, DOI 10.17487/RFC8308, March 2018, <https://www.rfc-editor.org/info/rfc8308>.

[RFC8332] Bider, D., «Use of RSA Keys with SHA-256 and SHA-512 in the Secure Shell (SSH) Protocol», RFC 8332, DOI 10.17487/RFC8332, March 2018, <https://www.rfc-editor.org/info/rfc8332>.

[RFC8709] Harris, B. and L. Velvindron, «Ed25519 and Ed448 Public Key Algorithms for the Secure Shell (SSH) Protocol», RFC 8709, DOI 10.17487/RFC8709, February 2020, <https://www.rfc-editor.org/info/rfc8709>.

11.2. Дополнительная литература

[IANA-PUBKEYS] IANA, «Public Key Algorithm Names», <https://www.iana.org/assignments/ssh-parameters/>.

[IANA-SSH] IANA, «Secure Shell (SSH) Protocol Parameters», <https://www.iana.org/assignments/ssh-parameters/>.

[IANA-SSH-CHANREQ] IANA, «Connection Protocol Channel Types», <https://www.iana.org/assignments/ssh-parameters/>.

[IANA-SSH-CHANTYPE] IANA, «Extension Names», <https://www.iana.org/assignments/ssh-parameters/>.

[IANA-SSH-EXT] IANA, «Connection Protocol Channel Request Names», <https://www.iana.org/assignments/ssh-parameters/>.

[RFC4252] Ylonen, T. and C. Lonvick, Ed., «The Secure Shell (SSH) Authentication Protocol», RFC 4252, DOI 10.17487/RFC4252, January 2006, <https://www.rfc-editor.org/info/rfc4252>.

[RFC8126] Cotton, M., Leiba, B., and T. Narten, «Guidelines for Writing an IANA Considerations Section in RFCs», BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, <https://www.rfc-editor.org/info/rfc8126>.

Благодарности

Протокол разработал и впервые реализовал Markus Friedl на основе похожего протокола для агента, поддерживающего устаревший протокол SSH версии 1, разработанного Tatu Ylonen.

Спасибо Simon Tatham, Niels Möller, James Spencer, Simon Josefsson, Matt Johnston, Jakub Jelen, Rich Salz, Caspar Schutijser, Florian Obser, Martin Thomson, Deb Cooley, Tero Kivinen за рецензии и помощь в улучшении документа.

Адрес автора

OpenSSH

Email: djm@openssh.com

URI: https://www.openssh.com/

Перевод на русский язык

Николай Малых

nmalykh@protokols.ru

1Inter Process Communications — взаимодействие между процессами. Прим. перев.

Запись опубликована в рубрике RFC. Добавьте в закладки постоянную ссылку.

Добавить комментарий