Pivit

Pivit è uno strumento da riga di comando per gestire certificati x509 memorizzati su smart card con supporto per l'applet PIV (Yubikey), e per utilizzare tali certificati per firmare e verificare dati.

È completamente compatibile con il modo in cui la riga di comando di git chiama programmi esterni per firmare e verificare commit e tag.

Installazione

Brew

brew install pivit

Go install

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

Utilizzo

Per configurare git per usare pivit per firmare e verificare le firme, esegui i seguenti comandi:

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

Reimposta e inizializza il PIV della Yubikey

pivit --reset

Reimposta l'applet PIV della Yubikey e crea un nuovo PIN per accedervi.

Genera un certificato

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

Genera una nuova coppia di chiavi nello slot di autenticazione della carta della Yubikey.
Questo comando genererà e memorizzerà anche un certificato x509 per la chiave generata, firmato da Yubico.

Se viene fornita l'opzione --p256, la coppia di chiavi viene generata utilizzando la curva ellittica P-256. Altrimenti, viene utilizzata la curva P-384.

Aggiungi il flag --self-sign per generare un certificato autofirmato; il certificato viene firmato con la chiave appena generata.
Ti verrà chiesto di confermare che un certificato autofirmato sia davvero desiderato, poi ti verrà chiesto il PIN, e infine ti verrà chiesto di toccare la tua Yubikey.
L'output conterrà 3 blocchi CERTIFICATE invece di un CERTIFICATE_REQUEST alla fine (esempio di output sotto).
Questa opzione è utile soprattutto per scopi di test. Il flag --assume-yes può essere usato in combinazione con l'opzione --self-sign per disabilitare la relativa richiesta s/n.

Aggiungi il flag --no-csr per saltare la stampa della richiesta di firma del certificato. In questo caso, non ti verrà chiesto di toccare la tua Yubikey.
Questa opzione è utile se non hai bisogno che la chiave generata faccia parte di una PKI esistente.
Puoi comunque verificare il certificato della chiave utilizzando il certificato di Yubico qui.

Il flag --pin-policy controlla quando richiedere un PIN per accedere alla chiave generata.
Impostalo su uno tra never, once o always (il valore predefinito è never).

Il flag --touch-policy controlla quando richiedere di toccare fisicamente l'hardware per accedere alla chiave generata.
Impostalo su uno tra never, cached o always (il valore predefinito è always).

L'output del comando sarà simile al seguente:

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-----

La CERTIFICATE REQUEST alla fine è firmata dalla nuova chiave privata generata, e può essere utilizzata per emettere un certificato firmato da una CA.

Se scegli di emettere e utilizzare il tuo certificato, è importante verificare anche che:

Il certificato di attestazione del dispositivo sia firmato da Yubico.
Il certificato della chiave sia firmato dal certificato di attestazione del dispositivo.
La chiave pubblica nella richiesta di firma del certificato sia la stessa della chiave pubblica nel certificato della chiave.

Parametri della richiesta di certificato

Pivit consente di impostare diversi attributi nella CSR tramite variabili d'ambiente.

Le seguenti opzioni del certificato verranno impostate come segue:

Subject.CommonName sarà impostato sul valore della variabile d'ambiente PIVIT_EMAIL.
Subject.Organization sarà impostato sul valore della variabile d'ambiente PIVIT_ORG.
Subject.OrganizationalUnit sarà impostato sul valore della variabile d'ambiente PIVIT_ORG_UNIT.

Inoltre, i seguenti Subject Alternative Name (SAN) saranno inclusi nella richiesta di certificato:

Indirizzi email includeranno PIVIT_EMAIL
URI includeranno tutti gli URL specificati nella variabile d'ambiente PIVIT_CERT_URIS (gli URI sono separati da uno spazio)

Supporto per gli slot PIV

Il modulo PIV supporta più slot in cui è possibile memorizzare chiavi e certificati.
Slot disponibili - 9a, 9c, 9d e 9e.

9e è lo slot "Card Authentication" (autenticazione della carta).
È l'unico slot che non richiede un PIN per accedere alla chiave privata quando si firma con esso, riducendo così l'attrito nell'utilizzo.
9a è lo slot "Authentication" (autenticazione). Utilizzato per azioni come l'accesso al sistema.
9c è lo slot "Digital Signature" (firma digitale). Utilizzato per la firma di documenti, o per firmare file ed eseguibili.
9d è lo slot "Key Management" (gestione delle chiavi). Utilizzato per cose come la crittografia di e-mail o file a scopo di riservatezza.

Per maggiori informazioni

pivit consente di scegliere uno slot usando il flag -w.
Per ogni comando, se non viene specificato alcuno slot, viene usato 9e per impostazione predefinita.
Per esempio:

Generazione del certificato
```
pivit --generate [-w slot]
```
Firma
```
pivit -s -u userid [-w slot]
```
Stampa di un certificato
```
pivit --print [-w slot]
```

Specificare una Yubikey tramite numero di serie

Per impostazione predefinita, pivit prevede che sia collegata una singola Yubikey. Se un sistema ha più lettori di carte o più Yubikey, o semplicemente per garantire che pivit stia comunicando con la Yubikey desiderata, specifica il numero di serie tramite la variabile d'ambiente PIVIT_YK_SERIAL.

Esempio:

PIVIT_YK_SERIAL=13078292 pivit --print

Questo può essere usato con qualsiasi comando.

Importare un certificato nella Yubikey

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

Importa un certificato da file.
Il nome file fornito deve contenere un certificato x509 serializzato codificato come blocco PEM.

Questa azione richiede il PIN della Yubikey.

Aggiungi --first-pem per importare il primo blocco PEM da file, ignorando il resto. È utile se si utilizza una CA che fornisce i certificati emessi come catena o bundle, con il certificato dell'entità finale per primo (questa è la convenzione).

Stampa le informazioni del certificato

pivit --print

Stampa il certificato memorizzato nello slot di autenticazione della carta della Yubikey, insieme alla sua impronta.
Per esempio:

> 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'impronta del certificato viene calcolata eseguendo un checksum SHA1 sui byte grezzi del certificato e codificando poi il checksum come stringa esadecimale.

Utilizza l'impronta del certificato per far sapere a git quale certificato usare quando firmi commit e tag:

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

Firma

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

-a (--armor) - se avvolgere la firma in ASCII armor per renderla stampabile.
-b (--detach-sign) - crea una firma distaccata.
-u (--local-user) - un indirizzo email o un'impronta della chiave codificata come stringa esadecimale.
Questo identificatore determina quale certificato usare. Se viene fornito un indirizzo email, cerca un certificato che contenga l'indirizzo specificato.
Se viene fornita un'impronta della chiave, cerca un certificato il cui checksum SHA1 corrisponda alla stringa esadecimale data.
--status-fd - descrittore di file su cui emettere i messaggi di stato. 1 è stdout, 2 è stderr.
Qualsiasi valore 0 o inferiore significa che non verrà scritto alcun messaggio di stato.
-t (--timestamp-authority) - URL dell'autorità di timestamp RFC3161 da utilizzare per l'apposizione della marca temporale.

Questo comando farà lampeggiare la Yubikey e rimarrà in attesa finché non viene toccata.

Quando git è configurato per firmare commit e tag, userà i seguenti parametri fissi -sbau [user.signingkey] --status-fd=1.
user.signingkey viene preso dalla configurazione locale/globale di git.

Nota: Pivit è stato progettato per supportare la firma dei commit git.
Tuttavia, se la chiave in uso è stata creata con --pin-policy=always, potrebbe non essere completamente supportata.
Al momento, Pivit richiede il PIN solo tramite riga di comando. Se si utilizzano client git basati su GUI come GitKraken o SourceTree, probabilmente quella richiesta non verrà vista.

Verifica della firma

pivit --verify [file ...]

Verifica i dati firmati specificati negli argomenti file.

Se non viene specificato alcun file, legge da stdin.
Se viene specificato uno o nessun percorso file, presuppone che la firma sia allegata ai dati firmati.

Altrimenti, presuppone che il primo file contenga la firma e il secondo i dati firmati.
Specifica - per indicare che i dati firmati devono essere letti da stdin.

pivit

Più Popolari