certtool man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

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 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 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 dif‐
       ferent 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	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 pre‐
       vents an attack using DNS spoofing.

       A brief note about cert/key usage: the normal configuration of  Secure‐
       Transport  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  SSLSetEncryptionCertifi‐
       cate().

       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:

       ·      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 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  dif‐
       ferent  items  which  are used to generate the keypair and the CSR. The
       prompts given, and the format of the data you must supply, are  identi‐
       cal 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 pub‐
       lic 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",	 indi‐
       ciates  that  the CSR is in DER format rather than the default PEM for‐
       mat.  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;  suf‐
       fice  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, documen‐
       tation, and payment they require, the CA will provide you with  a  cer‐
       tificate. Use this command to add that certificate to the keychain con‐
       taining 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  key‐
       chain  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,	 cert‐
       tool  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:

       ·      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 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
       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  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 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)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net