manpagez: man pages & more
man keytool(1)
Home | html | info | man
keytool(1)                                                          keytool(1)




NAME

       keytool - key and certificate management tool


SYNOPSIS

       keytool [ commands ]


DESCRIPTION

       keytool  is  a key and certificate management utility. It enables users
       to administer their own public/private key pairs  and  associated  cer-
       tificates  for use in self-authentication (where the user authenticates
       himself/herself to other users/services) or data integrity and  authen-
       tication  services,  using  digital signatures. It also allows users to
       cache the public keys (in the form of certificates) of  their  communi-
       cating peers.

       A  certificate is a digitally signed statement from one entity (person,
       company, and so forth), saying that the  public  key  (and  some  other
       information)  of  some  other entity has a particular value.  (See Cer-
       tificates.) When data is digitally signed, the signature can  be  veri-
       fied  to  check  the  data integrity and authenticity.  Integrity means
       that the data has not been modified or tampered with, and  authenticity
       means  the  data  indeed  comes from whoever claims to have created and
       signed it.

       keytool stores the keys and certificates in a so-called keystore.   The
       keytool  default  keystore  implementation implements the keystore as a
       file. It protects private keys with a password.

       The jarsigner(1) tool uses information from a keystore to  generate  or
       verify  digital  signatures  for  Java ARchive (JAR) files. (A JAR file
       packages class files, images, sounds, and/or other digital  data  in  a
       single  file).   jarsigner(1)  verifies  the digital signature of a JAR
       file, using the certificate that comes with it (it is included  in  the
       signature  block  file of the JAR file), and then checks whether or not
       the public key of that certificate is "trusted", that is, is  contained
       in the specified keystore.

       Please  note: the keytool and jarsigner(1) tools completely replace the
       javakey tool provided in JDK 1.1. These new tools provide more features
       than javakey, including the ability to protect the keystore and private
       keys with passwords, and the ability to verify signatures  in  addition
       to generating them. The new keystore architecture replaces the identity
       database that javakey created and managed. It is possible to import the
       information from an identity database into a keystore, via the -identi-
       tydb subcommand.

   Keystore Entries
       There are two different types of entries in a keystore:

       1.   key entries--each holds very sensitive cryptographic key  informa-
            tion,  which  is  stored in a protected format to prevent unautho-
            rized access.  Typically, a key stored in this type of entry is  a
            secret  key,  or  a  private  key  accompanied  by the certificate
            "chain" for the corresponding public key.  The  keytool  and  jar-
            signer(1)  tools  only  handle  the latter type of entry, that is,
            private keys and their associated certificate chains.

       2.   trusted certificate entries--each contains  a  single  public  key
            certificate  belonging  to  another party. It is called a "trusted
            certificate" because the keystore owner trusts that the public key
            in  the  certificate  indeed belongs to the identity identified by
            the "subject" (owner) of the certificate. The issuer of  the  cer-
            tificate vouches for this, by signing the certificate.

   Keystore Aliases
       All keystore entries (key and trusted certificate entries) are accessed
       via unique aliases. Aliases are case-insensitive; the aliases Hugo  and
       hugo would refer to the same keystore entry.

       An  alias is specified when you add an entity to the keystore using the
       -genkey subcommand to generate a key pair (public and private  key)  or
       the -import subcommand to add a certificate or certificate chain to the
       list of trusted certificates. Subsequent keytool commands must use this
       same alias to refer to the entity.

       For  example,  suppose  you  use  the alias duke to generate a new pub-
       lic/private key pair and wrap the public key into  a  self-signed  cer-
       tificate (see Certificate Chains) via the following command:

       keytool -genkey -alias duke -keypass dukekeypasswd

       This  specifies  an inital password of dukekeypasswd required by subse-
       quent commands to access the private key assocated with the alias duke.
       If you later want to change duke's private key password, you use a com-
       mand like the following:

       keytool -keypasswd -alias duke -keypass\
                  dukekeypasswd -new newpass

       This changes the password from "dukekeypasswd" to "newpass".

       Please note: A password should not actually be specified on  a  command
       line  or in a script unless it is for testing purposes, or you are on a
       secure system. If you don't specify a required  password  option  on  a
       command  line,  you will be prompted for it.  When typing in a password
       at the password prompt, the password  is  currently  echoed  (displayed
       exactly as typed), so be careful not to type it in front of anyone.

   Keystore Location
       Each keytool command has a -keystore option for specifying the name and
       location of the persistent keystore file for the  keystore  managed  by
       keytool.   The  keystore is by default stored in a file named .keystore
       in the user's home directory, as determined by the  "user.home"  system
       property.

       Note  that  the input stream from the -keystore option is passed to the
       KeyStore.load method. If NONE is specified as  the  URL,  then  a  null
       stream  is passed to the KeyStore.load method. NONE should be specified
       if the KeyStore is not file-based, for example,  if  it  resides  on  a
       hardware token device.

   Keystore Creation
       A  keystore is created whenever you use a -genkey, -import, or -identi-
       tydb subcommand to add data to a keystore that doesn't yet exist.

       More specifically, if you specify, in the -keystore option, a  keystore
       that doesn't yet exist, that keystore will be created.

       If you don't specify a -keystore option, the default keystore is a file
       named .keystore in your home directory.  If  that  file  does  not  yet
       exist, it will be created.

   Keystore Implementation
       The KeyStore class provided in the java.security package supplies well-
       defined interfaces to access and modify the information in a  keystore.
       It  is possible for there to be multiple different concrete implementa-
       tions, where each implementation is that for a particular type of  key-
       store.

       Currently,  there are two command-line tools (keytool and jarsigner(1))
       and also a GUI-based tool named policytool.  Since KeyStore is publicly
       available,  JDK  users  can write additional security applications that
       use it.

       There is a built-in default implementation, provided by  Sun  Microsys-
       tems.   It  implements  the keystore as a file, utilizing a proprietary
       keystore type (format) named "JKS".  It protects each private key  with
       its  individual password, and also protects the integrity of the entire
       keystore with a (possibly different) password.

       Keystore implementations are provider-based.   More  specifically,  the
       application interfaces supplied by KeyStore are implemented in terms of
       a "Service Provider Interface" (SPI).  That is, there is a  correspond-
       ing  abstract  KeystoreSpi  class,  also  in the java.security package,
       which defines the Service Provider Interface methods  that  "providers"
       must  implement.   (The term "provider" refers to a package or a set of
       packages that supply a concrete implementation of a subset of  services
       that  can  be  accessed  by the Java Security API.)  Thus, to provide a
       keystore implementation, clients must implement a "provider" and supply
       a KeystoreSpi subclass implementation, as described in How to Implement
       a Provider for the Java Cryptography Architecture.

       Applications can choose different  types  of  keystore  implementations
       from  different  providers, using the "getInstance" factory method sup-
       plied in the KeyStore class. A keystore type defines  the  storage  and
       data  format  of  the  keystore information, and the algorithms used to
       protect private keys in the keystore and the integrity of the  keystore
       itself. Keystore implementations of different types are not compatible.

       keytool works on any file-based keystore  implementation.   (It  treats
       the  keytore  location  that  is  passed to it at the command line as a
       filename and converts it to a FileInputStream, from which it loads  the
       keystore  information.)  The  jarsigner(1) and policytool tools, on the
       other hand, can read a keystore from any location that can be specified
       using a URL.

       For  keytool  and  jarsigner(1), you can specify a keystore type at the
       command line, via the -storetype option.   For  Policy  Tool,  you  can
       specify  a  keystore type via the "Change Keystore" command in the Edit
       menu.

       If you don't explicitly specify a keystore type,  the  tools  choose  a
       keystore  implementation based simply on the value of the keystore.type
       property specified in the security properties file.  The security prop-
       erties file is called java.security, and it resides in the JDK security
       properties directory, java.home/lib/security, where  java.home  is  the
       JDK installation directory.

       Each  tool  gets the keystore.type value and then examines all the cur-
       rently-installed providers until it finds one that implements keystores
       of  that  type.  It  then  uses  the  keystore implementation from that
       provider.

       The KeyStore class defines a static method  named  getDefaultType  that
       lets  applications  and applets retrieve the value of the keystore.type
       property. The following line of code creates an instance of the default
       keystore type (as specified in the keystore.type property):

       KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());

       The  default  keystore  type is "jks" (the proprietary type of the key-
       store implementation provided by Sun). This is specified by the follow-
       ing line in the security properties file:

       keystore.type=jks

       To  have  the  tools  utilize  a keystore implementation other than the
       default, you can change that line to specify a different keystore type.

       For  example,  if  you have a provider package that supplies a keystore
       implementation for a keystore type called "pkcs12", change the line to

       keystore.type=pkcs12

       Note: case doesn't matter in keystore type designations.  For  example,
       "JKS" would be considered the same as "jks".

   Supported Algorithms and Key Sizes
       keytool  allows  users to specify any key pair generation and signature
       algorithm supplied by  any  of  the  registered  cryptographic  service
       providers. That is, the -keyalg and -sigalg options for various subcom-
       mands must be supported by a provider implementation. The  default  key
       pair  generation algorithm is "DSA". The signature algorithm is derived
       from the algorithm of the underlying private  key:  If  the  underlying
       private  key  is  of  type  "DSA",  the  default signature algorithm is
       "SHA1withDSA", and if the underlying private key is of type "RSA",  the
       default signature algorithm is "MD5withRSA".

       When  generating a DSA key pair, the key size must be in the range from
       512 to 1024 bits, and must be a multiple of 64. The  default  key  size
       for any algorithm is 1024 bits.

   Certificates
       A  certificate  (also known as a public-key certificate) is a digitally
       signed statement from one entity (the issuer), saying that  the  public
       key  (and  some  other information) of another entity (the subject) has
       some

       Let us expand on some of the key terms used in this sentence:

       Public Keys         These are  numbers  associated  with  a  particular
                           entity,  and  are  intended to be known to everyone
                           who needs to have trusted  interactions  with  that
                           entity.  Public keys are used to verify signatures.

       Digitally Signed    If some data is digitally signed it has been stored
                           with  the  "identity" of an entity, and a signature
                           that proves that entity knows about the  data.  The
                           data  is  rendered  unforgeable by signing with the
                           entity's private key.

       Identity            A known way of addressing an entity. In  some  sys-
                           tems  the  identity is the public key, in others it
                           can be anything from a Unix UID to an Email address
                           to an X.509 Distinguished Name.

       Signature           A  signature  is  computed over some data using the
                           private key of an entity (the signer, which in  the
                           case of a certificate is also known as the issuer).

       Private Keys        These are numbers, each of which is supposed to  be
                           known  only  to the particular entity whose private
                           key it is  (that  is,  it's  supposed  to  be  kept
                           secret).  Private and public keys exist in pairs in
                           all public key cryptography systems (also  referred
                           to  as  "public  key crypto systems"). In a typical
                           public key crypto system, such as  DSA,  a  private
                           key  corresponds to exactly one public key. Private
                           keys are used to compute signatures.

       Entity              An entity is a person, organization, program,  com-
                           puter,  business,  bank,  or something else you are
                           trusting to some degree.

       Basically, public key cryptography requires  access  to  users'  public
       keys.  In a large-scale networked environment it is impossible to guar-
       antee that prior relationships between communicating entities have been
       established  or  that  a trusted repository exists with all used public
       keys. Certificates were invented as a solution to this public key  dis-
       tribution  problem.  Now  a  Certification  Authority (CA) can act as a
       trusted third party. CAs are entities (for  example,  businesses)  that
       are  trusted  to  sign  (issue)  certificates for other entities. It is
       assumed that CAs will only create valid and reliable  certificates,  as
       they are bound by legal agreements. There are many public Certification
       Authorities, such as VeriSign, Thawte, Entrust, and so on. You can also
       run  your  own  Certification  Authority  using  products  such  as the
       Netscape/Microsoft Certificate Servers or the Entrust  CA  product  for
       your organization.

       Using  keytool,  it is possible to display, import, and export certifi-
       cates. It is also possible to generate self-signed certificates.

       keytool currently handles X.509 certificates.

   X.509 Certificates
       The X.509 standard defines what information can go into a  certificate,
       and  describes  how  to write it down (the data format). All X.509 cer-
       tificates have the following data, in addition to the signature:

       Version        This identifies which  version  of  the  X.509  standard
                      applies to this certificate, which affects what informa-
                      tion can be specified in it. Thus  far,  three  versions
                      are  defined.  keytool can import and export v1, v2, and
                      v3 certificates. It generates v1 certificates.

       Serial Number  The entity that created the certificate  is  responsible
                      for  assigning it a serial number to distinguish it from
                      other certificates it issues. This information  is  used
                      in  numerous  ways,  for  example  when a certificate is
                      revoked its serial number is  placed  in  a  Certificate
                      Revocation List (CRL).

       Signature Algorithm Identifier
                      This identifies the algorithm used by the CA to sign the
                      certificate.

       Issuer Name    The X.500 Distinguished Name of the entity  that  signed
                      the  certificate. This is normally a CA. Using this cer-
                      tificate implies trusting the entity  that  signed  this
                      certificate.  (Note  that in some cases, such as root or
                      top-level CA certificates, the issuer signs its own cer-
                      tificate.)

       Validity Period
                      Each  certificate  is valid only for a limited amount of
                      time. This period is described by a start date and  time
                      and  an  end date and time, and can be as short as a few
                      seconds or almost as long as  a  century.  The  validity
                      period  chosen  depends  on a number of factors, such as
                      the strength of the private key used to  sign  the  cer-
                      tificate  or the amount one is willing to pay for a cer-
                      tificate. This is the expected period that entities  can
                      rely  on the public value, if the associated private key
                      has not been compromised.

       Subject Name   The name of the entity whose public key the  certificate
                      identifies.  This name uses the X.500 standard, so it is
                      intended to be unique across the Internet. This  is  the
                      X.500  Distinguished  Name (DN) of the entity, for exam-
                      ple,

       CN=Java Duke, OU=Java Software Division, O=Sun Microsystems Inc, C=US

       (These refer to the subject's Common Name, Organizational Unit, Organi-
       zation, and Country.)

       Subject Public Key Information
                      This  is  the  public  key  of  the  entity being named,
                      together with an algorithm  identifier  which  specifies
                      which  public  key crypto system this key belongs to and
                      any associated key parameters.

       X.509 Version 1 has been available since 1988, is widely deployed,  and
       is the most generic.

       X.509  Version  2  introduced  the concept of subject and issuer unique
       identifiers to handle the possibility of reuse of subject and/or issuer
       names  over time. Most certificate profile documents strongly recommend
       that names not be reused, and that certificates should not make use  of
       unique identifiers. Version 2 certificates are not widely used.

       X.509  Version  3  is the most recent (1996) and supports the notion of
       extensions, whereby anyone can define an extension and  include  it  in
       the  certificate.  Some  common  extensions  in use today are: KeyUsage
       (limits the use of the keys to particular purposes  such  as  "signing-
       only") and AlternativeNames (allows other identities to also be associ-
       ated with this public key, for example, DNS names, Email addresses,  IP
       addresses).  Extensions  can  be  marked  critical to indicate that the
       extension should be checked and enforced/used. For example, if  a  cer-
       tificate  has  the KeyUsage extension marked critical and set to "keyC-
       ertSign" then if this certificate is presented  during  SSL  communica-
       tion,  it  should  be  rejected, as the certificate extension indicates
       that the associated private key should only be used  for  signing  cer-
       tificates and not for SSL use.

       All  the  data  in a certificate is encoded using two related standards
       called ASN.1/DER.  Abstract Syntax Notation 1 describes data. The Defi-
       nite  Encoding  Rules  describe a single way to store and transfer that
       data.

   X.500 Distinguished Names
       X.500 Distinguished Names are used to identify entities, such as  those
       which are named by the subject and issuer (signer) fields of X.509 cer-
       tificates.  keytool supports the following subparts:

       o commonName--common name of a person, for example, "Susan Jones"

       o organizationUnit--small  organization  (for  example,  department  or
         division) name, such as, "Purchasing"

       o organizationName--large organization
         name, for example, "ABCSystems, Inc."

       o localityName--locality (city) name, for example, "Palo Alto"

       o stateName--state or province name, for example, "California"

       o country--two-letter country code, for example, "CH"

       When  supplying  a  distinguished  name string as the value of a -dname
       option, as for the -genkey or -selfcert subcommands, the string must be
       in the following format:

       CN=cName, OU=orgUnit, O=org, L=city, S=state, C=countryCode

       where  all  the  italicized items represent actual values and the above
       keywords are abbreviations for the following:

       CN=commonName
       OU=organizationUnit
       O=organizationName
       L=localityName
       S=stateName
       C=country

       A sample distinguished name string is

       CN=Mark Smith, OU=Java, O=Sun, L=Cupertino, S=California, C=US

       and a sample command using such a string is

       keytool -genkey -dname "CN=Mark Smith, OU=Java,
       O=Sun, L=Cupertino, S=California, C=US" -alias mark

       Case does not matter for the keyword abbreviations.  For  example,  CN,
       cn, and Cn
        are all treated the same.

       Order  matters;  each subcomponent must appear in the designated order.
       However, it is not necessary to have all the subcomponents. You may use
       a subset, for example:

       CN=Steve Meier, OU=SunSoft, O=Sun, C=US

       If  a  distinguished  name  string  value  contains a comma, it must be
       escaped by a "\" character when you specify the  string  on  a  command
       line, as in

       cn=peter schuster, o=Sun Microsystems\, Inc., o=sun, c=us

       It  is never necessary to specify a distinguished name string on a com-
       mand line.  If it is needed for a command, but not supplied on the com-
       mand line, the user is prompted for each of the subcomponents.  In this
       case, a comma does not need to be escaped by a "\"

   The Internet RFC 1421 Certificate Encoding Standard
       Certificates are often  stored  using  the  printable  encoding  format
       defined  by  the  Internet  RFC  1421 standard, instead of their binary
       encoding. This certificate format, also known as  "Base  64  encoding",
       facilitates  exporting  certificates  to other applications by email or
       through some other mechanism.

       Certificates read by the -import and -printcert subcommands can  be  in
       either this format or binary encoded.

       The  -export  subcommand  by  default  outputs  a certificate in binary
       encoding, but will instead output a certificate in the printable encod-
       ing format, if the -rfc option is specified.

       The  -list  subcommand  by default prints the MD5 fingerprint of a cer-
       tificate. If the -v option is specified, the certificate is printed  in
       human-readable  format, while if the -rfc option is specified, the cer-
       tificate is output in the printable encoding format.

       In its printable encoding format, the encoded certificate is bounded at
       the beginning by

       -----BEGIN CERTIFICATE-----

       and at the end by

       -----END CERTIFICATE-----

   Certificate Chains
       keytool  can create and manage keystore "key" entries that each contain
       a private key and an associated certificate "chain". The first certifi-
       cate  in the chain contains the public key corresponding to the private
       key.

       When keys are first generated (see the -genkey subcommand),  the  chain
       starts  off  containing  a single element, a self-signed certificate. A
       self-signed certificate is one for which the  issuer  (signer)  is  the
       same as the subject (the entity whose public key is being authenticated
       by the certificate). Whenever the -genkey subcommand is called to  gen-
       erate  a new public/private key pair, it also wraps the public key into
       a self-signed certificate.

       Later, after a Certificate Signing Request  (CSR)  has  been  generated
       (see  the  -certreq  subcommand)  and sent to a Certification Authority
       (CA), the response from the CA is imported (see -import), and the self-
       signed  certificate is replaced by a chain of certificates. At the bot-
       tom of the chain is the certificate (reply) issued by the CA  authenti-
       cating  the  subject's public key. The next certificate in the chain is
       one that authenticates the CA's public key.

       In many cases, this is a self-signed certificate (that is,  a  certifi-
       cate  from  the CA authenticating its own public key) and the last cer-
       tificate in the chain. In other cases, the CA may  return  a  chain  of
       certificates.  In this case, the bottom certificate in the chain is the
       same (a certificate signed by the CA, authenticating the public key  of
       the  key  entry), but the second certificate in the chain is a certifi-
       cate signed by a different CA, authenticating the public key of the  CA
       you  sent the CSR to. Then, the next certificate in the chain will be a
       certificate authenticating the second CA's key,  and  so  on,  until  a
       self-signed  "root"  certificate  is  reached.  Each certificate in the
       chain (after the first) thus authenticates the public key of the signer
       of the previous certificate in the chain.

       Many  CAs only return the issued certificate, with no supporting chain,
       especially when there is a flat hierarchy (no  intermediates  CAs).  In
       this  case, the certificate chain must be established from trusted cer-
       tificate information already stored in the keystore.

       A different reply format (defined by the PKCS#7 standard) also includes
       the  supporting  certificate  chain, in addition to the issued certifi-
       cate. Both reply formats can be handled by keytool.

       The top-level (root) CA certificate is self-signed. However, the  trust
       into  the  root's  public  key  does not come from the root certificate
       itself (anybody could generate a self-signed certificate with the  dis-
       tinguished  name of say, the VeriSign root CA!), but from other sources
       like a newspaper. The root CA public key is widely known. The only rea-
       son  it is stored in a certificate is because this is the format under-
       stood by most tools, so the certificate in this case is only used as  a
       "vehicle"  to  transport  the  root CA's public key. Before you add the
       root CA certificate to your keystore, you should  view  it  (using  the
       -printcert option) and compare the displayed fingerprint with the well-
       known fingerprint (obtained from a newspaper, the  root  CA's  webpage,
       and so forth).

   Importing Certificates
       To import a certificate from a file, use the -import subcommand, as in

       keytool -import -alias joe -file jcertfile.cer

       This  sample  command  imports  the  certificate(s)  in the file jcert-
       file.cer and stores it in the keystore entry identified  by  the  alias
       joe.

       You import a certificate for two reasons:

       1.   to add it to the list of trusted certificates, or

       2.   to  import a certificate reply received from a CA as the result of
            submitting a Certificate Signing Request (see the -certreq subcom-
            mand) to that CA.

       Which  type  of  import  is  intended  is indicated by the value of the
       -alias option.


       o If the alias points to a key entry,
         then keytool assumes you are importing a certificate reply.   keytool
         checks  whether  the  public key in the certificate reply matches the
         public key stored with the alias, and exits if they are different.


       o If the alias does not point to a key entry,
         then keytool assumes you are adding a trusted certificate  entry.  In
         this case, the alias should not already exist in the keystore. If the
         alias does already exist, then keytool outputs an error, since  there
         is  already a trusted certificate for that alias, and does not import
         the certificate. If the alias does not exist in the keystore, keytool
         creates  a trusted certificate entry with the specified alias and as-
         sociates it with the imported certificate.

       WARNING Regarding Importing Trusted Certificates

       IMPORTANT: Be sure to check a certificate very carefully before import-
       ing it as a trusted certificate!

       View  it first (using the -printcert subcommand, or the -import subcom-
       mand without the -noprompt option), and make sure  that  the  displayed
       certificate  fingerprint(s)  match the expected ones. For example, sup-
       pose someone sends or emails you a certificate, and you  put  it  in  a
       file  named /tmp/cert.Beforeyou consider adding the certificate to your
       list of trusted certificates, you can execute a  -printcert  subcommand
       to view its fingerprints, as in

       keytool -printcert -file /tmp/cert
       Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
       Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
       Serial Number: 59092b34
       Valid from: Thu Sep 25 18:01:13 PDT 1997 until: Wed Dec 24 17:01:13 PST 1997
       Certificate Fingerprints:
       MD5:  11:81:AD:92:C8:E5:0E:A2:01:2E:D4:7A:D7:5F:07:6F
       SHA1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE

       Then call or otherwise contact the person who sent the certificate, and
       compare the fingerprint(s) that you see with the ones that  they  show.
       Only  if  the fingerprints are equal is it guaranteed that the certifi-
       cate has not been replaced in transit with somebody else's  (for  exam-
       ple, an attacker's) certificate.  If such an attack took place, and you
       did not check the certificate before you imported it, you would end  up
       trusting anything the attacker has signed (for example, a JAR file with
       malicious class files inside).

       Note: it is not required that you execute a -printcert subcommand prior
       to  importing  a  certificate, since before adding a certificate to the
       list of trusted certificates in the keystore,  the  -import  subcommand
       prints  out  the  certificate information and prompts you to verify it.
       You then have the option of aborting the import operation.  Note,  how-
       ever,  this is only the case if you invoke the -import subcommand with-
       out the -noprompt option. If the -noprompt option is given, there is no
       interaction with the user.

   Exporting Certificates
       To export a certificate to a file, use the -export subcommand, as in

       keytool -export -alias jane -file janecertfile.cer

       This  sample  command  exports jane's certificate to the file janecert-
       file.cer.  That is, if jane is the alias for a key entry,  the  command
       exports  the certificate at the bottom of the certificate chain in that
       keystore entry. This is the certificate that authenticates jane's  pub-
       lic key.

       If,  instead,  jane  is the alias for a trusted certificate entry, then
       that trusted certificate is exported.

   Displaying Certificates
       To print out the contents of a keystore entry, use  the  -list  subcom-
       mand, as in

       keytool -list -alias joe

       If you don't specify an alias, as in

       keytool -list

       the contents of the entire keystore are printed.

       To  display  the  contents  of  a certificate stored in a file, use the
       -printcert subcommand, as in

       keytool -printcert -file certfile.cer

       This displays information about the  certificate  stored  in  the  file
       certfile.cer.

       Note:  This works independently of a keystore, that is, you do not need
       a keystore in order to display a certificate that's stored in a file.

   Generating a Self-signed Certificate
       A self-signed certificate is one for which the issuer (signer)  is  the
       same as the subject (the entity whose public key is being authenticated
       by the certificate). Whenever the -genkey subcommand is called to  gen-
       erate  a new public/private key pair, it also wraps the public key into
       a self-signed certificate.

       You may occasionally wish to generate a  new  self-signed  certificate.
       For  example,  you  may want to use the same key pair under a different
       identity (distinguished name). For example, suppose you change  depart-
       ments. You can then:

       1.   copy (clone) the original key entry. See -keyclone.

       2.   generate a new self-signed certificate for the cloned entry, using
            your new distinguished name. See below.

       3.   generate a Certificate Signing Requests for the cloned entry,  and
            import  the  reply  certificate  or  certificate  chain.   See the
            -certreq and -import subcommand.

       4.   delete the original (now obsolete) entry.  See -delete.

       To generate a self-signed certificate, use the -selfcert subcommand, as
       in

       keytool -selfcert -alias dukeNew -keypass b92kqmp
       -dname "cn=Duke Smith, ou=Purchasing, o=BlueSoft, c=US"

       The  generated  certificate  is  stored as a single-element certificate
       chain in the keystore entry identified by the specified alias (in  this
       case dukeNew) where it replaces the existing certificate chain.


COMMAND AND OPTION NOTES

       The  various  subcommands  and  their  options are listed and described
       below.  Note:

       o All subcommand and option names are preceded by a minus sign (-).

       o The options for each subcommand may be provided in any order.


       o All items not italicized or in braces or square brackets are required
         to appear as is.

       o Braces  surrounding  an option generally signify that a default value
         will be used if the option is not  specified  on  the  command  line.
         Braces  are also used around the -v, -rfc, and -J options, which only
         have meaning if they appear on the command line (that is, they  don't
         have any "default" values other than not existing).

       o Brackets  surrounding an option signify that the user is prompted for
         the value(s) if the option is not specified on the command line. (For
         a  -keypass  option,  if you do not specify the option on the command
         line, keytool will first attempt to  use  the  keystore  password  to
         recover  the private key, and if this fails, will then prompt you for
         the private key password.)

       o Items in italics (option values) represent  the  actual  values  that
         must  be  supplied. For example, here is the format of the -printcert
         subcommand:

       keytool -printcert {-file cert_file} {-v}

       When specifying a -printcert subcommand,  replace  cert_file  with  the
       actual file name, as in:

       keytool -printcert -file VScert.cer


       o Option values must be quoted if they contain a blank (space).


       o The -help subcommand is the default. Thus, the command line

       keytool

       is equivalent to

       keytool -help

   Option Defaults
       Below are the defaults for various option values.

       -alias "mykey"
       -keyalg "DSA"
       -keysize 1024
       -validity 90
       -keystore the file named .keystore in the user's home directory
       -file stdin if reading, stdout if writing

       The signature algorithm ( -sigalg option) is derived from the algorithm
       of the underlying private key: If the underlying private key is of type
       "DSA",  the  -sigalg  private key is of type "RSA", -sigalg defaults to
       "MD5withRSA".

   Options that Appear for Most Subcommands
       The -v option can appear for  all  subcommands  except  -help.   If  it
       appears,  it signifies "verbose" mode; detailed certificate information
       will be output.

       There is also a -Jjavaoption option that may appear for any subcommand.
       If  it  appears,  the  specified  -javaoption  string is passed through
       directly to the Java interpreter.  (keytool  is  actually  a  "wrapper"
       around  the  interpreter.)   This option should not contain any spaces.
       It is useful for adjusting the execution environment or  memory  usage.
       For  a list of possible interpreter options, type java -h or java -X at
       the command line.

       These options may appear for all commands operating on a keystore:

       -storetype storetype
              This qualifier specifies the type of keystore  to  be  instanti-
              ated.  The default keystore type is the one that is specified as
              the value of the "keystore.type" property in the security  prop-
              erties  file,  which  is  returned  by the static getDefaultType
              method in java.security.KeyStore.

       -keystore keystore
              The keystore (database file) location.   Defaults  to  the  file
              .keystore  in  the  user's  home directory, as determined by the
              user.home system property.

       -storepass storepass
              The password which is used to protect the integrity of the  key-
              store.

       storepass  must  be at least 6 characters long.  It must be provided to
       all subcommands that access the keystore contents.   For  such  subcom-
       mands,  if a -storepass option is not provided at the command line, the
       user is prompted for it.

       When  retrieving  information  from  the  keystore,  the  password   is
       optional;  if  no  password  is  given,  the integrity of the retrieved
       information cannot be checked and a warning is displayed.

       Be careful with passwords - see Warning Regarding Passwords.

       -provider provider_class_name
              Used to specify the name of the cryptographic service provider's
              master class file when the service provider is not listed in the
              security properties file.

   Warning Regarding Passwords
       Most commands operating on a keystore require the store password.  Some
       commands require a private key password.

       Passwords  can  be specified on the command line (in the -storepass and
       -keypass options, respectively).  However, a  password  should  not  be
       specified  on  a  command  line or in a script unless it is for testing
       purposes, or you are on a secure system.

       If you don't specify a required password option on a command line,  you
       will  be  prompted  for  it.  When typing in a password at the password
       prompt, the password is currently echoed (displayed exactly as  typed),
       so be careful not to type it in front of anyone.

   COMMANDS
       See also COMMAND AND OPTION NOTES.

   Adding Data to the Keystore
       -genkey {-alias alias} {-keyalg keyalg} {-keysize keysize}
                   {-sigalg sigalg} [-dname dname] [-keypass keypass]
                   {-validity valDays} {-storetype storetype}
                   {-keystore keystore} [-storepass storepass]
                   [-provider provider_class_name] {-v}
                   {-Jjavaoption}

              Generates  a key pair (a public key and associated private key).
              Wraps the public key into an X.509 v1  self-signed  certificate,
              which is stored as a single-element certificate chain. This cer-
              tificate chain and the private key are stored in a new  keystore
              entry identified by alias.

              keyalg  specifies  the  algorithm to be used to generate the key
              pair, and keysize specifies the size of each key  to  be  gener-
              ated.   sigalg  specifies  the  algorithm that should be used to
              sign the self-signed certificate; this algorithm must be compat-
              ible with keyalg. See Supported Algorithms and Key Sizes.

              dname  specifies  the  X.500 Distinguished Name to be associated
              with alias, and is used as the issuer and subject fields in  the
              self-signed  certificate.   If no distinguished name is provided
              at the command line, the user will be prompted for one.

              keypass is a password used to protect the  private  key  of  the
              generated  key  pair.  If  no  password is provided, the user is
              prompted for it. If you press RETURN  at  the  prompt,  the  key
              password  is  set to the same password as that used for the key-
              store.  keypass must be at least 6 characters long.  Be  careful
              with passwords: See Warning Regarding Passwords.

              valDays  tells  the  number  of  days  for which the certificate
              should be considered valid.

       -import {-alias alias} {-file cert_file} [-keypass keypass]
                   {-noprompt} {-trustcacerts} {-storetype storetype}
                   {-keystore keystore} [-storepass storepass]
                   [-provider provider_class_name]
                   {-v} {-Jjavaoption}

              Reads the certificate or certificate chain (where the latter  is
              supplied  in  a PKCS#7 formatted reply) from the file cert_file,
              and stores it in the keystore entry identified by  alias  given,
              the certificate or PKCS#7 reply is read from stdin.

              keytool can import X.509 v1, v2, and v3 certificates, and PKCS#7
              formatted certificate chains consisting of certificates of  that
              type.  The data to be imported must be provided either in binary
              encoding format, or in printable encoding format (also known  as
              Base64  encoding)  as defined by the Internet RFC 1421 standard.
              In the latter case, the encoding must be bounded at  the  begin-
              ning  by  a string that starts with "-----BEGIN", and bounded at
              the end by a string that starts with "-----END".

              You import a certification for two reasons:

              1. to add it to the list of trusted certificates, or

              2. to import a certificate reply  received  from  a  CA  as  the
              result  of  submitting  a  Certificate  Signing Request (see the
              -certreq command) to that CA.


Importing a New Trusted Certificate

       When importing a new trusted certificate, alias must not yet  exist  in
       the  keystore.  Before  adding the certificate to the keystore, keytool
       tries to verify it by attempting to construct a  chain  of  trust  from
       that certificate to a self-signed certificate (belonging to a root CA),
       using trusted certificates that are already available in the  keystore.

       If the -trustcacerts option has been specified, additional certificates
       are considered for the chain of trust, namely  the  certificates  in  a
       file named cacerts.

       If  keytool  fails to establish a trust path from the certificate to be
       imported up to a self-signed certificate (either from the  keystore  or
       the  "cacerts"  file),  the certificate information is printed out, and
       the user is prompted to verify it, e.g.,  by  comparing  the  displayed
       certificate fingerprints with the fingerprints obtained from some other
       (trusted) source of information, which might be the  certificate  owner
       himself/herself.  Be  very  careful  to ensure the certificate is valid
       prior to importing it  as  a  "trusted"  certificate!  --  see  WARNING
       Regarding  Importing Trusted Certificates. The user then has the option
       of aborting the import operation.  If the -noprompt  option  is  given,
       however, there will be no interaction with the user.


Importing a Certificate Reply

       When  importing a certificate reply, the certificate reply is validated
       using trusted certificates from the keystore, and optionally using  the
       certificates configured in the cacerts keystore file (if the -trustcac-
       erts option was specified).

       The methods of determining whether the certificate reply is trusted are
       described in the following:

       If  the reply is a single X.509 certificate, keytool attempts to estab-
       lish a trust chain, starting at the certificate reply and ending  at  a
       self-signed certificate (belonging to a root CA). The certificate reply
       and the hierarchy of certificates used to authenticate the  certificate
       reply form the new certificate chain of alias.

       If  the  reply  is  a  PKCS#7 formatted certificate chain, the chain is
       first ordered (with the user certificate first and the self-signed root
       CA certificate last), before keytool attempts to match the root CA cer-
       tificate provided in the reply with any of the trusted certificates  in
       the  keystore or the cacerts keystore file (if the -trustcacerts option
       was specified). If no match can be found, the information of  the  root
       CA  certificate  is printed out, and the user is prompted to verify it,
       for example, by comparing the displayed certificate  fingerprints  with
       the  fingerprints obtained from some other (trusted) source of informa-
       tion, which might be the root CA itself. The user then has  the  option
       of  aborting  the  import  operation. If the -noprompt option is given,
       however, there will be no interaction with the user.

       The new certificate chain of alias replaces the old  certificate  chain
       associated  with  this  entry.  The old chain can only be replaced if a
       valid keypass, the password used to protect  the  private  key  of  the
       entry,  is  supplied.  If  no password is provided, and the private key
       password is different from the keystore password, the user is  prompted
       for it.  Be careful with passwords: See Warning Regarding Passwords.


The cacerts Certificates File

       A  certificates file named "cacerts" resides in the security properties
       directory, java.home/lib/security, where java.home is the runtime envi-
       ronment's  directory  (the  jre  directory  in the SDK or the top-level
       directory of the Java 2 Runtime Environment).

       The "cacerts" file represents a system-wide keystore with  CA  certifi-
       cates.  System  administrators can configure and manage that file using
       keytool, specifying "jks" as the keystore type.  The "cacerts" keystore
       file ships with several root CA certificates with the following aliases
       and X.500 owner distinguished names:

            Alias: thawtepersonalfreemailca Owner  DN:  EmailAddress=personal-
            freemail@thawte.com, CN=Thawte Personal Freemail CA, OU=Certifica-
            tion Services Division, O=Thawte Consulting, L=Cape Town, ST=West-
            ern Cape, C=ZA

            Alias:   thawtepersonalbasicca  Owner  DN:  EmailAddress=personal-
            basic@thawte.com, CN=Thawte Personal  Basic  CA,  OU=Certification
            Services  Division,  O=Thawte  Consulting, L=Cape Town, ST=Western
            Cape, C=ZA

            Alias: thawtepersonalpremiumca  Owner  DN:  EmailAddress=personal-
            premium@thawte.com,  CN=Thawte  Personal Premium CA, OU=Certifica-
            tion Services Division, O=Thawte Consulting, L=Cape Town, ST=West-
            ern Cape, C=ZA

            Alias:     thawteserverca     Owner    DN:    EmailAddress=server-
            certs@thawte.com, CN=Thawte Server CA,  OU=Certification  Services
            Division,  O=Thawte  Consulting  cc, L=Cape Town, ST=Western Cape,
            C=ZA

            Alias:  thawtepremiumserverca  Owner   DN:   EmailAddress=premium-
            server@thawte.com,  CN=Thawte  Premium Server CA, OU=Certification
            Services Division, O=Thawte Consulting cc, L=Cape Town, ST=Western
            Cape, C=ZA

            Alias: verisignclass1ca Owner DN: OU=Class 1 Public Primary Certi-
            fication Authority, O="VeriSign, Inc.", C=US

            Alias: verisignclass2ca Owner DN: OU=Class 2 Public Primary Certi-
            fication Authority, O="VeriSign, Inc.", C=US

            Alias: verisignclass3ca Owner DN: OU=Class 3 Public Primary Certi-
            fication Authority, O="VeriSign, Inc.", C=US

            Alias: verisignclass4ca Owner DN: OU=Class 4 Public Primary Certi-
            fication Authority, O="VeriSign, Inc.", C=US

            Alias:  verisignserverca  Owner DN: OU=Secure Server Certification
            Authority, O="RSA Data Security, Inc.", C=US

            Alias: baltimorecodesigningca Owner  DN:  CN=Baltimore  CyberTrust
            Code Signing Root, OU=CyberTrust, O=Baltimore, C=IE

            Alias:  gtecybertrustca  Owner  DN:  CN=GTE CyberTrust Root, O=GTE
            Corporation, C=US

            Alias:  gtecybertrust5ca  Owner  DN:  CN=GTE  CyberTrust  Root  5,
            OU="GTE CyberTrust Solutions, Inc.", O=GTE Corporation, C=US

       The  initial  password  of  the  "cacerts" keystore file is "changeit".
       System administrators should  change  that  password  and  the  default
       access permission of that file upon installing the SDK.

       IMPORTANT: Verify Your cacerts File Since you trust the CAs in the cac-
       erts file as entities for signing and  issuing  certificates  to  other
       entities,  you must manage the cacerts file carefully. The cacerts file
       should contain only certificates of the  CAs  you  trust.  It  is  your
       responsibility  to  verify  the trusted root CA certificates bundled in
       the cacerts file and make  your  own  trust  decisions.  To  remove  an
       untrusted  CA  certificate from the cacerts file, use the delete option
       of the keytool command. You can find the You can find the  cacerts file
       in  the  JRE installation directory.  Contact your system administrator
       if you do not have permission to edit this file.

       -selfcert {-alias alias} {-sigalg sigalg} {-dname dname}
                   {-validity valDays} [-keypass keypass]
                   {-storetype storetype} {-keystore keystore}
                   [-storepass storepass]
                   [-provider provider_class_name]
                   {-v} {-Jjavaoption}

              Generates an X.509 v1 self-signed  certificate,  using  keystore
              information  including the private key and public key associated
              with alias.  If dname is supplied at the  command  line,  it  is
              used  as  the  X.500  Distinguished Name for both the issuer and
              subject of the certificate. Otherwise, the  X.500  Distinguished
              Name  associated  with alias (at the bottom of its existing cer-
              tificate chain) is used.

              The generated certificate is stored as a single-element certifi-
              cate  chain  in the keystore entry identified by alias, where it
              replaces the existing certificate chain.

              sigalg specifies the algorithm that should be used to  sign  the
              certificate. See Supported Algorithms and Key Sizes.

              In  order  to  access  the private key, the appropriate password
              must be provided, since private keys are protected in  the  key-
              store with a password. If keypass is not provided at the command
              line, and is different from the password  used  to  protect  the
              integrity  of  the  keystore,  the  user is prompted for it.  Be
              careful with passwords: See Warning Regarding Passwords.

              valDays tells the number  of  days  for  which  the  certificate
              should be considered valid.

       -identitydb {-file idb_file} {-storetype storetype}
                   {-keystore keystore} [-storepass storepass]
                   [-provider provider_class_name]
                   {-v} {-Jjavaoption}

              Reads  the  JDK  1.1.x-style  identity  database  from  the file
              idb_file, and adds its entries to the keystore. If  no  file  is
              given,  the  identity database is read from stdin. If a keystore
              does not exist, it is created.

              Only identity database entries ("identities") that  were  marked
              as  trusted  will be imported in the keystore. All other identi-
              ties will be ignored. For  each  trusted  identity,  a  keystore
              entry  will be created. The identity's name is used as the alias
              for the keystore entry.

              The private keys from trusted identities will all  be  encrypted
              under  the  same password, storepass.  This is the same password
              that is used to protect  the  keystore's  integrity.  Users  can
              later assign individual passwords to those private keys by using
              the -keypasswd keytool command option.

              An identity in an identity database may hold more than one  cer-
              tificate,  each  certifying  the same public key. But a keystore
              key entry for a private key has that private key  and  a  single
              "certificate chain" (initially just a single certificate), where
              the first certificate in the chain contains the public key  cor-
              responding  to  the  private key. When importing the information
              from an identity, only the first certificate of the identity  is
              stored in the keystore. This is because an identity's name in an
              identity database is used as the  alias  for  its  corresponding
              keystore entry, and alias names are unique within a keystore,

   Exporting Data
       -certreq {-alias alias} {-sigalg sigalg} {-file certreq_file}
                   [-keypass keypass]
                   {-storetype storetype} {-keystore keystore}
                   [-storepass storepass]
                   [-provider provider_class_name]
                   {-v} {-Jjavaoption}

              Generates a Certificate Signing Request (CSR), using the PKCS#10
              format.

              A CSR is intended to be sent to a  certificate  authority  (CA).
              The CA will authenticate the certificate requestor (usually off-
              line) and will return a certificate or certificate  chain,  used
              to  replace the existing certificate chain (which initially con-
              sists of a self-signed certificate) in the keystore.

              The private key and X.500  Distinguished  Name  associated  with
              alias  are  used  to  create the PKCS#10 certificate request. In
              order to access the private key, the appropriate  password  must
              be  provided,  since  private keys are protected in the keystore
              with a password. If keypass is not provided at the command line,
              and is different from the password used to protect the integrity
              of the keystore, the user is prompted for it.

              Be careful with passwords: See Warning Regarding Passwords.

              sigalg specifies the algorithm that should be used to  sign  the
              CSR. See Supported Algorithms and Key Sizes.

              The  CSR  is  stored  in  the  file certreq_file.  If no file is
              given, the CSR is output to stdout.

              Use the import command to import the response from the CA.

       -export {-alias alias} {-file cert_file} {-storetype storetype}
                   {-keystore keystore} [-storepass storepass]
                   [-provider provider_class_name]
                   {-rfc} {-v} {-Jjavaoption}

              Reads (from the keystore) the certificate associated with alias,
              and stores it in the file cert_file.

              If no file is given, the certificate is output to stdout.

              The  certificate  is  by  default output in binary encoding, but
              will instead be output in  the  printable  encoding  format,  as
              defined by the Internet RFC 1421 standard, if the -rfc option is
              specified.

              If alias refers to a trusted certificate,  that  certificate  is
              output.  Otherwise,  alias refers to a key entry with an associ-
              ated certificate chain. In that case, the first  certificate  in
              the chain is returned. This certificate authenticates the public
              key of the entity addressed by alias.

   Displaying Data
       -list {-alias alias} {-storetype storetype} {-keystore keystore}
                   [-storepass storepass]
                   [-provider provider_class_name]
                   {-v | -rfc} {-Jjavaoption}

              Prints (to stdout) the contents of the keystore entry identified
              by  alias.  If no alias is specified, the contents of the entire
              keystore are printed.

              This command by default prints the MD5 fingerprint of a certifi-
              cate.  If the -v option is specified, the certificate is printed
              in human-readable format, with additional  information  such  as
              the  owner,  issuer,  and  serial number.  If the -rfc option is
              specified, certificate contents are printed using the  printable
              encoding format, as defined by the Internet RFC 1421 standard

              You cannot specify both -v and -rfc.

       -printcert {-file cert_file} {-v} {-Jjavaoption}

              Reads  the  certificate  from the file cert_file, and prints its
              contents in a human-readable format. If no file  is  given,  the
              certificate is read from stdin.

              The  certificate  may  be  either binary encoded or in printable
              encoding format, as defined by the Internet RFC 1421 standard.

              Note: This option can be used independently of a keystore.

   Managing the Keystore
       -keyclone {-alias alias} [-dest dest_alias] [-keypass keypass]
                   {-new new_keypass} {-storetype storetype}
                   {-keystore keystore} [-storepass storepass]
                   [-provider provider_class_name]
                   {-v} {-Jjavaoption}

              Creates a new keystore entry, which has the same private key and
              certificate chain as the original entry.

              The  original  entry  is  identified by alias (which defaults to
              "mykey" if not provided). The new (destination) entry is identi-
              fied  by dest_alias.  If no destination alias is supplied at the
              command line, the user is prompted for it.

              If the private key password is different from the keystore pass-
              word,  then  the entry will only be cloned if a valid keypass is
              supplied.  This is the password used to protect the private  key
              associated  with  alias.   If no key password is supplied at the
              command line, and the private key password is different from the
              keystore password, the user is prompted for it.  The private key
              in the cloned entry may be protected with a different  password,
              if  desired.  If no -new option is supplied at the command line,
              the user is prompted for  the  new  entry's  password  (and  may
              choose  to  let it be the same as for the cloned entry's private
              key).

              Be careful with passwords: See Warning Regarding Passwords.

              This command can  be  used  to  establish  multiple  certificate
              chains  corresponding  to  a  given key pair, or for backup pur-
              poses.

       -storepasswd {-new new_storepass} {-storetype storetype}
                   {-keystore keystore} [-storepass storepass]
                   [-provider provider_class_name]
                   {-v} {-Jjavaoption}

              Changes the password used to protect the integrity of  the  key-
              store contents. The new password is new_storepass, which must be
              at least 6 characters long.

              Be careful with passwords: Warning Regarding Passwords.

       -keypasswd {-alias alias} [-keypass old_keypass]
                   [-new new_keypass] {-storetype storetype}
                   {-keystore keystore} [-storepass storepass]
                   [-provider provider_class_name]
                   {-v} {-Jjavaoption}

              Changes the password under which the private key  identified  by
              alias is protected, from old_keypass to new_keypass.

              If  the -keypass option is not provided at the command line, and
              the private key password is different from  the  keystore  pass-
              word, the user is prompted for it.

              If the -new option is not provided at the command line, the user
              is prompted for it.

              Be careful with passwords: See  Warning Regarding Passwords.

       -delete [-alias alias] {-storetype storetype}
                   {-keystore keystore} [-storepass storepass]
                   [-provider provider_class_name]
                   {-v} {-Jjavaoption}

              Deletes from the keystore the entry identified  by  alias.   The
              user  is  prompted for the alias, if no alias is provided at the
              command line.

   Getting Help
       -help  Lists all the command and their options.


EXAMPLES

       Suppose you want to create a keystore for managing your  public/private
       key pair and certificates from entities you trust.

   Generating Your Key Pair
       The  first  thing  you need to do is create a keystore and generate the
       key pair. You could use a command such as the following:

       keytool -genkey -dname "cn=Mark Jones, ou=Java, o=Sun, c=US"
       -alias business -keypass kpi135 -keystore /working/mykeystore
       -storepass ab987c -validity 180

       (Please note: This must be typed as a single line.  Multiple lines  are
       used in the examples just for legibility purposes.)

       This  command  creates  the  keystore  named  mykeystore in the working
       directory (assuming it does not already  exist),  and  assigns  it  the
       password ab987c.  It generates a public/private key pair for the entity
       whose "distinguished name" has a common name  of  MarkJones,  organiza-
       tional unit of Java, organization of Sun and two-letter country code of
       US.  It uses the default "DSA" key generation algorithm to  create  the
       keys, both 1024 bits long.

       It  creates  a self-signed certificate (using the default "SHA1withDSA"
       signature algorithm) that includes the public key and the distinguished
       name  information.  This certificate will be valid for 180 days, and is
       associated with the private key in a keystore entry referred to by  the
       alias business.  The private key is assigned the password kpi135.

       The  command  could  be  significantly  shorter if option defaults were
       accepted. As a matter of fact, no options are  required;  defaults  are
       used  for  unspecified  options  that  have default values, and you are
       prompted for any required values. Thus, you could simply have the  fol-
       lowing:

       keytool -genkey

       In  this  case,  a  keystore  entry with alias mykey is created, with a
       newly-generated key pair and a certificate that is valid for  90  days.
       This  entry  is  placed  in  the  keystore named .keystore in your home
       directory. (The keystore is created if it doesn't already  exist.)  You
       will  be  prompted for the distinguished name information, the keystore
       password, and the private key password.

       The rest of the examples assume you executed the -genkey command  with-
       out  options specified, and that you responded to the prompts with val-
       ues equal to those given in the first -genkey command, above (a private
       key password of kpi135, and so forth.)

   Requesting a Signed Certificate
   from a Certification Authority
       So  far  all  we've  got is a self-signed certificate. A certificate is
       more likely to be trusted by others if it is signed by a  Certification
       Authority  (CA). To get such a signature, you first generate a Certifi-
       cate Signing Request (CSR), via the following:

       keytool -certreq -file MarkJ.csr

       This creates a CSR (for the entity  identified  by  the  default  alias
       mykey  and  puts  the request in the file named MarkJ.csr.  Submit this
       file to a CA, such as VeriSign, Inc. The CA will authenticate you,  the
       requestor  (usually  off-line),  and  then  will  return a certificate,
       signed by them, authenticating your public key. (In  some  cases,  they
       will  actually  return a chain of certificates, each one authenticating
       the public key of the signer of the previous certificate in the chain.)

   Importing a Certificate for the CA
       You  need  to  replace  your self-signed certificate with a certificate
       chain, where each certificate in the chain authenticates the public key
       of  the signer of the previous certificate in the chain, up to a "root"
       CA.

       Before you import the certificate reply from a CA, you need one or more
       "trusted certificates" in your keystore or in the cacerts keystore file
       (which is described in importcommand):

       o If the certificate reply is a certificate chain, you  just  need  the
         top  certificate  of  the  chain  (that is, the "root" CA certificate
         authenticating that CA's public key).

       o If the certificate reply is a single certificate, you need a certifi-
         cate  for  the  issuing CA (the one that signed it), and if that cer-
         tificate is not self-signed, you need a certificate for  its  signer,
         and so on, up to a self-signed "root" CA certificate.

       The  cacerts  keystore  file  ships with five VeriSign root CA certifi-
       cates, so you probably won't need to import a VeriSign certificate as a
       trusted  certificate in your keystore. But if you request a signed cer-
       tificate from a different CA, and  a  certificate  authenticating  that
       CA's public key hasn't been added to cacerts, you will need to import a
       certificate from the CA as a "trusted certificate".

       A certificate from a CA is usually either  self-signed,  or  signed  by
       another  CA  (in  which case you also need a certificate authenticating
       that CA's public key).  Suppose company ABC, Inc., is  a  CA,  and  you
       obtain  a  file  named ABCCA.cer that is purportedly a self-signed cer-
       tificate from ABC, authenticating that CA's public key.

       Be very careful to ensure the certificate is valid prior  to  importing
       it as a "trusted" certificate! View it first (using the -printcert sub-
       command, or the -import subcommand without the -noprompt  option),  and
       make  sure  that  the  displayed  certificate  fingerprint(s) match the
       expected ones. You can call the person who sent  the  certificate,  and
       compare  the  fingerprint(s)  that you see with the ones that they show
       (or that a secure public key repository shows).  Only  if  the  finger-
       prints  are  equal  is  it guaranteed that the certificate has not been
       replaced in transit with somebody else's (for example,  an  attacker's)
       certificate.  If  such  an attack took place, and you did not check the
       certificate before you imported it, you would end up trusting  anything
       the attacker has signed.

       If you trust that the certificate is valid, then you can add it to your
       keystore via the following:

       keytool -import -alias abc -file ABCCA.cer

       This creates a "trusted certificate" entry in the  keystore,  with  the
       data from the file ABCCA.cer, and assigns the alias abc to the entry.

   Importing the Certificate
   Reply from the CA
       Once you've imported a certificate authenticating the public key of the
       CA you submitted  your  certificate  signing  request  to  (or  there's
       already  such  a  certificate  in the cacerts file), you can import the
       certificate reply and thereby replace your self-signed certificate with
       a  certificate  chain.  This  chain  is  the  one returned by the CA in
       response to your request (if the CA reply is  a  chain),  or  one  con-
       structed  (if  the CA reply is a single certificate) using the certifi-
       cate reply and trusted certificates that are already available  in  the
       keystore where you import the reply or in the cacerts keystore file.

       For  example,  suppose  you  sent  your  certificate signing request to
       VeriSign. You can then  import  the  reply  via  the  following,  which
       assumes the returned certificate is named VSMarkJ.cer:

       keytool -import -trustcacerts -file VSMarkJ.cer

   Exporting a Certificate Authenticating Your
   Public Key
       Suppose  you  have  used  the  jarsigner(1) tool to sign a Java ARchive
       (JAR) file. Clients that want to use the file will want to authenticate
       your signature.

       One way they can do this is by first importing your public key certifi-
       cate into their keystore as a "trusted" entry. You can export the  cer-
       tificate  and  supply  it  to your clients. As an example, you can copy
       your certificate to a file named MJ.cer via the following, assuming the
       entry is aliased by mykey:

       keytool -export -alias mykey -file MJ.cer

       Given  that  certificate, and the signed JAR file, a client can use the
       jarsigner(1) tool to authenticate your signature.

   Changing Your Distinguished
   Name but Keeping your Key Pair
       Suppose your distinguished name changes, for example because  you  have
       changed  departments  or moved to a different city. If desired, you may
       still use the public/private key pair you've previously used,  and  yet
       update your distinguished name. For example, suppose your name is Susan
       Miller, and you created your initial key entry with the  alias  sMiller
       and the distinguished name

       "cn=Susan Miller, ou=Finance Department, o=BlueSoft, c=us"

       Suppose  you  change  from  the  Finance  Department  to the Accounting
       Department. You can still use the  previously-generated  public/private
       key pair and yet update your distinguished name by doing the following.
       First, copy (clone) your key entry:

       keytool -keyclone -alias sMiller -dest sMillerNew

       (This prompts for the store password and for the initial  and  destina-
       tion  private  key passwords, since they aren't provided at the command
       line.) Now you need to change the certificate chain associated with the
       copy,  so  that  the first certificate in the chain uses your different
       distinguished name.  Start by generating a self-signed certificate with
       the appropriate name:

       keytool -selfcert -alias sMillerNew
       -dname "cn=Susan Miller, ou=Accounting Department, o=BlueSoft, c=us"

       Then generate a Certificate Signing Request based on the information in
       this new certificate:

       keytool -certreq -alias sMillerNew

       When you get the CA certificate reply, import it:

       keytool -import -alias sMillerNew -file VSSMillerNew.cer

       After importing the certificate reply, you may want to remove the  ini-
       tial key entry that used your old distinguished name:

       keytool -delete -alias sMiller


SEE ALSO

       jar(1), jarsigner(1)

       See (or search java.sun.com) for the following:

       Security in the Java 2 Platform @
                 http://java.sun.com/docs/books/tutorial/secu-
                 rity1.2/index.html



                                 22 June 2004                       keytool(1)

Mac OS X 10.7.4 - Generated Thu May 10 10:15:59 CDT 2012
© manpagez.com 2000-2019
Individual documents may contain additional copyright information.