zot/pkg/meta/signatures/README.md

Verifying signatures

How to configure zot for verifying signatures

In order to configure zot for verifying signatures, the user should provide:

1. public keys (which correspond to the private keys used to sign images with cosign)

or

2. certificates (used to sign images with notation)

These files could be uploaded using one of these requests:

1. upload a public key

   Example of request

   curl --data-binary @file.pub -X POST "http://localhost:8080/v2/_zot/ext/mgmt?resource=signatures&tool=cosign"
   

2. upload a certificate

   Example of request

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

Besides the requested files, the user should also specify the tool which should be :

• cosign for uploading public keys
• notation for uploading certificates

Also, if the uploaded file is a certificate then the user should also specify the type of the truststore through truststoreType param and also its name through truststoreName param.

Based on the uploaded files, signatures verification will be performed for all the signed images. Then the information known 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

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": [
                    "*"
                ]
            }
        ]
    }