[apple/security.git] / CertTool / CertTool.html

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.75C-CCK-MCD {C-UDP; EBM-APPLE} (Macintosh; U; PPC) [Netscape]">
   <title>CertTool.html</title>
</head>
<body>

<center>
<h2>
<b>CertTool</b></h2></center>

<center>
<h2>
<b>Last Update 5/20/02</b></h2></center>

<h2>
Table Of Contents</h2>
1. <a href="#Introduction">Introduction</a>
<br>2. <a href="#Generating a Self-Signed Certificate">Generating a Self-Signed
Certificate</a>
<br>3. <a href="#Generating a Certificate Signing Request (CSR)">Generating
a Certificate Signing Request (CSR)</a>
<br>4. <a href="#Verifying a CSR">Verifying a CSR</a>
<br>5. <a href="#Importing a Certificate from a Certificate Authority">Importing
a Certificate from a Certificate Authority</a>
<br>6. <a href="#Displaying a Certificate">Displaying a Certificate</a>
<br>7. <a href="#Certificate Authorities and CSRs">Certificate Authorities
and CSRs</a>
<br>&nbsp;
<h2>
1.&nbsp;<a NAME="Introduction"></a>Introduction</h2>

<blockquote>CertTool is a UNIX command-line program which is used to create
key pairs, certificates, and certificate signing requests; to import externally
generated certificates into a Keychain, and to display the contents of
certificates. Currently. the primary use of CertTool is to perform the
certificate-related administration required to configure an SSL server
based on Mac OS X's SecureTransport library. Each supported CertTool operation
is described below in detail.
<p>The reader of this document, and the user of CertTool, is assumed to
be familiar with the following:
<ul>
<li>
General principles of public key cryptography</li>

<li>
The concepts of certificates and trust</li>

<li>
General operation of the Secure Socket Layer (SSL) protocol</li>

<li>
General operation of the Mac OS X Keychain</li>

<li>
The Mac OS X SecureTransport library</li>
</ul>
No programming knowledge is assumed or required. An excellent primer on
the topics of public key cryptography, certificates, and SSL can be found
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>
<p>Note: in all examples of usage of the command line tool which follow,
the user's input is shown in <b>bold</b>. Running CertTool with no command-line
arguments results in usage info being displayed.
<br>&nbsp;</blockquote>

<h2>
2.&nbsp;<a NAME="Generating a Self-Signed Certificate"></a>Generating a
Self-Signed Certificate</h2>

<blockquote>This command generates a key pair and a self-signed (root)
certificate and places them in a keychain. The root cert is signed by the
private key generated during this command. The cert generated by this command
is totally untrustworth and cannot be used in the "real world"; the primary
use of this command is to facilitate early development of SSL server applications
based on SecureTransport. In particular, "real world" SSL clients (e.g.,
web browsers) will complain to varying degrees when they attempt to connect
to an SSL server which presents a cert which is generated by this command.
Some broswers, after a fair amount of handholding, will allow you to conditionally
"trust" this cert.
<p>The format of this command is
<p># <b>CertTool c [options]</b>
<p>The available options are:
<blockquote>k=keyChainName
<blockquote>Where "KeyChainName" is the name of the keychain into which
keys and the cert will be added. If no keychain is specified, keys and
certs are added to the default keychain. The specified keychain must exist
unless you specify the 'c' option.</blockquote>
c
<blockquote>Specifies that the designated key is to be created.</blockquote>
</blockquote>
This an interactive command; you will be prompted for a number of different
items which are used to generate the keypair and the cert. A sample sesion
follows.
<br>&nbsp;
<blockquote># <b>CertTool k=certkc</b>
<br>Enter key and certificate label: <b>testCert</b>
<p>Please specify parameters for the key pair you will generate.
<p>&nbsp; r&nbsp; RSA
<br>&nbsp; d&nbsp; DSA
<br>&nbsp; f&nbsp; FEE
<p>Select key algorithm by letter: <b><font size=+1>r</font></b>
<p>Valid key sizes for RSA are 512..2048; default is 512
<br>Enter key size in bits or CR for default: <b><font size=+1>512</font></b>
<p>You have selected algorithm RSA, key size 512 bits.
<br>OK (y/anything)? <b><font size=+1>y</font></b>
<br>Enter cert/key usage (s=signing, b=signing AND encrypting): b
<br>...Generating key pair...
<p><i>&lt;&lt;Note: you will be prompted for the Keychain's passphrase
by the Keychain system at this point if the specified keychain is not open.>></i>
<p>Please specify the algorithm with which your certificate will be signed.
<p>&nbsp; 5&nbsp; RSA with MD5
<br>&nbsp; s&nbsp; RSA with SHA1
<p>Select signature algorithm by letter:<b><font size=+1> s</font></b>
<p>You have selected algorithm RSA with SHA1.
<br>OK (y/anything)? <b><font size=+1>y</font></b>
<br>...creating certificate...
<p>You will now specify the various components of the certificate's
<br>Relative Distinguished Name (RDN). An RDN has a number of
<br>components, all of which are optional, but at least one of
<br>which must be present.
<p>Note that if you are creating a certificate for use in an
<br>SSL/TLS server, the Common Name component of the RDN must match
<br>exactly the host name of the server. This must not be an IP
<br>address, but the actual domain name, e.g. www.apple.com.
<p>Entering a CR for a given RDN component results in no value for
<br>that component.
<p>Common Name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (e.g, www.apple.com)
: <b><font size=+1>10.0.61.5</font></b>
<br>Country&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
(e.g, US) :
<br>Organization&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
(e.g, Apple Computer, Inc.) : <b><font size=+1>Apple</font></b>
<br>Organization Unit&nbsp;&nbsp;&nbsp;&nbsp; (e.g, Apple Data Security)
:
<br>State/Province&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
(e.g., California) : <b><font size=+1>California</font></b>
<p>You have specified:
<br>&nbsp; Common Name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; : 10.0.61.5
<br>&nbsp; Organization&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
: Apple
<br>&nbsp; State/Province&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
: California
<br>Is this OK (y/anything)? <b><font size=+1>y</font></b>
<br>..cert stored in Keychain.
<br>#</blockquote>
The "Common Name" portion of the RDN - in the above case, "10.0.61.5" -
MUST match the host name of the machine you'll running sslServer on. (In
this case the test machine doesn't have an actual hostname; it's DHCP'd
behind a firewall which is why "10.0.61.5" was specified for Common Name.)
This is part of SSL's certificate verification; it prevents an attack using
DNS spoofing.
<p>A brief note about cert/key usage: the normal configuration of SecureTransport
is that the server cert specified in SSLSetCertificate() is capable of
both signing and encryption. If this cert is only capable of signing, then
you must create a second keychain ontaining a cert which is capable of
encryption, and pass that to SSLSetEncryptionCertificate().
<br>&nbsp;
<br>&nbsp;</blockquote>

<h2>
3.&nbsp;<a NAME="Generating a Certificate Signing Request (CSR)"></a>Generating
a Certificate Signing Request (CSR)</h2>

<blockquote>A CSR is the standard means by which an administrator of a
web server provides information to a Certificate Authority (CA) in order
to obtain a valid certificate which is signed by the CA. This type of cert
is used in the real world; certs signed by CAs such as Verisign or Thawte
are recognized by all web browsers when performing SSL transactions.
<p>The general procedure for obtaining a "real" cert is:
<br>&nbsp;
<ul>
<li>
Generate a key pair</li>

<li>
Generate a CSR</li>

<li>
Provide the CSR and some other information and/or documentation to the
CA</li>

<li>
CA sends you a certificate which is signed by the CA.</li>

<li>
You import that certificate, obtained from the CA, into your keychain.
The items in that keychain can now be used in SecureTranspoert's SSLSetCertificate()
call.</li>
</ul>
This command performs the first two steps in the above procedure. See <a href="#Importing a Certificate from a Certificate Authority">Section
5</a> for information on importing the resulting certificate into your
keychain.
<p>The format of this command is
<p># <b>CertTool r outFileName [options]</b>
<p>The resulting CSR will be written to "outFileName".
<p>The available options are:
<p>k=keyChainName
<blockquote>Where "KeyChainName" is the name of the keychain into which
keys and the cert will be added. If no keychain is specified, keys and
certs are added to the default keychain. The specified keychain must exist
unless you specify the 'c' option.</blockquote>
d
<blockquote>The 'd' option tells CertTool to create the CSR in DER-encoded
format. The default is PEM-encoded, which is what most CAs expect. PEM
encoded data consists of printable ASCII text which can, for example, be
pasted into an email message. DER-encoded data is nonprintable binary data.</blockquote>
c
<blockquote>Specifies that the designated key is to be created.</blockquote>
This an interactive command; you will be prompted for a number of different
items which are used to generate the keypair and the CSR. The prompts given,
and the format of the data you must supply, are identical to the data shown
in the sample session in Section 2.
<p>See Section 7 for more information on using CSRs and about CAs.
<br>&nbsp;
<br>&nbsp;</blockquote>

<h2>
4.&nbsp;<a NAME="Verifying a CSR"></a>Verifying a CSR</h2>

<blockquote>A CSR contains, among other things, the public key which was
generated in <a href="#Generating a Certificate Signing Request (CSR)">Section
3</a>. The CSR is signed with the associated private key. Thus the inteegrity
of a CSR can be verified by extracting its public key and verifying the
signature of the CSR. This command performs this integrity check.
<p>The format of this command is
<p># <b>CertTool v inFileName [options]</b>
<p>The resulting CSR will be written to "outFileName".
<p>The only available option is the 'd' flag, which as described in <a href="#Generating a Certificate Signing Request (CSR)">Section
3</a>, indiciates that the CSR is in DER format rather than the default
PEM format.
<p>A typical (successful) run of this command is like so:
<p># <b>CertTool v myCsr.pem</b>
<br>...CSR verified successfully.
<p>A large number of things can go wrong of the verification fails; suffice
it to say that if you see anything other than the above success message,
you have a bad or corrupted CSR.
<br>&nbsp;
<blockquote>&nbsp;</blockquote>
</blockquote>

<h2>
5.&nbsp;<a NAME="Importing a Certificate from a Certificate Authority"></a>Importing
a Certificate from a Certificate Authority</h2>

<blockquote>Once you have negotiated with your CA, and provided them with
the CSR generated in <a href="#Generating a Certificate Signing Request (CSR)">Section
3</a> as well as any other information, documentation, and payment thay
require, the CA will provide you with a certificate. Use this command to
add that certificate to the keychain containing the keypair you generated
in <a href="#Generating a Certificate Signing Request (CSR)">Section 3</a>.
You currently also have to specify the string you provided as "key and
certificate label" when executing this command. <i>&lt;Note this requirement
will go away soon.></i>
<p>The format of this command is
<p># <b>CertTool i inFileName label [options]</b>
<p>The cert to import is obtained from "inFileName". The label argument
is the string you provided to the prompt "Enter key and certificate label:"
in <a href="#Generating a Certificate Signing Request (CSR)">Section 3</a>.
<p>The available options are:
<p>k=keyChainName
<blockquote>Where "KeyChainName" is the name of the keychain to which the
cert will be added. If no keychain is specified, the cert is added to the
default keychain. The specified keychain must exist, and it must contain
the keypair you generated in <a href="#Generating a Certificate Signing Request (CSR)">Section
3</a>. If the keychain is not open when this command is executed, you will
be prompted by the Keychain system for its passphrase.</blockquote>
d
<blockquote>Specifies DER format as described above. The default is PEM
format.</blockquote>
</blockquote>

<h2>
6.&nbsp;<a NAME="Displaying a Certificate"></a>Displaying a Certificate</h2>

<blockquote>This displays the contents of an existing certificate, obtained
from a file.
<p>The format of this command is
<p># <b>CertTool d inFileName [options]</b>
<p>The cert to display is obtained from "inFileName".
<p>The only available option is the 'd' flag, specifying DER format as
described above. The default is PEM format
<br>&nbsp;</blockquote>

<h2>
7.&nbsp;<a NAME="Certificate Authorities and CSRs"></a>Certificate Authorities
and CSRs</h2>

<blockquote>As mentioned above, the general procedure for obtaining a "real"
cert is:
<ul>
<li>
Generate a key pair</li>

<li>
Generate a CSR</li>

<li>
Provide the CSR and some other information and/or documentation to the
CA</li>

<li>
CA sends you a certificate which is signed by the CA.</li>

<li>
You import that certificate, obtained from the CA, into your keychain.
The items in that keychain can now be used in SecureTranspoert's SSLSetCertificate()
call.</li>
</ul>
</blockquote>

<blockquote>One CA with an excellent web-based interface for obtaining
a cert is Verisign (<a href="http://www.verisign.com/products/site/index.html">http://www.verisign.com/products/site/index.html</a>).
You can get a free 14-day trial certificate using nothing but CertTool,
Verisign's web site, and email. You need to provide some personal information;
then you paste in the CSR generated in <a href="#Generating a Certificate Signing Request (CSR)">Section
3</a> into a form on the web site. A few minutes later Verisign emails
you a certificate, which you import into your keychain per <a href="#Importing a Certificate from a Certificate Authority">Section
5</a>.&nbsp; The whole process takes less than 10 minutes. The free certificate
obtained in this manner is signed by a temporary root cert which is not
recognized by any browsers, but Verisign also provides a measn of installing
this temporary root cert into your browser, directly from their web site.
Typically one would use the free, temporary cert to perform initial configuration
of a server and to ring out the general SSL infrastructure. Once you feel
comfortable with the operation of the server, then it's time to buy a "real"
certificate which will allow your web server to be recognized by any browser.
<p>Thawte has a similar, very friendly service at <a href="http://www.thawte.com">http://www.thawte.com/.</a></blockquote>

<blockquote>Note that, for early web server development and/or testing,
you can skip the entire procedure described above and just generate your
own self-signed root cert as described in section 1. No CA is involved;
no CSR is generated; no cert needs to be imported - CertTool generates
a cert for you and immediately adds it to your keychain. Bear in mind that
this option requires tolerance of the various SSL clients you'll be testing
with, none of whom recognize your root cert.</blockquote>

</body>
</html>
Commit	Line	Data
29654253 A	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>
	32	<h2>
	33	1. <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> </blockquote>
67
68	<h2>
69	2. <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>
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>  r  RSA
101	<br>  d  DSA
102	<br>  f  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><<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>  5  RSA with MD5
114	<br>  s  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       (e.g, www.apple.com)
130	: <b><font size=+1>10.0.61.5</font></b>
131	<br>Country
132	(e.g, US) :
133	<br>Organization
134	(e.g, Apple Computer, Inc.) : <b><font size=+1>Apple</font></b>
135	<br>Organization Unit     (e.g, Apple Data Security)
136	:
137	<br>State/Province
138	(e.g., California) : <b><font size=+1>California</font></b>
139	<p>You have specified:
140	<br>  Common Name       : 10.0.61.5
141	<br>  Organization
142	: Apple
143	<br>  State/Province
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>
160	<br> </blockquote>
161
162	<h2>
163	3. <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>
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>
217	<br> </blockquote>
218
219	<h2>
220	4. <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>
240	<blockquote> </blockquote>
241	</blockquote>
242
243	<h2>
244	5. <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><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. <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> </blockquote>
285
286	<h2>
287	7. <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>.  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>