github.com/venafi-iw/cosign@v1.3.4/TOKENS.md (about) 1 # Hardware Tokens 2 3 The `cosign` command line tool optionally supports hardware tokens for signing and key management. 4 This support is enabled through the [PIV protocol](https://csrc.nist.gov/projects/piv/piv-standards-and-supporting-documentation) 5 and the [go-piv](https://github.com/go-piv/piv-go) library, which is not included in the standard release. Use [`make cosign-pivkey`](https://github.com/sigstore/cosign/blob/a8d1cc1132d4a019a62ff515b9375c8c5b98a5c5/Makefile#L52), or `go build -tags=pivkey`, to build `cosign` with support for hardware tokens. 6 7 --- 8 **NOTE** 9 10 `cosign`'s hardware token support requires `libpcsclite` on platforms other than Windows and OSX. 11 See [`go-piv`'s installation instructions for your platform.](https://github.com/go-piv/piv-go#installation) 12 13 --- 14 15 We recommend using an application provided by your hardware vendor to manage keys and permissions for advanced use-cases, but `cosign piv-tool` should work well for most users. 16 17 ## Quick Start 18 19 ### Setup 20 21 To get started, insert a key to your computer and run the `cosign generate-key` command. 22 We recommend using the `--random-management-key=true` flag. 23 24 This command generates a cryptographically-random management key and configures the device to use it. 25 This management key is destroyed, requiring a hardware reset to modify the signing key (this can be done with the `cosign piv-tool reset` command). 26 27 A signing key is generated on the hardware, and the resulting attestations are printed to stdout. 28 You do not need to save these, they can be retrieved later with the `cosign piv-tool attestation` command. 29 30 ```shell 31 $ cosign piv-tool generate-key --random-management-key 32 Resetting management key to random value. You must factory reset the device to change this value: y 33 Generating new signing key. This will destroy any previous keys.: y 34 Generated public key 35 -----BEGIN PUBLIC KEY----- 36 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEbZHvZgxjkqWlY865CPlmAqjLK6y 37 PhL+7MoxI3LLmO/gOhH8Q6elVcAZJgAUZY+GXlN0u1/TatI+sdw2DEQThw== 38 -----END PUBLIC KEY----- 39 40 Printing device attestation certificate 41 -----BEGIN CERTIFICATE----- 42 MIIC+jCCAeKgAwIBAgIJAJDjrwcvIYiiMA0GCSqGSIb3DQEBCwUAMCsxKTAnBgNV 43 BAMMIFl1YmljbyBQSVYgUm9vdCBDQSBTZXJpYWwgMjYzNzUxMCAXDTE2MDMxNDAw 44 MDAwMFoYDzIwNTIwNDE3MDAwMDAwWjAhMR8wHQYDVQQDDBZZdWJpY28gUElWIEF0 45 dGVzdGF0aW9uMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyS4ANsMp 46 RQA9cigP1oUG8yQ8tQkel2IergXvY9WSYy/muj30exFWXvO323i9RaQtoT7hOS5d 47 SsH1hNvSTD56fIaKpg+8jHsQLM6mF2Jo0Kb4rBduYNi+waFbGcwgrmRX1d9NcYb6 48 UDJt0o0RW6aGPY6wqUvMlIj0EwNIN7Ct1wSjIdL1qFmyVwUkQkPDd/0jDv7giE0P 49 M36qISQ6U8t2jNg5aWDEjf7wwWTIiMjbv0FaaiL5Vqmc7WboofKZN5nQyWGAtAtz 50 jTXzSkBfNPDO1eAUgbCbmu5efD8WeAtiPQyz8zQDU5UyihmDUEF1Dgr9/QMtQ5bd 51 Z+FkBTtBYFp4aQIDAQABoykwJzARBgorBgEEAYLECgMDBAMFAgYwEgYDVR0TAQH/ 52 BAgwBgEB/wIBADANBgkqhkiG9w0BAQsFAAOCAQEAQutaY0Wf/o2MPyRmsMM1QQuX 53 JI1ncaiDczWpFGj8YFUqlwLsEgYMzzGMrgPHIyE+CCgbYfyJu2mGU7goEHFq2/Ky 54 i8mjJtk/nVMF/m+dD7zbLvXPU0f9BKdpm1LUjC/YscvkFuI+sFrZvk8e1DAM49D5 55 Dm3MsEw9KjGhhTSv8iMoz9QMN7O1ozfsLTkj5eJQFEzkeUtgPxoJVnJqd4JkqnhF 56 ZoN7tG+9N6wouG5pCzOJDgraGwow11UdcheQze2SVktYcRdWVgr86YBiYdfAzkLz 57 FN4tXEiGuQyX6gWKBdd91niHF27RIWNGuz6X9KzMwgJ374n2ld8BiLg9PU30xA== 58 -----END CERTIFICATE----- 59 60 Printing key attestation certificate 61 -----BEGIN CERTIFICATE----- 62 MIICVTCCAT2gAwIBAgIQARbGLrd6RGhDODMN+neZczANBgkqhkiG9w0BAQsFADAh 63 MR8wHQYDVQQDDBZZdWJpY28gUElWIEF0dGVzdGF0aW9uMCAXDTE2MDMxNDAwMDAw 64 MFoYDzIwNTIwNDE3MDAwMDAwWjAlMSMwIQYDVQQDDBpZdWJpS2V5IFBJViBBdHRl 65 c3RhdGlvbiA5YzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABBG2R72YMY5KlpWP 66 OuQj5ZgKoyyusj4S/uzKMSNyy5jv4DoR/EOnpVXAGSYAFGWPhl5TdLtf02rSPrHc 67 NgxEE4ejTjBMMBEGCisGAQQBgsQKAwMEAwUCBjAUBgorBgEEAYLECgMHBAYCBADH 68 kP4wEAYKKwYBBAGCxAoDCAQCAwIwDwYKKwYBBAGCxAoDCQQBAzANBgkqhkiG9w0B 69 AQsFAAOCAQEAesDBFM7J67HCaJ6YzF2Ztz9UwQWVVid9AXG0b3rTdDBUAm85I+9a 70 zr8kS/adx2DKXQwQ2XTkSh4uMd4vVXMPr/MCiVzKzVnCgel1Fv97OaozpEicnTTn 71 0/cvf6NSdFeRDL06NBphp3gdWEkvuTb0LmCKnCldKbtGllK6yfZ/kVZexdnUrFIi 72 Hy45LclHKHKe3nveDD1WuGCpSABrxkx/BL/BNHB1y/gwiPHBFX+RShAtHwlW8uDK 73 g/8KdqKm021Eq/NJ+3WxINbRLFgYx8b+jTc7TE6ASNSNnbeG9UYlJ8kzfVII6C/4 74 H0RutMyJMyduyT5c8F3OmDY5FDdX1F1VRQ== 75 -----END CERTIFICATE----- 76 77 Verifying certificates... 78 Verified ok 79 80 Device info: 81 Issuer: CN=Yubico PIV Root CA Serial 263751 82 Form factor: unknown: 0 83 PIN Policy: Always 84 Serial number: 10550341 85 Version: 4.4.5 86 ``` 87 88 ### Signing 89 90 You can then use the normal `cosign` commands to sign images and blobs with your security key and PIN. 91 **NOTE**: The default PIN is `123456`. 92 93 ```shell 94 $ cosign sign --sk gcr.io/dlorenc-vmtest2/demo 95 Enter PIN for security key: 96 Please tap security key... 97 Pushing signature to: gcr.io/dlorenc-vmtest2/demo:sha256-410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd.sig 98 ``` 99 100 To verify, you can either use the hardware key directly: 101 102 ```shell 103 $ cosign verify --sk gcr.io/dlorenc-vmtest2/demo 104 105 Verification for gcr.io/dlorenc-vmtest2/demo -- 106 The following checks were performed on each of these signatures: 107 - The cosign claims were validated 108 - The signatures were verified against the specified public key 109 - Any certificates were verified against the Fulcio roots. 110 111 [{"critical":{"identity":{"docker-reference":"gcr.io/dlorenc-vmtest2/demo"},"image":{"docker-manifest-digest":"sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd"},"type":"cosign container image signature"},"optional":null}] 112 ``` 113 114 Or export the public key and verify against that: 115 116 ```shell 117 $ cosign public-key --sk > pub.key 118 119 $ cosign verify --key pub.key gcr.io/dlorenc-vmtest2/demo 120 121 Verification for gcr.io/dlorenc-vmtest2/demo -- 122 The following checks were performed on each of these signatures: 123 - The cosign claims were validated 124 - The signatures were verified against the specified public key 125 - Any certificates were verified against the Fulcio roots. 126 127 [{"critical":{"identity":{"docker-reference":"gcr.io/dlorenc-vmtest2/demo"},"image":{"docker-manifest-digest":"sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd"},"type":"cosign container image signature"},"optional":null}] 128 ``` 129 130 ## CLI Usage 131 132 ### Setup 133 134 The `cosign piv-tool reset` command will restore your device to factory defaults. 135 This will **DESTROY** any keys on the device, you cannot recover them. 136 137 The default management key, PIN and PUK will be configured after this command. 138 139 The `cosign piv-tool generate-key` command is used to provision a key compatible with `cosign` and the rest of `sigstore`. 140 We recommend using the `--random-management-key=true` flag. 141 142 ### Access Control 143 144 The management-key, PIN and PUK can all be configured with the `set-management-key`, `set-pin` and `set-puk` commands. 145 Leaving the `old-<type>` flag empty will result in the default value being used. 146 147 The PIN is used for signing, so you should set that to a value you can remember. 148 The PUK is used to reset the PIN in case you forget, without needing to regenerate the signing key. 149 150 We recommend configuring these after the initial setup and key generation. 151 152 ## Tested Devices 153 154 This set of commands has been tested against the following hardware: 155 156 * YubiKey 5C 157 * YuibiKey 5C Nano FIPS 158 * YubiKey 4 Series 159 160 **Note**: We aim to expand this list. 161 If you have hardware and can test it out, please send a PR with your results! 162 163 Tests can be run against a device with the following command. 164 **WARNING**: These tests will destroy any keys on your device. 165 166 ```shell 167 $ go test ./test -tags=resetyubikey,e2e -count=1 168 ``` 169 170 **WARNING**: These tests will destroy any keys on your device. 171 172 ## Attestations 173 174 There are two attestations available from the hardware key. 175 The first is the device attestation. 176 This can be used to verify the hardware is authentic and came from the manufacturer. 177 To verify this, retrieve the manufacturers CA. 178 See [here](https://developers.yubico.com/yubico-piv-tool/Attestation.html) for instructions from Yubico. 179 180 This certificate can be validated with `openssl` or other tooling: 181 182 ```shell 183 # Obtained from https://developers.yubico.com/PIV/Introduction/piv-attestation-ca.pem 184 $ echo '-----BEGIN CERTIFICATE----- 185 MIIDFzCCAf+gAwIBAgIDBAZHMA0GCSqGSIb3DQEBCwUAMCsxKTAnBgNVBAMMIFl1 186 YmljbyBQSVYgUm9vdCBDQSBTZXJpYWwgMjYzNzUxMCAXDTE2MDMxNDAwMDAwMFoY 187 DzIwNTIwNDE3MDAwMDAwWjArMSkwJwYDVQQDDCBZdWJpY28gUElWIFJvb3QgQ0Eg 188 U2VyaWFsIDI2Mzc1MTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMN2 189 cMTNR6YCdcTFRxuPy31PabRn5m6pJ+nSE0HRWpoaM8fc8wHC+Tmb98jmNvhWNE2E 190 ilU85uYKfEFP9d6Q2GmytqBnxZsAa3KqZiCCx2LwQ4iYEOb1llgotVr/whEpdVOq 191 joU0P5e1j1y7OfwOvky/+AXIN/9Xp0VFlYRk2tQ9GcdYKDmqU+db9iKwpAzid4oH 192 BVLIhmD3pvkWaRA2H3DA9t7H/HNq5v3OiO1jyLZeKqZoMbPObrxqDg+9fOdShzgf 193 wCqgT3XVmTeiwvBSTctyi9mHQfYd2DwkaqxRnLbNVyK9zl+DzjSGp9IhVPiVtGet 194 X02dxhQnGS7K6BO0Qe8CAwEAAaNCMEAwHQYDVR0OBBYEFMpfyvLEojGc6SJf8ez0 195 1d8Cv4O/MA8GA1UdEwQIMAYBAf8CAQEwDgYDVR0PAQH/BAQDAgEGMA0GCSqGSIb3 196 DQEBCwUAA4IBAQBc7Ih8Bc1fkC+FyN1fhjWioBCMr3vjneh7MLbA6kSoyWF70N3s 197 XhbXvT4eRh0hvxqvMZNjPU/VlRn6gLVtoEikDLrYFXN6Hh6Wmyy1GTnspnOvMvz2 198 lLKuym9KYdYLDgnj3BeAvzIhVzzYSeU77/Cupofj093OuAswW0jYvXsGTyix6B3d 199 bW5yWvyS9zNXaqGaUmP3U9/b6DlHdDogMLu3VLpBB9bm5bjaKWWJYgWltCVgUbFq 200 Fqyi4+JE014cSgR57Jcu3dZiehB6UtAPgad9L5cNvua/IWRmm+ANy3O2LH++Pyl8 201 SREzU8onbBsjMg9QDiSf5oJLKvd/Ren+zGY7 202 -----END CERTIFICATE-----' > yubico.crt 203 204 # Obtained from "cosign piv-tool attestation" (the first certificate) 205 $ echo '-----BEGIN CERTIFICATE----- 206 MIIC+jCCAeKgAwIBAgIJAJDjrwcvIYiiMA0GCSqGSIb3DQEBCwUAMCsxKTAnBgNV 207 BAMMIFl1YmljbyBQSVYgUm9vdCBDQSBTZXJpYWwgMjYzNzUxMCAXDTE2MDMxNDAw 208 MDAwMFoYDzIwNTIwNDE3MDAwMDAwWjAhMR8wHQYDVQQDDBZZdWJpY28gUElWIEF0 209 dGVzdGF0aW9uMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyS4ANsMp 210 RQA9cigP1oUG8yQ8tQkel2IergXvY9WSYy/muj30exFWXvO323i9RaQtoT7hOS5d 211 SsH1hNvSTD56fIaKpg+8jHsQLM6mF2Jo0Kb4rBduYNi+waFbGcwgrmRX1d9NcYb6 212 UDJt0o0RW6aGPY6wqUvMlIj0EwNIN7Ct1wSjIdL1qFmyVwUkQkPDd/0jDv7giE0P 213 M36qISQ6U8t2jNg5aWDEjf7wwWTIiMjbv0FaaiL5Vqmc7WboofKZN5nQyWGAtAtz 214 jTXzSkBfNPDO1eAUgbCbmu5efD8WeAtiPQyz8zQDU5UyihmDUEF1Dgr9/QMtQ5bd 215 Z+FkBTtBYFp4aQIDAQABoykwJzARBgorBgEEAYLECgMDBAMFAgYwEgYDVR0TAQH/ 216 BAgwBgEB/wIBADANBgkqhkiG9w0BAQsFAAOCAQEAQutaY0Wf/o2MPyRmsMM1QQuX 217 JI1ncaiDczWpFGj8YFUqlwLsEgYMzzGMrgPHIyE+CCgbYfyJu2mGU7goEHFq2/Ky 218 i8mjJtk/nVMF/m+dD7zbLvXPU0f9BKdpm1LUjC/YscvkFuI+sFrZvk8e1DAM49D5 219 Dm3MsEw9KjGhhTSv8iMoz9QMN7O1ozfsLTkj5eJQFEzkeUtgPxoJVnJqd4JkqnhF 220 ZoN7tG+9N6wouG5pCzOJDgraGwow11UdcheQze2SVktYcRdWVgr86YBiYdfAzkLz 221 FN4tXEiGuQyX6gWKBdd91niHF27RIWNGuz6X9KzMwgJ374n2ld8BiLg9PU30xA== 222 -----END CERTIFICATE-----' > device.crt 223 224 $ openssl verify -CAfile yubico.crt device.crt 225 device.crt: OK 226 ``` 227 228 The key attestation can be used to verify that the signing key was generated on the device, not loaded from an external source. 229 230 This can be verified against the device attestation cert, which forms a chain back to the manufacturer. 231 232 ```shell 233 # Use the same crt files from the previous step, create the CA chain 234 $ cat yubico.crt device.crt > chain.pem 235 236 # This cert was obtained from "cosign piv-tool attestation", the second cert 237 $ echo '-----BEGIN CERTIFICATE----- 238 MIICVTCCAT2gAwIBAgIQARF+TvIOm46Oc+FF3+YHITANBgkqhkiG9w0BAQsFADAh 239 MR8wHQYDVQQDDBZZdWJpY28gUElWIEF0dGVzdGF0aW9uMCAXDTE2MDMxNDAwMDAw 240 MFoYDzIwNTIwNDE3MDAwMDAwWjAlMSMwIQYDVQQDDBpZdWJpS2V5IFBJViBBdHRl 241 c3RhdGlvbiA5YzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABBG2R72YMY5KlpWP 242 OuQj5ZgKoyyusj4S/uzKMSNyy5jv4DoR/EOnpVXAGSYAFGWPhl5TdLtf02rSPrHc 243 NgxEE4ejTjBMMBEGCisGAQQBgsQKAwMEAwUCBjAUBgorBgEEAYLECgMHBAYCBADH 244 kP4wEAYKKwYBBAGCxAoDCAQCAwIwDwYKKwYBBAGCxAoDCQQBAzANBgkqhkiG9w0B 245 AQsFAAOCAQEAeT5EXMm1PfVImtFinOPUsVY4tq2mPaZQ67//OiPisuSaF90YJIRJ 246 PyndeKHDpscFwN1h8XhACb6e6XAyswB//qMdt+2VEeJCFatcuUHki4Vb8plRkZNU 247 IDTbnZ3TnqY9eH4POmbHS9MmsDJPBFqCAvbX4hgHOiYmpim2tf4U562LMzpYU44c 248 rb9ZMlAhjlOHgft02Gduv2DK1THfUacMYR1L0p9WgCaRKAlAWsvyl3Xmfjf3NRJT 249 gzHKg/sREq1fns6kff5rj0kqZhuuhSYfOrhS3pRbMOEcKksymBwYbQpEgJYJndwO 250 uCPMJZqsNyWMmfksjulR9XAQvBCImkXncw== 251 -----END CERTIFICATE-----' > key.crt 252 253 $ openssl verify -CAfile chain.pem key.crt 254 key.crt: OK 255 ```