osx man page for certtool

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 C
       domainName [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 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 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)

       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 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. 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 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 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 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, 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 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.  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 SecureTrans-
	      port'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 non-
	      printable 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 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 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.  Creating a System Identity This creates a key pair and a self-signed (root)  cer-
	      tificate	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
	      # CertTool C domainName [options]
	      The available options are:
	      u
	      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.
	      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 information, doc-
	      umentation, 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  cer-
	      tificate 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  sys-
	      tem 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 cer-
	      tificate, 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 cer-
	      tificate (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 SecureTranspo-
	      ert'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 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  certifi-
	      cate, which you import into your keychain.  The whole process takes less than 10 minutes. The free certificate obtained in this man-
	      ner 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 per-
	      form 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.	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.

FILES
       /System/Library/Keychains/X509Anchors System root certificate database /Library/Keychains/System.keychain System Keychain

SEE ALSO
       openssl(1)

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