How to Set Up a Third-Party Package Repository with GPG Signatures
Last modified: July 19, 2022
Third-party customers who want to create their own repositories must create digest files and GnuPG (GPG) signatures as well as the necessary package files.
Most of cPanel’s software dependencies ship as package archives. These packages download from the cPanel, L.L.C. repository during installations and updates. The repository is a collection of packages that exist on an accessible HTTP server. The
url_templates field in the
rpm.versions file determines the location of the packages on this server.
Each package directory contains a
sha512 digest file. This file lists the appropriate digest values for each of the directory’s packages. The cPanel, L.L.C update system uses the digest file to ensure the integrity of the downloaded files.
The system also creates a GPG signature with cPanel, L.L.C.’s private keys. It sends the signature with each of the digest files to make sure the files are legitimate. The signature also prevents any compromises on the download mirrors.
Set up a third-party repository with GPG signatures
Generate sha512 digest files
In each directory in the repository that contains package files, you must create a
sha512 digest file.
For example, consider the following directory, which contains these two package files:
To create the digest file for this directory, run the following command:
/home/www/thirdparty_pkg/11.92/centos/7/x86_64# sha512sum *.rpm > sha512
This file will contain a list of the package file digests:
On servers running the Ubuntu® operating system, replace the
.rpm filenames with
.deb package names.
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:
Sign the sha512 digest file
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 a
sha512file that exists at
http://example.com/pkg_repo/11.92/centos/7/x86_64/sha512, set the filename notation to
To sign the file in the previous examples, you would run the following command:
gpg –output sha512.asc -u "example_[email protected]" –armor –sig-notation "[email protected]=/thirdparty_pkg/11.92/centos/7/x86_64/sha512" –armor –detach-sign sha512
Add your key to the vendor keystore
In order to set up your cPanel & WHM servers to use the repository, you must add a copy of the public key that signed the packages to each cPanel & WHM server. This allows each cPanel & WHM server to verify the signed package digests.
To export the public key, run the following command:
gpg –output example_pkg_repo.pub.asc –armor –export
For the examples in this document, you could store this key as the
- You must store this key in a publicly web-accessible location.
- We strongly recommend that you store the key in a location that uses HTTPS/SSL verification and encryption.
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/pkg_repo/example_pkg_repo.pub.asc
Add the repository to the local versions file
To configure the system to use the repository’s public key, update the
For more information about this file, read our The
For more information about the
/scripts/update_local_rpm_versionsscript, which we strongly recommend for updates to the
local.versionsfile, read our The
Each package’s entry in the
local.versions file includes a corresponding
rpm_location entry. Each
rpm_location entry includes entries for
url_templatesentry contains the location of each package, which includes the operating system version, architecture, package name, package version, and package revision.
location_keysentry contains the vendor and category that you specified when you ran the
For the examples in this document, the
local.versions file might appear similar to the following example:
Repositories without GPG signatures
If you do not need or want to verify the signature on your packages, you can disable signature verification. To do this, add a
disabled entry for the desired package to the
location_keys section, as in the following example: