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 <cert>
119 \
120 Replace cert with the entire contents of cert.pem (including the
122 BEGIN CERTIFICATE and END CERTIFICATE lines). So you will have
123 an entry like this:
124 certificate: \
126 -----BEGIN CERTIFICATE-----
127 MIIDQjCCAiqgAwIBAgIJAIUgsIqSnesGMA0GCSqGSIb3DQEBCwUAMDkxFzAVBgNV
128 .
129 .
130 .
131 +NOVBamEvjn58ZcLfWh2oKee7ulIZg==
132 -----END CERTIFICATE-----
133 \
134 4. Sign Repository
136 When generating the repository manifests with the bpkg-rep-cre‐
137 ate(1) command, specify the path to key.pem with the --key op‐
138 tion:
139 bpkg rep-create --key /path/to/key.pem /path/to/repository
141 You will be prompted for a password to unlock the private key.
143 5. Using PIV/PKCS#11 Device
145 This optional step shows how to load the private key into Yu‐
146 bikey 4 and then use it instead of the private key itself for
147 signing the repository. Note that you will need OpenSSL 1.0.2 or
148 later for the signing part to work.
149 First change the Yubikey MKEY, PUK, and PIN if necessary. You
151 should definitely do this if it still has the factory defaults.
152 Then import the private key and the certificate into Yubikey
153 (replace mkey with the management key):
154 yubico-piv-tool --key=<mkey> -a import-key -s 9c <key.pem
156 yubico-piv-tool --key=<mkey> -a import-certificate -s 9c <cert.pem
157 After this you will normally save the certificate/private key
159 onto backup media, store it in a secure, offline location, and
160 remove the key from the build machine.
161 To sign the repository with Yubikey specify the following op‐
163 tions instead of just --key as at step 4 ("SIGN key" is the la‐
164 bel for the slot 9c private key):
165 bpkg rep-create \
167 --openssl-option rsautl:-engine --openssl-option rsautl:pkcs11 \
168 --openssl-option rsautl:-keyform --openssl-option rsautl:engine \
169 --key "pkcs11:object=SIGN%20key" /path/to/repository
170
172 Send bug reports to the users@build2.org mailing list.
173
175 Copyright (c) 2014-2021 the build2 authors.
176 Permission is granted to copy, distribute and/or modify this document
178 under the terms of the MIT License.
179bpkg 0.14.0 October 2021 bpkg-repository-signing(1)