cashapp/pivitGérer les certificats x509 sur les YubiKeys compatibles PIV, générer des clés et des demandes de certificat, et signer ou vérifier les commits git et les fichiers.
Pivit est un outil en ligne de commande pour gérer les certificats x509 stockés sur des cartes à puce avec prise en charge de l'applet PIV (Yubikey), et pour utiliser ces certificats afin de signer et vérifier des données.
Il est entièrement compatible avec la manière dont la commande git appelle des programmes externes pour signer et vérifier les commits et les tags.
brew install pivit
go install github.com/cashapp/pivit/cmd/pivit@latest
Pour configurer git afin d'utiliser pivit pour signer et vérifier les signatures, exécutez les commandes suivantes :
git config --(local|global) gpg.format x509
git config --(local|global) gpg.x509.program pivit
pivit --reset
Réinitialise l'applet PIV de la Yubikey et crée un nouveau code PIN pour y accéder.
pivit --generate [--p256] [--self-sign | --no-csr] [--assume-yes] [--pin-policy] [--touch-policy]
Génère une nouvelle paire de clés dans le slot d'authentification de carte de la Yubikey.
Cette commande génère et stocke également un certificat x509 pour la clé générée, signé par Yubico.
Si l'option --p256 est fournie, la paire de clés est générée à l'aide de la courbe elliptique P-256.
Sinon, la courbe P-384 est utilisée.
Ajoutez l'option --self-sign pour générer un certificat auto-signé ;
le certificat est signé avec la clé nouvellement générée.
Vous serez invité à confirmer qu'un certificat auto-signé est réellement souhaité,
puis invité à saisir le code PIN, puis invité à toucher votre Yubikey.
La sortie contiendra 3 blocs CERTIFICATE au lieu d'un CERTIFICATE_REQUEST à la fin (exemple de sortie ci-dessous).
Cette option est utile principalement à des fins de test.
L'option --assume-yes peut être utilisée en combinaison avec l'option --self-sign pour désactiver son invite o/n.
Ajoutez l'option --no-csr pour ignorer l'impression de la demande de signature de certificat. Dans ce cas, vous ne serez pas invité à toucher votre Yubikey.
Cette option est utile si vous n'avez pas besoin que la clé générée fasse partie d'une PKI existante.
Vous pouvez toujours vérifier le certificat de la clé à l'aide du certificat de Yubico ici.
L'option --pin-policy contrôle le moment où le code PIN est demandé lors de l'accès à la clé générée.
Définissez-la sur never, once ou always (par défaut : never).
L'option --touch-policy contrôle le moment où un contact physique avec le matériel est demandé lors de l'accès à la clé générée.
Définissez-la sur never, cached ou always (par défaut : always).
La sortie de la commande ressemblera à ceci :
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-----
Le CERTIFICATE REQUEST à la fin est signé par la nouvelle clé privée générée,
et peut être utilisé pour émettre un certificat signé par une AC.
Si vous choisissez d'émettre et d'utiliser votre propre certificat, il est également important de vérifier que :
Pivit permet de définir différents attributs dans la CSR via des variables d'environnement.
Les options de certificat suivantes seront définies comme suit :
Subject.CommonName sera défini sur la valeur de la variable d'environnement PIVIT_EMAIL.Subject.Organization sera défini sur la valeur de la variable d'environnement PIVIT_ORG.Subject.OrganizationalUnit sera défini sur la valeur de la variable d'environnement PIVIT_ORG_UNIT.En outre, les Subject Alternative Names (SAN) suivants seront inclus dans la demande de certificat :
PIVIT_EMAILPIVIT_CERT_URIS (les URI sont séparées par une espace)Le module PIV prend en charge plusieurs slots où des clés et des certificats peuvent être stockés.
Slots disponibles - 9a, 9c, 9d et 9e.
9e est le slot "Card Authentication".9a est le slot "Authentication". Utilisé pour des actions comme la connexion au système.9c est le slot "Digital Signature". Utilisé pour la signature de documents, ou pour signer des fichiers et des exécutables.9d est le slot "Key Management". Utilisé pour des opérations comme le chiffrement d'e-mails ou de fichiers à des fins de confidentialité.Pour plus d'informations
pivit permet de choisir un slot à l'aide de l'option -w.
Pour chaque commande, si aucun slot n'est spécifié, 9e est utilisé par défaut.
Par exemple :
Génération de certificat
pivit --generate [-w slot]
Signature
pivit -s -u userid [-w slot]
Affichage d'un certificat
pivit --print [-w slot]
Par défaut, pivit s'attend à ce qu'une seule Yubikey soit connectée. Si un système possède plusieurs lecteurs de cartes ou plusieurs Yubikeys, ou
pour simplement s'assurer que pivit communique avec la Yubikey souhaitée, spécifiez le numéro de série via la variable d'environnement
PIVIT_YK_SERIAL.
Exemple :
PIVIT_YK_SERIAL=13078292 pivit --print
Cela peut être utilisé avec n'importe quelle commande.
pivit --import [--first-pem] [file]
Importe un certificat depuis file.
Le nom de fichier fourni doit contenir un certificat x509 sérialisé encodé en bloc PEM.
Cette action demande le code PIN de la Yubikey.
Ajoutez --first-pem pour importer le premier bloc PEM de file, en ignorant le reste. Ceci est utile si vous utilisez une AC qui
fournit ses certificats émis sous forme de chaîne ou de bundle, avec le certificat d'entité finale en premier (c'est la convention).
pivit --print
Affiche le certificat stocké dans le slot d'authentification de carte de la Yubikey, accompagné de son empreinte.
Par exemple :
> 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-----
L'empreinte du certificat est calculée en effectuant une somme de contrôle SHA1 sur les octets bruts du certificat, puis en encodant la somme de contrôle sous forme de chaîne hexadécimale.
Utilisez l'empreinte du certificat pour indiquer à git quel certificat utiliser lors de la signature des commits et des tags :
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) - indique s'il faut envelopper la signature dans une armure ASCII pour la rendre imprimable.-b (--detach-sign) - créer une signature détachée.-u (--local-user) - soit une adresse e-mail, soit une empreinte de clé encodée sous forme de chaîne hexadécimale.--status-fd - descripteur de fichier vers lequel émettre les messages de statut. 1 correspond à stdout, 2 à stderr.0 ou inférieure signifie qu'aucun message de statut ne sera écrit.-t (--timestamp-authority) - URL de l'autorité d'horodatage RFC3161 à utiliser pour l'horodatage.Cette commande fera clignoter la Yubikey et bloquera jusqu'à ce qu'elle soit touchée.
Lorsque git est configuré pour signer les commits et les tags, il utilisera les paramètres codés en dur suivants : -sbau [user.signingkey] --status-fd=1.
user.signingkey est tiré de la configuration locale/globale de git.
Remarque : Pivit a été conçu pour prendre en charge la signature des commits git.
Mais si la clé utilisée a été créée avec--pin-policy=always, elle peut ne pas être entièrement prise en charge.
Actuellement, Pivit ne demande le code PIN qu'en ligne de commande. Si vous utilisez des clients git basés sur une interface graphique comme GitKraken ou SourceTree, vous manquerez probablement cette invite.
pivit --verify [file ...]
Vérifie les données signées spécifiées dans le ou les arguments de fichier.
Si aucun fichier n'est spécifié, lit depuis stdin.
Si un ou aucun chemin de fichier n'est spécifié, considère que la signature est jointe aux données signées.
Sinon, considère que le premier fichier contient la signature et le second les données signées.
Spécifiez - pour indiquer que les données signées doivent être lues depuis stdin.
file - chemin vers le fichier qui sera signé. Si aucun nom de fichier n'est spécifié, utilisez stdin.