CertTool

Last Update 5/20/02

Table Of Contents

1. Introduction
2. Generating a Self-Signed Certificate
3. Generating a Certificate Signing Request (CSR)
4. Verifying a CSR
5. Importing a Certificate from a Certificate Authority
6. Displaying a Certificate
7. Certificate Authorities and CSRs
 

1. Introduction

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.

The reader of this document, and the user of CertTool, is assumed to be familiar with the following:

No programming knowledge is assumed or required. An excellent primer on the topics of public key cryptography, certificates, and SSL can be found at http://httpd.apache.org/docs-2.0/ssl/ssl_intro.html.

Note: in all examples of usage of the command line tool which follow, the user's input is shown in bold. Running CertTool with no command-line arguments results in usage info being displayed.
 

2. Generating a Self-Signed Certificate

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.

The format of this command is

# CertTool c [options]

The available options are:

k=keyChainName
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.
c
Specifies that the designated key is to be created.
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.
 
# CertTool k=certkc
Enter key and certificate label: testCert

Please specify parameters for the key pair you will generate.

  r  RSA
  d  DSA
  f  FEE

Select key algorithm by letter: r

Valid key sizes for RSA are 512..2048; default is 512
Enter key size in bits or CR for default: 512

You have selected algorithm RSA, key size 512 bits.
OK (y/anything)? y
Enter cert/key usage (s=signing, b=signing AND encrypting): b
...Generating key pair...

<<Note: you will be prompted for the Keychain's passphrase by the Keychain system at this point if the specified keychain is not open.>>

Please specify the algorithm with which your certificate will be signed.

  5  RSA with MD5
  s  RSA with SHA1

Select signature algorithm by letter: s

You have selected algorithm RSA with SHA1.
OK (y/anything)? y
...creating certificate...

You will now specify the various components of the certificate's
Relative Distinguished Name (RDN). An RDN has a number of
components, all of which are optional, but at least one of
which must be present.

Note that if you are creating a certificate for use in an
SSL/TLS server, the Common Name component of the RDN must match
exactly the host name of the server. This must not be an IP
address, but the actual domain name, e.g. www.apple.com.

Entering a CR for a given RDN component results in no value for
that component.

Common Name       (e.g, www.apple.com) : 10.0.61.5
Country                  (e.g, US) :
Organization            (e.g, Apple Computer, Inc.) : Apple
Organization Unit     (e.g, Apple Data Security) :
State/Province          (e.g., California) : California

You have specified:
  Common Name       : 10.0.61.5
  Organization            : Apple
  State/Province         : California
Is this OK (y/anything)? y
..cert stored in Keychain.
#

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.

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().
 
 

3. Generating a Certificate Signing Request (CSR)

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.

The general procedure for obtaining a "real" cert is:
 

This command performs the first two steps in the above procedure. See Section 5 for information on importing the resulting certificate into your keychain.

The format of this command is

# CertTool r outFileName [options]

The resulting CSR will be written to "outFileName".

The available options are:

k=keyChainName

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.
d
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.
c
Specifies that the designated key is to be created.
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.

See Section 7 for more information on using CSRs and about CAs.
 
 

4. Verifying a CSR

A CSR contains, among other things, the public key which was generated in Section 3. 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.

The format of this command is

# CertTool v inFileName [options]

The resulting CSR will be written to "outFileName".

The only available option is the 'd' flag, which as described in Section 3, indiciates that the CSR is in DER format rather than the default PEM format.

A typical (successful) run of this command is like so:

# CertTool v myCsr.pem
...CSR verified successfully.

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.
 

 

5. Importing a Certificate from a Certificate Authority

Once you have negotiated with your CA, and provided them with the CSR generated in Section 3 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 Section 3. You currently also have to specify the string you provided as "key and certificate label" when executing this command. <Note this requirement will go away soon.>

The format of this command is

# CertTool i inFileName label [options]

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 Section 3.

The available options are:

k=keyChainName

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 Section 3. If the keychain is not open when this command is executed, you will be prompted by the Keychain system for its passphrase.
d
Specifies DER format as described above. The default is PEM format.

6. Displaying a Certificate

This displays the contents of an existing certificate, obtained from a file.

The format of this command is

# CertTool d inFileName [options]

The cert to display is obtained from "inFileName".

The only available option is the 'd' flag, specifying DER format as described above. The default is PEM format
 

7. Certificate Authorities and CSRs

As mentioned above, the general procedure for obtaining a "real" cert is:
One CA with an excellent web-based interface for obtaining a cert is Verisign (http://www.verisign.com/products/site/index.html). 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 Section 3 into a form on the web site. A few minutes later Verisign emails you a certificate, which you import into your keychain per Section 5.  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.

Thawte has a similar, very friendly service at http://www.thawte.com/.

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.