zot/pkg/extensions/README_imagetrust.md

Image Trust

The imagetrust extension provides a mechanism to verify image signatures using certificates and public keys

How to configure zot for verifying signatures

In order to configure zot for verifying signatures, the user should first enable this feature:

    "extensions": {
        "trust": {
            "enable": true,
            "cosign": true,
            "notation": true
        }
    }

In order for verification to run, the user needs to enable at least one of the cosign or notation options above.

Uploading public keys or certificates

Next the user needs to upload the keys or certificates used for the verification.

Supported queries	Input	Output	Description
Upload a certificate	certificate	None	Add certificate for verifying notation signatures
Upload a public key	public key	None	Add public key for verifying cosign signatures

Uploading a Cosign public key

The Cosign public keys uploaded correspond to the private keys used to sign images with cosign.

Example of request

curl --data-binary @file.pub -X POST "http://localhost:8080/v2/_zot/ext/cosign

As a result of this request, the uploaded file will be stored in _cosign directory under the rootDir specified in the zot config.

Uploading a Notation certificate

Notation certificates are used to sign images with the notation tool. The user needs to specify the type of the truststore through the truststoreType query parameter and its name through the truststoreName parameter. truststoreType defaults to ca, while truststoreName is a mandatory parameter.

Example of request

curl --data-binary @certificate.crt -X POST "http://localhost:8080/v2/_zot/ext/notation?truststoreType=ca&truststoreName=upload-cert"

As a result of this request, the uploaded file will be stored in _notation/truststore/x509/{truststoreType}/{truststoreName} directory under the rootDir specified in the zot config. The truststores field found in _notation/trustpolicy.json file will be updated automatically as well.

Verification and results

Based on the uploaded files, signatures verification will be performed for all the signed images. The information determined about the signatures will be:

• the tool used to generate the signature (cosign or notation)

• info about the trustworthiness of the signature (if there is a certificate or a public key which can successfully verify the signature)

• the author of the signature which will be:

  • the public key -> for signatures generated using cosign
  • the subject of the certificate -> for signatures generated using notation

The information above will be included in the ManifestSummary objects returned by the search extension.

Example of GraphQL output

{
    "data": {
        "Image": {
            "Manifests": [
                {
                    "Digest":"sha256:6c19fba547b87bde9a45df2f8563e0c61826d098dd30192a2c8b86da1e1a6360"
                }
            ],
            "IsSigned": true,
            "Tag": "latest",
            "SignatureInfo":[
                {
                    "Tool":"cosign",
                    "IsTrusted":false,
                    "Author":""
                },
                {
                    "Tool":"cosign",
                    "IsTrusted":false,
                    "Author":""
                },
                {
                    "Tool":"cosign",
                    "IsTrusted": true,
                    "Author":"-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9pN+/hGcFlh4YYaNvZxNvuh8Qyhl\npURz77qScOHe3DqdmiWiuqIseyhEdjEDwpL6fHRwu3a2Nd9wbKqm0la76w==\n-----END PUBLIC KEY-----\n"
                },
                {
                    "Tool":"notation",
                    "IsTrusted": false,
                    "Author":"CN=v4-test,O=Notary,L=Seattle,ST=WA,C=US"
                },
                {
                    "Tool":"notation",
                    "IsTrusted": true,
                    "Author":"CN=multipleSig,O=Notary,L=Seattle,ST=WA,C=US"
                }
            ]
        }
    }
}

Notes

• The files (public keys and certificates) uploaded using the exposed routes will be stored in some specific directories called _cosign and _notation under $rootDir.

  • _cosign directory will contain the uploaded public keys

    _cosign
    ├── $publicKey1
    └── $publicKey2
    

  • _notation directory will have this structure:

    _notation
    ├── trustpolicy.json
    └── truststore
        └── x509
            └── $truststoreType
                └── $truststoreName
                    └── $certificate
    

    where trustpolicy.json file has this default content which can not be modified by the user and which is updated each time a new certificate is added to a new truststore:

    {
        "version": "1.0",
        "trustPolicies": [
            {
                "name": "default-config",
                "registryScopes": [ "*" ],
                "signatureVerification": {
                    "level" : "strict" 
                },
                "trustStores": [],
                "trustedIdentities": [
                    "*"
                ]
            }
        ]
    }