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