1<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en"> 2<html> 3<head> 4 5 <meta http-equiv="Content-Type" 6 content="text/html; charset=iso-8859-1"> 7 8 <meta name="GENERATOR" 9 content="Mozilla/4.75C-CCK-MCD {C-UDP; EBM-APPLE} (Macintosh; U; PPC) [Netscape]"> 10 <title>CertTool.html</title> 11</head> 12 <body> 13 14<center> 15<h2> <b>CertTool</b></h2> 16</center> 17 18<center> 19<h2> <b>Last Update 10/10/02</b></h2> 20</center> 21 22<h2> Table Of Contents</h2> 23 1. <a href="#Introduction">Introduction</a> <br> 242. <a href="#Generating%20a%20Self-Signed%20Certificate">Generating a Self-Signed 25Certificate</a> <br> 263. <a 27 href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Generating 28a Certificate Signing Request (CSR)</a> <br> 294. <a href="#Verifying%20a%20CSR">Verifying a CSR</a> <br> 305. <a 31 href="#Importing%20a%20Certificate%20from%20a%20Certificate%20Authority">Importing 32a Certificate from a Certificate Authority</a> <br> 336. <a href="#Displaying%20a%20Certificate">Displaying a Certificate</a> <br> 347. <a href="#Certificate%20Authorities%20and%20CSRs">Certificate Authorities 35and CSRs</a> <br> 368. <a href="#5._Importing_a_CRL">Importing a CRL</a> <br> 379. <a href="#6._Displaying_a_CRL">Displaying a CRL</a> 38<h2> 1. <a name="Introduction"></a>Introduction</h2> 39 40<blockquote>CertTool is a UNIX command-line program which is used to create 41key pairs, certificates, and certificate signing requests; to import externally 42generated certificates into a Keychain, and to display the contents of certificates. 43Currently. the primary use of CertTool is to perform the certificate-related 44administration required to configure an SSL server based on Mac OS X's SecureTransport 45library. Each supported CertTool operation is described below in detail. 46 <p>The reader of this document, and the user of CertTool, is assumed to 47be familiar with the following: </p> 48 <ul> 49 <li> General principles of public key cryptography</li> 50 <li> The concepts of certificates and trust</li> 51 <li> General operation of the Secure Socket Layer (SSL) protocol</li> 52 <li> General operation of the Mac OS X Keychain</li> 53 <li> The Mac OS X SecureTransport library</li> 54 55 </ul> 56 No programming knowledge is assumed or required. An excellent primer on the 57topics of public key cryptography, certificates, and SSL can be found at 58 <a href="http://httpd.apache.org/docs-2.0/ssl/ssl_intro.html">http://httpd.apache.org/docs-2.0/ssl/ssl_intro.html.</a> 59 <p>Note: in all examples of usage of the command line tool which follow, 60the user's input is shown in <b>bold</b>. Running CertTool with no command-line 61arguments results in usage info being displayed. <br> 62 </p> 63</blockquote> 64 65<h2> 2. <a name="Generating a Self-Signed Certificate"></a>Generating 66a Self-Signed Certificate</h2> 67 68<blockquote>This command generates a key pair and a self-signed (root) certificate 69and places them in a keychain. The root cert is signed by the private key 70generated during this command. The cert generated by this command is totally 71untrustworth and cannot be used in the "real world"; the primary use of this 72command is to facilitate early development of SSL server applications based 73on SecureTransport. In particular, "real world" SSL clients (e.g., web browsers) 74will complain to varying degrees when they attempt to connect to an SSL server 75which presents a cert which is generated by this command. Some broswers, 76after a fair amount of handholding, will allow you to conditionally "trust" 77this cert. 78 <p>The format of this command is </p> 79 <p># <b>CertTool c [options]</b> </p> 80 <p>The available options are: </p> 81 <blockquote>k=keyChainName 82 <blockquote>Where "KeyChainName" is the name of the keychain into which 83keys and the cert will be added. If no keychain is specified, keys and certs 84are added to the default keychain. The specified keychain must exist unless 85you specify the 'c' option.</blockquote> 86 c 87 <blockquote>Specifies that the designated keychain is to be created.</blockquote> 88 </blockquote> 89 This an interactive command; you will be prompted for a number of different 90items which are used to generate the keypair and the cert. A sample sesion 91follows. <br> 92 93 <blockquote># <b>CertTool k=certkc</b> <br> 94Enter key and certificate label: <b>testCert</b> 95 <p>Please specify parameters for the key pair you will generate. </p> 96 <p> r RSA <br> 97 d DSA <br> 98 f FEE </p> 99 <p>Select key algorithm by letter: <b><font size="+1">r</font></b> </p> 100 <p>Valid key sizes for RSA are 512..2048; default is 512 <br> 101Enter key size in bits or CR for default: <b><font size="+1">512</font></b> 102 </p> 103 <p>You have selected algorithm RSA, key size 512 bits. <br> 104OK (y/anything)? <b><font size="+1">y</font></b> <br> 105Enter cert/key usage (s=signing, b=signing AND encrypting): b <br> 106...Generating key pair... </p> 107 <p><i><<Note: you will be prompted for the Keychain's passphrase 108by the Keychain system at this point if the specified keychain is not open.>></i> 109 </p> 110 <p>Please specify the algorithm with which your certificate will be signed. 111 </p> 112 <p> 5 RSA with MD5 <br> 113 s RSA with SHA1 </p> 114 <p>Select signature algorithm by letter:<b><font size="+1"> s</font></b> 115 </p> 116 <p>You have selected algorithm RSA with SHA1. <br> 117OK (y/anything)? <b><font size="+1">y</font></b> <br> 118...creating certificate... </p> 119 <p>You will now specify the various components of the certificate's <br> 120Relative Distinguished Name (RDN). An RDN has a number of <br> 121components, all of which are optional, but at least one of <br> 122which must be present. </p> 123 <p>Note that if you are creating a certificate for use in an <br> 124SSL/TLS server, the Common Name component of the RDN must match <br> 125exactly the host name of the server. This must not be an IP <br> 126address, but the actual domain name, e.g. www.apple.com. </p> 127 <p>Entering a CR for a given RDN component results in no value for <br> 128that component. </p> 129 <p>Common Name (e.g, www.apple.com) 130: <b><font size="+1">10.0.61.5</font></b> <br> 131Country 132(e.g, US) : <br> 133Organization 134(e.g, Apple Computer, Inc.) : <b><font size="+1">Apple</font></b> <br> 135Organization Unit (e.g, Apple Data Security) : <br> 136State/Province (e.g., 137California) : <b><font size="+1">California</font></b> </p> 138 <p>You have specified: <br> 139 Common Name : 10.0.61.5 <br> 140 Organization 141: Apple <br> 142 State/Province : California 143 <br> 144Is this OK (y/anything)? <b><font size="+1">y</font></b> <br> 145..cert stored in Keychain. <br> 146#</p> 147 </blockquote> 148 The "Common Name" portion of the RDN - in the above case, "10.0.61.5" - MUST 149match the host name of the machine you'll running sslServer on. (In this 150case the test machine doesn't have an actual hostname; it's DHCP'd behind 151a firewall which is why "10.0.61.5" was specified for Common Name.) This 152is part of SSL's certificate verification; it prevents an attack using DNS 153spoofing. 154 <p>A brief note about cert/key usage: the normal configuration of SecureTransport 155is that the server cert specified in SSLSetCertificate() is capable of both 156signing and encryption. If this cert is only capable of signing, then you 157must create a second keychain ontaining a cert which is capable of encryption, 158and pass that to SSLSetEncryptionCertificate(). <br> 159 <br> 160 </p> 161</blockquote> 162 163<h2> 3. <a name="Generating a Certificate Signing Request (CSR)"></a>Generating 164a Certificate Signing Request (CSR)</h2> 165 166<blockquote>A CSR is the standard means by which an administrator of a web 167server provides information to a Certificate Authority (CA) in order to obtain 168a valid certificate which is signed by the CA. This type of cert is used 169in the real world; certs signed by CAs such as Verisign or Thawte are recognized 170by all web browsers when performing SSL transactions. 171 <p>The general procedure for obtaining a "real" cert is: <br> 172 </p> 173 <ul> 174 <li> Generate a key pair</li> 175 <li> Generate a CSR</li> 176 <li> Provide the CSR and some other information and/or documentation to 177the CA</li> 178 <li> CA sends you a certificate which is signed by the CA.</li> 179 <li> You import that certificate, obtained from the CA, into your keychain. 180The items in that keychain can now be used in SecureTranspoert's SSLSetCertificate() 181call.</li> 182 183 </ul> 184 This command performs the first two steps in the above procedure. See <a 185 href="#Importing%20a%20Certificate%20from%20a%20Certificate%20Authority">Section 1865</a> for information on importing the resulting certificate into your keychain. 187 <p>The format of this command is </p> 188 <p># <b>CertTool r outFileName [options]</b> </p> 189 <p>The resulting CSR will be written to "outFileName". </p> 190 <p>The available options are: </p> 191 <p>k=keyChainName </p> 192 <blockquote>Where "KeyChainName" is the name of the keychain into which 193keys and the cert will be added. If no keychain is specified, keys and certs 194are added to the default keychain. The specified keychain must exist unless 195you specify the 'c' option.</blockquote> 196 d 197 <blockquote>The 'd' option tells CertTool to create the CSR in DER-encoded 198format. The default is PEM-encoded, which is what most CAs expect. PEM encoded 199data consists of printable ASCII text which can, for example, be pasted into 200an email message. DER-encoded data is nonprintable binary data.</blockquote> 201 c 202 <blockquote>Specifies that the designated keychain is to be created.</blockquote> 203 This an interactive command; you will be prompted for a number of different 204items which are used to generate the keypair and the CSR. The prompts given, 205and the format of the data you must supply, are identical to the data shown 206in the sample session in Section 2. 207 <p>See Section 7 for more information on using CSRs and about CAs. <br> 208 <br> 209 </p> 210</blockquote> 211 212<h2> 4. <a name="Verifying a CSR"></a>Verifying a CSR</h2> 213 214<blockquote>A CSR contains, among other things, the public key which was generated 215in <a 216 href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Section 2173</a>. The CSR is signed with the associated private key. Thus the inteegrity 218of a CSR can be verified by extracting its public key and verifying the signature 219of the CSR. This command performs this integrity check. 220 <p>The format of this command is </p> 221 <p># <b>CertTool v inFileName [options]</b> </p> 222 <p>The resulting CSR will be written to "outFileName". </p> 223 <p>The only available option is the 'd' flag, which as described in <a 224 href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Section 2253</a>, indiciates that the CSR is in DER format rather than the default PEM 226format. </p> 227 <p>A typical (successful) run of this command is like so: </p> 228 <p># <b>CertTool v myCsr.pem</b> <br> 229...CSR verified successfully. </p> 230 <p>A large number of things can go wrong of the verification fails; suffice 231it to say that if you see anything other than the above success message, you 232have a bad or corrupted CSR. <br> 233 </p> 234 <blockquote> </blockquote> 235 </blockquote> 236 237<h2> 5. <a 238 name="Importing a Certificate from a Certificate Authority"></a>Importing 239a Certificate from a Certificate Authority</h2> 240 241<blockquote>Once you have negotiated with your CA, and provided them with 242the CSR generated in <a 243 href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Section 2443</a> as well as any other information, documentation, and payment thay require, 245the CA will provide you with a certificate. Use this command to add that 246certificate to the keychain containing the keypair you generated in <a 247 href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Section 2483</a>. <i></i> 249 <p>The format of this command is </p> 250 <p># <b>CertTool i inFileName [options]</b> </p> 251 <p>The cert to import is obtained from "inFileName". </p> 252 <p>The available options are: </p> 253 <p>k=keyChainName </p> 254 <blockquote>Where "KeyChainName" is the name of the keychain to which the 255cert will be added. If no keychain is specified, the cert is added to the 256default keychain. The specified keychain should contain the keypair you generated 257in <a 258 href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Section 2593</a>. (Note you can import a certificate into a keychain which does not 260contain keys you generated but there will be no linkage between the imported 261certificate and a private key if you do this.) If the keychain is not open 262when this command is executed, you will be prompted by the Keychain system 263for its passphrase.</blockquote> 264 d 265 <blockquote>Specifies DER format as described above. The default is PEM 266format.<br> 267 <br> 268 </blockquote> 269 c 270 <blockquote>Specifies that the designated keychain is to be created.<br> 271 <br> 272 </blockquote> 273 </blockquote> 274 275<h2> 6. <a name="Displaying a Certificate"></a>Displaying a Certificate</h2> 276 277<blockquote>This displays the contents of an existing certificate, obtained 278from a file. 279 <p>The format of this command is </p> 280 <p># <b>CertTool d inFileName [options]</b> </p> 281 <p>The cert to display is obtained from "inFileName". </p> 282 <p>The only available option is the 'd' flag, specifying DER format as described 283above. The default is PEM format <br> 284 </p> 285</blockquote> 286 287<h2> 7. <a name="Certificate Authorities and CSRs"></a>Certificate Authorities 288and CSRs</h2> 289 290<blockquote>As mentioned above, the general procedure for obtaining a "real" 291cert is: 292 <ul> 293 <li> Generate a key pair</li> 294 <li> Generate a CSR</li> 295 <li> Provide the CSR and some other information and/or documentation to 296the CA</li> 297 <li> CA sends you a certificate which is signed by the CA.</li> 298 <li> You import that certificate, obtained from the CA, into your keychain. 299The items in that keychain can now be used in SecureTranspoert's SSLSetCertificate() 300call.</li> 301 302 </ul> 303 </blockquote> 304 305<blockquote>One CA with an excellent web-based interface for obtaining a 306cert is Verisign (<a 307 href="http://www.verisign.com/products/site/index.html">http://www.verisign.com/products/site/index.html</a>). 308You can get a free 14-day trial certificate using nothing but CertTool, Verisign's 309web site, and email. You need to provide some personal information; then 310you paste in the CSR generated in <a 311 href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Section 3123</a> into a form on the web site. A few minutes later Verisign emails you 313a certificate, which you import into your keychain per <a 314 href="#Importing%20a%20Certificate%20from%20a%20Certificate%20Authority">Section 3155</a>. The whole process takes less than 10 minutes. The free certificate 316obtained in this manner is signed by a temporary root cert which is not recognized 317by any browsers, but Verisign also provides a measn of installing this temporary 318root cert into your browser, directly from their web site. Typically one 319would use the free, temporary cert to perform initial configuration of a 320server and to ring out the general SSL infrastructure. Once you feel comfortable 321with the operation of the server, then it's time to buy a "real" certificate 322which will allow your web server to be recognized by any browser. 323 <p>Thawte has a similar, very friendly service at <a 324 href="http://www.thawte.com">http://www.thawte.com/.</a></p> 325</blockquote> 326 327<blockquote>Note that, for early web server development and/or testing, you 328can skip the entire procedure described above and just generate your own 329self-signed root cert as described in section 1. No CA is involved; no CSR 330is generated; no cert needs to be imported - CertTool generates a cert for 331you and immediately adds it to your keychain. Bear in mind that this option 332requires tolerance of the various SSL clients you'll be testing with, none 333of whom recognize your root cert.</blockquote> 334 335<blockquote> </blockquote> 336 337<h2><a name="5._Importing_a_CRL"></a> 5. <a name="Importing_a_CRL"></a>Importing 338a CRL</h2> 339 340<blockquote>This command is used to add a Certificate Revocation List (CRL) 341to a keychain.<i></i> 342 <p>The format of this command is </p> 343 <p># <b>CertTool I inFileName [options]</b> </p> 344 <p>The CRL to import is obtained from "inFileName". </p> 345 <p>The available options are: </p> 346 <p>k=keyChainName </p> 347 <blockquote>Where "KeyChainName" is the name of the keychain to which the 348CRL will be added. If no keychain is specified, the cert is added to the default 349keychain. If the keychain is not open when this command is executed, 350you will be prompted by the Keychain system for its passphrase.</blockquote> 351 d 352 <blockquote>Specifies DER format as described above. The default is PEM 353format.<br> 354 </blockquote> 355 c 356 <blockquote>Specifies that the designated keychain is to be created.<br> 357 </blockquote> 358 <blockquote> 359 <blockquote> <br> 360 </blockquote> 361 <br> 362 </blockquote> 363 </blockquote> 364 365<h2><a name="6._Displaying_a_CRL"></a> 6. <a 366 name="Displaying_a_CRL"></a>Displaying a CRL</h2> 367 368<blockquote>This displays the contents of an existing Certificate Revocation 369List (CRL) , obtained from a file. 370 <p>The format of this command is </p> 371 <p># <b>CertTool D inFileName [options]</b> </p> 372 <p>The cert to display is obtained from "inFileName". </p> 373 <p>The only available option is the 'd' flag, specifying DER format as described 374above. The default is PEM format <br> 375 </p> 376</blockquote> 377<br> 378</body> 379</html> 380