1{\rtf1\ansi\ansicpg1252\cocoartf1010 2{\fonttbl\f0\fswiss\fcharset0 Helvetica;\f1\fnil\fcharset0 LucidaGrande;} 3{\colortbl;\red255\green255\blue255;} 4\margl1440\margr1440\vieww19940\viewh21540\viewkind0 5\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural 6 7\f0\fs24 \cf0 \ 8\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural 9 10\fs28 \cf0 11\b CertificateInstructions.rtf 12\b0\fs26 \ 13\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural 14 15\f1\fs24 \cf0 \ 16\pard\tx1440\tx2880\tx4320\tx5760\tx7200\tx8640\slleading40\ql\qnatural 17\cf0 These are the procedures to follow when adding a root and/or intermediate certificate to the system.\ 18\ 19For 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:\ 20\ 21 svk-co-branch PR-xxxxxxx security_certificates\ 22 cd tla/security_certificates\ 23 set SECCERTDIR=`pwd`\ 24\ 25(export SECCERTDIR=`pwd` if using zsh).\ 26\ 27\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural 28 29\b \cf0 To add a root certificate:\ 30\ 31 32\b0 - Convert the certificate to DER form with either a .der, .crt, or .cer extension\ 33- Copy the file to $SECCERTDIR/roots/\ 34- Test all anchors, including the one you just added. You must have built cspxutils and clxutils; see the section\ 35 entitled " 36\b To make the test tools". 37\b0 \ 38- Set SECCERTDIR to the security_certificates directory of your branch. Usually this can be omitted if you cd there\ 39- Set SECTESTSDIR to the directory with the sources for SecurityTests, e.g. /Volumes/xenos/dev/tla2/SecurityTests\ 40- Set LOCAL_BUILD_DIR\ 41\ 42On my machine, I use for example\ 43\ 44 export LOCAL_BUILD_DIR=/Volumes/xenos/dev/build\ 45 export SECCERTDIR=/Volumes/xenos/dev/tla-PR-6216412/security_certificates\ 46 export SECTESTSDIR=/Volumes/xenos/dev/tla2/SecurityTests\ 47\ 48- Run the root tests and build a new SystemRootCertificates.keychain and SystemTrustSettings.plist in place on your branch like this:\ 49\ 50 cd $SECCERTDIR\ 51 ./addNewRoot\ 52\ 53- The results of running the buildRootKeychain script are placed in $SECCERTDIR/BuiltKeychains. These are\ 54 installed after making a backup of the system files you're replacing. The final operation in the script is to \ 55 run the anchorTest script. The 't' argument tells anchorTest to test SystemRootCertificates.keychain, not X509Anchors. \ 56\ 57- Assuming that test passes, check your changes into SVK - 58\b including the new SystemRootCertificates.keychain and SystemTrustSettings.plist. \ 59 60\b0 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)\ 61 Security.framework and securityd in order to build and install security_certificates.\ 62\ 63\ 64 65\b To add an intermediate certificate:\ 66\ 67\pard\tx1440\tx2880\tx4320\tx5760\tx7200\tx8640\slleading40\ql\qnatural 68 69\b0 \cf0 - Follow the steps above " 70\b To add a root certificate: 71\b0 " if necessary. The additions of files can be done simultaneously,\ 72 but the roots must be actually installed for the intermediate tests to run properly.\ 73\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural 74\cf0 - Convert the certificate to DER form with either a .der, .crt, or .cer extension\ 75- Copy the file to tla/security_certificates/certs/\ 76- Add the file to the security_certificates.xcode project in the "certs" folder\ 77- Open the security_certificates target and drag (copy) the file to the 78\b bottom 79\b0 "Copy Files" section\ 80- Test all intermediates, including the one you just added. You must have built cspxutils and clxutils; see the section\ 81 entitled " 82\b To make the test tools". 83\b0 \ 84\ 85 cd $SECCERTDIR/certs\ 86 $SECTESTSDIR/clxutils/anchorTest/intermedSourceTest .\ 87\ 88 NOTE as of 8/29/06 the intermedSourceTest script *fails* due to expired certs per Radar 4614279. \ 89\ 90- Build a new SystemCACertificates.keychain in place on your branch like this:\ 91\ 92 cd $SECCERTDIR\ 93 ./buildCAKeychain\ 94\ 95- The result of running the buildCAKeychain script is placed in $SECCERTDIR/BuiltKeychains. Manually\ 96 install that file like this, as root (this includes making a backup of the system file you're replacing):\ 97\ 98 mkdir /System/Library/Keychains/saved\ 99 cp /System/Library/Keychains/SystemCACertificates.keychain /System/Library/Keychains/saved\ 100 cp $SECCERTDIR/BuiltKeychains/SystemCACertificates.keychain /System/Library/Keychains\ 101\ 102- Now run this (no longer as root, and assuming you've build cspxutils and clxutils):\ 103\ 104 $SECTESTSDIR/clxutils/anchorTest/intermedTest\ 105\ 106 NOTE as of 8/29/06 the intermedTest script allows for expired certs per Radar 4614279. \ 107\ 108- Assuming that test passes, check your changes into SVK - 109\b including the new SystemCACertificates.keychain. \ 110 111\b0 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)\ 112 Security.framework and securityd in order to build and install security_certificates.\ 113\ 114\ 115 116\b To pre-flight an intermediate certificate 117\b0 \ 118\ 119- Assume that the intermediate is intermed.crt with corresponding root root.crt\ 120- Run\ 121\ 122 $LOCAL_BUILD_DIR/certcrl -c intermed.crt -C root.crt -f\ 123\pard\tx1440\tx2880\tx4320\tx5760\tx7200\tx8640\slleading40\ql\qnatural 124\cf0 \ 125\pard\tx1440\tx2880\tx4320\tx5760\tx7200\tx8640\slleading40\ql\qnatural 126 127\b \cf0 To remove a root or intermediate 128\b0 \ 129\ 130- Remove the file from the project\ 131- Remove the file from svk\ 132\ 133 134\b To make the test tools 135\b0 \ 136\ 137To build and run the test tools, you must have the LOCAL_BUILD_DIR env var set to point to a build directory.\ 138\ 139- cd tla/SecurityTests/cspxutils\ 140- set LOCAL_BUILD_DIR ....\ 141- make all\ 142\ 143\ 144 145\b Adding a new extended validation OID for a certificate authority\ 146\pard\tx1440\tx2880\tx4320\tx5760\tx7200\tx8640\slleading40\ql\qnatural 147 148\b0 \cf0 \ 149Certificate 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.\ 150\ 151To 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:\ 152\ 1532.16.840.1.114028.10.1.2 "webroot.cer"\ 154\ 155\pard\tx1440\tx2880\tx4320\tx5760\tx7200\tx8640\slleading40\ql\qnatural 156 157\b \cf0 To build EVRoots.plist\ 158\pard\tx1440\tx2880\tx4320\tx5760\tx7200\tx8640\slleading40\ql\qnatural 159 160\b0 \cf0 \ 161To build the extended validation plist file, you must currently build or otherwise obtain the following tools:\ 162- 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.\ 163\ 164Check out the security_certificates project and 'cd' into that directory:\ 165 svk-co-branch PR-xxxxxxx security_certificates\ 166 cd tla/security_certificates\ 167\ 168Edit the buildEVRoots script to set the location of the certlist and PlistBuddy tools, as needed.\ 169\ 170Finally, you can run the buildEVRoots script. This will generate a new EVRoots.plist file in the ./BuiltKeychains/ directory.\ 171\ 172\ 173\pard\tx1440\tx2880\tx4320\tx5760\tx7200\tx8640\slleading40\ql\qnatural 174 175\b \cf0 Converting from PEM 176\b0 \ 177\ 178- openssl x509 -outform DER -in SoneraClass1CA.pem -out SoneraClass1.crt\ 179\ 180 181\b Converting from PKCS#7 182\b0 \ 183\ 184If 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.\ 185\ 186openssl pkcs7 -inform DER -in IdenTrust_Root_X3.p7b -print_certs -out IdenTrust_Root_X3.pem\ 187openssl x509 -outform DER -in IdenTrust_Root_X3.pem -out IdenTrust_Root_X3.der\ 188\ 189 190\b Other useful scripts 191\b0 \ 192\ 193\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural 194 195\f0 \cf0 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.\ 196\ 197 for n in *; do echo `openssl x509 -inform DER -noout -fingerprint -in $n` " $n";done | sed 's/MD5 Fingerprint=//' | sort\ 198\pard\tx1440\tx2880\tx4320\tx5760\tx7200\tx8640\slleading40\ql\qnatural 199 200\f1 \cf0 \ 201\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural 202 203\f0\b \cf0 Finding expired roots 204\b0 \ 205\ 206This is a useful check to run periodically, to see which roots may expire soon.\ 207\ 208 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\ 209\ 210Note that it does not sort in strict chronological order (e.g. Aug 2006 appears before Feb 2006).\ 211\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\slleading60\ql\qnatural 212 213\b \cf0 \ 214Description of tools 215\b0 \ 216 217\f1 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. \ 218\ 219anchorSourceTest - 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.\ 220\ 221intermedTest - verifies contents of /System/Library/Keychains/SystemCACertificates.keychain. Run with no args, or with \'91q\'92 for quiet.\ 222\ 223intermedSourceTest - 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).\ 224\ 225\pard\tx1440\tx2880\tx4320\tx5760\tx7200\tx8640\slleading40\ql\qnatural 226 227\b \cf0 History 228\b0 \ 229\ 230\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural 231 232\f0\fs26 \cf0 29 Aug 2006 dmitch Updated to reflect new trust structure for Leopard\ 23318 Dec 2006 jhurley Added more useful scripts, history section, notes on zsh\ 234\ 235\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural 236 237\f1\fs24 \cf0 \ 238}