     [file defs.ru.inc not included]

Вызов GPGSM
***********

gpgsm.ru.1

ВЫЗОВ

ОПИСАНИЕ
gpgsm представляет средство, подобное gpg, решающее задачи цифрового шифрования и подписи на базе сертификатов X.509 и протокола CMS. Оно применяется главным образом как служебная программа для обработки почты по S/MIME. gpgsm реализует полнофункциональное управление сертификатами, удовлетворяя всем правилам, определенным в немецком проекте Sphinx.

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

КОМАНДЫ

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

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

Команды, не связанные с конкретными функциями
---------------------------------------------

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

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

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

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

Команды выбора типа операции
----------------------------

--encrypt
     Зашифровать. Ключи, для которых шифруются данные, должны быть заданы параметром --recipient.

--decrypt
     Расшифровать; форма данных на входе определяется автоматически. Это может быть двоичный формат или кодировка PEM; автоматическое распознавание кодировки base-64 не производится.

--sign
     Сделать цифровую подпись. Используется либо первый ключ, найденный на щите с ключами, либо ключи, заданные параметром --local-user.

--verify
     Проверить цифровую подпись. В зависимости от аргументов может проверяться также отделенная подпись.

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

--call-dirmngr КОМАНДА [АРГУМЕНТЫ]
     Имитировать программу-клиент Dirmngr с заданной командой и необязательным списком аргументов. Вывод Dirmngr печатается в стандартном потоке вывода. Обратите внимание, что имена файлов, передаваемые в качестве аргументов, должны быть абсолютными (т.е. начинаться с /), потому что они передаются в Dirmngr буквально, а рабочий каталог Dirmngr может не совпадать с рабочим каталогом вызвавшей программы. В настоящее время передавать данные в Dirmngr через стандартный поток ввода невозможно. В аргументе КОМАНДА не должно быть пробелов.

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

--call-protect-tool АРГУМЕНТЫ
     Определенные регламентные операции проводятся с помощью внешней программы gpg-protect-tool; она обычно не устанавливается в каталоге, перечисленном в переменной PATH. Команда предоставляет простую оболочку для доступа к этому средству. Аргументы передаются в эту команду буквально; --help выдает список доступных операций.

Как управлять сертификатами и ключами
-------------------------------------

--generate-key
--gen-key
     Эта команда позволяет создавать запрос подписи сертификата или самоподписанный сертификат. Часто она используется с параметром --output, чтобы сохранить результат в файле. Если задан параметр --batch, при создании запроса подписи сертификата или сертификата используется файл настроек, и можно создавать несамоподписанные сертификаты.

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

--list-secret-keys
-K
     Перечислить все доступные сертификаты, для которых есть секретный ключ.

--list-external-keys ШАБЛОН
     Перечислить сертификаты, соответствующие аргументу, из внешнего сервера. Команда задействует службу dirmngr.

--list-chain
     То же, что --list-keys, но выводит также все ключи, составляющие цепочку.

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

--dump-chain
     То же, что --dump-keys, но выводит также все ключи, составляющие цепочку.

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

--dump-external-keys ШАБЛОН
     Перечислить сертификаты, соответствующие шаблону, из внешнего сервера. Команда задействует службу dirmngr. Формат, в котором выводится список, полезен главным образом для отладки.

--keydb-clear-some-cert-flags
     Это средство отладки для сброса определенных признаков в базе данных ключей, используемой как буфер для определенных элементов состояния ключей. Особенно полезно, когда испорчен список отозванных сертификатов или странно работающий ответчик OCSP действительно случайно отозвал сертификат. Эта команда не представляет проблем безопасности, потому что gpgsm всегда гарантирует, что достоверность сертификата проверяется непосредственно перед его применением.

--delete-keys ШАБЛОН
     Удалить ключи, соответствующие шаблону. Обратите внимание, что команды для прямого удаления секретной части ключа нет. В случае, если вам это нужно, перед удалением ключа следует выполнить команду gpgsm --dump-secret-keys идентификатор_ключа, скопировать последовательность шестнадцатеричных чисел в строке «код ключа» и удалить файл, имя которого состоит из этой последовательности и суффикса .key из каталога private-keys-v1.d, находящегося в домашнем каталоге GnuPG (обычно ~/.gnupg).

--export [ШАБЛОН]
     Экспортировать все сертификаты, хранящиеся на щите с ключами, указанные необязательным аргументом. Шаблон состоит из списка идентификаторов пользователя (see как задать идентификатор пользователя). При вводе с параметром --armor перед каждым блоком выводится несколько информационных строк. Есть одно ограничение: поскольку нет общепринятого способа упаковки нескольких сертификатов в одну структуру ASN.1, двоичный вариант (без параметра --armor) работает только для экспорта одного сертификата. Одноразовые сертификаты экспортируются, только если все шаблоны представляют коды ключей или отпечатки.

--export-secret-key-p12 ИДЕНТИФИКАТОР КЛЮЧА
     Экспортировать секретный ключ и сертификат, указанный аргументом, в формате PKCS#12. При вводе с параметром --armor перед данными на выходе выводится несколько информационных строк. Обратите внимание, что формат PKCS#12 не очень защищен и передавать экспортированный ключ нужно по защищенному каналу. (see параметр --p12-charset.)

--export-secret-key-p8 ИДЕНТИФИКАТОР КЛЮЧА
--export-secret-key-raw ИДЕНТИФИКАТОР КЛЮЧА
     Экспортировать секретный ключ сертификата, указанного в аргументе, в полностью незашифрованном виде. Команда ...-raw выводит в формате PKCS#1, команда ...-p8 выводит в формате PKCS#8. При вводе с параметром --armor перед данными на выходе выводится несколько информационных строк. Эти команды полезны для подготовки ключа к использованию на сервере TLS.

--import [ФАЙЛЫ]
     Импортировать сертификаты из двоичных файлов или файлов в кодировке PEM, а также из сообщений, которые только подписаны. Этой командой можно импортировать также секретный ключ из файла PKCS#12.

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

--change-passphrase ИДЕНТИФИКАТОР ПОЛЬЗОВАТЕЛЯ
--passwd ИДЕНТИФИКАТОР ПОЛЬЗОВАТЕЛЯ
     Изменить фразу-пароль секретного ключа, принадлежащего сертификату, указанному в аргументе. Обратите внимание, что изменение фразы-пароля или PIN электронной карты пока не поддерживается.

ПАРАМЕТРЫ

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

GPGSM характеризуется множеством параметров для управления деталями работы и для изменения исходных настроек.

Как изменять настройки
----------------------

Эти параметры применяются для изменения настроек и обычно находятся в файле параметров.

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

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

-v

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

--policy-file ФАЙЛ
     Изменить исходное имя файла с правилами на заданное в аргументе.

--agent-program ФАЙЛ
     Указать программу-агент для операций с секретными ключами. Исходное значение определяется командой gpgconf. Обратите внимание, что символ конвейера («|») применяется для регрессионного тестирования и поэтому не может появляться в имени файла.

--dirmngr-program ФАЙЛ
     Указать программу dirmngr для проверок списков отозванных сертификатов. Исходное значение — BINDIR/dirmngr.

--prefer-system-dirmngr
     Этот параметр устарел, он игнорируется.

--disable-dirmngr
     Полностью отключить пользование программой Dirmngr.

--no-autostart
     Не запускать gpg-agent и dirmngr, когда они еще не запущены, а их функции требуются. Этот параметр полезен главным образом на машинах, где подключение к gpg-agent перенаправляется на другие машины. Если dirmngr требуется на удаленной машине, его можно запускать вручную с помощью gpgconf --launch dirmngr.

--no-secmem-warning
     Не выводить предупреждение, когда так называемой «защищенной памятью» не удается воспользоваться.

--log-file ФАЙЛ
     При работе в режиме сервера дописывать весь протокол работы в заданный файл. Укажите socket://, если нужно протоколировать в сокет.

Параметры, связанные с сертификатами
------------------------------------

--enable-policy-checks
--disable-policy-checks
     По умолчанию проверка правил включена. Этими параметрами это можно менять.

--enable-crl-checks
--disable-crl-checks
     По умолчанию проверки списков отозванных сертификатов включены, и dirmngr используется для проверки отозванных сертификатов. Параметр --disable-crl-checks полезнее всего, когда сеть отключена и проверки нужно подавить.

--enable-trusted-cert-crl-check
--disable-trusted-cert-crl-check
     По умолчанию списки отозванных сертификатов для доверенных корневых сертификатов проверяются, как для любых других сертификатов. Это позволяет удостоверяющему центру отзывать свои собственные сертификаты без необходимости размещения всех когда-либо выданных сертификатов в списоке отозванных сертификатов. Параметр --disable-trusted-cert-crl-check можно использовать, чтобы отключить эту дополнительную проверку. Из-за буферирования, проводимого в dirmngr, заметного выигрыша в быстродействии не будет. Обратите внимание, что это отключает также возможные проверки доверенных корневых сертификатов по OCSP. Более выборочно эту проверку можно отключить, добавляя ключевое слово «relax» в строку корневого удостоверяющего центра в файле trustlist.txt.

--force-crl-refresh
     Дать программе dirmngr указание перезагружать список отозванных сертификатов на каждом запросе. Для ускорения dirmngr в действительности оптимизирует это, подавляя загрузки на короткое время (напр., 30 минут). Этот параметр полезен, чтобы гарантировать, что для сертификатов со щита с ключами есть свежий список отозванных сертификатов. Предлагается делать это, используя этот с параметром --with-validation для команды перечисления ключей. Этот параметр не следует записывать в файл настроек.

--enable-ocsp
--disable-ocsp
     По умолчанию проверки по OCSP выключены. Параметром --enable-ocsp можно включить проверки по OCSP через dirmngr. Если проверки списков отозванных сертификатов тоже включены, списки отозванных сертификатов будут использованы как запасной вариант, если по какой-то причине запрос OCSP не пройдет. Обратите внимание, что в настройках dirmngr тоже нужно включать запросы по OCSP (параметр --allow-ocsp), и dirmngr нужно соответственно настроить. Если этого не сделать, будет выдана ошибка Не поддерживается.

--auto-issuer-key-retrieve
     Если при проверке цепочки сертификатов требуемый сертификат отсутствует, пытаться загрузить этот сертификат из внешнего источника. Это обычно означает, что для поиска сертификата задействуется dirmngr. Обратите внимание, что это может привести к «сетевому проколу». Операторы сервера LDAP могут узнать, какие ключи вы запрашиваете, так что оператор может узнать и ваш адрес IP, и время, когда вы проверяли подпись, если пошлет вам сообщение, подписанное свежесозданным ключом (которого у вас в локальной таблице ключей, естественно, не найдется).

--validation-model НАЗВАНИЕ
     Этот параметр изменяет исходную схему проверки. Возможны значения: «shell» (исходная), «chain» (цепочная схема) и «steed» (новая упрощенная схема). Цепочная схема применяется также, если этого требует параметр в trustlist.txt или атрибут в сертификате. Однако в этом случае сначала всегда применяется исходная модель («shell»).

--ignore-cert-extension OID
     Добавить OID к списку игнорируемых расширений сертификатов. Аргумент должен представлять десятичные числа, разделенные точками, например, 2.5.29.3. Этот параметр можно задавать несколько раз. Расширения сертификата, совпадающие с перечисленными OID и помеченные как критичные, будут считаться обработанными, так что сертификат не будет отбракован из-за неизвестного критичного расширения. Пользуйтесь этим параметром с осторожностью, потому что расширения обычно не помечаются как критичные без причины.

Ввод и вывод
------------

--armor
-a
     Выводить данные в кодировке PEM. По умолчанию они выводятся в двоичном виде.

--base64
     Выводить данные в кодировке base-64, т.е. PEM без заголовочных строк.

--assume-armor
     Считать, что данные вводятся в кодировке PEM. По умолчанию кодировка детектируется автоматически, но это может дать сбой.

--assume-base64
     Считать, что данные вводятся в кодировке base-64.

--assume-binary
     Считать, что данные вводятся в двоичном виде.

--p12-charset КОДИРОВКА
     gpgsm кодирует фразы-пароли в файлах PKCS#12 в кодировке UTF-8. Этим параметром можно принудительно сохранять фразу-пароль в заданной кодировке. Это полезно, если приложение, импортирующее ключ, пользуется другой кодировкой и поэтому не сможет импортировать файл, созданный gpgsm. Часто используются кодировки Latin1 и CP850. Обратите внимание, что сама gpgsm при импорте автоматически определяет фразы-пароли в наиболее употребительных кодировках.

--default-key ИДЕНТИФИКАТОР ПОЛЬЗОВАТЕЛЯ
     Задать основной ключ для подписи. Этот ключ используется, если для подписи не определен никакой другой ключ. Обратите внимание, что первый параметр --local-users также задает этот ключ, если он еще не задан; --default-key всегда переопределяет этот ключ.

--local-user ИДЕНТИФИКАТОР ПОЛЬЗОВАТЕЛЯ

-u ИДЕНТИФИКАТОР ПОЛЬЗОВАТЕЛЯ
     Задать пользователей, ключами которых будет производиться подпись. Исходное значение — первый секретный ключ, находящийся в базе данных.

--recipient ИМЯ
-r
     Шифровать для указанного пользователя. Идентификатор пользователя можно задавать разными способами (see как задать идентификатор пользователя).

--output ФАЙЛ
-o ФАЙЛ
     Записывать результат в ФАЙЛ. По умолчанию используется стандартный поток вывода.

--with-key-data
     При выполнении команд --list-keys выводить дополнительную информацию, главным образом код ключа в строке с пометкой grp. Эта строка используется, например, как имя файла с секретным ключом. Подразумевает --with-colons.

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

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

--with-md5-fingerprint
     При обычных перечислениях ключей выводить также отпечаток MD5 сертификата.

--with-keygrip
     Выводить код ключа при обычных перечислениях ключей. Обратите внимание, что код ключа всегда выводится в режиме --with-colons.

--with-secret
     Выводить сведения о присутствии секретного ключа в списках открытых ключей, производимых --with-colons.

Как изменять создание CMS
-------------------------

--include-certs N
     Значение аргумента, равное -2, включает все сертификаты, кроме корневого, -1 — все сертификаты, 0 — не включает никакие, 1 — только сертификаты подписавшего, все другие положительные числа включают все сертификаты до N-го, начиная с сертификата подписавшего. Исходное значение равно -2.

--cipher-algo OID
     Применять для шифрования симметричный шифр с указанным идентификатором объекта ASN.1. Для удобства вместо идентификаторов можно использовать строки 3DES, AES и AES256. Исходное значение — AES (2.16.840.1.101.3.4.1.2).

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

То, чего обычно делать не нужно
-------------------------------

--extra-digest-algo НАЗВАНИЕ
     Иногда в неисправных подписях заявлен не тот алгоритм хеша, который в них применяется. gpgsm обрабатывает данные в один проход, поэтому для правильного вычисления хеша программе приходится рассчитывать на то, что в подписи применяются заявленные алгоритмы. Этот параметр позволяет указать gpgsm, что нужно дополнительно вычислять указанный хеш; это немного замедляет обработку, но позволяет проверять такие неисправные подписи. Если gpgsm выводит такую ошибку, как «алгоритм 8 не подключен», можно попробовать ввести этот параметр с SHA256 в качестве аргумента.

--faked-system-time МОМЕНТ
     Этот параметр полезен только для тестирования; он переводит системное время к моменту, заданному аргументом в виде количества секунд с начала 1970 года. Время можно задавать также в виде полной строки времени ИСО (напр., «20070924T154812»).

--with-ephemeral-keys
     Включать одноразовые ключи в перечисления ключей. Обратите внимание, что они все равно включаются, если ключ для перечисления указан в виде отпечатка или кода ключа.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     Обратите внимание, что все флаги, установленные этим параметром, могут переустанавливаться с помощью параметра --debug-level.

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

--debug-allow-core-dump
     Обычно gpgsm в целях безопасности предотвращает вывод дампа памяти высоким качеством программы, а также отключением вывода дампа памяти. Однако ошибки живучи, и чтобы отловить их, иногда полезно получить дамп памяти. Этот параметр включает дампы памяти, если только эта дрянь не происходит еще до распознавания параметров.

--debug-no-chain-validation
     Это на самом деле не параметр отладки, но полезен только как таковой. Он позволяет gpgsm обходить все проверки цепочек сертификатов.

--debug-ignore-expiration
     Это на самом деле не параметр отладки, но он полезен только как таковой. Он позволяет gpgsm игнорировать все даты notAfter, это применяется в регрессионном тестировании.

--passphrase-fd n
     Читать фразу-пароль из файлового дескриптора n. Из дескриптора читается только первая строка. Если в качестве n указать 0, фраза-пароль считывается из стандартного потока ввода. Это возможно, только если передается одна фраза-пароль.

     Обратите внимание, что эта фраза-пароль используется только вместе с параметром --batch.

--pinentry-mode режим
     Установить указанный режим программы ввода пароля. Допустимые значения аргумента:

     default
          Исходный режим агента (ask).

     ask
          Принудительно пользоваться программой ввода пароля.

     cancel
          Имитировать нажатие в программе ввода пароля кнопки отмены.

     error
          Возвратить ошибку («Нет программы ввода пароля»).

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

--request-origin ИСТОЧНИК
     Считать, что операция исходит из заданного источника. В зависимости от источника применяются определенные ограничения, а программа ввода пароля может выводить дополнительное замечание об источнике. Параметр может принимать значения: local (исходное), remote (удаленный источник) и browser (операция запрашивается браузером).

--no-common-certs-import
     Подавить импорт общих сертификатов при создании щита с ключами.

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

ВВОД ИДЕНТИФИКАТОРОВ ПОЛЬЗОВАТЕЛЯ

ФАЙЛЫ

Файлы настроек
==============

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

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

policies.txt
     Список допустимых правил удостоверяющих центров. В этом файле должны построчно перечисляться идентификаторы объектов правил. Пустые строки и строки, начинающиеся с «#», игнорируются. Если правило, которого нет в этом файле, не помечено в сертификате как критичное, это приводит только к предупреждению; если оно помечено как критичное, проверка подписи выдаст ошибку. Для этого файла следует проводить резервное копирование.

     Например, чтобы было разрешено только правило 2.289.9.9, файл должен иметь вид:

          # Allowed policies
          2.289.9.9

qualified.txt
     Список корневых сертификатов, используемых для квалифицированных сертификатов. Они определяются как сертификаты, способные создавать такие же юридически обязывающие подписи, как подписи от руки. Примечания, начинающиеся с «#», и пустые строки игнорируются. Строки ограничены по длине, но это несущественно, потому что формат элементов фиксирован и проверяется gpgsm: строка начинается с необязательных пробелов, за которыми следуют в точности 40 шестнадцатеричных символов, пробелы и две строчных буквы, составляющие код страны. Дополнительные данные, разделенные пробелами, в настоящее время не учитываются, но впоследствии могут использоваться в других целях.

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

     Это глобальный файл, установленный в каталоге данных (напр., DATADIR/qualified.txt). GnuPG устанавливает соответствующий файл с корневыми сертификатами, применяемыми в Германии. Поскольку со временем могут выдаваться новые корневые сертификаты удостоверяющих центров, этот список тоже нужно обновлять; новые выпуски этого пакета программ должны содержать обновленный список, но ответственность за проверку этого списка все равно лежит на администраторе.

     Каждый раз, когда gpgsm пользуется сертификатом для подписи или проверки, программа обращается к этому файлу, чтобы проверить, выпущен ли данный сертификат одним из этих удостоверяющих центров. Если это так, пользователя извещают, что проверенная подпись представляет юридически обязывающую («квалифицированную») подпись. При создании подписи с помощью такого сертификата производится дополнительный запрос, чтобы пользователь подтвердил, что такая юридически обязывающая подпись действительно должна быть создана.

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

help.txt
     Это текстовый файл с несколькими пунктами справки, которые используются в программе ввода пароля pinentry, а также большой список текстов справки для gpg и gpgsm. В файле без суффикса записаны английские тексты; для установки переведенных версий пользуйтесь файлами help.LL.txt, где LL — код языка. В GnuPG устанавливает первоначальный набор файлов в каталоге данных (напр., DATADIR/gnupg/help.de.txt) и позволяет заменять любые пункты справки из файлов, установленных в системном каталоге настроек (напр., SYSCONFDIR/help.de.txt). Справку по синтаксису файла см. в установленном файле help.txt.

com-certs.pem
     Сборник общих сертификатов, которые записываются во вновь создаваемые pubring.kbx. Администратор может заменять этот файл в соответствии с местными требованиями. Этот глобальный файл устанавливается в каталог данных (напр., DATADIR/com-certs.pem).

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

Для внутреннего пользования gpgsm создает и ведет несколько других файлов; все они располагаются в текущем домашнем каталоге (see параметр --homedir). Эти файлы можно изменять только программой gpgsm.

pubring.kbx
     Это файл базы данных, в которой хранятся сертификаты, а также сопутствующие данные. Для отладки можно воспользоваться средством kbxutil, которое показывает внутреннюю структуру этого файла. Для этого файла следует проводить резервное копирование.

random_seed
     Содержимое этого файла используется для сохранения внутреннего состояния генератора случайных чисел между вызовами. Этот же файл используется и другими программами этого пакета.

S.gpg-agent
     Если этот файл существует, gpgsm попытается соединиться с этим сокетом для доступа к gpg-agent перед тем, как запускать новый экземпляр gpg-agent. Под Windows этот сокет (который в действительности представляет простой файл с описанием обычного принимающего порта TCP) является основным способом подключения к gpg-agent.

ПРИМЕРЫ

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

     $ gpgsm -er foo@test.org < открытый-текст > шифровка

Автоматическая работа
=====================

gpgsm часто применяется как служебная программа в других программах. Чтобы облегчить такое использование, был определен машинный интерфейс, в котором исключаются неоднозначности. Скорее всего это будет применяться с командой --server, но этим можно пользоваться также в обычном режиме, задавая параметр --status-fd.

Автоматическая проверка подписи
-------------------------------

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

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

     подпись верна, ничего не просрочено
          GOODSIG, VALIDSIG, TRUST_FULLY

     подпись верна, но по крайней мере один сертификат просрочен
          EXPKEYSIG, VALIDSIG, TRUST_FULLY

     подпись верна, но просрочена
          EXPSIG, VALIDSIG, TRUST_FULLY Обратите внимание, что этот случай в настоящее время не реализован.

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

     BADSIG

     GOODSIG, VALIDSIG TRUST_NEVER

Ошибка при проверке подписи
     По той или иной причине подпись проверить не удалось, т.е. нельзя определить, верна она или нет. Обычно это бывает из-за отсутствия сертификата.

Создание CSR и сертификатов
---------------------------

Команду --generate-key можно применять с параметром --batch для создания запроса на подпись сертификата (CSR) или сертификата X.509. Это управляется файлом параметров; формат этого файла следующий:

  * Только текст, длина строк ограничена примерно 1000 символов.

  * Для символов, не входящих в набор ASCII, используется UTF-8.

  * Пустые строки игнорируются.

  * Пробелы в начале и конце строк игнорируются.

  * Строки, первым символом которых (не считая пробелов) является «#», представляют комментарий.

  * Управляющие конструкции отмечаются знаком процента перед ними, аргументы отделяются от ключевого слова пробелами.

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

  * Первым параметром должен быть Key-Type; управляющие конструкции могут быть в любом месте.

  * Порядок параметров не имеет значения (не считая того, что первым должен быть Key-Type). Параметры используются только для создаваемого блока; параметры из предыдущих наборов не используются. Могут проводиться некоторые проверки синтаксиса.

  * Создание ключа производится по достижении конца файла параметров, при появлении следующего параметра Key-Type или при появлении управляющей конструкции %commit.

Управляющие конструкции:

%echo ТЕКСТ
     Вывести ТЕКСТ в качестве диагностики.

%dry-run
     Подавить действительное создание ключа (полезно для проверки синтаксиса).

%commit
     Выполнить создание ключа. Обратите внимание, что неявно эта конструкция вводится перед следующим параметром Key-Type.

Общие параметры:

Key-Type: АЛГОРИТМ
     Открывает новый блок параметров, задавая тип первичного ключа. Алгоритм должен подходить для подписей. Это обязательный параметр. В качестве аргумента поддерживается только rsa.

Key-Length: N
     Заданная длина создаваемого ключа в битах. Исходное значение 2048.

Key-Grip: ШЕСТНАДЦАТЕРИЧНАЯ СТРОКА
     Необязательный параметр; используется для создания запроса на подпись сертификата или сертификата для уже существующего ключа. Параметр Key-Length при этом игнорируется.

Key-Usage: СПИСОК
     Список функций ключа с пробелом или запятой в качестве разделителя. Допустимы значения encrypt (шифрование), sign (подпись) и cert (сертификация). Используется для задания расширения keyUsage. Проверьте, пожалуйста, что алгоритм может выполнять эти функции. По умолчанию назначаются функции шифрования и подписи.

Name-DN: ИМЯ СУБЪЕКТА
     Это уникальное имя (DN) субъекта в формате RFC-2253.

Name-Email: СТРОКА
     Это адрес электронной почты для altSubjectName. Это необязательный параметр, но он может появляться несколько раз, чтобы добавить к сертификату несколько адресов электронной почты.

Name-DNS: СТРОКА
     Это имя DNS для altSubjectName. Это необязательный параметр, но он может появляться несколько раз, чтобы добавить к сертификату несколько имен DNS.

Name-URI: СТРОКА
     Это URI для altSubjectName. Это необязательный параметр, но он может появляться несколько раз, чтобы добавить к сертификату несколько URI.

Дополнительные параметры для создания сертификата (в отличие от запроса на подпись сертификата):

Serial: НОМЕР
     Если этот параметр задан, будет создан сертификат X.509. Аргумент должен быть шестнадцатеричной строкой, представляющей целое число произвольной длины без знака. Особое значение random можно вводить, чтобы создавать случайный 64-битный серийный номер.

Issuer-DN: ИМЯ ИЗДАТЕЛЯ
     Это уникальное имя издателя в формате RFC-2253. Если не задано, будет использовано уникальное имя субъекта; кроме того, в сертификат будет добавлено специальное расширение GnuPG, чтобы пометить это как независимый сертификат.

Creation-Date: ДАТА ИСО
Not-Before: ДАТА ИСО
     Установить дату notBefore в сертификате. Можно использовать либо дату в виде 1986-04-26 или 1986-04-26 12:00, либо стандартную дату ИСО в виде 19860426T042640. Время считается Всемирным координированным (UTC). Если не задано, используется текущее время.

Expire-Date: ДАТА ИСО
Not-After: ДАТА ИСО
     Установить дату notAfter в сертификате. Можно использовать либо дату в виде 2063-04-05 или 2063-04-05 17:00, либо стандартную дату ИСО в виде 20630405T170000. Время считается Всемирным координированным (UTC). Если не задано, используется текущее время.

Signing-Key: КОД КЛЮЧА
     Задает код ключа, которым подписывается сертификат. Если не задан, создается самоподписанный сертификат. Для совместимости с будущими версиями предлагается писать перед кодом ключа &.

Hash-Algo: АЛГОРИТМ ХЕША
     Применить для этого сертификата или запроса на подпись сертификата заданный алгоритм хеша: sha1, sha256, sha384 или sha512; их можно указывать также прописными буквами. Исходное значение равно sha256.

Протокол, применяемый в режиме сервера
======================================

Описание протокола доступа к gpgsm. Программа gpgsm реализует и протокол Assuan, но в дополнение предоставляет нормальный протокол командной строки, который обеспечивает все функции этого протокола (но с помощью внутреннего связывания). Для запуска gpgsm в качестве сервера нужно задать параметр командной строки --server. Дополнительные параметры служат для выбора метода связи (т.е. имени сокета).

Мы предполагаем, что соединение уже установлено; подробности см. в руководстве по Assuan.

Шифрование сообщения
--------------------

Перед шифрованием нужно задать получателя командой:

       RECIPIENT ИДЕНТИФИКАТОР ПОЛЬЗОВАТЕЛЯ

Задать получателя шифрованного сообщения. Идентификатор пользователя должен быть внутренним представлением ключа; сервер может принимать любой другой способ указания. Если это достоверный и доверенный получатель, сервер отвечает кодом OK; в противном случае он возвращает ERR с причиной, по которой получатель недопустим, шифрование для этого получателя производиться не будет. Если нужно, чтобы шифрование не производилось, если не все получатели достоверны, об этом должна позаботиться программа-клиент. Все команды RECIPIENT накапливаются до команды RESET или до успешной команды ENCRYPT.

       INPUT FD[=N] [--armor|--base64|--binary]

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

Параметр --armor можно применять, чтобы указать серверу, что данные на входе представлены в формате PEM, --base64 указывает на простую кодировку base-64, --binary указывает на двоичный формат (BER). Если не задан ни один из параметров, сервер пытается определить кодировку по входным данным, но результат иногда может быть неверен.

       OUTPUT FD[=N] [--armor|--base64]

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

Параметр --armor можно применять, чтобы указать серверу, что данные на входе представлены в формате PEM, --base64 указывает на простую кодировку base-64. Если аргумента нет, данные выводятся в двоичном формате (BER).

Само шифрование проводится с помощью команды

       ENCRYPT

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

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

Расшифровка сообщения
---------------------

Входной и выходной файловые дескрипторы задаются, как для шифрования, но INPUT относится к зашифрованному тексту, а OUTPUT — к расшифрованному. Задавать получателей не нужно. gpgsm автоматически удаляет все заголовки S/MIME из данных на входе, так что во входной канал можно направлять часть MIME полностью.

Расшифровка производится с помощью команды

       DECRYPT

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

Подпись сообщения
-----------------

Подпись обычно производится командами:

       INPUT FD[=N] [--armor|--base64|--binary]

Это указывает gpgsm, что подписываемые данные нужно читать из файлового дескриптора N.

       OUTPUT FD[=M] [--armor|--base64]

Записать результат в файловый дескриптор M. Если запрашивается отделенная подпись, записывается только подпись.

       SIGN [--detached]

Подписать данные, заданные командой INPUT, и записать их в канал, заданный командой OUTPUT. Если задан параметр --detached, выводить отделенную подпись.

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

       SIGNER ИДЕНТИФИКАТОР ПОЛЬЗОВАТЕЛЯ

для задания подписывающего ключа. Идентификатор пользователя должен быть внутренним представлением ключа; сервер может принимать любой другой способ указания. Если это достоверный и доверенный получатель, сервер отвечает кодом OK; в противном случае он возвращает ERR с причиной, по которой ключ недопустим, подпись с помощью этого ключа производиться не будет. Если задано правило, по которому подпись не производится, если не все ключи достоверны, программа-клиент должна об этом позаботиться. Все команды SIGNER накапливаются до команды RESET. Обратите внимание, что команда SIGN не сбрасывает список подписывающих, в отличие от команд ENCRYPT и RECIPIENT.

Проверка сообщения
------------------

Для проверки сообщения предназначена команда

       VERIFY

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

Создание ключа
--------------

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

       GENKEY

Программа gpgsm проверяет, разрешена ли эта команда, а затем проводит запрос, чтобы получить параметры ключа — программа-клиент должна переслать параметры ключа в собственном формате gpgsm:

         S: INQUIRE KEY_PARAM native
         C: D foo:fgfgfg
         C: D bar
         C: END

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

Перечисление доступных ключей
-----------------------------

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

       LISTKEYS  ШАБЛОН

Для указания нескольких образцов (при поиске выдаются ключи, соответствующие хотя бы одному из них) их нужно экранировать: пробелы нужно заменять на «+» или «%20»; это, в свою очередь, требует применения обычных правил для экранирующих символов.

       LISTSECRETKEYS ШАБЛОН

Перечислить только те ключи, для которых есть секретный ключ.

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

       OPTION list-mode=РЕЖИМ

где режим может быть равен

0
     Исходный режим (обычно то же, что 1).

1
     Перечислять только внутренние ключи.

2
     Перечислять только внешние ключи.

3
     Перечислять внутренние и внешние ключи

Обратите внимание, что параметры работают на протяжении всего сеанса.

Экспорт сертификатов
--------------------

Для экспорта сертификатов предназначена команда

       EXPORT [--data [--armor] [--base64]] [--] ШАБЛОН

Для указания нескольких образцов (при поиске выдаются ключи, соответствующие хотя бы одному из них) их нужно экранировать: пробелы нужно заменять на «+» или «%20»; это, в свою очередь, требует применения обычных правил для экранирующих символов.

Если параметр --data не задан, формат данных на выходе зависит от от того, что задано командой OUTPUT. Когда применяется кодировка PEM, перед данными выводится несколько информационных строк.

Если параметр --data задан, назначение, заданное через OUTPUT, не учитывается, и данные выводятся в виде обычных строк, начинающихся на D. При этом задавать дополнительно файловый дескриптор не требуется. В этом случае параметры --armor и --base64 можно применять так же, как с командой OUTPUT.

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

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

       IMPORT [--re-import]

Данные вводятся из файлового дескриптора, заданного командой INPUT. Сертификат проходит определенные проверки. Обратите внимание, что этой командой можно обрабатывать также файлы PKCS#12 и импортировать секретные ключи; для этого используется вспомогательная программа.

С параметром --re-import данные на входе считаются отпечатками (по одному на строку). Команда повторно импортирует соответствующие сертификаты, т.е. одноразовые сертификаты становятся постоянными.

Удаление сертификатов
---------------------

Для удаления сертификатов предназначена команда

       DELKEYS ШАБЛОН

Для указания нескольких образцов (при поиске выдаются ключи, соответствующие хотя бы одному из них) их нужно экранировать: пробелы нужно заменять на «+» или «%20»; это, в свою очередь, требует применения обычных правил для экранирующих символов.

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

Извлечь аудиторский след
------------------------

Эта команда предназначена для извлечения аудиторского следа.

     GETAUDITLOG [--data] [--html]

Если задан параметр --data, аудиторский след выводится в виде строк, начинающихся с D, вместо вывода в файловый дескриптор, заданный командой OUTPUT. Если задан параметр --html, данные форматируются в виде блока XHTML, составленного для включения в документ HTML.

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

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

     GETINFO РАЗРЯД

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

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

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

agent-check
     Вывести OK, если работает программа-агент.

cmd_has_option КОМАНДА ПАРАМЕТР
     Вывести OK, если в заданной команде реализован указанный параметр. Параметр должен указываться без «--» в начале.

offline
     Вывести OK, если связи с сетью нет. Это может произойти в результате ввода параметра OPTION offline=1 или при запуске gpgsm с параметром --disable-dirmngr.

Параметры сеанса
----------------

Стандартный обработчик параметров Assuan поддерживает параметры:

     OPTION ПАРАМЕТР[=ЗНАЧЕНИЕ]

Распознаются параметры:

putenv
     Изменить среду сеанса для передачи через gpg-agent в программу ввода пароля. Здесь ЗНАЧЕНИЕ — строка в виде <КЛЮЧ>[=[<СТРОКА>]]. Если задан только <КЛЮЧ>, переменная среды <КЛЮЧ> удаляется из среды сеанса, если задано <КЛЮЧ>=, переменной среды присваивается пустая строка, если задана <СТРОКА>, она присваивается переменной.

display
     Установить переменную среды сеанса DISPLAY.

ttyname
     Установить переменную среды сеанса GPG_TTY.

ttytype
     Установить переменную среды сеанса TERM.

lc-ctype
     Установить переменную среды сеанса LC_CTYPE.

lc-messages
     Установить переменную среды сеанса LC_MESSAGES.

xauthority
     Установить переменную среды сеанса XAUTHORITY.

pinentry-user-data
     Установить переменную среды сеанса PINENTRY_USER_DATA.

include-certs
     Этим параметром отменяется параметр командной строки --include-certs. Значение аргумента, равное -2, включает все сертификаты, кроме корневого, -1 — все сертификаты, 0 — не включает никакие, 1 — только сертификаты подписавшего, все другие положительные числа включают все сертификаты до указанного числа, начиная с сертификата подписавшего.

list-mode
     See команда gpgsm listkeys.

list-to-output
     Если значение аргумента не равно 0, команды перечисления (see команда gpgsm listkeys) записывают в файловый дескриптор, заданный последней командой OUTPUT. Если значение равно 0, запись производится через строки данных; это исходное значение.

with-validation
     Если значение аргумента не равно 0, для каждого перечисленного сертификата выводится состояние проверки. Это может приводить к получению списка отозванных сертификатов по сети или запросу пользователя о доверии к корневому сертификату. Исходное значение задается параметром командной строки (see параметр gpgsm --with-validation).

with-secret
     Если значение аргумента не равно 0, сертификаты с соответствующим секретным ключом отмечаются в выводимых списках.

validation-model
     Этим параметром отменяется параметр командной строки validation-model для сеанса. (see параметр gpgsm --validation-model.)

with-key-data
     Этим параметром глобально включается параметр командной строки --with-key-data. (see параметр gpgsm --with-key-data.)

enable-audit-log
     Если значение аргумента не равно 0, данные для записи в аудиторский след собираются. (see команда gpgsm getauditlog.)

allow-pinentry-notify
     Если задан этот параметр, в программу-клиент передаются уведомления о запуске программы ввода пароля.

with-ephemeral-keys
     Если значение аргумента не равно 0, одноразовые сертификаты включаются в перечисления ключей.

no-encrypt-to
     Если задан этот параметр, все ключи, заданные параметром командной строки --encrypt-to, игнорируются.

offline
     Если параметр не равен 0 или не задан, всякий доступ к сети на время текущего сеанса прекращается. То же самое, что параметр командной строки --disable-dirmngr.

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