Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for certtool (opendarwin section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

       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 externally generated certificates and Certifi-
       cate 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 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.  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
       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
       #
       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 pre-
       vents 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 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  enti-
       tled  "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, 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 certifi-
       cate into a keychain which does not contain keys you generated but there will be no  link-
       age 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 for-
       mat). 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  certifi-
       cate (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 cer-
       tificate using nothing but CertTool, Verisign's web site, and email.  You need to  provide
       some personal information; 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 con-
       figuration 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 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  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)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:34 PM.