1Use of digital signatures in pkg_install
2----------------------------------------
3
4(1) pkg_vulnerabilities: list of known vulnerabilities, provided by
5    the pkgsrc security team and updated regulary
6(2) binary packages: check who provided binary packages
7
8For (1) gpg is currently the only choice. After pkgsrcCon (?) a PKCS7
9signature will be added as well. With the pkg_install-renovation branch,
10PKCS7 is the only supported verification mechanism for (2) and preferred
11for (1) once the infrastructure exists.
12
13PKCS7 is a format to use RSA public key cryptography with X509
14certificates. Those are commonly used for SSL. X509 implements a
15hierachical trust model. For this purpose it means that one or more
16certificates are installed and marked as trusted. A certificate used for
17signing a binary package or pkg_vulnerabilities will have to be included
18in the list to be trusted OR it must be itself signed by a trusted
19certificate. The original list is called the TRUST ANCHOR.
20
21Optionally, a second list of certificates can be provided to fill gaps.
22Let's assume A is a trust anchor and C is used to sign a package. C
23itself is not signed by A, so it won't be trusted. Instead, there's a
24third certificate B; and C includes a signature with B. The certificate
25chain file can now provide B signed by A. This gives a certificate chain
26of C -> B (included in the package) -> A (with the chain file) and the
27signature is valid and trusted.
28
29
30Practical implications for pkgsrc users:
31- get the pkgsrc-security certificate and point CERTIFICATE_ANCHOR_PKGVULN to it
32- get the certificate used by your bulk builder and point
33CERTIFICATE_ANCHOR_PKGS to it
34- at some later point a CA for pkgsrc might be created, in that case it
35will serve as certificate for both purposes; a list of all certificates
36will be provided in that case to point CERTIFICATE_CHAIN to.
37
38
39How to create your own keys:
40
41The pkgsrc.sh script and the corresponding pkgsrc.cnf file provide a working
42wrapper around the OpenSSL command line tool.
43
44The root certificate can be created by running "sh pkgsrc.sh setup",
45the output can found in the pkgsrc subdirectory of the current directory.
46The meta data is for human beings and displayed e.g. by pkg_add, but not
47relevant for cryptographic purposes.  pkgsrc/newcerts/00.pem is the
48public key and can be used as trust anchor.
49A certificate for signing packages can be created by running
50"sh pkgsrc.sh pkgkey". The private key can be found in pkgkey_key.pem
51and the certificate in pkgkey_cert.pem.
52Similary, "sh pkgsrc.sh pkgsec" will create a certificate/key pair for
53signing pkg-vulnerabilities.
54
55How to verify a certificate:
56- decode the data with "openssl x509 -text -noout -in newcert.pem"
57- "Issuer" is vouching for the identity (and reliability) of "Subject"
58- "X509v3 Basic Constraints" should list "CA:FALSE" for all keys that are not allowed
59  to sign further keys.
60