Pivit

Pivit — это инструмент командной строки для управления сертификатами x509, хранящимися на смарт-картах с поддержкой апплета PIV (Yubikey), и для использования этих сертификатов для подписи и проверки данных.

Он полностью совместим с тем, как командная строка git вызывает внешние программы для подписи и проверки коммитов и тегов.

Установка

Brew

brew install pivit

Установка через Go

go install github.com/cashapp/pivit/cmd/pivit@latest

Использование

Чтобы настроить git на использование pivit для подписи и проверки подписей, выполните следующие команды:

git config --(local|global) gpg.format x509
git config --(local|global) gpg.x509.program pivit

Сброс и инициализация Yubikey PIV

pivit --reset

Сбрасывает апплет PIV на Yubikey и создаёт новый PIN-код для доступа к нему.

Генерация сертификата

pivit --generate [--p256] [--self-sign | --no-csr] [--assume-yes] [--pin-policy] [--touch-policy]

Создаёт новую пару ключей в слоте аутентификации карты Yubikey.
Эта команда также создаёт и сохраняет сертификат x509 для сгенерированного ключа, подписанный компанией Yubico.

Если указан параметр --p256, пара ключей генерируется с использованием эллиптической кривой P-256. В противном случае используется кривая P-384.

Добавьте флаг --self-sign, чтобы сгенерировать самоподписанный сертификат; сертификат подписывается только что созданным ключом.
Будет запрошено подтверждение того, что самоподписанный сертификат действительно нужен, затем запрошен PIN-код, а затем — прикосновение к Yubikey.
Вывод будет содержать 3 блока CERTIFICATE вместо CERTIFICATE_REQUEST в конце (пример вывода ниже).
Эта опция полезна в основном для целей тестирования. Флаг --assume-yes можно использовать в сочетании с опцией --self-sign, чтобы отключить запрос подтверждения y/n.

Добавьте флаг --no-csr, чтобы пропустить вывод запроса на подпись сертификата. В этом случае прикосновение к Yubikey не запрашивается.
Эта опция полезна, если вам не нужно, чтобы сгенерированный ключ был частью существующей PKI.
Вы всё ещё можете проверить сертификат ключа, используя сертификат аттестации Yubico здесь.

Флаг --pin-policy управляет тем, когда запрашивать PIN-код при доступе к сгенерированному ключу.
Установите одно из значений never, once или always (по умолчанию — never).

Флаг --touch-policy управляет тем, когда требовать физического прикосновения к устройству при доступе к сгенерированному ключу.
Установите одно из значений never, cached или always (по умолчанию — always).

Вывод команды будет выглядеть так:

Printing Yubikey device attestation certificate:
----- BEGIN CERTIFICATE -----
...
----- END CERTIFICATE -----
Printing generated key certificate:
----- BEGIN CERTIFICATE -----
...
----- END CERTIFICATE -----
Printing certificate signing request:
----- BEGIN CERTIFICATE REQUEST -----
...
----- END CERTIFICATE REQUEST-----

CERTIFICATE REQUEST в конце подписан новым сгенерированным закрытым ключом и может быть использован для выпуска сертификата, подписанного удостоверяющим центром (CA).

Если вы решите выпустить и использовать собственный сертификат, важно также проверить, что:

Сертификат аттестации устройства подписан компанией Yubico.
Сертификат ключа подписан сертификатом аттестации устройства.
Открытый ключ в запросе на подпись сертификата совпадает с открытым ключом в сертификате ключа.

Параметры запроса на подпись сертификата

Pivit позволяет задавать различные атрибуты в CSR через переменные окружения.

Следующие параметры сертификата будут установлены следующим образом:

Subject.CommonName будет установлен в значение переменной окружения PIVIT_EMAIL.
Subject.Organization будет установлен в значение переменной окружения PIVIT_ORG.
Subject.OrganizationalUnit будет установлен в значение переменной окружения PIVIT_ORG_UNIT.

Дополнительно в запрос сертификата будут включены следующие альтернативные имена субъекта (SAN):

Адреса электронной почты будут включать PIVIT_EMAIL
URI будут включать все URL-адреса, указанные в переменной окружения PIVIT_CERT_URIS (URI разделяются пробелом)

Поддержка слотов PIV

Модуль PIV поддерживает несколько слотов, в которых могут храниться ключи и сертификаты.
Доступные слоты: 9a, 9c, 9d и 9e.

9e — слот «Card Authentication» (аутентификация карты).
Это единственный слот, который не требует PIN-кода для доступа к закрытому ключу при подписании, что снижает трение при использовании.
9a — слот «Authentication» (аутентификация). Используется для таких действий, как вход в систему.
9c — слот «Digital Signature» (цифровая подпись). Используется для подписания документов, файлов и исполняемых файлов.
9d — слот «Key Management» (управление ключами). Используется для таких задач, как шифрование электронных писем или файлов в целях конфиденциальности.

Дополнительная информация

pivit позволяет выбрать слот с помощью флага -w.
Для каждой команды, если слот не указан, по умолчанию используется 9e.
Например:

Генерация сертификата
```
pivit --generate [-w slot]
```
Подпись
```
pivit -s -u userid [-w slot]
```
Вывод сертификата
```
pivit --print [-w slot]
```

Указание Yubikey по серийному номеру

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

Пример:

PIVIT_YK_SERIAL=13078292 pivit --print

Это можно использовать с любой командой.

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

pivit --import [--first-pem] [file]

Импортирует сертификат из file.
Предполагается, что указанное имя файла содержит сериализованный сертификат x509, закодированный в виде PEM-блока.

Это действие запрашивает PIN-код Yubikey.

Добавьте --first-pem, чтобы импортировать первый PEM-блок из file, игнорируя остальные. Это полезно, если вы используете CA, который предоставляет выпущенные сертификаты в виде цепочки или пакета, где сертификат конечного субъекта идёт первым (так принято).

Вывод информации о сертификате

pivit --print

Выводит сертификат, хранящийся в слоте аутентификации карты Yubikey, вместе с его отпечатком.
Например:

> pivit --print
bad126c47dc90e90e0c7ec90ec682b1717e52757
-----BEGIN CERTIFICATE-----
MIICczCCAVugAwIBAgIRANATKTxzlHOJgMdV30XRz5kwDQYJKoZIhvcNAQELBQAw
ITEfMB0GA1UEAwwWWXViaWNvIFBJViBBdHRlc3RhdGlvbjAgFw0xNjAzMTQwMDAw
MDBaGA8yMDUyMDQxNzAwMDAwMFowJTEjMCEGA1UEAwwaWXViaUtleSBQSVYgQXR0
ZXN0YXRpb24gOWUwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAT1l76Mvo6dJ4CwX2QQ
HImYRWbxLqt1kCVsn0PUn20DYtSKLuq8kCnMAn+kdneqjtaaBmWuPJH+g7LMyI18
QDQp2w+qSOf9ZWrOupMAGM8EpWXNTSNKoE50JhKXFbudBByjTjBMMBEGCisGAQQB
gsQKAwMEAwUBAjAUBgorBgEEAYLECgMHBAYCBACDq1IwEAYKKwYBBAGCxAoDCAQC
AQIwDwYKKwYBBAGCxAoDCQQBBDANBgkqhkiG9w0BAQsFAAOCAQEAGSmu0PUMDfEb
PkmkJ/rKYvpOKhbmpryjXuZ7ENJ3jGq3foyLSN+aBbd3M1im2ejC6/upthcp1N5M
Mg2SN6MBRS4crtt43DVHepBPt2W07vW8h4uFosJX29HdhK0dP+RnBGDdWYo0nq7y
7q1Y1c0BI7oGnaORL0DzSDtdxAJAphjspWsWNCIP2DTWQPhLTg4DqmYd/ahygVsZ
IE64QvJDQC72Dfyad6tIajmtPncqPt857H0hEJv2X58iOoJA/wAeuId4or859cJU
GTDbN7Ke4LWXRbs7StJTgefmNgWmKjm1Q2qs80WGShyQ6OrxALejd8jivtcTwsDz
WvzdmHCOmg==
-----END CERTIFICATE-----

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

Используйте отпечаток сертификата, чтобы сообщить git, какой сертификат использовать при подписании коммитов и тегов:

FINGERPRINT=`pivit --print | head -1`
git config --(local|global) user.signingkey $FINGERPRINT

Подпись

pivit -s [-a] [-b] [-u userid] [--status-fd=[num]] [-t url] [file]

-a (--armor) — определяет, следует ли обернуть подпись в ASCII armor для возможности её печати.
-b (--detach-sign) — создаёт отсоединённую (detached) подпись.
-u (--local-user) — либо адрес электронной почты, либо отпечаток ключа, закодированный в виде шестнадцатеричной строки.
Этот идентификатор определяет, какой сертификат использовать. Если указан адрес электронной почты, выполняется поиск сертификата, содержащего данный адрес.
Если указан отпечаток ключа, выполняется поиск сертификата, чья SHA1-контрольная сумма совпадает с указанной шестнадцатеричной строкой.
--status-fd — файловый дескриптор для вывода статусных сообщений. 1 — stdout, 2 — stderr.
Любое значение 0 или ниже означает, что статусные сообщения выводиться не будут.
-t (--timestamp-authority) — URL службы меток времени RFC3161, используемой для проставления метки времени.

Эта команда вызовет мигание Yubikey и будет блокировать выполнение, пока к нему не прикоснутся.

Когда git настроен на подпись коммитов и тегов, он будет использовать следующие жёстко заданные параметры: -sbau [user.signingkey] --status-fd=1.
user.signingkey берётся из локальной/глобальной конфигурации git.

Примечание: Pivit был разработан для поддержки подписи git-коммитов.
Но если используемый ключ был создан с параметром --pin-policy=always, полная поддержка может отсутствовать.
Сейчас Pivit запрашивает PIN-код только через командную строку. Если вы используете git-клиенты с графическим интерфейсом, такие как GitKraken или SourceTree, вы, скорее всего, пропустите этот запрос.

Проверка подписи

pivit --verify [file ...]

Проверяет подписанные данные, указанные в аргументе(ах) file.

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

В противном случае предполагается, что первый файл содержит подпись, а второй — подписанные данные.
Укажите -, чтобы обозначить, что подписанные данные должны читаться из stdin.

pivit

Популярное