CertificateInstructions.rtf

These are the procedures to follow when adding a root and/or intermediate certificate to the system.

For the purposes of these instructions, assume that $SRCDIR is e.g. ~/tla. For purposes of illustration, assume that you have checked out a branch of the security_certificates project to the directory SECCERTDIR:

	svk-co-branch PR-xxxxxxx security_certificates
	cd tla/security_certificates
	set SECCERTDIR=`pwd`

(export SECCERTDIR=`pwd` if using zsh).

To add a root certificate:

- Convert the certificate to DER form with either a .der, .crt, or .cer extension
- Copy the file to $SECCERTDIR/roots/
- Test all anchors, including the one you just added. You must have built cspxutils and clxutils; see the section
   entitled "To make the test tools". 
- Set SECCERTDIR to the security_certificates directory of your branch. Usually this can be omitted if you cd there
- Set SECTESTSDIR to the directory with the sources for SecurityTests, e.g. /Volumes/xenos/dev/tla2/SecurityTests
- Set LOCAL_BUILD_DIR

On my machine, I use for example

	export LOCAL_BUILD_DIR=/Volumes/xenos/dev/build
	export SECCERTDIR=/Volumes/xenos/dev/tla-PR-6216412/security_certificates
	export SECTESTSDIR=/Volumes/xenos/dev/tla2/SecurityTests

- Run the root tests and build a new SystemRootCertificates.keychain and SystemTrustSettings.plist in place on your branch like this:

      		cd $SECCERTDIR
		./addNewRoot

- The results of running the buildRootKeychain script are placed in $SECCERTDIR/BuiltKeychains. These are
   installed after making a backup of the system files you're replacing. The final operation in the script is to 
   run the anchorTest script. The 't' argument tells anchorTest to test SystemRootCertificates.keychain, not X509Anchors. 

- Assuming that test passes, check your changes into SVK - including the new SystemRootCertificates.keychain and SystemTrustSettings.plist. 
   As of 8/29/06, these files are submitted to B&I "as is" in binary form, so they don't have to have an up-to-date (or even working)
   Security.framework and securityd in order to build and install security_certificates.

To add an intermediate certificate:

- Follow the steps above "To add a root certificate:" if necessary. The additions of files can be done simultaneously,
   but the roots must be actually installed for the intermediate tests to run properly.
- Convert the certificate to DER form with either a .der, .crt, or .cer extension
- Copy the file to tla/security_certificates/certs/
- Add the file to the security_certificates.xcode project in the "certs" folder
- Open the security_certificates target and drag (copy) the file to the bottom "Copy Files" section
- Test all intermediates, including the one you just added. You must have built cspxutils and clxutils; see the section
   entitled "To make the test tools". 

		cd $SECCERTDIR/certs
		$SECTESTSDIR/clxutils/anchorTest/intermedSourceTest .

   NOTE as of 8/29/06 the intermedSourceTest script *fails* due to expired certs per Radar 4614279. 

- Build a new SystemCACertificates.keychain in place on your branch like this:

      		cd $SECCERTDIR
		./buildCAKeychain

- The result of running the buildCAKeychain script is placed in $SECCERTDIR/BuiltKeychains. Manually
   install that file like this, as root (this includes making a backup of the system file you're replacing):

   		mkdir /System/Library/Keychains/saved
		cp /System/Library/Keychains/SystemCACertificates.keychain /System/Library/Keychains/saved
		cp $SECCERTDIR/BuiltKeychains/SystemCACertificates.keychain /System/Library/Keychains

- Now run this (no longer as root, and assuming you've build cspxutils and clxutils):

		$SECTESTSDIR/clxutils/anchorTest/intermedTest

  NOTE as of 8/29/06 the intermedTest script allows for expired certs per Radar 4614279. 

- Assuming that test passes, check your changes into SVK - including the new SystemCACertificates.keychain. 
   As of 8/29/06, this file is submitted to B&I "as is" in binary form, so they don't have to have an up-to-date (or even working)
   Security.framework and securityd in order to build and install security_certificates.

To pre-flight an intermediate certificate

- Assume that the intermediate is intermed.crt with corresponding root root.crt
- Run

	$LOCAL_BUILD_DIR/certcrl -c intermed.crt -C root.crt -f

To remove a root or intermediate

- Remove the file from the project
- Remove the file from svk

To make the test tools

To build and run the test tools, you must have the LOCAL_BUILD_DIR env var set to point to a build directory.

- cd tla/SecurityTests/cspxutils
- set LOCAL_BUILD_DIR ....
- make all

Adding a new extended validation OID for a certificate authority

Certificate authorities define their own OID values for EV certificate issuance. The EV standard puts the onus onto the browser vendor to maintain a trusted mapping between each EV OID and the root certificates which are allowed to anchor chains for a given EV certificate containing that OID.

To add a new EV OID for a CA, edit and then run the buildEVRoots script (in the security_certificates project.) This file contains the mappings from dotted-decimal OID representations to one or more allowed root certificates (which are specified by their filenames in the ./roots/ directory). For example, the line which specifies Entrust's EV OID looks like this, since the Entrust root lives in ./roots/webroot.cer:

2.16.840.1.114028.10.1.2 "webroot.cer"

To build EVRoots.plist

To build the extended validation plist file, you must currently build or otherwise obtain the following tools:
- PlistBuddy (normally in /usr/libexec/PlistBuddy, but as of this writing, the tool has a fatal data length calculation bug <rdar://6208924> which requires you to apply the diffs attached to that bug and build a fixed version.) The script will verify the data values and let you know if the bug is present.

Check out the security_certificates project and 'cd' into that directory:
	svk-co-branch PR-xxxxxxx security_certificates
	cd tla/security_certificates

Edit the buildEVRoots script to set the location of the certlist and PlistBuddy tools, as needed.

Finally, you can run the buildEVRoots script. This will generate a new EVRoots.plist file in the ./BuiltKeychains/ directory.

Converting from PEM

- openssl x509 -outform DER -in SoneraClass1CA.pem -out SoneraClass1.crt

Converting from PKCS#7

If the file contains multiple certificates, you may have to split the file apart. Alternatively, import the p7 file into a blank keychain in Keychain Access, the drag each certificate out.

openssl pkcs7  -inform DER -in IdenTrust_Root_X3.p7b -print_certs -out IdenTrust_Root_X3.pem
openssl x509 -outform DER -in IdenTrust_Root_X3.pem -out IdenTrust_Root_X3.der

Other useful scripts

The following line was useful in determining which DoD roots and intermediates were not already in the source tree. It was run in the tla directory, then in the new directory. An opendiff of the two outputs shows what is new.

	for n in *; do echo `openssl x509 -inform DER -noout -fingerprint -in $n` "   $n";done | sed 's/MD5 Fingerprint=//'   | sort

Finding expired roots

This is a useful check to run periodically, to see which roots may expire soon.

	for n in *; do echo `openssl x509 -inform DER -noout -enddate -in $n` "   $n";done | sed 's/notAfter=//' | awk '{print $4," ",$1," ",$2," ",$6}' | sort

Note that it does not sort in strict chronological order (e.g. Aug 2006 appears before Feb 2006).

Description of tools
anchorTest - verifies all the roots in either SystemRootCertificates.keychain (if you specify the 't' option) or X509Anchors. This test can be persuaded to ignore expired roots via the 'e' option. 

anchorSourceTest - like anchorTest, but just tests a directory full of anchor certs. Intended to pre-screen changes to security_certificates/roots. Run with one arg, a path to the directory full of root certs. Run with no args to get a hint.

intermedTest - verifies contents of /System/Library/Keychains/SystemCACertificates.keychain. Run with no args, or with ‘q’ for quiet.

intermedSourceTest - like intermedTest crossed with anchorSourceTest. Prescreens a directory full of intermediate certs. Run with one arg, a path to the directory full of intermediate certs. Run with no args to get a hint. All of these must be verifiable by the current SystemRootCertificates.keychain (so if you add an intermediate and the associated root to the security_certificates project, without updating SystemRootCertificates.keychain, this test will fail).

History

29 Aug 2006	dmitch	Updated to reflect new trust structure for Leopard
18 Dec 2006	jhurley	Added more useful scripts, history section, notes on zsh