1## cosign sign
2
3Sign the supplied container image.
4
5### Synopsis
6
7Sign the supplied container image.
8
9Make sure to sign the image by its digest (@sha256:...) rather than by tag
10(:latest) so that you actually sign what you think you're signing! This prevents
11race conditions or (worse) malicious tampering.
12
13
14```
15cosign sign [flags]
16```
17
18### Examples
19
20```
21 cosign sign --key <key path>|<kms uri> [--payload <path>] [-a key=value] [--upload=true|false] [-f] [-r] <image digest uri>
22
23 # sign a container image with the Sigstore OIDC flow
24 cosign sign <IMAGE DIGEST>
25
26 # sign a container image with a local key pair file
27 cosign sign --key cosign.key <IMAGE DIGEST>
28
29 # sign a multi-arch container image AND all referenced, discrete images
30 cosign sign --key cosign.key --recursive <MULTI-ARCH IMAGE DIGEST>
31
32 # sign a container image and add annotations
33 cosign sign --key cosign.key -a key1=value1 -a key2=value2 <IMAGE DIGEST>
34
35 # sign a container image with a key stored in an environment variable
36 cosign sign --key env://[ENV_VAR] <IMAGE DIGEST>
37
38 # sign a container image with a key pair stored in Azure Key Vault
39 cosign sign --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] <IMAGE DIGEST>
40
41 # sign a container image with a key pair stored in AWS KMS
42 cosign sign --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] <IMAGE DIGEST>
43
44 # sign a container image with a key pair stored in Google Cloud KMS
45 cosign sign --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY]/versions/[VERSION] <IMAGE DIGEST>
46
47 # sign a container image with a key pair stored in Hashicorp Vault
48 cosign sign --key hashivault://[KEY] <IMAGE DIGEST>
49
50 # sign a container image with a key pair stored in a Kubernetes secret
51 cosign sign --key k8s://[NAMESPACE]/[KEY] <IMAGE DIGEST>
52
53 # sign a container image with a key, attaching a certificate and certificate chain
54 cosign sign --key cosign.key --cert cosign.crt --cert-chain chain.crt <IMAGE DIGEST>
55
56 # sign a container in a registry which does not fully support OCI media types
57 COSIGN_DOCKER_MEDIA_TYPES=1 cosign sign --key cosign.key legacy-registry.example.com/my/image@<DIGEST>
58
59 # sign a container image and upload to the transparency log
60 cosign sign --key cosign.key <IMAGE DIGEST>
61
62 # sign a container image and skip uploading to the transparency log
63 cosign sign --key cosign.key --tlog-upload=false <IMAGE DIGEST>
64
65 # sign a container image by manually setting the container image identity
66 cosign sign --sign-container-identity <NEW IMAGE DIGEST> <IMAGE DIGEST>
67
68 # sign a container image and honor the creation timestamp of the signature
69 cosign sign --key cosign.key --record-creation-timestamp <IMAGE DIGEST>
70```
71
72### Options
73
74```
75 --allow-http-registry whether to allow using HTTP protocol while connecting to registries. Don't use this for anything but testing
76 --allow-insecure-registry whether to allow insecure connections to registries (e.g., with expired or self-signed TLS certificates). Don't use this for anything but testing
77 -a, --annotations strings extra key=value pairs to sign
78 --attachment string DEPRECATED, related image attachment to sign (sbom), default none
79 --attachment-tag-prefix [AttachmentTagPrefix]sha256-[TargetImageDigest].[AttachmentName] optional custom prefix to use for attached image tags. Attachment images are tagged as: [AttachmentTagPrefix]sha256-[TargetImageDigest].[AttachmentName]
80 --certificate string path to the X.509 certificate in PEM format to include in the OCI Signature
81 --certificate-chain string path to a list of CA X.509 certificates in PEM format which will be needed when building the certificate chain for the signing certificate. Must start with the parent intermediate CA certificate of the signing certificate and end with the root certificate. Included in the OCI Signature
82 --fulcio-auth-flow string fulcio interactive oauth2 flow to use for certificate from fulcio. Defaults to determining the flow based on the runtime environment. (options) normal|device|token|client_credentials
83 --fulcio-url string address of sigstore PKI server (default "https://fulcio.sigstore.dev")
84 -h, --help help for sign
85 --identity-token string identity token to use for certificate from fulcio. the token or a path to a file containing the token is accepted.
86 --insecure-skip-verify skip verifying fulcio published to the SCT (this should only be used for testing).
87 --issue-certificate issue a code signing certificate from Fulcio, even if a key is provided
88 --k8s-keychain whether to use the kubernetes keychain instead of the default keychain (supports workload identity).
89 --key string path to the private key file, KMS URI or Kubernetes Secret
90 --oidc-client-id string OIDC client ID for application (default "sigstore")
91 --oidc-client-secret-file string Path to file containing OIDC client secret for application
92 --oidc-disable-ambient-providers Disable ambient OIDC providers. When true, ambient credentials will not be read
93 --oidc-issuer string OIDC provider to be used to issue ID token (default "https://oauth2.sigstore.dev/auth")
94 --oidc-provider string Specify the provider to get the OIDC token from (Optional). If unset, all options will be tried. Options include: [spiffe, google, github-actions, filesystem, buildkite-agent]
95 --oidc-redirect-url string OIDC redirect URL (Optional). The default oidc-redirect-url is 'http://localhost:0/auth/callback'.
96 --output-certificate string write the certificate to FILE
97 --output-payload string write the signed payload to FILE
98 --output-signature string write the signature to FILE
99 --payload string path to a payload file to use rather than generating one
100 --record-creation-timestamp set the createdAt timestamp in the signature artifact to the time it was created; by default, cosign sets this to the zero value
101 -r, --recursive if a multi-arch image is specified, additionally sign each discrete image
102 --registry-password string registry basic auth password
103 --registry-referrers-mode registryReferrersMode mode for fetching references from the registry. allowed: legacy, oci-1-1
104 --registry-token string registry bearer auth token
105 --registry-username string registry basic auth username
106 --rekor-url string address of rekor STL server (default "https://rekor.sigstore.dev")
107 --sign-container-identity string manually set the .critical.docker-reference field for the signed identity, which is useful when image proxies are being used where the pull reference should match the signature
108 --sk whether to use a hardware security key
109 --slot string security key slot to use for generated key (default: signature) (authentication|signature|card-authentication|key-management)
110 --timestamp-client-cacert string path to the X.509 CA certificate file in PEM format to be used for the connection to the TSA Server
111 --timestamp-client-cert string path to the X.509 certificate file in PEM format to be used for the connection to the TSA Server
112 --timestamp-client-key string path to the X.509 private key file in PEM format to be used, together with the 'timestamp-client-cert' value, for the connection to the TSA Server
113 --timestamp-server-name string SAN name to use as the 'ServerName' tls.Config field to verify the mTLS connection to the TSA Server
114 --timestamp-server-url string url to the Timestamp RFC3161 server, default none. Must be the path to the API to request timestamp responses, e.g. https://freetsa.org/tsr
115 --tlog-upload whether or not to upload to the tlog (default true)
116 --upload whether to upload the signature (default true)
117 -y, --yes skip confirmation prompts for non-destructive operations
118```
119
120### Options inherited from parent commands
121
122```
123 --output-file string log output to a file
124 -t, --timeout duration timeout for commands (default 3m0s)
125 -d, --verbose log debug output
126```
127
128### SEE ALSO
129
130* [cosign](cosign.md) - A tool for Container Signing, Verification and Storage in an OCI registry.
131
View as plain text