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