How to Set Up a Third-Party RPM Repository with GPG Signatures

Overview

In order for third-party customers to create their own RPM repositories, they must create digest files and GnuPG (GPG) signatures as well as the necessary RPM files.

Most of cPanel’s software dependencies ship as RPM archives. These RPMs download from the cPanel, L.L.C. RPM repository during installations and updates. The RPM repository is a collection of RPMs that exist on an accessible HTTP server. The url_templates field in the rpm.versions file determines the location of the RPMs on this server.

Each RPM directory contains an rpm.md5 or rpm.sha512 digest file, which contains the appropriate digest values for each of the directory’s RPMs. The cPanel, L.L.C. update system uses the digest file to ensure the integrity of downloaded files. In addition, a GPG signature, which the system creates with cPanel, L.L.C.’s private keys, accompanies each of these digest files to ensure the legitimacy of the files and to prevent the compromise of download mirrors.

Set up a third-party RPM repository with GPG signatures

Generate rpm sha512 digest files

In each directory in the repository that contains RPM files, you must create an rpm.sha512 digest file.

For example, consider the following directory, which contains two RPM files:

1
2
3
4

root@httpupdate1:/home/www/thirdparty_rpm/11.92/centos/7/x86_64# ls -l
total 6876
-rw-r--r-- 1 tux tux 6191460 Aug 12 18:57 cpanel-angularjs-1.4.3-1.cp1154.noarch.rpm
-rw-r--r-- 1 tux tux 843872 Sep 11 17:33 cpanel-angularjs-1.4.4-1.cp1154.noarch.rpm

To create the digest file for this directory, run the following command:

/home/www/thirdparty_rpm/11.92/centos/7/x86_64# sha512sum *.rpm > rpm.sha512

This file will contain a list of the RPM file digests:

1
2

01fe3fefade91693d2e03cd2f2a2cde7613e54586e994f3477658eefbe24c6ba0347129286789ad9fc8f1aa3f32859896aed16d39055031808eea057557691d2 cpanel-angularjs-1.4.3-1.cp1154.noarch.rpm
f91a02c9fd3ef6551809ebb23e726cbe460fa8c334f592f53c773cbccc1b0cede9d139386b7e60b91bf25cd640ce9ecfd948c077bac12d2d8e069ca08a257da2 cpanel-angularjs-1.4.4-1.cp1154.noarch.rpm

Generate a GPG key pair

After you create the digest file, create a GPG key pair in order to sign it. We recommend that you use the GPG command line utilities to generate the GPG key pair.

• We strongly recommend that you generate this key on a non-public system to protect the private key’s security.

• For more information, read the GnuPG documentation.

For example, to create a GPG key pair, you might run the following commands:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

root@httpupdate1:~# gpg --gen-key
gpg (GnuPG) 1.4.12; Copyright (C) 2012 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
Your selection? 4
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 2048
Requested keysize is 2048 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 1y
Key expires at Fri 11 Nov 2016 06:59:43 PM UTC
Is this correct? (y/N) y
You need a user ID to identify your key; the software constructs the user ID
from the Real Name, Comment and Email Address in this form:
    "Heinrich Heine (Der Dichter) <[email protected]>"
Real name: Example RPM Repo
Email address: example_rpm_repo@example.net
Comment: This is demonstrating the creationg of a third party cPanel RPM repository.
You selected this USER-ID:
    "Example RPM Repo (This is demonstrating the creationg of a third party cPanel RPM repository.) <[email protected]>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
You need a Passphrase to protect your secret key.
...
gpg: key 2A8507D6 marked as ultimately trusted
public and secret key created and signed.
gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: next trustdb check due at 2016-11-11
pub   2048R/2A8507D6 2015-11-12 [expires: 2016-11-11]
      Key fingerprint = A554 73AE 728E CBA9 8283  C6B3 4FE9 C226 2A85 07D6
uid                  Example RPM Repo (This is demonstrating the creationg of a third party cPanel RPM repository.) <example_rpm_repo@example.net>
Note that this key cannot be used for encryption.  You may want to use
the command "--edit-key" to generate a subkey for this purpose.

Sign the rpm.sha512 digest files

In order to prevent rollback, old version, or file-copy attacks, cPanel, L.L.C. uses a specific GPG signature notation that specifies the filename on the remote server.

• You must set this notation to use the public HTTP path for the file.

• For example, for an rpm.sha512 file that exists at http://example.com/rpm_repo/11.92/centos/7/x86_64/rpm.sha512, set the filename notation to /rpm_repo/11.92/centos/7/x86_64/rpm.sha512.

To sign the file in the previous examples, you would run the following command:

gpg --output rpm.sha512.asc -u "[email protected]" --armor --sig-notation "[email protected]=/thirdparty_rpm/11.92/centos/7/x86_64/rpm.sha512" --armor --detach-sign rpm.sha512

Add your key to the vendor keystore

In order to set up your cPanel & WHM servers to use the RPM repository, you must add a copy of the public key that signed the RPMs to each cPanel & WHM server. This allows each cPanel & WHM server to verify the signed RPM digests.

To export the public key, run the following command:

gpg --output example_rpm_repo.pub.asc --armor --export

For the examples in this document, you could store this key as the https://example.com/rpm_repo/example_rpm_repo.pub.asc file.

To add this key to the local system, run the following command, where thirdparty represents the vendor name and release represents the category:

/scripts/updatesigningkey --vendor thirdparty --category release --url https://example.com/rpm_repo/example_rpm_repo.pub.asc

Add the repository to the local versions file

To configure the system to use the RPM repository’s public key, update the /var/cpanel/rpm.versions.d/local.versions file.

• For more information about this file, read our The rpm.versions File documentation.

• For more information about the /scripts/update_local_rpm_versions script, which we strongly recommend for updates to the local.versions file, read our The update_local_rpm_versions Script documentation.

Each RPM entry in the local.versions file includes a corresponding rpm_location entry. Each rpm_location entry includes entries for url_templates and location_keys values.

• The url_templates entry contains the location of each RPM, which includes the operating system version, architecture, package name, package version, and package revision.
• The location_keys entry contains the vendor and category that you specified when you ran the /scripts/updatesigningkey script.

For the examples in this document, the local.versions file might appear similar to the following example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

---
file_format:
  version: 2
install_targets: {}
location_keys:
  thirdparty_rpm:
    categories:
      - release
    vendor: thirdparty
rpm_groups: {}
rpm_locations:
  cpanel-angularjs: thirdparty_rpm
srpm_sub_packages: {}
srpm_versions:
  cpanel-angularjs: 1.4.4-1.cp1154
target_settings: {}
url_templates:
  thirdparty_rpm: 'http://example.com/rpm_repo/11.92/centos/[% rpm_dist_ver %]/[% rpm_arch %]/[% package %]-[% package_version %]-[% package_revision %].noarch.rpm'

RPM repositories without GPG signatures

If you do not need or want to verify the signature on your RPMs, you can disable signature verification. To do this, add a disabled entry for the desired RPM to the location_keys section, as in the following example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

---
file_format:
  version: 2
install_targets: {}
location_keys:
  thirdparty_rpm:
    disabled: 1
rpm_groups: {}
rpm_locations:
  cpanel-angularjs: thirdparty_rpm
srpm_sub_packages: {}
srpm_versions:
  cpanel-angularjs: 1.4.4-1.cp1154
target_settings: {}
url_templates:
  thirdparty_rpm: 'http://example.com/rpm_repo/11.92/centos/[% rpm_dist_ver %]/[% rpm_arch %]/[% package %]-[% package_version %]-[% package_revision %].noarch.rpm'