| df0e469f |
1 | <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">\r<html>\r<head>\r \r <meta http-equiv="Content-Type"\r content="text/html; charset=iso-8859-1">\r \r <meta name="GENERATOR"\r content="Mozilla/4.75C-CCK-MCD {C-UDP; EBM-APPLE} (Macintosh; U; PPC) [Netscape]">\r <title>CertTool.html</title>\r</head>\r <body>\r \r<center> \r<h2> <b>CertTool</b></h2>\r</center>\r \r<center> \r<h2> <b>Last Update 10/10/02</b></h2>\r</center>\r \r<h2> Table Of Contents</h2>\r 1. <a href="#Introduction">Introduction</a> <br>\r2. <a href="#Generating%20a%20Self-Signed%20Certificate">Generating a Self-Signed \rCertificate</a> <br>\r3. <a\r href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Generating \ra Certificate Signing Request (CSR)</a> <br>\r4. <a href="#Verifying%20a%20CSR">Verifying a CSR</a> <br>\r5. <a\r href="#Importing%20a%20Certificate%20from%20a%20Certificate%20Authority">Importing \ra Certificate from a Certificate Authority</a> <br>\r6. <a href="#Displaying%20a%20Certificate">Displaying a Certificate</a> <br>\r7. <a href="#Certificate%20Authorities%20and%20CSRs">Certificate Authorities \rand CSRs</a> <br>\r8. <a href="#5._Importing_a_CRL">Importing a CRL</a> <br>\r9. <a href="#6._Displaying_a_CRL">Displaying a CRL</a> \r<h2> 1. <a name="Introduction"></a>Introduction</h2>\r \r<blockquote>CertTool is a UNIX command-line program which is used to create \rkey pairs, certificates, and certificate signing requests; to import externally \rgenerated certificates into a Keychain, and to display the contents of certificates.\rCurrently. the primary use of CertTool is to perform the certificate-related\radministration required to configure an SSL server based on Mac OS X's SecureTransport\rlibrary. Each supported CertTool operation is described below in detail. \r <p>The reader of this document, and the user of CertTool, is assumed to \rbe familiar with the following: </p>\r <ul>\r <li> General principles of public key cryptography</li>\r <li> The concepts of certificates and trust</li>\r <li> General operation of the Secure Socket Layer (SSL) protocol</li>\r <li> General operation of the Mac OS X Keychain</li>\r <li> The Mac OS X SecureTransport library</li>\r \r </ul>\r No programming knowledge is assumed or required. An excellent primer on the\rtopics of public key cryptography, certificates, and SSL can be found at\r <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> \r <p>Note: in all examples of usage of the command line tool which follow, \rthe user's input is shown in <b>bold</b>. Running CertTool with no command-line \rarguments results in usage info being displayed. <br>\r </p>\r</blockquote>\r \r<h2> 2. <a name="Generating a Self-Signed Certificate"></a>Generating\ra Self-Signed Certificate</h2>\r \r<blockquote>This command generates a key pair and a self-signed (root) certificate\rand places them in a keychain. The root cert is signed by the private key\rgenerated during this command. The cert generated by this command is totally\runtrustworth and cannot be used in the "real world"; the primary use of this\rcommand is to facilitate early development of SSL server applications based\ron SecureTransport. In particular, "real world" SSL clients (e.g., web browsers)\rwill complain to varying degrees when they attempt to connect to an SSL server\rwhich presents a cert which is generated by this command. Some broswers,\rafter a fair amount of handholding, will allow you to conditionally "trust"\rthis cert. \r <p>The format of this command is </p>\r <p># <b>CertTool c [options]</b> </p>\r <p>The available options are: </p>\r <blockquote>k=keyChainName \r <blockquote>Where "KeyChainName" is the name of the keychain into which \rkeys and the cert will be added. If no keychain is specified, keys and certs\rare added to the default keychain. The specified keychain must exist unless\ryou specify the 'c' option.</blockquote>\r c \r <blockquote>Specifies that the designated keychain is to be created.</blockquote>\r </blockquote>\r This an interactive command; you will be prompted for a number of different \ritems which are used to generate the keypair and the cert. A sample sesion \rfollows. <br>\r \r <blockquote># <b>CertTool k=certkc</b> <br>\rEnter key and certificate label: <b>testCert</b> \r <p>Please specify parameters for the key pair you will generate. </p>\r <p> r RSA <br>\r d DSA <br>\r f FEE </p>\r <p>Select key algorithm by letter: <b><font size="+1">r</font></b> </p>\r <p>Valid key sizes for RSA are 512..2048; default is 512 <br>\rEnter key size in bits or CR for default: <b><font size="+1">512</font></b> \r </p>\r <p>You have selected algorithm RSA, key size 512 bits. <br>\rOK (y/anything)? <b><font size="+1">y</font></b> <br>\rEnter cert/key usage (s=signing, b=signing AND encrypting): b <br>\r...Generating key pair... </p>\r <p><i><<Note: you will be prompted for the Keychain's passphrase \rby the Keychain system at this point if the specified keychain is not open.>></i> \r </p>\r <p>Please specify the algorithm with which your certificate will be signed. \r </p>\r <p> 5 RSA with MD5 <br>\r s RSA with SHA1 </p>\r <p>Select signature algorithm by letter:<b><font size="+1"> s</font></b> \r </p>\r <p>You have selected algorithm RSA with SHA1. <br>\rOK (y/anything)? <b><font size="+1">y</font></b> <br>\r...creating certificate... </p>\r <p>You will now specify the various components of the certificate's <br>\rRelative Distinguished Name (RDN). An RDN has a number of <br>\rcomponents, all of which are optional, but at least one of <br>\rwhich must be present. </p>\r <p>Note that if you are creating a certificate for use in an <br>\rSSL/TLS server, the Common Name component of the RDN must match <br>\rexactly the host name of the server. This must not be an IP <br>\raddress, but the actual domain name, e.g. www.apple.com. </p>\r <p>Entering a CR for a given RDN component results in no value for <br>\rthat component. </p>\r <p>Common Name (e.g, www.apple.com) \r: <b><font size="+1">10.0.61.5</font></b> <br>\rCountry \r(e.g, US) : <br>\rOrganization \r(e.g, Apple Computer, Inc.) : <b><font size="+1">Apple</font></b> <br>\rOrganization Unit (e.g, Apple Data Security) : <br>\rState/Province (e.g.,\rCalifornia) : <b><font size="+1">California</font></b> </p>\r <p>You have specified: <br>\r Common Name : 10.0.61.5 <br>\r Organization \r: Apple <br>\r State/Province : California \r <br>\rIs this OK (y/anything)? <b><font size="+1">y</font></b> <br>\r..cert stored in Keychain. <br>\r#</p>\r </blockquote>\r The "Common Name" portion of the RDN - in the above case, "10.0.61.5" - MUST\rmatch the host name of the machine you'll running sslServer on. (In this\rcase the test machine doesn't have an actual hostname; it's DHCP'd behind\ra firewall which is why "10.0.61.5" was specified for Common Name.) This\ris part of SSL's certificate verification; it prevents an attack using DNS\rspoofing. \r <p>A brief note about cert/key usage: the normal configuration of SecureTransport \ris that the server cert specified in SSLSetCertificate() is capable of both\rsigning and encryption. If this cert is only capable of signing, then you\rmust create a second keychain ontaining a cert which is capable of encryption,\rand pass that to SSLSetEncryptionCertificate(). <br>\r <br>\r </p>\r</blockquote>\r \r<h2> 3. <a name="Generating a Certificate Signing Request (CSR)"></a>Generating \ra Certificate Signing Request (CSR)</h2>\r \r<blockquote>A CSR is the standard means by which an administrator of a web\rserver provides information to a Certificate Authority (CA) in order to obtain\ra valid certificate which is signed by the CA. This type of cert is used\rin the real world; certs signed by CAs such as Verisign or Thawte are recognized\rby all web browsers when performing SSL transactions. \r <p>The general procedure for obtaining a "real" cert is: <br>\r </p>\r <ul>\r <li> Generate a key pair</li>\r <li> Generate a CSR</li>\r <li> Provide the CSR and some other information and/or documentation to\rthe CA</li>\r <li> CA sends you a certificate which is signed by the CA.</li>\r <li> You import that certificate, obtained from the CA, into your keychain. \rThe items in that keychain can now be used in SecureTranspoert's SSLSetCertificate() \rcall.</li>\r \r </ul>\r This command performs the first two steps in the above procedure. See <a\r href="#Importing%20a%20Certificate%20from%20a%20Certificate%20Authority">Section \r5</a> for information on importing the resulting certificate into your keychain. \r <p>The format of this command is </p>\r <p># <b>CertTool r outFileName [options]</b> </p>\r <p>The resulting CSR will be written to "outFileName". </p>\r <p>The available options are: </p>\r <p>k=keyChainName </p>\r <blockquote>Where "KeyChainName" is the name of the keychain into which \rkeys and the cert will be added. If no keychain is specified, keys and certs\rare added to the default keychain. The specified keychain must exist unless\ryou specify the 'c' option.</blockquote>\r d \r <blockquote>The 'd' option tells CertTool to create the CSR in DER-encoded \rformat. The default is PEM-encoded, which is what most CAs expect. PEM encoded\rdata consists of printable ASCII text which can, for example, be pasted into\ran email message. DER-encoded data is nonprintable binary data.</blockquote>\r c \r <blockquote>Specifies that the designated keychain is to be created.</blockquote>\r This an interactive command; you will be prompted for a number of different \ritems which are used to generate the keypair and the CSR. The prompts given, \rand the format of the data you must supply, are identical to the data shown \rin the sample session in Section 2. \r <p>See Section 7 for more information on using CSRs and about CAs. <br>\r <br>\r </p>\r</blockquote>\r \r<h2> 4. <a name="Verifying a CSR"></a>Verifying a CSR</h2>\r \r<blockquote>A CSR contains, among other things, the public key which was generated\rin <a\r href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Section \r3</a>. The CSR is signed with the associated private key. Thus the inteegrity \rof a CSR can be verified by extracting its public key and verifying the signature\rof the CSR. This command performs this integrity check. \r <p>The format of this command is </p>\r <p># <b>CertTool v inFileName [options]</b> </p>\r <p>The resulting CSR will be written to "outFileName". </p>\r <p>The only available option is the 'd' flag, which as described in <a\r href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Section \r3</a>, indiciates that the CSR is in DER format rather than the default PEM\rformat. </p>\r <p>A typical (successful) run of this command is like so: </p>\r <p># <b>CertTool v myCsr.pem</b> <br>\r...CSR verified successfully. </p>\r <p>A large number of things can go wrong of the verification fails; suffice \rit to say that if you see anything other than the above success message, you\rhave a bad or corrupted CSR. <br>\r </p>\r <blockquote> </blockquote>\r </blockquote>\r \r<h2> 5. <a\r name="Importing a Certificate from a Certificate Authority"></a>Importing \ra Certificate from a Certificate Authority</h2>\r \r<blockquote>Once you have negotiated with your CA, and provided them with \rthe CSR generated in <a\r href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Section \r3</a> as well as any other information, documentation, and payment thay require,\rthe CA will provide you with a certificate. Use this command to add that\rcertificate to the keychain containing the keypair you generated in <a\r href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Section\r3</a>. <i></i> \r <p>The format of this command is </p>\r <p># <b>CertTool i inFileName [options]</b> </p>\r <p>The cert to import is obtained from "inFileName". </p>\r <p>The available options are: </p>\r <p>k=keyChainName </p>\r <blockquote>Where "KeyChainName" is the name of the keychain to which the \rcert will be added. If no keychain is specified, the cert is added to the \rdefault keychain. The specified keychain should contain the keypair you generated\rin <a\r href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Section \r3</a>. (Note you can import a certificate into a keychain which does not\rcontain keys you generated but there will be no linkage between the imported\rcertificate and a private key if you do this.) If the keychain is not open\rwhen this command is executed, you will be prompted by the Keychain system\rfor its passphrase.</blockquote>\r d \r <blockquote>Specifies DER format as described above. The default is PEM \rformat.<br>\r <br>\r </blockquote>\r c \r <blockquote>Specifies that the designated keychain is to be created.<br>\r <br>\r </blockquote>\r </blockquote>\r \r<h2> 6. <a name="Displaying a Certificate"></a>Displaying a Certificate</h2>\r \r<blockquote>This displays the contents of an existing certificate, obtained \rfrom a file. \r <p>The format of this command is </p>\r <p># <b>CertTool d inFileName [options]</b> </p>\r <p>The cert to display is obtained from "inFileName". </p>\r <p>The only available option is the 'd' flag, specifying DER format as described\rabove. The default is PEM format <br>\r </p>\r</blockquote>\r \r<h2> 7. <a name="Certificate Authorities and CSRs"></a>Certificate Authorities \rand CSRs</h2>\r \r<blockquote>As mentioned above, the general procedure for obtaining a "real" \rcert is: \r <ul>\r <li> Generate a key pair</li>\r <li> Generate a CSR</li>\r <li> Provide the CSR and some other information and/or documentation to\rthe CA</li>\r <li> CA sends you a certificate which is signed by the CA.</li>\r <li> You import that certificate, obtained from the CA, into your keychain. \rThe items in that keychain can now be used in SecureTranspoert's SSLSetCertificate() \rcall.</li>\r \r </ul>\r </blockquote>\r \r<blockquote>One CA with an excellent web-based interface for obtaining a\rcert is Verisign (<a\r href="http://www.verisign.com/products/site/index.html">http://www.verisign.com/products/site/index.html</a>). \rYou can get a free 14-day trial certificate using nothing but CertTool, Verisign's\rweb site, and email. You need to provide some personal information; then\ryou paste in the CSR generated in <a\r href="#Generating%20a%20Certificate%20Signing%20Request%20%28CSR%29">Section \r3</a> into a form on the web site. A few minutes later Verisign emails you\ra certificate, which you import into your keychain per <a\r href="#Importing%20a%20Certificate%20from%20a%20Certificate%20Authority">Section \r5</a>. The whole process takes less than 10 minutes. The free certificate \robtained in this manner is signed by a temporary root cert which is not recognized\rby any browsers, but Verisign also provides a measn of installing this temporary\rroot cert into your browser, directly from their web site. Typically one\rwould use the free, temporary cert to perform initial configuration of a\rserver and to ring out the general SSL infrastructure. Once you feel comfortable\rwith the operation of the server, then it's time to buy a "real" certificate\rwhich will allow your web server to be recognized by any browser. \r <p>Thawte has a similar, very friendly service at <a\r href="http://www.thawte.com">http://www.thawte.com/.</a></p>\r</blockquote>\r \r<blockquote>Note that, for early web server development and/or testing, you\rcan skip the entire procedure described above and just generate your own\rself-signed root cert as described in section 1. No CA is involved; no CSR\ris generated; no cert needs to be imported - CertTool generates a cert for\ryou and immediately adds it to your keychain. Bear in mind that this option\rrequires tolerance of the various SSL clients you'll be testing with, none\rof whom recognize your root cert.</blockquote>\r \r<blockquote> </blockquote>\r \r<h2><a name="5._Importing_a_CRL"></a> 5. <a name="Importing_a_CRL"></a>Importing \ra CRL</h2>\r \r<blockquote>This command is used to add a Certificate Revocation List (CRL)\rto a keychain.<i></i> \r <p>The format of this command is </p>\r <p># <b>CertTool I inFileName [options]</b> </p>\r <p>The CRL to import is obtained from "inFileName". </p>\r <p>The available options are: </p>\r <p>k=keyChainName </p>\r <blockquote>Where "KeyChainName" is the name of the keychain to which the\rCRL will be added. If no keychain is specified, the cert is added to the default\rkeychain. If the keychain is not open when this command is executed,\ryou will be prompted by the Keychain system for its passphrase.</blockquote>\r d \r <blockquote>Specifies DER format as described above. The default is PEM \rformat.<br>\r </blockquote>\r c \r <blockquote>Specifies that the designated keychain is to be created.<br>\r </blockquote>\r <blockquote>\r <blockquote> <br>\r </blockquote>\r <br>\r </blockquote>\r </blockquote>\r \r<h2><a name="6._Displaying_a_CRL"></a> 6. <a\r name="Displaying_a_CRL"></a>Displaying a CRL</h2>\r \r<blockquote>This displays the contents of an existing Certificate Revocation\rList (CRL) , obtained from a file. \r <p>The format of this command is </p>\r <p># <b>CertTool D inFileName [options]</b> </p>\r <p>The cert to display is obtained from "inFileName". </p>\r <p>The only available option is the 'd' flag, specifying DER format as described\rabove. The default is PEM format <br>\r </p>\r</blockquote>\r<br>\r</body>\r</html>\r |
projects / apple / security.git / blame