Last modified: February 22, 2024

Overview

Most of cPanel’s software dependencies ship as package archives. These packages download from the WebPros International, LLC 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 WebPros International, LLC update system uses the digest file to ensure the integrity of the downloaded files.

The system also creates a GPG signature with WebPros International, LLC’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:

1
2
3
4

root@httpupdate1:/home/www/thirdparty_pkg/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_pkg/11.92/centos/7/x86_64# sha512sum *.rpm > sha512

This file will contain a list of the package 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 Package Repo
Email address: example_pkg_repo@example.net
Comment: This is demonstrating the creation of a third-party cPanel repository.
You selected this USER-ID:
    "Example Package Repo (This is demonstrating the creation of a third-party cPanel 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 Package Repo (This is demonstrating the creation of a third-party cPanel repository.) <example_pkg_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 sha512 digest file

In order to prevent rollback, old version, or file-copy attacks, WebPros International, LLC 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 sha512 file that exists at http://example.com/pkg_repo/11.92/centos/7/x86_64/sha512, set the filename notation to /pkg_repo/11.92/centos/7/x86_64/sha512.

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 https://example.com/pkg_repo/example_pkg_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/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 /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 package’s 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 package, 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/pkg_repo/11.92/centos/[% rpm_dist_ver %]/[% rpm_arch %]/[% package %]-[% package_version %]-[% package_revision %].noarch.rpm'

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:

 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/pkg_repo/11.92/centos/[% rpm_dist_ver %]/[% rpm_arch %]/[% package %]-[% package_version %]-[% package_revision %].noarch.rpm'