certtool man page on Darwin

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
Darwin 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 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 ALSO
       openssl(1)

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

List of man pages available for Darwin

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