CERTTOOL(1)						      General Commands Manual						       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 i inFileName [options]

       certtool d inFileName [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

       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 speci-
	      fied 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)

       a      Generate private key with default ACL

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

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 pri-
       vate 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.
       # 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 keychain 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 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 Keychain 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 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 compo-
       nent 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
       #
       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().

       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:

       o      Generate a key pair

       o      Generate a CSR

       o      Provide the CSR and some other information and/or documentation to the CA

       o      CA sends you a certificate which is signed by the CA.

       o      You import that certificate, obtained from the CA, into your keychain.

       The items in that keychain can now be used in SecureTransport'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 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 keychain 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.

       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 command 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 command 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.

       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 information, docu-
       mentation, 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 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.
	d
       Specifies DER format as described above. The default is PEM format.
	c
       Specifies that the designated keychain is to be created.

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

       Displaying a CRL

       This displays the contents of an existing Certificate 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 Certificates 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:

       o      Generate a key pair

       o      Generate a CSR

       o      Provide the CSR and some other information and/or documentation to the CA

       o      CA sends you a certificate which is signed by the CA.

       o      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.

       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 informa-
       tion;  then  you  paste in 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 recog-
       nized 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 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 requires tolerance of the various SSL clients you'll be testing with, none of whom recognize your root cert.

FILES

       /System/Library/Keychains/X509Anchors System root certificate database

SEE ALSO

       openssl(1)

Apple Computer, Inc.						  March 19, 2003						       CERTTOOL(1)