Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

===================================================================
RCS file: /ftp/cvs/cvsroot/pkgsrc/pkgtools/pkg_install/files/x509/signing.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -p -r1.1 -r1.1.2.1
--- pkgsrc/pkgtools/pkg_install/files/x509/signing.txt	2008/09/08 23:07:16	1.1
+++ pkgsrc/pkgtools/pkg_install/files/x509/signing.txt	2008/09/08 23:07:16	1.1.2.1
@@ -0,0 +1,59 @@
+Use of digital signatures in pkg_install
+----------------------------------------
+
+(1) pkg_vulnerabilities: list of known vulnerabilities, provided by
+    the pkgsrc security team and updated regulary
+(2) binary packages: check who provided binary packages
+
+For (1) gpg is currently the only choice. After pkgsrcCon (?) a PKCS7 
+signature will be added as well. With the pkg_install-renovation branch,
+PKCS7 is the only supported verification mechanism for (2) and preferred
+for (1) once the infrastructure exists.
+
+PKCS7 is a format to use RSA public key cryptography with X509
+certificates. Those are commonly used for SSL. X509 implements a
+hierachical trust model. For this purpose it means that one or more
+certificates are installed and marked as trusted. A certificate used for
+signing a binary package or pkg_vulnerabilities will have to be included
+in the list to be trusted OR it must be itself signed by a trusted
+certificate. The original list is called the TRUST ANCHOR.
+
+Optionally, a second list of certificates can be provided to fill gaps.
+Let's assume A is a trust anchor and C is used to sign a package. C
+itself is not signed by A, so it won't be trusted. Instead, there's a
+third certificate B; and C includes a signature with B. The certificate
+chain file can now provide B signed by A. This gives a certificate chain
+of C -> B (included in the package) -> A (with the chain file) and the
+signature is valid and trusted.
+
+
+Practical implications for pkgsrc users:
+- get the pkgsrc-security certificate and point CERTIFICATE_ANCHOR_PKGVULN to it
+- get the certificate used by your bulk builder and point
+CERTIFICATE_ANCHOR_PKGS to it
+- at some later point a CA for pkgsrc might be created, in that case it
+will serve as certificate for both purposes; a list of all certificates
+will be provided in that case to point CERTIFICATE_CHAIN to.
+
+
+How to create your own keys:
+
+The pkgsrc.sh script and the corresponding pkgsrc.cnf file provide a working
+wrapper around the OpenSSL command line tool.
+
+The root certificate can be created by running "sh pkgsrc.sh setup",
+the output can found in the pkgsrc subdirectory of the current directory.
+The meta data is for human beings and displayed e.g. by pkg_add, but not
+relevant for cryptographic purposes.  pkgsrc/newcerts/00.pem is the
+public key and can be used as trust anchor.
+A certificate for signing packages can be created by running
+"sh pkgsrc.sh pkgkey". The private key can be found in pkgkey_key.pem
+and the certificate in pkgkey_cert.pem.
+Similary, "sh pkgsrc.sh pkgsec" will create a certificate/key pair for
+signing pkg-vulnerabilities.
+
+How to verify a certificate:
+- decode the data with "openssl x509 -text -noout -in newcert.pem"
+- "Issuer" is vouching for the identity (and reliability) of "Subject"
+- "X509v3 Basic Constraints" should list "CA:FALSE" for all keys that are not allowed
+  to sign further keys.