# Collection Signing Stories

Diagram: https://www.xmind.net/m/jYMP8n
[](https://www.xmind.net/m/jYMP8n )

---

:::info
**PAH** = Private Automation Hub
**CAH** = Cloud Automation Hub
**Pulp** = Any topic or work to be developed on pulp upstream
:::

## Pulp

Related existing issues:

- As a user, I want to able to distinguish signed and unsigned Collections
- https://pulp.plan.io/issues/8049

### Pulp: Create Signature Content Type

- **What**: A pulp Content Type (Signature) to enable storing signatures along
with its metadata as part of a pulp repository.

  class ContentSignature(BaseModel):
      signature_file: FilePath
      metadata: JsonField
      content_id: Uuid = OneToOne(T[Collection, Container, ...])

- **Where**: Pulpcore or PulpAnsible (to be discussed)

https://pulp.plan.io/issues/9543

### Pulp: Api to surface signatures

:::warning
Alternative implementation: Surface the signature only as metadata on content API
:::

- **What**: A Viewset + serializer where clients go to fetch signatures for a specific related content
e.g:

  GET /api/signatures/collections/<id>

  {"signatures": [{"signature_file": "....", "metadata": "..."}]}

- **Where**: Pulpcore or PulpAnsible (to be discussed)
- **Depends on**:
- Pulp: Create Signature Content Type

https://pulp.plan.io/issues/9544

### Pulp: Import/export must include signatures

- **What**: import/export tooling needs to include related signatures for exported content.
- **Where**: Pulp Ansible
- **Depends on**
- Pulp: Create Signature Content Type

https://pulp.plan.io/issues/9545

### Pulp Ansible: Ensure sync takes signatures into account for comparison

- **What**: If for example a signature is corrupted on the source system, user may wamt to invalidate the current and create the signature again and then the clients will need to resync to fetch new signatures
- **Where**: Pulp Ansible
- **Depends on**
- Pulp: Create Signature Content Type

https://pulp.plan.io/issues/9546

---

## DOCS

EPIC: https://issues.redhat.com/browse/AAH-1031

### PAH: Document how users can create and configure custom signing service

- **What**: Post installation, users can define and configure a Signing service
using their own keys and signing script.
https://docs.pulpproject.org/pulpcore/workflows/signed-metadata.html#

    pulpcore-manager add-signing-service name key sign-script-executable

https://issues.redhat.com/browse/AAH-1051

### PAH: Document how users can manually sign a specific collection using API and UI

- **What**: Users may want to sign (or replace the existing signature) of a specific collection.
- **Depends on:**:
- "API: Create API to sign individual collection"
- "UI: Add a `sign` button to the collection view"

https://issues.redhat.com/browse/AAH-1052

---

## Installer

### PAH: Create a default signing service during installation.

- **When**: Install post task (pulp_installer.role.galaxy_postinstall)
If the user enabled this option on the main install playbook.

    vars: 
      create_default_collection_signing_service: true

- **How**: Installer will ship a simple **ASCIIArmoredSigningService** detached signing script and create a signing service named **"ansible-default"** (there will be a container-default in future), the installer will generate the key pairs necessary and based on configuration let those keys to be replaced.
- **Where**: Installers (pulp-installer, platform installer, galaxy_ng post install role)

https://issues.redhat.com/browse/AAH-1063

### PAH: Allow definition of which signing service to be used for the whole system

- **When**: Install post task (pulp_installer.role.galaxy_postinstall)
- **How**: Setting the key `COLLECTION_SIGNING_SERVICE="unique-name"` on `/etc/pulp/settings.py` or as equivalent environment variable.

    # setting.py
    COLLECTION_SIGNING_SERVICE="ansible-default"
    COLLECTION_SIGNING_ON_APPROVAL=True

- **Where**: Galaxy NG User settings

https://issues.redhat.com/browse/AAH-1064

### CAH: Configure rpm-sign based SigningService during installation

- **When**: During cloud deployment
- **How**:
1. Use `pulpcore-manager add-signing-service` to create a [`rpm-sign`](https://docs.engineering.redhat.com/display/PRODSEC/Signing+Server+User+Guide#SigningServerUserGuide-2.GoldandContainerReadyKeySigning) based signing service
2. And configure `settings.COLLECTION_SIGNING_SERVICE` pointing to that service.
- **Where**: Cloud installer

https://issues.redhat.com/browse/AAH-1065

---

## Backend tasks

:::danger
🛑 If the signing process fails it fails the whole approval process.
:::

### Create a task that will take an artifact and a signing service and perform the signature process.

https://issues.redhat.com/browse/AAH-1054

### PAH: Sign collections during approval process

- **When**: During "approval" task (regardless if is manual or auto approval)
or as a subtask in the same task group
if a `settings.COLLECTION_SIGNING_SERVICE` is defined.
- **How**:
1. Query pulp.**SigningService** to load the **pre-configured signing service**
2. If the collection artifact is stored in an **external storage** it needs to be
**downloaded locally in a temporary location**.
3. Invoke the `sign` method on the SigningService to produce the signature
Artifact for the collection content.
4. **Store the SignatureContentType** in the same repo where the
collection is included.
5. **Approve the collection and move to published repository**.
- **Where**: Galaxy NG Approval Task
- **Depends on**:
- "[Pulp] Create Signature Content Type"

https://issues.redhat.com/browse/AAH-1053

### CAH: Sign collections during certification process

- **When**: During Partner Engineer Certification process
assuming `settings.COLLECTION_SIGNING_SERVICE` points
to a RedHat Signing Server intance.

> Everything else is the same as `PAH: Sign collections during approval process`

- **Depends on**:
- "Pulp: Create Signature Content Type"
- CAH: Configure a rpm-sign SigningService during installation

https://issues.redhat.com/browse/AAH-1055

---

## API

### API: Surface collection signature and metadata on collection API

- **When**: If collection has signatures associated.
- **How**: Query the SignatureArtifact model and include its URL on CollectionSerializer ensure it is present on the APIs consumed by sync clients and ansible-galaxy cli.
- **Where**: GalaxyNG API
- **Depends on**:
- "Pulp: Create Signature Content Type"

https://issues.redhat.com/browse/AAH-1057

### API: Allow filtering signed collections

- **How/What**: Add a filter to collection viewset that allows filtering collections having a signature.
- **Where**: GalaxyNG API
- **Depends on**:
- "API: Surface collection signature and metadata on collection API"

https://issues.redhat.com/browse/AAH-1058

### API: Create API to sign individual or multiple collection versions

- **What**: User might need to sign individual collection, or to add additional signature or
To invalidate a signature on existing collection and providing a new signature.
- **How**: Via API user informs the collection to sign, which signing service to use for signature
The API spawns a signature task after checking the permissions to perform the signing.

  POST /v3/content/collections/<id>/<version>/sign/ -d ''{"signing_service":  "ansible-default"}'

- **Where**: GalaxyNG API
- **Depends on**:
- "Pulp: Create Signature Content Type"

https://issues.redhat.com/browse/AAH-1056

---

## UI

### UI: Show a badge on signed collections

- **When**: Collection has signature metadata
- **How/What**: Add a Verified Badge in collection view ✅ that distinguishes signed collections.
- **Where**: Ansible-Hub-UI
- **Depends on**:
- "API: Surface collection signature and metadata on collection API"

https://issues.redhat.com/browse/AAH-1059

### UI: Allow filtering signed collections

- **How/What**: Add dropdown filters to select signed collections only
- **Where**: Ansible Hub UI
- **Depends on**:
- "API: Allow filtering signed collections"

https://issues.redhat.com/browse/AAH-1060

### UI: Add signature download link with collection version download page

- **What**: Add a link to download the signature file for a signed collection
- **Where: Ansible Hub UI / Collection download page
- **Depends on**
- API: Surface collection signature and metadata on collection API

https://issues.redhat.com/browse/AAH-1061

### UI: Add a `sign` button to the collection view (for each version)

- **What**: Users mught need to sign a specific collection using the UI
The UI will show a button on colelction view and this button
opens a modal for the user to select a signing service and
perform the sign.
- **Where: Ansible Hub UI / Collection page
- **Depends on**
- API: Create API to sign individual collection

https://issues.redhat.com/browse/AAH-1062

---

## Questions

- Do we need to surface the Signing Service on API/UI?
- Admin user might want to check which signing service is configured without looking to the settings files
- Also might be useful to include that info on loggings and status apis.