1bpkg-repository-signing(1) General Commands Manual bpkg-repository-signing(1)
2
6 bpkg-repository-signing - how to sign repository
7
9 bpkg rep-create --key ...
10
12 The purpose of signing a repository is to prevent tampering with pack‐
13 ages either during transmission or on the repository host machine. Ide‐
14 ally, you would generate and sign the repository manifests on a sepa‐
15 rate build machine that is behind a firewall. This way, if (or, really,
16 when) your host machine is compromised, it will be difficult for an at‐
17 tacker to compromise the repository packages without being noticed.
18 Since the repository key is kept on the build machine (or, better yet,
19 on a one-way PIV/PKCS#11 device; see below) they will not be able to
20 re-sign the modified repository.
21 bpkg uses X.509 public key cryptography for repository signing. Cur‐
23 rently, only the explicit first use certificate authentication is im‐
24 plemented. That is, for an unknown (to this bpkg configuration) repos‐
25 itory certificate its subject information and fingerprint are presented
26 to the user. If the user confirms the authenticity of the certificate,
27 then it is added to the configuration and any repository that in the
28 future presents this certificate is trusted without further confirma‐
29 tions, provided its name matches the certificate's subject (see below).
30 In the future a certificate authority (CA)-based model may be added.
31 The rest of this guide shows how to create a key/certificate pair for
33 pkg repository signing and use it to sign a repository. At the end it
34 also briefly explains how to store the private key on a PIV/PKCS#11 de‐
35 vice using Yubikey 4 as an example.
36 1. Generate Private Key
38 The first step is to generate the private key:
39 $ openssl genrsa -aes256 2048 >key.pem
41 If you would like to generate a key without password protection
43 (not a good idea except for testing), leave the -aes256 option
44 out. You may also need to add -nodes depending on your
45 openssl(1) configuration.
46 2. Generate Certificate
48 Next create the certificate configuration file by saving the
49 following into cert.conf. You may want to keep it around in case
50 you need to renew an expired certificate, etc.
51 name = example.com
53 org = Example, Inc
54 email = admin@example.com
55 [req]
57 distinguished_name = req_distinguished_name
58 x509_extensions = v3_req
59 prompt = no
60 utf8 = yes
61 [req_distinguished_name]
63 O = $org
64 CN = name:$name
65 [v3_req]
67 keyUsage = critical,digitalSignature
68 extendedKeyUsage = critical,codeSigning
69 subjectAltName = email:$email
70 Adjust the first three lines to match your details. If the
72 repository is hosted by an organization, use the organization's
73 name for org. If you host it as an individual, put your full,
74 real name there. Using any kind of aliases or nicknames is a bad
75 idea (except, again, for testing). Remember, users of your
76 repository will be presented with this information and if they
77 see it was signed by someone named SmellySnook, they will un‐
78 likely trust it. Also use a working email address in case users
79 need to contact you about issues with your certificate. Note
80 that the name: prefix in the CN value is not a typo.
81 The name field is a canonical repository name prefix with the
83 pkg: type part stripped. Any repository with a canonical name
84 that starts with this prefix can be authenticated by this cer‐
85 tificate (see the repository manifest documentation for more in‐
86 formation on canonical names). For example, name example.com
87 will match any repository hosted on {,www.,pkg.,bpkg.}exam‐
88 ple.com. While name example.com/math will match {...}exam‐
89 ple.com/pkg/1/math but not {...}example.com/pkg/1/misc.
90 A certificate name can also contain a subdomain wildcard. A
92 wildcard name in the *.example.com form matches any single-level
93 subdomain, for example foo.example.com but not foo.bar.exam‐
94 ple.com while a wildcard name in the **.example.com form matches
95 any subdomain, including multi-level. The above two forms do not
96 match the domain itself (example.com in the above example). If
97 this is desired, the *example.com and **example.com forms should
98 be used instead. Note that these forms still only match subdo‐
99 mains. In other words, they won't match fooexample.com. Wildcard
100 names are less secure and therefore are normally only used for
101 testing and/or internal repositories.
102 Once the configuration file is ready, generate the certificate:
104 openssl req -x509 -new -sha256 -key key.pem \
106 -config cert.conf -days 730 >cert.pem
107 To verify the certificate information, run:
109 openssl x509 -noout -nameopt RFC2253,sep_multiline \
111 -subject -dates -email <cert.pem
112 3. Add Certificate to Repository
114 Add the certificate: field for the base repository (role: base)
115 in the repositories manifest file(s):
116 certificate:
118 \
119 <cert>
120 \
121 Replace cert with the entire contents of cert.pem (including the
123 BEGIN CERTIFICATE and END CERTIFICATE lines). So you will have
124 an entry like this:
125 certificate:
127 \
128 -----BEGIN CERTIFICATE-----
129 MIIDQjCCAiqgAwIBAgIJAIUgsIqSnesGMA0GCSqGSIb3DQEBCwUAMDkxFzAVBgNV
130 .
131 .
132 .
133 +NOVBamEvjn58ZcLfWh2oKee7ulIZg==
134 -----END CERTIFICATE-----
135 \
136 4. Sign Repository
138 When generating the repository manifests with the bpkg-rep-cre‐
139 ate(1) command, specify the path to key.pem with the --key op‐
140 tion:
141 bpkg rep-create --key /path/to/key.pem /path/to/repository
143 You will be prompted for a password to unlock the private key.
145 5. Using PIV/PKCS#11 Device
147 This optional step shows how to load the private key into Yu‐
148 bikey 4 and then use it instead of the private key itself for
149 signing the repository. Note that you will need OpenSSL 1.0.2 or
150 later for the signing part to work.
151 First change the Yubikey MKEY, PUK, and PIN if necessary. You
153 should definitely do this if it still has the factory defaults.
154 Then import the private key and the certificate into Yubikey
155 (replace mkey with the management key):
156 yubico-piv-tool --key=<mkey> -a import-key -s 9c <key.pem
158 yubico-piv-tool --key=<mkey> -a import-certificate -s 9c <cert.pem
159 After this you will normally save the certificate/private key
161 onto backup media, store it in a secure, offline location, and
162 remove the key from the build machine.
163 To sign the repository with Yubikey specify the following op‐
165 tions instead of just --key as at step 4 ("SIGN key" is the la‐
166 bel for the slot 9c private key):
167 bpkg rep-create \
169 --openssl-option pkeyutl:-engine --openssl-option pkeyutl:pkcs11 \
170 --openssl-option pkeyutl:-keyform --openssl-option pkeyutl:engine \
171 --key "pkcs11:object=SIGN%20key" /path/to/repository
172 Note that for openssl versions prior to 3.0.0 bpkg uses the
174 rsautl command instead of pkeyutl for the data signing opera‐
175 tion.
176
178 Send bug reports to the users@build2.org mailing list.
179
181 Copyright (c) 2014-2022 the build2 authors.
182 Permission is granted to copy, distribute and/or modify this document
184 under the terms of the MIT License.
185bpkg 0.15.0 July 2022 bpkg-repository-signing(1)