mirror of
https://github.com/project-zot/zot.git
synced 2026-06-17 21:17:58 +08:00
refactor(extensions)!: refactor the extensions URLs and errors (#1636)
BREAKING CHANGE: The functionality provided by the mgmt endpoint has beed redesigned - see details below BREAKING CHANGE: The API keys endpoint has been moved - see details below BREAKING CHANGE: The mgmt extension config has been removed - endpoint is now enabled by having both the search and the ui extensions enabled BREAKING CHANGE: The API keys configuration has been moved from extensions to http>auth>apikey mgmt and imagetrust extensions: - separate the _zot/ext/mgmt into 3 separate endpoints: _zot/ext/auth, _zot/ext/notation, _zot/ext/cosign - signature verification logic is in a separate `imagetrust` extension - better hanling or errors in case of signature uploads: logging and error codes (more 400 and less 500 errors) - add authz on signature uploads (and add a new middleware in common for this purpose) - remove the mgmt extension configuration - it is now enabled if the UI and the search extensions are enabled userprefs estension: - userprefs are enabled if both search and ui extensions are enabled (as opposed to just search) apikey extension is removed and logic moved into the api folder - Move apikeys code out of pkg/extensions and into pkg/api - Remove apikey configuration options from the extensions configuration and move it inside the http auth section - remove the build label apikeys other changes: - move most of the logic adding handlers to the extensions endpoints out of routes.go and into the extensions files. - add warnings in case the users are still using configurations with the obsolete settings for mgmt and api keys - add a new function in the extension package which could be a single point of starting backgroud tasks for all extensions - more clear methods for verifying specific extensions are enabled - fix http methods paired with the UI handlers - rebuild swagger docs Signed-off-by: Andrei Aaron <aaaron@luxoft.com>
This commit is contained in:
Andrei Aaron
@@ -0,0 +1,162 @@
|
||||
# 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:
|
||||
|
||||
```json
|
||||
"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***
|
||||
|
||||
```bash
|
||||
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***
|
||||
|
||||
```bash
|
||||
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***
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"trustPolicies": [
|
||||
{
|
||||
"name": "default-config",
|
||||
"registryScopes": [ "*" ],
|
||||
"signatureVerification": {
|
||||
"level" : "strict"
|
||||
},
|
||||
"trustStores": [],
|
||||
"trustedIdentities": [
|
||||
"*"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user