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
17 attacker 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
24 implemented. That is, for an unknown (to this bpkg configuration)
25 repository certificate its subject information and fingerprint are pre‐
26 sented to the user. If the user confirms the authenticity of the cer‐
27 tificate, then it is added to the configuration and any repository that
28 in the future presents this certificate is trusted without further con‐
29 firmations, provided its name matches the certificate's subject (see
30 below). In the future a certificate authority (CA)-based model may be
31 added.
32 The rest of this guide shows how to create a key/certificate pair for
34 pkg repository signing and use it to sign a repository. At the end it
35 also briefly explains how to store the private key on a PIV/PKCS#11
36 device using Yubikey 4 as an example.
37 1. Generate Private Key
39 The first step is to generate the private key:
40 $ openssl genrsa -aes256 2048 >key.pem
42 If you would like to generate a key without password protection
44 (not a good idea except for testing), leave the -aes256 option
45 out. You may also need to add -nodes depending on your
46 openssl(1) configuration.
47 2. Generate Certificate
49 Next create the certificate configuration file by saving the
50 following into cert.conf. You may want to keep it around in case
51 you need to renew an expired certificate, etc.
52 name = example.com
54 org = Example, Inc
55 email = admin@example.com
56 [req]
58 distinguished_name = req_distinguished_name
59 x509_extensions = v3_req
60 prompt = no
61 utf8 = yes
62 [req_distinguished_name]
64 O = $org
65 CN = name:$name
66 [v3_req]
68 keyUsage = critical,digitalSignature
69 extendedKeyUsage = critical,codeSigning
70 subjectAltName = email:$email
71 Adjust the first three lines to match your details. If the
73 repository is hosted by an organization, use the organization's
74 name for org. If you host it as an individual, put your full,
75 real name there. Using any kind of aliases or nicknames is a bad
76 idea (except, again, for testing). Remember, users of your
77 repository will be presented with this information and if they
78 see it was signed by someone named SmellySnook, they will
79 unlikely trust it. Also use a working email address in case
80 users need to contact you about issues with your certificate.
81 Note that the name: prefix in the CN value is not a typo.
82 The name field is a canonical repository name prefix with the
84 pkg: type part stripped. Any repository with a canonical name
85 that starts with this prefix can be authenticated by this cer‐
86 tificate (see the repository manifest documentation for more
87 information on canonical names). For example, name example.com
88 will match any repository hosted on {,www.,pkg.,bpkg.}exam‐
89 ple.com. While name example.com/math will match {...}exam‐
90 ple.com/pkg/1/math but not {...}example.com/pkg/1/misc.
91 A certificate name can also contain a subdomain wildcard. A
93 wildcard name in the *.example.com form matches any single-level
94 subdomain, for example foo.example.com but not foo.bar.exam‐
95 ple.com while a wildcard name in the **.example.com form matches
96 any subdomain, including multi-level. The above two forms do not
97 match the domain itself (example.com in the above example). If
98 this is desired, the *example.com and **example.com forms should
99 be used instead. Note that these forms still only match subdo‐
100 mains. In other words, they won't match fooexample.com. Wildcard
101 names are less secure and therefore are normally only used for
102 testing and/or internal repositories.
103 Once the configuration file is ready, generate the certificate:
105 openssl req -x509 -new -sha256 -key key.pem \
107 -config cert.conf -days 730 >cert.pem
108 To verify the certificate information, run:
110 openssl x509 -noout -nameopt RFC2253,sep_multiline \
112 -subject -dates -email <cert.pem
113 3. Add Certificate to Repository
115 Add the certificate: field for the base repository (role: base)
116 in the repositories manifest file(s):
117 certificate: \
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 -----BEGIN CERTIFICATE-----
128 MIIDQjCCAiqgAwIBAgIJAIUgsIqSnesGMA0GCSqGSIb3DQEBCwUAMDkxFzAVBgNV
129 .
130 .
131 .
132 +NOVBamEvjn58ZcLfWh2oKee7ulIZg==
133 -----END CERTIFICATE-----
134 \
135 4. Sign Repository
137 When generating the repository manifests with the bpkg-rep-cre‐
138 ate(1) command, specify the path to key.pem with the --key
139 option:
140 bpkg rep-create --key /path/to/key.pem /path/to/repository
142 You will be prompted for a password to unlock the private key.
144 5. Using PIV/PKCS#11 Device
146 This optional step shows how to load the private key into
147 Yubikey 4 and then use it instead of the private key itself for
148 signing the repository. Note that you will need OpenSSL 1.0.2 or
149 later for the signing part to work.
150 First change the Yubikey MKEY, PUK, and PIN if necessary. You
152 should definitely do this if it still has the factory defaults.
153 Then import the private key and the certificate into Yubikey
154 (replace mkey with the management key):
155 yubico-piv-tool --key=<mkey> -a import-key -s 9c <key.pem
157 yubico-piv-tool --key=<mkey> -a import-certificate -s 9c <cert.pem
158 After this you will normally save the certificate/private key
160 onto backup media, store it in a secure, offline location, and
161 remove the key from the build machine.
162 To sign the repository with Yubikey specify the following
164 options instead of just --key as at step 4 ("SIGN key" is the
165 label for the slot 9c private key):
166 bpkg rep-create \
168 --openssl-option rsautl:-engine --openssl-option rsautl:pkcs11 \
169 --openssl-option rsautl:-keyform --openssl-option rsautl:engine \
170 --key "pkcs11:object=SIGN%20key" /path/to/repository
171
173 Send bug reports to the users@build2.org mailing list.
174
176 Copyright (c) 2014-2019 Code Synthesis Ltd
177 Permission is granted to copy, distribute and/or modify this document
179 under the terms of the MIT License.
180bpkg 0.12.0 November 2019 bpkg-repository-signing(1)