Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

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] cert-tool certtool
       tool 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  Cer-tificate Certificate
       tificate 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 certifi-cate certificate
       cate  signing  requests; to import externally 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)  cer-tificate certificate
       tificate  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 appli-cations applications
       cations 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 com-mand; command;
       mand; 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 encryp-tion, encryption,
       tion, 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 Cer-tificate Certificate
       tificate 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:

       •      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 key-chain keychain
              chain 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 Cer-tificate" Certificate"
              tificate" for information on importing the resulting certificate into your keychain. The  for-mat format
              mat 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 exam-ple, example,
       ple, 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 current user.  This is an interactive  com-mand; command;
       mand; 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 sig-nature signature
       nature 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 "Generat-ing "Generating
       ing  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) certificate in  the  System  keychain,  and
       registers the result in the System Identity database as being the IDentity associated with the speci-fied specified
       fied 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,  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 pri-vate private
       vate 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, speci-fying specifying
       fying  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, speci-fying specifying
       fying  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 key-chain keychain
              chain  can  now be used in SecureTranspoert's SSLSetCertificate() call.  One CA with an excel-lent excellent
              lent web-based interface for  obtaining  a  cert  is  Verisign  (http://www .verisign.com/prod-
              ucts/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  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" certifi-cate certificate
              cate  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 key-chain. keychain.
              chain. 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.key-chain /Library/Keychains/System.keychain
       chain System Keychain

SEE ALSO
       openssl(1)



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