# Sign an image

Trust a cosign key or a notation certificate, sign an image, and see whether the registry verifies the signature.

Signatures and SBOMs are stored as referrers of the image they describe. The registry checks
signatures itself, against the keys your organization trusts. Replace
org-example1234.ecr.example.com with your registry host, repository-id with the
repository's id and manifest-id with the image's id (`manifest.id` in
the output of `dcloud ecr images list`).

## Prerequisites

- Permission for `ecr:CreateSigningKey` to trust a key, `ecr:DeleteSigningKey` to stop trusting
  one. To open the console's **Signing** page, `ecr:GetSigningPolicy`; without it the page shows a
  refusal.
- To see an image's signatures: `ecr:DescribeImageSignatures` on the repository (and in the
  console `ecr:DescribeRepositories` on it, without which its page answers 404).
- Permission to push to the repository, for the signature itself.
- The organization is below its signing-key quota (see [Quotas](quotas.md)).

## Step 1: Trust a key

**Console**
1. Open **Container registry**, then choose **Signing**.
2. Under **Trust a key**, for **Name**, enter a name such as `release`.
3. For **Kind**, choose **cosign public key** or **notation certificate**.
4. (Optional) For **Repositories**, enter a pattern such as `team/*` instead of `*`.
5. Paste the PEM text, then choose **Trust key**.

**CLI**
```sh
dcloud ecr signing add-key --name release --kind cosign --pem @cosign.pub
```

**API**
```http
POST /ecr/api/signing-keys
{ "name": "release", "kind": "cosign", "pem": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----", "repositoryPattern": "*" }
```

**Terraform**
```hcl
resource "dcloud_ecr_signing_key" "release" {
  name = "release"
  kind = "cosign"
  pem  = file("cosign.pub")
}
```

A **cosign** key is the PEM public key (`cosign.pub`): ECDSA, RSA of at least 2048 bits, or
Ed25519. A **notation** entry is PEM certificates, a root, an intermediate or the signing
certificate itself, that a signature's certificate chain must reach. `repositoryPattern` (`*`
globs, `*` by default) limits which repositories a key vouches for.

## Step 2: Sign

```sh
cosign sign --key cosign.key org-example1234.ecr.example.com/my-app@sha256:<digest>
notation sign org-example1234.ecr.example.com/my-app@sha256:<digest>
oras attach --artifact-type application/spdx+json \
  org-example1234.ecr.example.com/my-app@sha256:<digest> sbom.spdx.json
```

cosign 2 and 3 are checked, in the tag and the referrer form; notation in its default JWS format.
cosign 3 also records the signature in the public Rekor transparency log unless you pass a
`--signing-config` without one; the registry does not need it.

## Step 3: See the result

**Console**
1. Open **Image repositories**, open the repository, then the **Signatures** tab.

It checks the newest 25 tagged images: **Signed** (a trusted key verifies a signature of this exact
digest), **Not by a trusted key**, or **Unsigned**, with each signature's format, status and why.

**CLI**
```sh
dcloud ecr signing verify repository-id manifest-id
```

**API**
```http
GET /ecr/api/repositories/repository-id/images/manifest-id/signatures
```

`status` is `signed`, `untrusted` or `unsigned`; each signature has a `status` of `verified`,
`untrusted`, `invalid` or `unsupported`, and `deployable` says whether the signing policy would let
the image deploy.

**Terraform:** not available. Verification is a read.

Keyless cosign signatures (Fulcio certificates) and notation's COSE format are stored but shown as
`unsupported`; sign notation with `--signature-format jws`.

## If it is refused

- `400` with why, when the PEM is not a usable key or certificate of that kind, such as
  `RSA keys must be at least 2048 bits`.
- `409` `A key with this name, or this key itself, is already trusted`.
- `409` with code `QuotaExceeded` at the signing-key quota.

## Related

- [Only deploy signed images](only-deploy-signed-images.md)
- `ecr.signing.add-key` · `dcloud ecr signing add-key` · `dcloud_ecr_signing_key`
