Testing Guide: rustls/upki

1. Service Reference Overview

Before beginning, here is a quick overview of the components managed by this package:

• upki-mirror
  • Timer: upki-mirror.timer
  • Service: upki-mirror.service
  • Default Data Location: /var/lib/upki-mirror
• upki (fetch)
  • Timer: upki-fetch.timer
  • Service: upki-fetch.service
  • Utility: upki (arg: fetch)
  • Configuration: /etc/xdg/upki/config.toml

2. Preparation & Installation

First, enable the Copr repository and install the required packages.

# Enable the repository
dnf copr enable fkrenzel/upki

# Install the client tool
dnf install upki

# Install the mirror tool (if you don't plan to use a public mirror)
dnf install upki-mirror

3. Configuring & Testing `upki-fetch`

Configure the fetch utility by editing the configuration file:

vim $(upki show-config-path)

Ensure the configuration looks similar to this. You can set fetch-url to a known public mirror, or point it to a local instance.

cache-dir = "/var/cache/upki"

[revocation]
fetch-url = "http://some-mirror/"

Test the Mirror URL

Verify that the manifest is reachable before fetching:

curl -I http://some-mirror/manifest.json

Fetch the Data

Run the fetch command manually to populate the cache directory:

upki fetch

Verify the cache directory was populated successfully. You should see a file tree resembling this:

/var/cache/upki/
└── revocation
    ├── 20260418-1-default.filter
    ├── 20260419-0-default.filter.delta
    ├── 20260419-1-default.filter.delta
    ├── 20260420-0-default.filter.delta
    ├── 20260420-1-default.filter.delta
    ├── 20260421-0-default.filter.delta
    └── manifest.json

(Optional) Start the timer service to enable periodic automated updates:

systemctl start upki-fetch.timer

Note: You can view all available commands by running man upki.

4. Testing Certificate Revocation Checks

Test the tool against known valid and revoked certificates.

Test a Valid Certificate

This should be valid at all times (though results may vary if Google rotates infrastructure unexpectedly):

curl -s -w '%{certs}' https://google.com | upki revocation check

Test a Revoked Certificate

At the time of writing, this DigiCert demo domain serves a revoked certificate:

curl -s -w '%{certs}' https://digicert-tls-ecc-p384-root-g5-revoked.chain-demos.digicert.com/ | upki revocation check

5. Testing Cache Integrity

Verify that upki correctly identifies and recovers from corrupted cache files.

First, intentionally corrupt one of the downloaded files (adjust the filename to match one currently in your cache):

echo "CORRUPTION_TEST" >> /var/cache/upki/revocation/20260421-0-default.filter.delta

Run the verify command:

upki verify

You should see an error output similar to:

Error: cache is outdated, 174297 bytes need downloading

To fix the corruption, simply run the fetch command again:

upki fetch

6. Testing `upki-mirror` (Server)

To test the mirror functionality, start the mirror timer or service. This will populate/update the /var/lib/upki-mirror directory.

# Start the automated timer
systemctl start upki-mirror.timer

# OR trigger a manual fetch
systemctl start upki-mirror.service

7. Nginx Minimal Mirror Setup (Testing Only)

If you want to test fetching from your own local upki-mirror instance, you can use this minimal Nginx configuration.

1. Create the Nginx Configuration

cat << 'EOF' > /etc/nginx/conf.d/upki-mirror.conf
server {
    listen 8080 default_server;
    listen [::]:8080 default_server;
    server_name _;

    root /var/lib/upki-mirror;

    # The manifest.json is the entry point for clients
    location / {
        index manifest.json;
        autoindex on;

        types {
            application/json json;
            application/octet-stream bin;
        }

        add_header Access-Control-Allow-Origin *;
    }
}
EOF

2. Verify and Start Nginx

# Check the config for syntax errors
nginx -t

# Start the Nginx service
systemctl start nginx

3. Test the Local Mirror

curl -I http://localhost:8080/manifest.json

Once verified, you can update your client configuration (/etc/xdg/upki/config.toml) to use your local mirror:

fetch-url = "http://localhost:8080/"