github.com/venafi-iw/cosign@v1.3.4/PKCS11.md (about)

     1  # PKCS11 Tokens
     2  
     3  The `cosign` command line tool optionally supports PKCS11 tokens for signing.
     4  This support is enabled through the [crypto11](https://github.com/ThalesIgnite/crypto11) and the [pkcs11](https://github.com/miekg/pkcs11) libraries, which are not included in the standard release. Use [`make cosign-pkcs11key`](https://github.com/sigstore/cosign/blob/a8d1cc1132d4a019a62ff515b9375c8c5b98a5c5/Makefile#L52), or `go build -tags=pkcs11key`, to build `cosign` with support for PKCS11 tokens.
     5  
     6  ## Quick Start
     7  
     8  ### Setup
     9  
    10  To get started, make sure you already have your PKCS11 module installed, and insert your PKCS11-compatible token.
    11  
    12  Then, run the command `cosign pkcs11-tool list-tokens` to get the slot id of your token, as follows :
    13  
    14  ```shell
    15  $ cosign pkcs11-tool list-tokens --module-path /usr/local/lib/libp11.so
    16  Listing tokens of PKCS11 module '/usr/local/lib/libp11.so'
    17  Token in slot 1
    18          Label: TokenLabel
    19          Manufacturer: Token Manufacturer
    20          Model: Token Model
    21          S/N: 68800ca5c75e074c
    22  ```
    23  
    24  Afterwards, run the command `cosign pkcs11-tool list-keys-uris` to retrieve the PKCS11 URI of the key you wish to use, as follows :
    25  
    26  ```shell
    27  $ cosign pkcs11-tool list-keys-uris --module-path /usr/local/lib/libp11.so --slot-id 1 --pin 1234
    28  Listing URIs of keys in slot '1' of PKCS11 module '/usr/local/lib/libp11.so'
    29  Object 0
    30          Label: key_label_1
    31          ID: 4a8d2f6ed9c4152b260d6c74a1ae72fcfdc64b65
    32          URI: pkcs11:token=TokenLabel;slot-id=1;id=%4a%8d%2f%6e%d9%c4%15%2b%26%0d%6c%74%a1%ae%72%fc%fd%c6%4b%65?module-path=/usr/local/lib/libp11.so&pin-value=1234
    33  Object 1
    34          Label: key_label_2
    35          ID: 57b39235cc6dec404c2310d7e37d5cbb5f1bba70
    36          URI: pkcs11:token=TokenLabel;slot-id=1;id=%57%b3%92%35%cc%6d%ec%40%4c%23%10%d7%e3%7d%5c%bb%5f%1b%ba%70?module-path=/usr/local/lib/libp11.so&pin-value=1234
    37  ```
    38  
    39  You can also construct the PKCS11 URI of your key manually by providing the following URI components :
    40  
    41  * **module-path** : the absolute path to the PKCS11 module **(optional)**
    42  
    43  * **token** and/or **slot-id** : either or both of the PKCS11 token label and the PKCS11 slot id **(mandatory)**
    44  
    45  * **object** and/or **id** : either or both of the PKCS11 key label and the PKCS11 key id **(mandatory)**
    46  
    47  * **pin-value** : the PIN of the PKCS11 token **(optional)**
    48  
    49  If `module-path` is not present in the URI, `cosign` expects the PKCS11 module path to be set using the environment variable `COSIGN_PKCS11_MODULE_PATH`. If neither are set, `cosign` will fail. If both are set, `module-path` has priority over `COSIGN_PKCS11_MODULE_PATH` environment variable.
    50  
    51  If `pin-value` is not present in the URI, `cosign` expects the PIN to be set using the environment variable `COSIGN_PKCS11_PIN`. If it is not, `cosign` checks whether the PKCS11 token requires user login (flag CKF_LOGIN_REQUIRED set), and if so, `cosign` will invite the user to enter the PIN only during signing. If both `pin-value` and `COSIGN_PKCS11_PIN` environment variable are set, `pin-value` has priority over `COSIGN_PKCS11_PIN`.
    52  
    53  ### Signing
    54  
    55  You can then use the normal `cosign` commands to sign images and blobs with your PKCS11 key.
    56  
    57  ```shell
    58  $ cosign sign --key "<PKCS11_URI>" gcr.io/dlorenc-vmtest2/demo
    59  Pushing signature to: gcr.io/dlorenc-vmtest2/demo:sha256-410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd.sig
    60  ```
    61  
    62  To verify, you can either use the PKCS11 token key directly:
    63  
    64  ```shell
    65  $ cosign verify --key "<PKCS11_URI>" gcr.io/dlorenc-vmtest2/demo
    66  Verification for gcr.io/dlorenc-vmtest2/demo --
    67  The following checks were performed on each of these signatures:
    68  - The cosign claims were validated
    69  - The signatures were verified against the specified public key
    70  - Any certificates were verified against the Fulcio roots.
    71  
    72  [{"critical":{"identity":{"docker-reference":"gcr.io/dlorenc-vmtest2/demo"},"image":{"docker-manifest-digest":"sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd"},"type":"cosign container image signature"},"optional":null}]
    73  ```
    74  
    75  Or export the public key and verify against that:
    76  
    77  ```shell
    78  $ cosign public-key --key "<PKCS11_URI>" > pub.key
    79  
    80  $ cosign verify --key pub.key gcr.io/dlorenc-vmtest2/demo
    81  Verification for gcr.io/dlorenc-vmtest2/demo --
    82  The following checks were performed on each of these signatures:
    83  - The cosign claims were validated
    84  - The signatures were verified against the specified public key
    85  - Any certificates were verified against the Fulcio roots.
    86  
    87  [{"critical":{"identity":{"docker-reference":"gcr.io/dlorenc-vmtest2/demo"},"image":{"docker-manifest-digest":"sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd"},"type":"cosign container image signature"},"optional":null}]
    88  
    89  ```