CERTTOOL(1)CERTTOOL(1)NAME
certtool - create key pairs, certificates and certificate signing
requests for use with Keychains
SYNOPSIS
certtool command [command-args] [options] certtool c [options] certtool
r outFileName [options] certtool v infileName [options] certtool C
domainName [options] certtool i inFileName [options] certtool d inFile‐
Name [options] certtool I inFileName [options] certtool D inFileName
[options] certtool y [options]
CERTTOOL COMMAND SUMMARY
c Create keypair and Certificate r Create CSR v Verify CSR C Create a
System Identity i Import Certificate d Display Certificate I Import CRL
D Display CRL I Import a CRL y Display all certs and CRLs in keychain
CERTTOOL OPTION SUMMARY
c Create the keychain, if one is needed.
d Create a CSR in DER format; default is PEM
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.
p=passphrase
Specify the keychain passphrase when creating
r=privateKeyFileName
Optional private key, for Import Certificate only
f=[18f]
Private Key Format = PKCS1/PKCS8/FIPS186; default is PKCS1
(openssl)
x=[aSsm]
Extended Key Usage: a=Any; s=SSL Client; S=SSL Server; m=SMIME
a Generate private key with default ACL
u Generate private key with ACL limiting access to current user
P Don't create System Identity if one already exists for specified
domain
h Print usage message
v Execute in verbose mode.
DESCRIPTION
Certtool is a UNIX command-line program which is used to create key
pairs, certificates, and certificate signing requests; to import exter‐
nally generated certificates and Certificate Revocation Lists (CRLs)
into a Keychain, and to display the contents of certificates and CRLs.
EXAMPLES
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 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 com‐
mand. Some broswers, after a fair amount of handholding, will allow you
to conditionally "trust" this cert.
# 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. 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.
c
Specifies that the designated keychain is to be created.
x=[aSsm]
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).
a
Results the the private key being created with a default ACL. If not
specified, the private key is created with no ACL.
u
Create the private key with an ACL limiting access to the current user.
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.
# 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 Key‐
chain system at this point if the specified keychain is not open and
you have not specified the passphrase via the 'p' option.
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
You will now specify the various components of the certificate's Rela‐
tive 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
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
#
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 host‐
name; it's DHCP'd behind a firewall which is why "10.0.61.5" was speci‐
fied 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, you must create a
second keychain containing a cert which is capable of encryption, and
pass that to SSLSetEncryptionCertificate(). Generating a Certificate
Signing Request (CSR) A CSR is the standard means by which an adminis‐
trator 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 per‐
forming SSL transactions. The general procedure for obtaining a "real"
cert is:
· Generate a key pair
· Generate a CSR
· Provide the CSR and some other information and/or documentation
to the CA
· CA sends you a certificate which is signed by the CA.
· You import that certificate, obtained from the CA, into your
keychain. The items in that keychain can now be used in Secure‐
Transport's SSLSetCertificate() call. 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
# CertTool r outFileName [options]
The resulting CSR will be written to "outFileName". The avail‐
able 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 key‐
chain 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 keychain is to be created.
a
Results the the private key being created with a default ACL. If
not specified, the private key is created with no ACL.
u
Create the private key with an ACL limiting access to the cur‐
rent user. 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. Verifying a CSR 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 com‐
mand performs this integrity check. The format of this command
is
# CertTool v inFileName [options]
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 com‐
mand is like so:
# CertTool v myCsr.pem
...CSR verified successfully.
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. Creating a
System Identity 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 run‐
ning as root to execute this command. The format of this com‐
mand is
# CertTool C domainName [options]
The available options are:
u
Create the private key with an ACL limiting access to the cur‐
rent user. If not specified, the private key wil be created with
a default ACL.
P
Don't create system identity if one already exists for specified
domain. Importing a Certificate from a Certificate Authority
Once you have negotiated with your CA, and provided them with
the CSR generated as described above as well as any other infor‐
mation, 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. The format of this command is
# CertTool i inFileName [options]
The cert to import is obtained from "inFileName". 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 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.
r=privateKeyFileName
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.
f=privateKeyFormat
Where "privateKeyFormat" is the format of the private key speci‐
fied 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.
d
Specifies DER format as described above. The default is PEM for‐
mat.
c
Specifies that the designated keychain is to be created. Dis‐
playing 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. Actually, in the
absence of this option, certtool will correctly determine the
format of the certificate (PEM or DER). Importing a CRL This
command is used to add a Certificate Revocation List (CRL) to a
keychain. The format of this command is
# CertTool I inFileName [options]
The CRL to import is obtained from "inFileName". The available
options are:
k=keyChainName
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.
d
Specifies DER format as described above. The default is PEM for‐
mat.
c
Specifies that the designated keychain is to be created. Dis‐
playing a CRL This displays the contents of an existing Certifi‐
cate Revocation List (CRL), 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. Displaying Certifi‐
cates and CRLs in a keychain This displays the contents of all
certificates and CRLs in a keychain. The format of this command
is
# CertTool y [options]
The available options are:
k=keyChainName
Where "KeyChainName" is the name of the keychain to display.
v
Specifies verbose mode. Certificate Authorities and CSRs As
mentioned above, the general procedure for obtaining a "real"
cert is:
· Generate a key pair
· Generate a CSR
· Provide the CSR and some other information and/or documentation
to the CA
· CA sends you a certificate which is signed by the CA.
· You import that certificate, obtained from the CA, into your
keychain. The items in that keychain can now be used in Secure‐
Transpoert's SSLSetCertificate() call. 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 per‐
sonal 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 com‐
fortable 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. 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 pro‐
cedure described above and just generate your own self-signed
root cert as described above. No CA is involved; no CSR is gen‐
erated; 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.
FILES
/System/Library/Keychains/X509Anchors System root certificate database
/Library/Keychains/System.keychain System Keychain
SEE ALSOopenssl(1)Apple Computer, Inc. March 19, 2003 CERTTOOL(1)