Image Signing
Relevant source files
The following files were used as context for generating this wiki page:
Image signing in Harbor ensures the authenticity and provenance of container images and OCI artifacts. By leveraging signing frameworks like Cosign and Notation (formerly Notary), Harbor allows users to verify that artifacts have not been tampered with and originate from a trusted source. This feature is integrated into Harbor's security policies, enabling administrators to enforce deployment restrictions based on the presence of valid signatures.
The project supports multiple signing methods, including the legacy Notary (Docker Content Trust) and modern OCI-native signing via Cosign. These signatures are treated as "Accessories" to the subject artifact, allowing Harbor to track the relationship between an image and its associated cryptographic proofs.
Sources: README.md:46-46, src/server/middleware/cosign/cosign.go:104-122, src/portal/src/i18n/lang/en-us-lang.json:1155-1165
Architectural Overview
Harbor's image signing architecture relies on middleware and background managers to detect, record, and validate signatures during artifact push and pull operations. Signatures are stored as independent OCI artifacts but are linked to their "subject" image through the Accessory model.
Signature Detection Flow
When an OCI manifest is pushed to Harbor, specialized middleware inspects the request path and manifest content to identify if the artifact is a signature (e.g., a .sig file for Cosign). If a signature is detected, Harbor creates an entry in the accessory database to link the signature to the subject artifact.
Signing Technologies
Harbor supports various signing standards, primarily categorized by how they interact with the OCI registry.
Cosign Integration
Cosign signatures are identified by a specific URL pattern ending in .sig or by OCI 1.1 subject fields. Harbor uses a SignatureMiddleware to capture these links. The middleware looks for the media type application/vnd.dev.cosign.simplesigning.v1+json within the manifest layers to confirm a valid Cosign signature.
Sources: src/server/middleware/cosign/cosign.go:42-45, src/server/middleware/cosign/cosign.go:115-125
Notation (Notary) Integration
Notation signatures provide OCI-native signing. Within the Harbor UI and API, these are presented alongside Cosign signatures under the "Accessories" tab of an artifact.
Sources: src/portal/src/i18n/lang/en-us-lang.json:1162-1164
Security Policies and Enforcement
Harbor allows project-level configuration to enforce content trust. These policies prevent the pulling or deployment of images that do not meet specific signing requirements.
| Policy Name | Description | Key Configuration |
|---|---|---|
| Content Trust | Prevents pulling unsigned images using legacy Notary. | enable_content_trust |
| Cosign Content Trust | Prevents pulling images without a valid Cosign signature. | enable_content_trust_cosign |
| Deployment Security | General toggle to allow only verified images to be deployed. | CONTENT_TRUST_POLICY |
Sources: api/v2.0/swagger.yaml:1665-1672, src/portal/src/i18n/lang/en-us-lang.json:285-285
Data Model and API
Accessory Model
Signatures are managed via the Accessory data structure, which maps the signature artifact to its subject.
| Field | Type | Description |
|---|---|---|
id | integer | Unique identifier for the accessory. |
artifact_id | integer | The ID of the signature artifact itself. |
subject_artifact_digest | string | The digest of the image being signed. |
type | string | Type of signature (e.g., cosign.signature). |
Sources: api/v2.0/swagger.yaml:3134-3170, src/server/middleware/cosign/cosign.go:136-144
Relevant API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/accessories | Lists all signatures and accessories for a specific artifact. |
GET | /projects/{project_name}/repositories/{repository_name}/artifacts/{reference} | Retrieves artifact details; can include signatures via with_signature=true. |
Sources: api/v2.0/swagger.yaml:784-825, api/v2.0/swagger.yaml:1062-1100
Implementation Details: Cosign Middleware
The SignatureMiddleware operates after a successful response (StatusCreated) is returned to the client. It performs the following logic:
- Pattern Matching: Validates if the request path matches
^/v2/.+/manifests/sha256-.+\.sig$. - Manifest Processing: Unmarshals the manifest body to verify the signature media type.
- Linkage: Queries the database for the subject artifact by digest and creates a new
AccessoryDatarecord with typemodel.TypeCosignSignature.
Sources: src/server/middleware/cosign/cosign.go:94-150, src/server/middleware/cosign/cosign.go:154-161
Conclusion
Image signing is a critical component of Harbor's "Trusted Cloud Native Registry" promise. By integrating modern OCI signing standards like Cosign and Notation into its middleware and data models, Harbor provides a robust framework for enforcing artifact integrity and security across the container lifecycle.
Sources: README.md:15-18, src/portal/src/i18n/lang/en-us-lang.json:673-673