Provided by: j2re1.4_1.4.2.02-1ubuntu3_i386 bug
 

NAME

        keytool - key and certificate management tool
 

SYNOPSIS

        keytool [ subcommands ]
 

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 cer‐
             tificate  belonging to another party. It is called a "trusted cer‐
             tificate" 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
             certificate 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:
 
        example% 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:
 
        example% 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.
 
    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
        guarantee that prior relationships between communicating entities  have
        been established or that a trusted repository exists with all used pub‐
        lic keys. Certificates were invented as a solution to this  public  key
        distribution  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 information 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 certifi‐
        cates it issues. This information is used in numerous ways, for example
        when a certificate is revoked its serial number is placed in a Certifi‐
        cate Revocation List (CRL).  Signature Algorithm Identifier This  iden‐
        tifies  the  algorithm  used by the CA to sign the certificate.  Issuer
        Name The X.500 Distinguished Name of the entity that  signed  the  cer‐
        tificate.  This is normally a CA. Using this certificate implies trust‐
        ing the entity that signed this certificate. (Note that in some  cases,
        such  as  root  or  top-level CA certificates, the issuer signs its own
        certificate.)  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  certificate or the amount one is willing to pay for a certificate.
        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 example,
 
        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  pub‐
        lic  key  of the entity being named, together with an algorithm identi‐
        fier 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:
 
        · commonName—common name of a person, for example, "Susan Jones"
 
        · organizationUnit—small organization (for example, department or divi‐
          sion) name, such as, "Purchasing"
 
        · organizationName—large organization
          name, for example, "ABCSystems, Inc."
 
        · localityName—locality (city) name, for example, "Palo Alto"
 
        · stateName—state or province name, for example, "California"
 
        · 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
 
        example% 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
        authenticating 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
 
        example% 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.  If the alias exists in the database, and identifies an
        entry with a private key, then it is assumed you want to import a  cer‐
        tificate  reply.  keytool checks whether the public key in the certifi‐
        cate reply matches the public key stored with the alias, and  exits  if
        they  are different. If the alias identifies the other type of keystore
        entry, the certificate will not be imported.  If  the  alias  does  not
        exist,  then  it  will be created and associated with the imported cer‐
        tificate.
 
        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
 
        example% 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
 
        example% 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
 
        example% keytool -list -alias joe
 
        If you don’t specify an alias, as in
 
        example% 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
 
        example% 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
 
        example% 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.
 

USAGE

        The  various  subcommands  and  their  options are listed and described
        below.  Note:
 
        · All subcommand and option names are preceded by a minus sign (-).
 
        · The options for each subcommand may be provided in any order.
 
        · All items not italicized or in braces or square brackets are required
          to appear as is.
 
        · 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).
 
        · 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.)
 
        · Items in italics (option values) represent  the  actual  values  that
          must  be  supplied. For example, here is the format of the -printcert
          subcommand:
 
        example% keytool -printcert {-file cert_file} {-v}
 
        When specifying a -printcert subcommand,  replace  cert_file  with  the
        actual file name, as in:
 
        example% keytool -printcert -file VScert.cer
 
        · Option values must be quoted if they contain a blank (space).
 
        · The -help subcommand is the default. Thus, the command line
 
        example% keytool
 
        is equivalent to
 
        example% 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.
 
        There are three options that may appear for all  subcommands  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 con‐
               tents.  For such subcommands, if a -storepass option is not pro‐
               vided at the command line, the user is prompted for it.
 
        -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.
 
        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.
 
    Warning Regarding Passwords
        Most  subcommands  operating  on a keystore require the store password.
        Some subcommands 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.
 
    SUBCOMMANDS
        See also USAGE.
 
    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
               keystore.   keypass must be at least 6 characters long. Be care‐
               ful 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 beginning by  a
               string  that starts with "-----BEGIN", and bounded at the end by
               a string that starts with "-----END".
 
               When importing a new trusted certificate,  alias  must  not  yet
               exist in the keystore. Before adding the certificate to the key‐
               store, keytool tries to verify it by attempting to  construct  a
               chain  of  trust from that certificate to a self-signed certifi‐
               cate (belonging to a root CA), using trusted  certificates  that
               are already available in the keystore.
 
               If  the -trustcacerts option has been specified, additional cer‐
               tificates are considered for the chain of trust, namely the cer‐
               tificates  in  a  file  named  cacerts, which resides in the JDK
               security  properties  directory,  java.home/lib/security,  where
               java.home  is  the JDK installation directory.  The cacerts file
               represents a system-wide keystore with CA certificates.   System
               administrators can configure and manage that file using keytool,
               specifying "jks" as the keystore type. The cacerts keystore file
               ships with five VeriSign root CA certificates with the following
               X.500 distinguished names:
 
               1.   OU=Class  1   Public   Primary   Certification   Authority,
                    O="VeriSign, Inc.", C=US
 
               2.   OU=Class   2   Public   Primary   Certification  Authority,
                    O="VeriSign, Inc.", C=US
 
               3.   OU=Class  3   Public   Primary   Certification   Authority,
                    O="VeriSign, Inc.", C=US
 
               4.   OU=Class   4   Public   Primary   Certification  Authority,
                    O="VeriSign, Inc.", C=US
 
               5.   OU=Secure Server Certification Authority, O="RSA Data Secu‐
                    rity, Inc.", 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 JDK.
 
               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, for example,
               by comparing the displayed  certificate  fingerprints  with  the
               fingerprints obtained from some other (trusted) source of infor‐
               mation, which might be the certificate owner himself/herself. Be
               very careful to ensure the certificate is valid prior to import‐
               ing it as a "trusted" certificate!  -- see WARNING Re: 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.
 
               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 key‐
               store file (if the -trustcacerts option was specified).
 
               If the reply is a single X.509 certificate, keytool attempts  to
               establish  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 certificate 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 infor‐
               mation, 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  pro‐
               vided,  and  the private key password is different from the key‐
               store password, the user is prompted for it.   Be  careful  with
               passwords: See Warning Regarding Passwords.
 
        -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  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, 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 subcommand 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
 

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:
 
        example% 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:
 
        example% 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:
 
        example% 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):
 
        · 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).
 
        · 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:
 
        example% 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:
 
        example% 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:
 
        example% 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:
 
        example% 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:
 
        example% 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:
 
        example% keytool -certreq -alias sMillerNew
 
        When you get the CA certificate reply, import it:
 
        example% 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:
 
        example% keytool -delete -alias sMiller
        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
 
                                  13 June 2000                       keytool(1)