Feature Overview (aka. Goal Summary)  

Extend oc-mirror v2 to mirror public keys necessary for signature verification, including Red Hat's public key for verifying Red Hat content and Rekor's public key for verifying signature transaction records. 

These keys will be made available offline alongside mirrored content, supporting secure offline verification scenarios, including those in sensitive environments requiring specific permissions for system-wide key storage.

Goals (aka. expected user outcomes)

• oc-mirror v2 can discover and mirror Rekor's public key required for verifying signature transaction records associated with mirrored content.

• When mirroring toDisk, oc-mirror v2 makes the mirrored public keys available locally within the mirror output directory structure.

• oc-mirror provides the mirrored public keys in a standard location within the output, enabling users with appropriate system permissions (e.g., root) to copy/move them to system trust stores under “/etc“ for offline verification if desired.

• Public key mirroring is an optional configuration to prevent potential failures related to key discovery or mirroring from blocking the overall image mirroring process.

Background

Building upon the Phase 1 OCPSTRAT-1869 work of mirroring images and their associated signatures (primarily using the Cosign tag convention), Phase 2 addresses the need for the public keys required to verify these signatures offline. 

Secure offline verification requires access to the trusted public keys corresponding to the private keys used for signing.  Red Hat content is signed by Red Hat's key, and SigStore workflows often optionally involve recording signature details in transparency logs like Rekor, which requires Rekor's key for verification.  

Providing these keys alongside the mirrored content helps enable signature verification in disconnected environments.  Handling system-level key storage (like in "/etc") for scenarios like enclave use cases introduces permission considerations that the tool needs to accommodate gracefully.

Requirements (aka. Acceptance Criteria):

• Public Key Discovery: Identify and locate the public keys associated with the content being mirrored, specifically:
  • Rekor's public key for verifying entries in the Rekor transparency log (relevant for verifying signature transaction records).

• • Keys should be discovered and prepared for mirroring alongside images and signatures.

• Public Key Mirroring (toDisk): Mirror the discovered public keys to the local file system within the oc-mirror output directory structure.
  • Keys must be placed in a well-defined, predictable location within the output directory (e.g., "output_dir/keys/").
  • The mirrored keys should be in a format suitable for verification tools (e.g., standard public key formats).
     

• Availability for Offline Verification & System Storage:
  • The mirrored public keys are available in the output directory for offline use.
  • Explain in the documentation to the users/admins that they need to manually copy the mirrored keys from the oc-mirror output directory to the appropriate system location (/etc/...) using commands with sufficient permissions (e.g., sudo cp) for system-wide offline verification.
    • oc-mirror itself will not attempt to write directly to /etc during a standard mirroring operation but only to make the keys available in the output.

• Public Key Mirroring Configuration: Provide a configuration option (e.g., in the imageset configuration file or via a command-line flag) to explicitly/optionally enable public key mirroring.  This allows users to optionally enable key mirroring (and not blocking the mirroring if key mirroring issues arise) or if they manage keys separately.

• Linking Public Key Mirroring to Signature Mirroring: Public key mirroring should be linked to signature mirroring.  If signature mirroring is disabled, public key mirroring could also be implicitly disabled (but can optionally be turned on by the configuration) since the primary use case is to verify mirrored signatures.

Open Questions:

• Red Hat's official public key:  Do we want to make oc-mirror v2 discover and mirror Red Hat's public key required for verifying Red Hat content signatures?  
  • This way, both Red Hat's official public key and Rekor's public key are output in the same predictable location within the output directory for verifying Red Hat content signatures and the signature transaction records.

Out-of-scope in Phase 2:

• Automatic "/etc" Placement by oc-mirror: oc-mirror will not automatically attempt to write public keys directly into system directories under “/etc“ during the mirroring operation.  This action requires elevated system privileges and is best handled by the admins as a separate step after mirroring is complete, utilizing the keys provided in the oc-mirror output.

• OCI 1.1 Referrer-based Discovery: While the mirrored keys are intended for use with signatures discovered via OCI 1.1 referrers in the future, the discovery mechanism itself (prioritizing OCI 1.1) is not part of this public key mirroring phase.  Key mirroring focuses on ensuring the necessary verification material is present regardless of the discovery method used for signatures.

• SigStore-style Attachments Mirroring (SBOMs, etc.): Mirroring other SigStore-style attachments besides signatures and keys remains out-of-scope for this specific public key phase.

Documentation Considerations

Provide information that needs to be considered and planned so that documentation will meet customer needs.  If the feature extends existing functionality, provide a link to its current documentation. Initial completion during Refinement status.

<your text here>