github.com/venafi-iw/cosign@v1.3.4/USAGE.md (about) 1 # Detailed Usage 2 3 ## Sign a container multiple times 4 5 Multiple signatures can be "attached" to a single container image: 6 7 ```shell 8 $ cosign sign --key cosign.key dlorenc/demo 9 Enter password for private key: 10 Pushing signature to: index.docker.io/dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig 11 12 $ cosign sign --key other.key dlorenc/demo 13 Enter password for private key: 14 Pushing signature to: index.docker.io/dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig 15 ``` 16 17 We only actually sign the digest, but you can pass by tag or digest. 18 19 The `-a` flag can be used to add annotations to the generated, signed payload. 20 This flag can be repeated: 21 22 ```shell 23 $ cosign sign --key other.key -a foo=bar dlorenc/demo 24 Enter password for private key: 25 Pushing signature to: index.docker.io/dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig 26 ``` 27 28 These values are included in the signed payload under the `Optional` section. 29 (More on this later): 30 31 ```json 32 "Optional":{"baz":"bat","foo":"bar"} 33 ``` 34 35 they can be verified with the `-a` flag to `cosign verify`. 36 37 ## Sign and upload a generated payload (in another format, from another tool) 38 39 The payload must be specified as a path to a file: 40 41 ```shell 42 $ cosign sign --key cosign.key --payload README.md dlorenc/demo 43 Using payload from: README.md 44 Enter password for private key: 45 Pushing signature to: index.docker.io/dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig 46 ``` 47 48 ## Signature Location and Management 49 50 Signatures are uploaded to an OCI artifact stored with a predictable name. 51 This name can be located with the `cosign triangulate` command: 52 53 ```shell 54 cosign triangulate dlorenc/demo 55 index.docker.io/dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig 56 ``` 57 58 They can be viewed with `crane`: 59 60 ```shell 61 crane manifest $(cosign triangulate gcr.io/dlorenc-vmtest2/demo) | jq . 62 { 63 "schemaVersion": 2, 64 "mediaType": "application/vnd.docker.distribution.manifest.v2+json", 65 "config": { 66 "mediaType": "application/vnd.docker.container.image.v1+json", 67 "size": 342, 68 "digest": "sha256:f5de0db6e714055d48b4bb3a374e9630c4923fa704d9311da6a2740cf625aaba" 69 }, 70 "layers": [ 71 { 72 "mediaType": "application/vnd.dev.cosign.simplesigning.v1+json", 73 "size": 210, 74 "digest": "sha256:1119abab63e605dcc281019bad0424744178b6f61ba57378701fe7391994c999", 75 "annotations": { 76 "dev.cosignproject.cosign/signature": "MEUCIG0ZmgqE3qTrHWp+HF9CrxsNH57Cck3cQI+zNNrUwSHfAiEAm+2eY/Z6ixQwjLbTraDN5ZB/P1Z5k/KwIoblry65r+s=" 77 } 78 }, 79 { 80 "mediaType": "application/vnd.dev.cosign.simplesigning.v1+json", 81 "size": 219, 82 "digest": "sha256:583246418c2afd5bfe29694793d07da37ffd552aadf8879b1d98047178b80398", 83 "annotations": { 84 "dev.cosignproject.cosign/signature": "MEUCIF/+szLKKA2q2+c86AXeWR7UeD5yYpW7p0waHordxNjhAiEAm5e+Hm7Jhv9JpSwHpTc6aGLSkL6/Acm/z+b8mhfGXqY=" 85 } 86 } 87 ] 88 } 89 ``` 90 91 Some registries support deletion too (DockerHub does not): 92 93 ```shell 94 $ cosign clean gcr.io/dlorenc-vmtest2/demo 95 ``` 96 97 ## Sign but skip upload (to store somewhere else) 98 99 The base64 encoded signature is printed to stdout. 100 This can be stored somewhere else. 101 102 ```shell 103 $ cosign sign --key key.pem --upload=false dlorenc/demo 104 Qr883oPOj0dj82PZ0d9mQ2lrdM0lbyLSXUkjt6ejrxtHxwe7bU6Gr27Sysgk1jagf1htO/gvkkg71oJiwWryCQ== 105 ``` 106 107 ## Generate the signature payload (to sign with another tool) 108 109 The json payload is printed to stdout: 110 111 ```shell 112 $ cosign generate dlorenc/demo 113 {"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8"},"Type":"cosign container image signature"},"Optional":null} 114 ``` 115 116 This can be piped directly into openssl: 117 118 ```shell 119 $ cosign generate dlorenc/demo | openssl... 120 ``` 121 122 ## Upload a generated signature 123 124 The signature is passed via the `--signature` flag. 125 It can be a file: 126 127 ```shell 128 $ cosign attach signature --signature file.sig dlorenc/demo 129 Pushing signature to: dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig 130 ``` 131 132 the base64-encoded signature: 133 134 ```shell 135 $ cosign attach signature --signature Qr883oPOj0dj82PZ0d9mQ2lrdM0lbyLSXUkjt6ejrxtHxwe7bU6Gr27Sysgk1jagf1htO/gvkkg71oJiwWryCQ== dlorenc/demo 136 Pushing signature to: dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def.sig 137 ``` 138 139 or, `-` for stdin for chaining from other commands: 140 141 ```shell 142 $ cosign generate dlorenc/demo | openssl... | cosign attach signature --signature -- dlorenc/demo 143 Pushing signature to: dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def.sig 144 ``` 145 146 ## Verifying claims 147 148 **Important Note**: 149 150 Signature payloads created by `cosign` included the digest of the container image they are attached to. 151 By default, `cosign` validates that this digest matches the container during `cosign verify`. 152 153 If you are using other payload formats with `cosign`, you can use the `--check-claims=false` flag: 154 155 ```shell 156 $ cosign verify --check-claims=false --key cosign.pub dlorenc/demo 157 Warning: the following claims have not been verified: 158 {"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8"},"Type":"cosign container image signature"},"Optional":null} 159 ``` 160 161 This will still verify the signature and payload against the supplied public key, but will not 162 verify any claims in the payload. 163 164 Annotations made in the original signature (`cosign sign -a foo=bar`) are present under the `Optional` section of the payload: 165 166 ```shell 167 $ cosign verify --key cosign.pub dlorenc/demo | jq . 168 { 169 "Critical": { 170 "Identity": { 171 "docker-reference": "" 172 }, 173 "Image": { 174 "Docker-manifest-digest": "97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36" 175 }, 176 "Type": "cosign container image signature" 177 }, 178 "Optional": { 179 "sig": "original" 180 } 181 } 182 ``` 183 184 These can be checked with matching `-a foo=bar` flags on `cosign verify`. 185 When using this flag, **every** specified key-value pair **must exist and match** in the verified payload. 186 The payload may contain other key-value pairs. 187 188 ```shell 189 # This works 190 $ cosign verify -a --key cosign.pub dlorenc/demo 191 {"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36"},"Type":"cosign container image signature"},"Optional":{"sig":"original"}} 192 193 # This works too 194 $ cosign verify -a sig=original --key cosign.pub dlorenc/demo 195 {"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36"},"Type":"cosign container image signature"},"Optional":{"sig":"original"}} 196 197 # This doesn't work 198 $ cosign verify -a sig=original -a=foo=bar --key cosign.pub dlorenc/demo 199 error: no matching claims: 200 invalid or missing annotation in claim: map[sig:original] 201 ``` 202 203 ## Download the signatures to verify with another tool 204 205 Each signature is printed to stdout in a json format: 206 207 ``` 208 $ cosign download signature us-central1-docker.pkg.dev/dlorenc-vmtest2/test/taskrun 209 {"Base64Signature":"Ejy6ipGJjUzMDoQFePWixqPBYF0iSnIvpMWps3mlcYNSEcRRZelL7GzimKXaMjxfhy5bshNGvDT5QoUJ0tqUAg==","Payload":"eyJDcml0aWNhbCI6eyJJZGVudGl0eSI6eyJkb2NrZXItcmVmZXJlbmNlIjoiIn0sIkltYWdlIjp7IkRvY2tlci1tYW5pZmVzdC1kaWdlc3QiOiI4N2VmNjBmNTU4YmFkNzliZWVhNjQyNWEzYjI4OTg5ZjAxZGQ0MTcxNjQxNTBhYjNiYWFiOThkY2JmMDRkZWY4In0sIlR5cGUiOiIifSwiT3B0aW9uYWwiOm51bGx9"} 210 ``` 211 212 ## Retrieve the Public Key From a Private Key or KMS 213 214 215 KMS: 216 ```shell 217 # Retrieve from Google Cloud KMS 218 $ cosign public-key --key gcpkms://projects/someproject/locations/us-central1/keyRings/foo/cryptoKeys/bug/versions/1 219 -----BEGIN PUBLIC KEY----- 220 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgrKKtyws86/APoULh/zXk4LONqII 221 AcxvLtLEgRjRI4TKnMAXtIGp8K4X4CTWPEXMqSYZZUa2I1YvHyLLY2bEzA== 222 -----END PUBLIC KEY----- 223 224 # Retrieve from HashiCorp Vault 225 $ cosign public-key --key hashivault://transit 226 -----BEGIN PUBLIC KEY----- 227 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgrKKtyws86/APoULh/zXk4LONqII 228 AcxvLtLEgRjRI4TKnMAXtIGp8K4X4CTWPEXMqSYZZUa2I1YvHyLLY2bEzA== 229 -----END PUBLIC KEY----- 230 ``` 231 232 Private Key: 233 ```shell 234 $ ./cosign public-key --key cosign.key 235 Enter password for private key: 236 -----BEGIN PUBLIC KEY----- 237 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEjCxhhvb1KmIfe1J2ceT25kHepstb 238 IDYuTA0U1ri4F0CXXazLiftzGlyfse1No4orr8w1ZIchQ8TJlyCSaSuR0Q== 239 -----END PUBLIC KEY----- 240 ``` 241 242 # Experimental Features 243 244 ## Verify a signature was added to the transparency log 245 There are two options for verifying a cosign signature was added to a transparency log: 246 1. Check the log to make sure the entry exists in the log 247 2. Use the `bundle` annotation on a cosign signature to verify an element was added to the log without hitting the log 248 249 The cosign `bundle` annotation contains a Signed Entry Timestamp (SET), which is conceptually similar to an SCT in a Web PKI system. 250 The SET is a signed inclusion promise provided by the transparency log, which acts as a guarantee by the log that an element has been included in it. 251 The SET can be verified with the logs public key and used to prove that an element is in the log without actually checking the log itself. 252 253 For more details on how the `bundle` annotation is formatted, see the cosign [spec](specs/SIGNATURE_SPEC.md). 254 255 To verify the `bundle` annotation, follow these steps: 256 1. Marshal the `bundle` Payload into JSON 257 1. Canonicalize the payload by following RFC 8785 rules 258 1. Verify the canonicalized payload and signedEntryTimestamp against the transparency logs public key