CertTool/CertTool.html

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