certtool.1   [plain text]


.de EX
.nf
.ft CW
.RS

..
.de EE
.br
.fi
.ft 1
.RE
.Pp
..
.de BL
.TP
\(bu
..
.TH CERTTOOL 1 "March 19, 2003" "Apple Computer, Inc."
.SH NAME
certtool \- create key pairs, certificates and certificate signing requests for
use with Keychains
.SH SYNOPSIS
.B certtool
command [command-args] [options]
.Pp
.B certtool
c [options]
.Pp
.B certtool
r outFileName [options]
.Pp
.B certtool
v infileName [options]
.Pp
.B certtool
C domainName [options]
.Pp
.B certtool
i inFileName [options]
.Pp
.B certtool
d inFileName [options]
.Pp
.B certtool
I inFileName [options]
.Pp
.B certtool
D inFileName [options]
.Pp
.B certtool
y [options]
.SH CERTTOOL COMMAND SUMMARY
.B c
Create keypair and Certificate
.Pp
.B r
Create CSR
.Pp
.B v
Verify CSR
.Pp
.B C
Create a System Identity
.Pp
.B i
Import Certificate
.Pp
.B d
Display Certificate
.Pp
.B I
Import CRL
.Pp
.B D
Display CRL
.Pp
.B I
Import a CRL
.Pp
.B y
Display all certs and CRLs in keychain
.Pp
.SH "CERTTOOL OPTION SUMMARY"
.TP
.B c
Create the keychain, if one is needed.
.TP
.B d
Create a CSR in DER format; default is PEM
.TP
.B k=keychainName
Specify the Keychain to use for the operation. If keychainName starts with a '/', an absolute path is assumed; otherwise, the specified filename is relative to the user's Library/Keychains directory.
.TP
.B p=passphrase
Specify the keychain passphrase when creating
.TP
.B r=privateKeyFileName
Optional private key, for Import Certificate only
.TP
.B f=[18f]
Private Key Format = PKCS1/PKCS8/FIPS186; default is PKCS1 (openssl)
.TP
.B x=[aSsm]
Extended Key Usage: a=Any; s=SSL Client; S=SSL Server; m=SMIME
.TP
.B a
Generate private key with default ACL
.TP
.B u
Generate private key with ACL limiting access to current user
.TP
.B P
Don't create System Identity if one already exists for specified domain
.TP
.B h
Print usage message
.TP
.B v
Execute in verbose mode.
.SH "DESCRIPTION"
.B Certtool
is a UNIX command-line program which is used to create key pairs, certificates,
and certificate signing requests; to import externally generated certificates
and Certificate Revocation Lists (CRLs) into a Keychain, and to display the 
contents of certificates and CRLs. 
.SH EXAMPLES
.Pp
.B "Generating a Self-Signed Certificate"
.Pp
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 untrustworthy 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. 
.EX
# CertTool c [options]
.EE
The available options are:
.EX
k=keyChainName 
.EE
Where "keyChainName" is the name of the keychain into which keys and the cert
will be added. The specified keychain must exist. If it doesn't exist and
you want the keychain created for you, specify the 'c' option. If no keychain
is specified, keys and certs are added to the default keychain. 
.EX
c 
.EE
Specifies that the designated keychain is to be created.
.EX
x=[aSsm]
.EE
Specifies an optional Extended Key Usage extension. Values are 'a' for ExtendedKeyUseAny; 's' for SSL client (ClientAuth); 'S' for SSL server (ServerAuth); and 'm' for S/MIME (EmailProtection).
.EX
a
.EE
Results the the private key being created with a default ACL. If not specified, the private key is created with no ACL. 
.Pp
.EX
u
.EE
Create the private key with an ACL limiting access to the current user. 
.Pp
This is 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 session
follows. 
.EX
# 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... 

.EE
Note: you will be prompted for the Keychain's passphrase by the Keychain
system at this point if the specified keychain is not open and you have not specified the passphrase via the 'p' option. 
.EX
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... 
.EE
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. 
.Pp
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. 
.EX
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 
Email Address     (e.g. johngalt@rand.com) : 
You have specified: 
 Common Name	: 10.0.61.5 
 Organization	: Apple 
 State/Province : California 
Is this OK (y/anything)? y 
..cert stored in Keychain. 
#
.EE
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 be running an SSL/TLS server 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. 
.Pp
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, you must
create a second keychain containing a cert which is capable of encryption, and
pass that to SSLSetEncryptionCertificate(). 
.Pp
.B "Generating a Certificate Signing Request (CSR)"
.Pp
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 and Thawte are recognized by most web
browsers when performing SSL transactions. 
.Pp
The general procedure for obtaining a "real" cert is: 
.BL
Generate a key pair
.BL
Generate a CSR
.BL
Provide the CSR and some other information and/or documentation to the CA
.BL
CA sends you a certificate which is signed by the CA.
.BL
You import that certificate, obtained from the CA, into your keychain.
.Pp
The
items in that keychain can now be used in SecureTransport's SSLSetCertificate()
call.
.Pp
This command performs the first two steps in the above procedure. See the 
section below entitled "Importing a Certificate" for information on 
importing the resulting certificate into your keychain. The format of 
this command is 
.EX
# CertTool r outFileName [options] 
.EE
The resulting CSR will be written to "outFileName". 
The available options are: 
.EX
k=keyChainName 
.EE
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.
.EX
 d 
.EE
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.
.EX
 c 
.EE
Specifies that the designated keychain is to be created.
.EX
a
.EE
Results the the private key being created with a default ACL. If not specified, the private key is created with no ACL. 
.EX
u
.EE
Create the private key with an ACL limiting access to the current user. 
.Pp
This is 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. 
.Pp
.B "Verifying a CSR"
.Pp
A CSR contains, among other things, the public key which was generated in
as described above. The CSR is signed with the associated private key. Thus the
integrity 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 
.EX
# CertTool v inFileName [options] 
.EE
The only available option is the 'd' flag, which as described above in the
section entitled "Generating a Certificate Signing Request", indiciates 
that the CSR is in DER format rather than the default PEM format. 
A typical (successful) run of this command is like so: 
.EX
# CertTool v myCsr.pem 
 ...CSR verified successfully. 
.EE
A large number of things can go wrong if 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. 
.Pp
.B "Creating a System Identity"
.Pp
This creates a key pair and a self-signed (root) certificate in the System keychain, and registers the result in the System Identity database as being the IDentity associated with the specified domain name. The domain name is typically a string of the form "com.apple.somedomain...". You must be running as root to execute this command. 
The format of this command is 
.EX
# CertTool C domainName [options] 
.EE
The available options are:
.EX
u
.EE
Create the private key with an ACL limiting access to the current user. If not specified, the private key wil be created with a default ACL. 
.EX
P
.EE
Don't create system identity if one already exists for specified domain.
.Pp
.B "Importing a Certificate from a Certificate Authority"
.Pp
Once you have negotiated with your CA, and provided them with the CSR generated
as described above as well as any other information, documentation, and payment they
require, the CA will provide you with a certificate. Use this command to add
that certificate to the keychain containing the keypair you generated previously.
.Pp
The format of this command is 
.EX
# CertTool i inFileName [options] 
.EE
The cert to import is obtained from "inFileName". The available options are: 
.EX
k=keyChainName 
.EE
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 typically contains the keypair you generated previously.
(Note you can import a certificate into a keychain which does not contain keys
you generated but there will be no linkage between the imported certificate and
a private key if you do this.) If the keychain is not open when this command is
executed, you will be prompted by the Keychain system for its passphrase.
.EX
r=privateKeyFileName
.EE
Where "privateKeyFileName" is the name of the optional private key file to imported along with the certificate. This option is used to import cert/key pairs which are generated by other means, such as OpenSSL. 
.EX
f=privateKeyFormat
.EE
Where "privateKeyFormat" is the format of the private key specified with the 'r' option. The formats are: '1' for PKCS1 (OpenSSL format), '8' (PKCS8), and 'f' (FIPS186, BSAFE format). The default is OpenSSL format for both RSA and DSA keys.   
.EX
 d 
.EE
Specifies DER format as described above. The default is PEM format.
.EX
 c 
.EE
Specifies that the designated keychain is to be created.
.Pp
.B "Displaying a Certificate"
.Pp
This displays the contents of an existing certificate, obtained from a file. 
The format of this command is 
.EX
# CertTool d inFileName [options] 
.EE
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. Actually, in the absence of this option, certtool will correctly determine the format of the certificate (PEM or DER). 
.Pp
.B "Importing a CRL"
.Pp
This command is used to add a Certificate Revocation List (CRL) to a keychain. 
The format of this command is 
.EX
# CertTool I inFileName [options] 
.EE
The CRL to import is obtained from "inFileName".  The available options are: 
.EX
k=keyChainName 
.EE
Where "KeyChainName" is the name of the keychain to which the CRL will be added.
If no keychain is specified, the cert is added to the default keychain.  If the
keychain is not open when this command is executed, you will be prompted by the
Keychain system for its passphrase.
.EX
 d 
.EE
Specifies DER format as described above. The default is PEM format.
.EX
 c 
.EE
Specifies that the designated keychain is to be created.
.Pp
.B "Displaying a CRL"
.Pp
This displays the contents of an existing Certificate Revocation List (CRL),
obtained from a file. The format of this command is 
.EX
# CertTool D inFileName [options] 
.EE
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.
.Pp
.B "Displaying Certificates and CRLs in a keychain"
.Pp
This displays the contents of all certificates and CRLs in a keychain. The format of this command is 
.EX
# CertTool y [options] 
.EE
The available options are: 
.EX
k=keyChainName 
.EE
Where "KeyChainName" is the name of the keychain to display.
.EX
v
.EE
Specifies verbose mode.
.Pp
.B "Certificate Authorities and CSRs"
.Pp
As mentioned above, the general procedure for obtaining a "real" cert is: 
.BL
Generate a key pair
.BL
Generate a CSR
.BL
Provide the CSR and some other information and/or documentation to the CA
.BL
CA sends you a certificate which is signed by the CA.
.BL
You import that certificate, obtained from the CA, into your keychain.
.Pp
The items in that keychain can now be used in SecureTranspoert's SSLSetCertificate()
call.
.Pp
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. Paste the CSR
generated as described in the section entitled "Generating a Certificate 
Signing Request" into a form on the web site. A few minutes later Verisign
emails you a certificate, which you import into your keychain.
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 means 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 trusted by any browser. 
.Pp
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 above. 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 will require support from various SSL clients you'll be testing with, none of which recognize your root cert.
.SH FILES
.B /System/Library/Keychains/X509Anchors
System root certificate database
.B /Library/Keychains/System.keychain
System Keychain
.SH SEE ALSO
.BR openssl ( 1 )