     [file defs.ru.inc not included]

Вызов GPG-AGENT
***************

gpg-agent.ru.1

ВЫЗОВ

ОПИСАНИЕ
gpg-agent — демон (программа фонового режима) для управления секретными ключами независимо от протокола. Он применяется как служебная программа для gpg и gpgsm, а также пары других утилит.

Программа автоматически запускается по мере необходимости программами gpg, gpgsm, gpgconf или gpg-connect-agent. Таким образом, запускать ее вручную не нужно. Если вы хотите пользоваться агентом SSH в составе этой программы, вы можете запустить ее командой:

     gpg-connect-agent /bye

Если вам нужно вручную остановить работающий агент, это можно безопасно сделать командой:

     gpgconf --kill gpg-agent

У вас в файле инициализации командного интерпретатора (таком, как .bashrc) всегда должны быть команды:

     GPG_TTY=$(tty)
     export GPG_TTY

Важно, чтобы эти переменные среды всегда отражали вывод команды tty. Для систем W32 это не требуется.

Позаботьтесь о том, чтобы подходящая программа ввода пароля была установлена в файле с принятым в данной системе именем, или воспользуйтесь параметром pinentry-program для указания полного имени этой программы. Нередко бывает полезно завести символическую ссылку от настоящей программы ввода пароля (напр., BINDIR/pinentry-gtk) к ожидаемой (напр., BINDIR/pinentry).

Указатель параметров содержит список команд и параметров GPG-AGENT.

КОМАНДЫ

Команды
=======

Команды отличаются от параметров только тем, что в вызове допустима только одна команда (если в описании команды не указано иное).

--version
     Вывести версию программы и лицензионные сведения. Эту команду нельзя сокращать (напр., как --versio).

--help
-h
     Вывести подсказку по наиболее полезным параметрам командной строки. Эту команду нельзя сокращать (напр., как --hel).

--dump-options
     Вывести список всех имеющихся параметров и команд. Эту команду нельзя сокращать (напр., как --dump-option).

--server
     Работать в серверном режиме и ожидать команд из стандартного потока ввода. В исходном режиме создается сокет, из которого принимаются команды.

--daemon [КОМАНДНАЯ СТРОКА]
     Запустить gpg-agent в виде демона, т.е. отвязать его от консоли и выполнять в фоновом режиме.

     В качестве альтернативы можно создавать новый процесс как дочерний процесс gpg-agent: gpg-agent --daemon /bin/sh. Таким образом вы получаете новый командный интерпретатор с настроенной должным образом средой; после выхода из этого командного интерпретатора gpg-agent завершается в пределах нескольких секунд.

--supervised
     Работать на переднем плане, отправляя протокол работы по умолчанию в стандартный поток ошибок и прослушивая заданные файловые дескрипторы, которые должны уже быть привязаны к действующим сокетам. Эта команда полезна при работе из systemd и тому подобных механизмов контроля процессов. Этот параметр не поддерживается под Windows.

     В режиме --supervised можно задавать разные файловые дескрипторы для сокетов разных типов (напр., ssh, extra), когда они идентифицируются переменными среды LISTEN_FDNAMES (подробнее см. sd_listen_fds(3) в некоторых дистрибутивах GNU/Linux).

ПАРАМЕТРЫ

Сводка параметров
=================

--options ФАЙЛ
     Считывать настройки из указанного файла вместо исходного файла настроек пользователя. Исходный файл настроек называется gpg-agent.conf и находится в каталоге .gnupg непосредственно в домашнем каталоге пользователя.

          [file opt-homedir.ru.texi not included]

-v

--verbose
     Выводит во время работы дополнительную информацию. Объем информации можно увеличивать, вводя параметр несколько раз, например, -vv.

-q

--quiet
     Стараться выводить на экран как можно меньше.

--batch
     Не вызывать программу ввода пароля и не делать ничего, что требует вмешательства человека.

--faked-system-time МОМЕНТ
     Этот параметр полезен только для тестирования; он переводит системное время к моменту, заданному аргументом в виде количества секунд с начала 1970 года.

--debug-level УРОВЕНЬ
     Выбрать уровень отладки для расследования проблем. Уровень может задаваться числом или словом:

     none
          Никаких отладочных сообщений. Соответствует значениям, меньшим 1.

     basic
          Некоторые простые отладочные сообщения. Соответствует значениям от 1 до 2.

     advanced
          Более подробные отладочные сообщения. Соответствует значениям от 3 до 5.

     expert
          Еще более подробные сообщения. Соответствует значениям от 6 до 8.

     guru
          Все отладочные сообщения, какие только есть. Соответствует значениям, большим 8.

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

--debug ПРИЗНАКИ
     Этот параметр полезен только для отладки, его действие может измениться в любое время без предупреждения. Признаки кодируются побитово, их можно задавать в обычном синтаксисе Си. В настоящее время определены биты:

     0  (1)
          данные, связанные с протоколами X.509 или OpenPGP

     1  (2)
          значения длинных чисел

     2  (4)
          криптографические операции низкого уровня

     5  (32)
          выделение памяти

     6  (64)
          буферизация

     7  (128)
          показать статистику памяти

     9  (512)
          записывать хeшируемые данные в файлы с именами dbgmd-000*

     10 (1024)
          отслеживать протокол Assuan

     12 (4096)
          пропустить все проверки сертификатов

--debug-all
     То же, что --debug=0xffffffff

--debug-wait N
     При работе в серверном режиме подождать указанное число секунд перед входом в цикл обработки и выводить идентификатор процесса. За это время можно подключить отладчик.

--debug-quick-random
     Этот параметр отменяет сверхвысокий уровень качества случайных чисел (GCRY_VERY_STRONG_RANDOM из Libgcrypt) и снижает его до обычного качества случайных чисел. Используется только для испытаний и никогда не должен применяться при создании ключей, предназначенных для реального пользования. Этот параметр действует только из командной строки.

     Под GNU/Linux есть другой способ быстрого создания некачественных ключей: воспользоваться командой rngd для заполнения резервуара энтропии ядра случайными данными низкого качества. Команда rngd обычно входит в пакет rng-tools. Ее можно вызвать так: sudo rngd -f -r /dev/urandom.

--debug-pinentry
     Этот параметр включает дополнительную отладочную информацию, относящуюся к программе ввода пароля. На настоящий момент полезен только вместе с --debug 1024.

--no-detach
     Не отрывать процесс от терминала. Полезно главным образом для отладки.

-s
--sh
-c
--csh
     Форматировать выходную информацию в режиме демона для применения в стандартном интерпретаторе Борна и Си-образном соответственно. По умолчанию выставляется по переменной среды SHELL, в большинстве случаев правильно.

--no-grab
     Запретить команде ввода пароля перехватывать клавиатуру и мышь. Этот параметр обычно не следует использовать, чтобы предотвратить перекрестное прослушивание.

--log-file ФАЙЛ
     Дописывать весь протокол работы в указанный файл. Это очень полезно, когда нужно понять, что же программа делает. Укажите socket://, если нужно протоколировать в сокет. Если на платформе Windows не задан ни файл, ни файловый дескриптор для протокола работы, используется пункт реестра HKCU\Software\GNU\GnuPG:DefaultLogFile, если он существует.

--no-allow-mark-trusted
     Не позволять программам-клиентам помечать ключи как доверенные, т.е. помещать их в файл trustlist.txt. Это мешает пользователям нечаянно принимать корневые сертификаты удостоверяющих центров.

--allow-preset-passphrase
     Параметр позволяет применять gpg-preset-passphrase для заполнения внутреннего буфера gpg-agent фразами-паролями.

--no-allow-loopback-pinentry

--allow-loopback-pinentry
     Запретить или позволить программам-клиентам пользоваться функциями обратного вызова программы ввода пароля; подробнее see параметр --pinentry-mode. В исходном состоянии позволено.

     Этот параметр управляет также параметром --force команды Assuan DELETE_KEY: параметр --force игнорируется, если обратный вызов запрещен.

--no-allow-external-cache
     Выключить в программе ввода паролей функции, которые задействуют внешний буфер фраз-паролей.

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

--allow-emacs-pinentry
     Позволить программе ввода паролей перенаправлять ввод фразы-пароля в работающий экземпляр Emacs. Как в точности это происходит, зависит от версии программы ввода паролей.

--ignore-cache-for-signing
     Этот параметр позволяет gpg-agent обходить буфер фраз-паролей для всех операций подписи. Обратите внимание, что есть также сеансовый параметр для управления этой особенностью, но параметр командной строки его отменяет.

--default-cache-ttl N
     Установить срок действия буферной записи равным N секундам. Исходное значение — 600 секунд. Секундомер записи обнуляется при каждом доступе к ней. Для задания максимального срока действия записи пользуйтесь --max-cache-ttl.

--default-cache-ttl-ssh N
     Установить срок действия буферной записи для ключей SSH равным N секундам. Исходное значение — 1800 секунд. Секундомер записи обнуляется при каждом доступе к ней. Для задания максимального срока действия записи пользуйтесь --max-cache-ttl-ssh.

--max-cache-ttl N
     Установить максимальный срок действия буферной записи равным N секундам. После этого срок действия буферной записи истекает, даже если к ней недавно обращались или она была заполнена с помощью gpg-preset-passphrase. Исходное значение — 2 часа (7200 секунд).

--max-cache-ttl-ssh N
     Установить максимальный срок действия буферной записи для ключей SSH равным N секундам. После этого срок действия буферной записи истекает, даже если к ней недавно обращались или она была заполнена с помощью gpg-preset-passphrase. Исходное значение — 2 часа (7200 секунд).

--enforce-passphrase-constraints
     Соблюдать ограничения на фразы-пароли, не позволяя пользователю обходить их с помощью кнопки «Все равно принять».

--min-passphrase-len N
     Задать минимальную длину пароля. При вводе новой фразы-пароля, длина которой меньше этого значения, будет выводиться предупреждение. Исходное значение равно 8.

--min-passphrase-nonalpha N
     Установить минимальное число цифр или специальных символов, требуемое для фразы-пароля. При вводе новой фразы-пароля, в которой число таких знаков меньше этого значения, будет выводиться предупреждение. Исходное значение равно 1.

--check-passphrase-pattern ФАЙЛ
     Проверять фразу-пароль по шаблонам, заданным в указанном файле. При вводе новой фразы-пароля, соответствующей одному из этих шаблонов, будет выводиться предупреждение. Аргумент должен быть абсолютным путем до файла. По умолчанию никакой файл шаблонов не используется.

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

--max-passphrase-days N
     Предлагать пользователю сменить фразу-пароль через N дней после последней смены. С параметром --enforce-passphrase-constraints это принуждает пользователя к смене фразы-пароля.

--enable-passphrase-history
     Этот параметр пока никак не действует.

--pinentry-invisible-char ЗНАК
     Этот параметр указывает программе ввода пароля пользоваться заданным знаком для отображения скрытых символов. Это может быть один символ или строка UTF-8. Программа ввода паролей может учитывать, а может не учитывать этот запрос.

--pinentry-timeout N
     Параметр указывает программе ввода пароля предельное время ожидания ввода со стороны пользователя в секундах. Исходное значение равно 0, т.е. программе ввода паролей не передается таких указаний, однако в ней может быть свое исходное значение. Программа ввода паролей может учитывать, а может не учитывать этот запрос.

--pinentry-program ПРОГРАММА
     Использовать указанную программу в качестве программы ввода пароля. Исходное значение определяется во время установки. При исходных настройках исходное имя программы — pinentry; если такой программы не существует, но есть pinentry-basic, то используется последняя.

     На платформе Windows по умолчанию используется первая существующая программа из списка: bin\pinentry.exe, ..\Gpg4win\bin\pinentry.exe, ..\Gpg4win\pinentry.exe, ..\GNU\GnuPG\pinentry.exe, ..\GNU\bin\pinentry.exe, bin\pinentry-basic.exe, где пути до файлов даны относительно каталога, в котором установлен GnuPG.

--pinentry-touch-file ИМЯ ФАЙЛА
     По умолчанию имя файла сокета, из которого gpg-agent принимает запросы, передается в программу ввода пароля, так что она может обновить времена доступа этого файла перед выходом (она делает этот только в режиме curses). Этот параметр задает файл, передаваемый в программу ввода пароля. Специальное имя /dev/null можно применять, чтобы полностью отключить эту особенность. Обратите внимание, что программа ввода пароля не будет создавать этот файл, она только изменит времена изменения и доступа.

--scdaemon-program ПРОГРАММА
     Использовать указанную программу в качестве демона электронных карт. Исходное значение определяется при установке и может быть показано командой gpgconf.

--disable-scdaemon
     Не пользоваться средством scdaemon. Этот параметр отключает возможность операций с электронными картами. Обратите внимание, что задание этого параметра во время выполнения не приводит к завершению уже работающего средства scdaemon.

--disable-check-own-socket
     Программа gpg-agent периодически производит самопроверку для обнаружения кражи сокетов. Обычно это значит, что сокет захватил другой экземпляр gpg-agent; в этом случае gpg-agent самозавершится. Этим параметром можно отключать такую самопроверку в целях отладки.

--use-standard-socket
--no-use-standard-socket
--use-standard-socket-p
     Начиная с GnuPG 2.1, всегда применяются стандартные сокеты. Эти параметры больше не действуют. Таким образом, команда gpg-agent --use-standard-socket-p всегда возвращает код успешного завершения.

--display СТРОКА
--ttyname СТРОКА
--ttytype СТРОКА
--lc-ctype СТРОКА
--lc-messages СТРОКА
--xauthority СТРОКА
     Эти параметры применяются в режиме сервера для передачи сведений о локализации программ.

--keep-tty
--keep-display
     Не учитывать запросы на смену текущего tty и переменной DISPLAY системы X Window соответственно. Это полезно для замыкания программы ввода пароля на терминале или дисплее, в котором вы запустили gpg-agent.

--extra-socket ИМЯ
     По умолчанию создается дополнительный сокет; этим параметром можно пользоваться, чтобы изменить его имя. Чтобы отменить создание сокета, задайте в качестве аргумента ИМЯ «none» или «/dev/null» .

     Принимать дополнительно подключения gpg-agent по заданному сокету. Этот дополнительный сокет предназначен для того, чтобы установить перенаправление сокета домена Unix из удаленной машины на этот сокет локальной машины. Работающий на этой удаленной машине gpg может тогда подключаться к локальному gpg-agent и пользоваться его секретными ключами. Это позволяет расшифровывать или подписывать данные на удаленной машине, не выставляя там секретные ключи.

--enable-extended-key-format
     Параметр включает создание ключей в расширенном формате секретного ключа. Изменение фразы-пароля ключа также преобразует ключа к этому новому формату. Применение этого параметра исключает чтение секретных ключей версиями gpg-agent, более ранними, чем 2.1.12. Преимущество нового формата состоит в том, что он текстовый и может содержать дополнительные метаданные. Обратите внимание, что этот параметр изменяет также формат защиты ключей на OCB.

--enable-ssh-support
--enable-putty-support

     Протокол агента OpenSSH всегда включен, но gpg-agent устанавливает переменную SSH_AUTH_SOCK только тогда, когда задан этот параметр.

     В этом режиме работы программа-агент не только реализует протокол gpg-agent, но также протокол программы-агента, применяемый в OpenSSH (через отдельный сокет). Следовательно, можно пользоваться программой gpg-agent в качестве прямой замены широко известного ssh-agent.

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

     Как только ключ таким образом добавлен в gpg-agent, gpg-agent готов к его использованию.

     Замечание: в случае, если gpg-agent получает запрос на подпись, пользователю может потребоваться ввести фразу-пароль для расшифровки сохраненного ключа. Поскольку протокол ssh-agent лишен механизма оповещения программы-агента о том, в каком терминале он выполняется, поддержка SSH в gpg-agent пользуется терминалом или дисплеем X Window, в котором был запущен gpg-agent. Для переключения на текущий дисплей можно воспользоваться командой:

          gpg-connect-agent updatestartuptty /bye

     Хотя все компоненты GnuPG пытаются по мере необходимости запускать gpg-agent, при поддержке ssh это невозможно, поскольку ssh не знает о gpg-agent. Таким образом, если не запускалось никакое средство GnuPG, которое обращалось бы к gpg-agent, ничто не гарантирует, что ssh сможет воспользоваться gpg-agent для проверки подлинности. Чтобы это исправить, gpg-agent можно запустить следующей простой командой:

          gpg-connect-agent /bye

     Добавив --verbose, можно наблюдать за ходом запуска программы.

     Параметр --enable-putty-support есть только под Windows, он позволяет применять gpg-agent с реализацией SSH под названием putty. Это сходно с обычной поддержкой ssh-agent, но применяется очередь сообщений Windows, как того требует putty.

--ssh-fingerprint-digest

     Выбрать алгоритм хеша для вычисления отпечатков ssh, передаваемых пользователю, например, в диалогах программы ввода пароля. В OpenSSH перешли от MD5 к более безопасному SHA256.

Все длинные параметры можно размещать в файле настроек без начальных символов «--».

ФАЙЛЫ

Настройки
=========

Есть несколько файлов настроек, необходимых для работы программы. По умолчанию все они находятся в текущем домашнем каталоге (see параметр --homedir).

gpg-agent.conf
     Это основной файл настроек, который gpg-agent считывает при запуске. В нем могут быть любые допустимые длинные параметры; символов «--» перед названием параметра быть не должно, сокращать параметры нельзя. Этот файл считывается также после сигнала SIGHUP, однако в этом случае учитывается только несколько параметров. Это исходное имя файла можно изменить в командной строке (see параметр --options). Для этого файла следует проводить резервное копирование.

trustlist.txt
     Это список доверенных ключей. Для этого файла следует проводить резервное копирование.

     Пустые строки и строки с комментарием, на которые указывает знак «#» в начале, игнорируются. Чтобы пометить ключ как доверенный, нужно ввести его отпечаток с последующим пробелом и прописной буквой S. Для разделения байтов отпечатка можно факультативно пользоваться двоеточиями; это позволяет копировать отпечаток напрямую из результатов работы команд перечисления ключей. Если в начале строки приписан «!», ключ явным образом помечается как недоверенный.

     Вот пример, в котором два ключа помечены как неограниченно доверенные, а один — как недоверенный:

          # CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
          A6935DD34EF3087973C706FC311AA2CCF733765B S

            # CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
          DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S

            # CN=Root-CA/O=Schlapphuete/L=Pullach/C=DE
          !14:56:98:D3:FE:9C:CA:5A:31:6E:BC:81:D3:11:4E:00:90:A3:44:C2 S

     Перед вводом ключа в этот файл надо удостовериться в его подлинности. Как это делается, зависит от вашей организации; возможно, ваш администратор уже ввел в этот файл те ключи, которые считаются достаточно достойными доверия. Отпечаток корневого сертификата можно проверять в письмах, полученных из удостоверяющего центра, или на сайте удостоверяющего центра (после того, как вы полностью убедились в том, что это действительно сайт данного центра). Можно подумать о том, чтобы запретить обновление этого файла с участием пользователя (see параметр --no-allow-mark-trusted). Можно было бы даже рекомендовать установить доступ к этому файлу только на чтение, чтобы его нельзя было нечаянно изменить.

     Специальная строка include-default подключает глобальный список доверенных сертификатов (напр., SYSCONFDIR/trustlist.txt). Этот глобальный список применяется также, когда пользовательский список отсутствует.

     После S можно добавлять дополнительные признаки для вызывающего:

     relax
          Снижать некоторые требования при проверке корневых сертификатов. На настоящий момент этот признак позволяет пользоваться корневыми сертификатами, в которых отсутствует атрибут basicConstraints (несмотря на то, что он должен быть в сертификатах удостоверяющих центров), и отключает проверку корневого сертификата по спискам отозванных сертификатов.

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

sshcontrol
     Этот файл используется, когда включена поддержка протокола SSH (see параметр --enable-ssh-support). В протоколе SSH используются только присутствующие в этом файле ключи. Для этого файла следует проводить резервное копирование.

     Для добавления в этот файл новых записей можно применять средство ssh-add; их можно также добавлять вручную. Строки комментария, на которые указывает знак «#» в начале, а также пустые строки игнорируются. Запись начинается с необязательных пробелов с последующим кодом ключа из 40 шестнадцатеричных цифр с последующим необязательным сроком действия буфера в секундах и другим необязательным полем для произвольных признаков. Ненулевой срок действия отменяет глобальное исходное значение, задаваемое с помощью --default-cache-ttl-ssh.

     Поддерживается только один признак, confirm. Если этот признак установлен, при каждом использовании ключа будет вызываться программа ввода пароля для подтверждения. Признак автоматически устанавливается, если новый ключ загружается в gpg-agent с помощью параметра -c команды ssh-add.

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

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

                 # Дата добавления ключа: 2011-07-20 20:38:46
                 # Отпечаток:  5e:8d:c4:ad:e7:af:6e:27:8a:d6:13:e4:79:ad:0b:81
                 34B62F25E277CF13D3C6BCEBFD3F85D08F0A864B 0 confirm

private-keys-v1.d/

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

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

СИГНАЛЫ

Пользование некоторыми сигналами
================================

Работающим экземпляром gpg-agent можно управлять посредством сигналов, посылая их с помощью команды kill.

Вот список поддерживаемых сигналов:

SIGHUP
     Этот сигнал сбрасывает все запомненные фразы-пароли; если программа была запущена с файлом настроек, этот файл считывается заново. Учитываются только определенные параметры: quiet, verbose, debug, debug-all, debug-level, debug-pinentry, no-grab, pinentry-program, pinentry-invisible-char, default-cache-ttl, max-cache-ttl, ignore-cache-for-signing, no-allow-external-cache, allow-emacs-pinentry, no-allow-mark-trusted, disable-scdaemon и disable-check-own-socket. Параметр scdaemon-program также поддерживается, но в текущей реализации, в которой scdaemon вызывается только один раз, пользы от этого мало, если только вы не прервете выполнение scdaemon вручную.

SIGTERM
     Завершает выполнение процесса, но ждет, пока все текущие запросы будут выполнены. Если процесс получил такой сигнал трижды, а запросы все еще не выполнены, то процесс завершается принудительно.

SIGINT
     Завершает выполнение процесса немедленно.

SIGUSR1
     Вывести внутреннюю информацию в файл протокола.

SIGUSR2
     Этот сигнал используется для внутренних нужд.

ПРИМЕРЫ

Примеры
=======

Важно устанавливать в командной оболочке своей учетной записи переменную среды GPG_TTY, например, в файле ~/.bashrc:

       export GPG_TTY=$(tty)

Если вы включили поддержку агента SSH, вам нужно также сообщить об этом ssh, добавив в свой сценарий инициализации:

     unset SSH_AGENT_PID
     if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then
       export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
     fi

Протокол Assuan агента
======================

Обратите внимание: этот раздел документирует только протокол, используемый компонентами GnuPG; он не касается протокола ssh-agent. Полное описание каждой команды можно получить с помощью

       gpg-connect-agent 'help КОМАНДА' /bye

Если указать просто «help», выводится список всех доступных команд.

Демон gpg-agent вызывается по мере необходимости компонентами GnuPG.

Чтобы идентифицировать ключ, мы пользуемся так называемом кодом ключа, представляющим собой SHA-1 от S-выражения открытого ключа в канонической кодировке в том виде, в каком он используется в Libgcrypt. С точки зрения протокола код ключа представляет шестнадцатеричную строку. Преимущество кода ключа перед хeшем сертификата состоит в том, что одну и ту же пару ключей можно применять в различных протоколах, экономя тем самым пространство на электронной карте, где хранятся секретные ключи.

Программа gpg-agent может отправлять сообщения о состоянии во время или после выполнения команд, чтобы информировать программу-клиент о ходе выполнения или результате операции. Например, сообщение INQUIRE_MAXLEN может отправляться во время опроса сервера, чтобы информировать программу-клиент о максимальном объеме запрошенных данных (который не должен превышаться).

Расшифровать сеансовый ключ
---------------------------

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

       SETKEY <код_ключа>

Указать серверу ключ, который должен применяться для расшифровки. Если команда не подана, gpg-agent может попытаться выявить ключ, пытаясь расшифровать сообщение всеми доступными ключами.

       PKDECRYPT

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

         S: INQUIRE CIPHERTEXT
         C: D (xxxxxx
         C: D xxxx)
         C: END

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

          (enc-val
            (<алгоритм>
              (<имя_параметра_1> <длинное_число>)
      	   ...
              (<имя_параметра_n> <длинное_число>)))

Где алгоритм представлен строкой с названием алгоритма; допустимый список алгоритмов см. в документации Libgcrypt. Имена и количество параметров зависят от алгоритма. Ошибка программой-агентом в случае несоответствия выдается.

Если расшифровка прошла успешно, расшифрованные данные выдаются в виде строк на «D».

Вот пример сеанса:

        C: PKDECRYPT
        S: INQUIRE CIPHERTEXT
        C: D (enc-val elg (a 349324324)
        C: D    (b 3F444677CA)))
        C: END
        S: # следует сеансовый ключ
        S: S PADDING 0
        S: D (значение 1234567890ABCDEF0)
        S: OK decryption successful

Строка состояния «PADDING» высылается, только если gpg-agent знает, какого рода заполнение используется. На сегодня применяется только значение 0, чтобы указать, что заполнение удалено.

Подписать хeш
-------------

Программа-клиент запрашивает подпись данного значения хeша. Если ключ не задан, будет использован основной ключ. Чтобы задать ключ, программа-клиент сначала подает команду:

        SIGKEY <код_ключа>

Это можно делать несколько раз, чтобы подписать несколькими ключами; список сбрасывается после следующей команды PKSIGN или RESET. Сервер проверяет, можно ли подписывать что-нибудь этим ключом, и выдает квитанцию об успешной операции.

        SETHASH --hash=<хeш>|<алгоритм> <шестнадцатеричная строка>

Эту команду можно применять, чтобы сообщить серверу, какие данные (<шестнадцатеричная строка>) надо подписать (обычно это хeш). Параметр <алгоритм> представляет номер алгоритма хeша в десятичной системе в нумерации Libgcrypt. Должен быть задан либо алгоритм, либо --hash=<хeш>. Допустимые значения аргумента <хeш>:

sha1
     Алгоритм SHA-1

sha256
     Алгоритм SHA-256

rmd160
     Алгоритм RIPE-MD160

md5
     Старый взломанный алгоритм MD5

tls-md5sha1
     Комбинированный алгоритм, применяемый в протоколе TLS.

Сама подпись производится командой:

        PKSIGN <параметры>

Параметры пока не определены, но впоследствии могут применяться для выбора различных алгоритмов. Затем gpg-agent проводит некоторые проверки, запрашивает фразу-пароль, и в результате сервер возвращает подпись в виде SPKI-подобного S-выражения в строках на «D»:

          (sig-val
            (<алгоритм>
              (<имя_параметра_1> <длинное_число>)
      	   ...
              (<имя_параметра_n> <длинное_число>)))

На работу влияет параметр

        OPTION use-cache-for-signing=0|1

Исходное значение, 1, означает пользование буфером. Установка этого параметра в 0 приведет к тому, что gpg-agent станет игнорировать буфер фраз-паролей. Обратите внимание, что есть также глобальный параметр командной строки gpg-agent, который позволяет глобально выключать буферы.

Вот пример сеанса:

        C: SIGKEY <код_ключа>
        S: OK key available
        C: SIGKEY <код_ключа>
        S: OK key available
        C: PKSIGN
        S: # Здесь запрос подтверждения подписи у пользователя
        S: # Здесь запрос фразы-пароля у пользователя
        S: INQUIRE HASHVAL
        C: D ABCDEF012345678901234
        C: END
        S: # далее подпись
        S: D (sig-val rsa (s 45435453654612121212))
        S: OK

Создать ключ
------------

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

        GENKEY [--no-protection] [--preset] [<cache_nonce>]

Вызывает процесс создания ключа; сервер запросит параметры создания:

        S: INQUIRE KEYPARM
        C: D (genkey (rsa (nbits  1024)))
        C: END

Формат параметров ключа зависит от алгоритма:

         (genkey
           (алгоритм
             (имя_параметра_1 ....)
               ....
             (имя_параметра_n ....)))

Если все в норме, сервер возвращает открытый ключ в SPKI-подобном S-выражении вида:

          (public-key
            (rsa
      	 (n <длинное_число>)
      	 (e <длинное_число>)))

Вот пример сеанса:

        C: GENKEY
        S: INQUIRE KEYPARM
        C: D (genkey (rsa (nbits  1024)))
        C: END
        S: D (public-key
        S: D   (rsa (n 326487324683264) (e 10001)))
        S  OK key created

Параметром --no-protection можно пользоваться, чтобы предотвратить запрос фразы-пароля для защиты секретного ключа и оставить секретный ключ незащищенным. Параметр --preset добавляет фразу-пароль в буфер, используя исходные параметры буфера.

Параметром --inq-passwd можно пользоваться для создания ключа с переданной фразой-паролем. При этом gpg-agent производит запрос с ключевым словом NEWPASSWD для получения фразы-пароля. Этим параметром отменяется --no-protection; однако когда программа-клиент посылает фразу-пароль нулевой длины, это эквивалентно параметру --no-protection.

Импортировать секретный ключ
----------------------------

Эта операция пока не поддерживается. Для этого следует пользоваться специализированными средствами.

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

Экспортировать секретный ключ
-----------------------------

Не реализовано.

Должно производиться дополнительными средствами.

Импортировать корневой сертификат
---------------------------------

На самом деле мы не импортируем корневой сертификат, а предоставляем способ проверить любой набор данных, сохраняя его хeш вместе с описанием, а также идентификатором в личной среде безопасности. Вот описание команды:

         ISTRUSTED <отпечаток>

Проверить, является ли первичный ключ OpenPGP сертификата X.509 с данным отпечатком абсолютно доверенным ключом или доверенным корневым сертификатом удостоверяющего центра. Отпечаток должен задаваться шестнадцатеричной строкой (без пробелов, двоеточий и т.д. между ними) и может заполняться слева байтом 00 в случае отпечатка MD5. В ответ на это программа выдает:

         OK

Ключ находится в таблице доверенных ключей.

         ERR 304 (Not Trusted)

Ключ не находится в этой таблице.

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

         LISTTRUSTED

Возвращается список доверенных ключей по одному в строке:

         S: D 000000001234454556565656677878AF2F1ECCFF P
         S: D 340387563485634856435645634856438576457A P
         S: D FEDC6532453745367FD83474357495743757435D S
         S: OK

Первый элемент в строке представляет шестнадцатеричный отпечаток, в котором отпечатки MD5 дополнены слева байтом 00, второй указывает на тип ключа (чтобы gpg можно было заниматься только ключами PGP). «P» означает PGP, «S» — S/MIME. Остаток строки программа-клиент должна игнорировать, чтобы в будущем мы могли расширять формат.

Наконец, программа-клиент может пометить ключ как доверенный:

        MARKTRUSTED ОТПЕЧАТОК "P"|"S"

Сервер выдаст пользователю запрос на подтверждение этого действия. Для этого можно использовать подобный текст:

        S: INQUIRE TRUSTDESC
        C: D Действительно ли вы доверяете ключу с отпечатком @FPR@?
        C: D трам-пам-пам.
        C: END
        S: OK

Известные последовательности вида @xyz@ заменяются по таблице:

@FPR16@
     Отформатировать отпечаток по правилам gpg для ключей версии 3.

@FPR20@
     Отформатировать отпечаток по правилам gpg для ключей версии 4.

@FPR@
     Выбрать для отпечатка подходящий формат.

@@
     Заменяется на один знак @.

Запросить фразу-пароль
----------------------

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

       GET_PASSPHRASE [--data] [--check] [--no-ask] [--repeat[=N]] \
                      [--qualitybar] ИДЕНТИФИКАТОР БУФЕРА    \
                      [СООБЩЕНИЕ ОБ ОШИБКЕ ПРИГЛАШЕНИЕ ОПИСАНИЕ]

В аргументе ИДЕНТИФИКАТОР БУФЕРА передается строка, указывающая на сохраненную фразу-пароль. Чтобы не пользоваться буфером, задайте X. Без других аргументов gpg-agent выдает сохраненную фразу-пароль или ошибку. По соглашению в качестве идентификатора используется либо шестнадцатеричный отпечаток ключа, либо произвольная строка, в начале которой стоит имя вызывающего приложения с двоеточием, например, gpg:что-то-там.

Аргумент СООБЩЕНИЕ ОБ ОШИБКЕ представляет либо один X, если сообщения нет, либо сообщение, которое нужно показать при ошибке (напр., «неверная фраза-пароль»). Пробелы должны быть экранированы процентом или заменяться на +.

Аргумент ПРИГЛАШЕНИЕ представляет либо один X, если исходное приглашение не заменяется, либо текст, который показывается в качестве приглашения. Пробелы должны быть экранированы процентом или заменяться на +.

Аргумент ОПИСАНИЕ представляет текст, выводимый сверху от поля ввода. Пробелы должны быть экранированы процентом или заменяться на +.

Агент отвечает сообщением об ошибке либо «OK» с последующей фразой-паролем в шестнадцатеричном виде. Обратите внимание, что длина строк неявно ограничивается максимальной длиной команды. Если задан параметр --data, фраза-пароль возвращается не в строке с «OK», а в обычных строках данных; этот метод предпочтителен.

Если задан параметр --check, проверяются обычные ограничения на фразу-пароль. Проверка не проводится, если фраза-пароль найдена в буфере.

Если задан параметр --no-ask, а фраза-пароль не находится в буфере, фраза-пароль у пользователя запрашиваться не будет; вместо этого будет возвращаться GPG_ERR_NO_DATA.

Если задан параметр --qualitybar и установлена минимальная длина фразы-пароля, то показывается визуальный индикатор качества вводимой фразы-пароля.

       CLEAR_PASSPHRASE ИДЕНТИФИКАТОР БУФЕРА

Сбросить фразу-пароль в буфере. Функция возвращает «OK», даже когда такой фразы-пароля нет.

Удалить фразу-пароль из буфера
------------------------------

Пользуйтесь этой командой для удаления запомненной фразы-пароля.

       CLEAR_PASSPHRASE [--mode=normal] <идентификатор буфера>

Параметром --mode=normal можно пользоваться, чтобы очистить указанный буфер, заполненный программой gpg-agent.

Задать фразу-пароль для кода ключа
----------------------------------

Эта команда добавляет фразу-пароль для заданного кода ключа в буфер.

       PRESET_PASSPHRASE [--inquire] <строка или код ключа> <время> [<число>]

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

Аргумент ВРЕМЯ указывает время хранения фразы-пароля в секундах. Значение -1 означает бесконечность, а 0 — исходное значение (в настоящее время допустимо только -1, т.е. сохранять навсегда).

Запросить подтверждение
-----------------------

Этой командой можно вызвать простой запрос подтверждения с текстом и двумя кнопками: «Да» и «Отмена».

       GET_CONFIRMATION ОПИСАНИЕ

Заданное ОПИСАНИЕ показывается с кнопками «Да» и «Отмена». Пробелы должны быть экранированы процентом или заменяться на +. Для вызова диалога подтверждения с текстом по умолчанию можно использовать X.

В ответ возвращается либо ошибка, либо «OK». Обратите внимание, что длина описания неявно ограничена максимальной длиной команды.

Проверить наличие ключа
-----------------------

Этой командой можно проверять наличие секретного ключа. Она не возвращает никакой информации о защите этого ключа.

       HAVEKEY КОДЫ КЛЮЧЕЙ

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

Зарегистрировать электронную карту
----------------------------------

       LEARN [--send]

Команда регистрирует электронную карту. С параметром --send заданные сертификаты отсылаются назад.

Сменить фразу-пароль
--------------------

       PASSWD [--cache-nonce=<c>] [--passwd-nonce=<s>] [--preset] КОД КЛЮЧА

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

Изменить дисплей
----------------

       UPDATESTARTUPTTY

Установить переменные начального TTY и X-DISPLAY равными значениям данного сеанса. Эта команда полезна, чтобы направить будущие вызовы программы запроса пароля на другой экран. Это нужно только потому, что другого способа передать эту информацию в ssh-agent не существует.

Получить счетчики событий
-------------------------

       GETEVENTCOUNTER

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

В настоящее время определены счетчики:

ANY
     Увеличивается с любым изменением любых других счетчиков.

KEY
     Увеличивается при добавлении или удалении секретных ключей.

CARD
     Увеличивается при изменении состояния устройств чтения электронных карт.

Вывод сведений о процессе
-------------------------

Это универсальная функция для вывода разного рода сведений.

     GETINFO РАЗРЯД

Значение аргумента определяет, какого рода данные выводятся:

version
     Вывести версию программы.

pid
     Вывести идентификатор процесса.

socket_name
     Вывести имя сокета, по которому производится подключение к gpg-agent.

ssh_socket_name
     Вывести имя сокета, по которому производится подключение к SSH. Если поддержка SSH не включена, возвращается ошибка GPG_ERR_NO_DATA.

Задать параметры сеанса
-----------------------

Вот список параметров сеанса, которые еще не описаны с другими командами. Общий синтаксис параметра Assuan таков:

     OPTION  ИМЯ=ЗНАЧЕНИЕ

Поддерживаются имена:

agent-awareness
     Это можно использовать, чтобы указать gpg-agent, с какой версией gpg-agent знакома программа-клиент. gpg-agent пользуется этими данными, чтобы выключать функции, которые могли бы привести к сбоям старых программ-клиентов.

putenv
     Изменить среду сеанса, которая используется с программой ввода пароля. Допустимы значения:

     ИМЯ
          Удалить переменную среды с указанным именем

     ИМЯ=
          Присвоить указанной переменной пустую строку

     ИМЯ=ЗНАЧЕНИЕ
          Присвоить указанной переменной указанное значение.

use-cache-for-signing
     См. команду Assuan PKSIGN.

allow-pinentry-notify
     Параметр используется без аргумента. Он используется для включения запроса PINENTRY_LAUNCHED.

pinentry-mode
     Параметр применяется для изменения режима работы программы ввода пароля. Определены значения:

     ask
          Это исходный режим, в котором программа ввода пароля вызывается по мере необходимости.

     cancel
          Вместо вызова программы ввода пароля возвращается код ошибки GPG_ERR_CANCELED.

     error
          Вместо вызова программы ввода пароля возвращается код ошибки GPG_ERR_NO_PIN_ENTRY.

     loopback
          Пользоваться программой ввода пароля с обратным вызовом. Это имитирует программу ввода пароля, возвращая запросы пароля вызывающей программе. Чтобы выключить эту функцию, используйте параметр --no-allow-loopback-pinentry.

cache-ttl-opt-preset
     Этот параметр задает время действия новых записей в буфере, созданных командами GENKEY и PASSWD с параметром --preset. Если параметр не задан, используется исходное значение.

s2k-count
     Вместо стандартного номера S2K (вычисляемого на ходу) пользоваться для новых ключей и при смене фразы-пароля заданным номером S2K. Значения ниже 65536 считаются равными 0. Этот параметр действует до конца сеанса, если его не сбросят в 0. Этот параметр полезен, если ключ используется впоследствии на машинах, которые либо гораздо медленнее, либо гораздо быстрее, чем нынешняя.

СМ. ТАКЖЕ
     [file see-also-note.ru.texi not included]