Overview

The keytool application provided with the IBMJCECCA provider is named hwkeytool. It manages a keystore (database) of private keys and their associated X.509 certificate chains authenticating the corresponding public keys. It also manages certificates from trusted entities and secret keys.

Synopsis

hwkeytool [ commands ]

Description

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

A certificate is a digitally signed statement from one entity (person, company, etc.) asserting that the public key (and some other information) of some other entity has a particular value. (See Certificates.) When data is digitally signed, the signature can be verified for data integrity and authenticity. Integrity means the data has not been modified or tampered with. Authenticity means the data comes from the expected source. hwkeytool also enables users to administer secret keys used in symmetric encryption/decryption (for example, DES).

hwkeytool stores keys and certificates in a keystore. The default keystore implementation implements the keystore as a file and protects private keys with a password.

The jarsigner 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 verifies the digital signature of a JAR file, using the certificate that comes with it (in the signature block file of the JAR file), and then determines whether or not the public key of that certificate is "trusted", that is, whether the public key is contained in the specified keystore.

Keystore Entries

The entries in a keystore can be created either using hwkeytool or by using the KeyStore APIs directly. If an entry is created using the KeyStore APIs, the secret key, certificate, or key and certificate chain stored in the entry can be created using Java APIs, the RACF RACDCERT command or the ICSF KGUP utility on z/OS, and OpenSSL on Linux for System z.

There are two types of entry in a keystore:

  1. key entries - each holds sensitive cryptographic key information which is stored in a protected format to prevent unauthorized access. Typically, a key stored in this type of entry is a secret key or a private key accompanied by a certificate "chain" for the corresponding public key. The hwkeytool and jarsigner tools only handle 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 belongs to the identity specified 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 using unique identifiers called aliases. The JCECCARACFKS and JCERACFKS keystores, only available on z/OS, are able to store and retrieve certificates from a keyring honoring mixed case label and alias names. Users are encouraged to make use of alias or label names that contain at least one different character in their name than the rest of the alias or label names that are attached to the keyring. It is highly encouraged that users do not make use of same character alias or label names that differ only by case. A search mismatch can occur when storing or retrieving information from a JCECCARACFKS and JCERACFKS keystore when using same character label or alias names differing only by case.

All aliases contained in keystores that are not based on RACF keyrings are not case sensitive; the aliases Hugo and hugo refer to the same keystore entry.

An alias is specified when an entry is added to the keystore using the -genkeypair command to generate a key pair (public and private key), the -genseckey command to generate a secret key, or the -importcert command to add a certificate or certificate chain to the list of trusted certificates. Subsequent hwkeytool commands must use this same alias to refer to the entry.

For example, suppose you use the alias duke to generate a new public/private key pair and wrap the public key in a self-signed certificate (see Certificate Chains) using the following command: 

hwkeytool -genkeypair -alias duke -keypass dukekeypasswd

This specifies an initial password of "dukekeypasswd" that will be required with subsequent commands to access the private key associated with the alias duke. If you want to change duke's private key password later, you cam use a command such as the following: 

hwkeytool -keypasswd -alias duke -keypass dukekeypasswd -new newpass

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

Note: 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 a password is entered at the password prompt, the password is not echoed, that is, it is not visible on the input screen.

Keystore Location

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

Keystore Creation

A keystore is created whenever you use a -genkeypair, -genseckey, or -importcert, command to add data to a keystore that doesn't yet exist.

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

If you don't specify a -keystore option, the default keystore is a file named .HWkeystore in your home directory. If that file does not yet exist, it will be created. This does not apply to RACF keystores, supported on z/OS only, or PKCS11 keystores, supported on z/OS and Linux for System z. For a RACF keystore, you must specify the -keystore option. For PKCS11 keystores, you must specify NONE for the -keystore option.

Keystore Implementation

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

Currently, two command-line tools (hwkeytool and jarsigner) and a GUI-based tool named Policy Tool make use of keystore implementations. Since KeyStore is publicly available, users can write additional security applications that use it.

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

Keystore implementations are provider-based. Specifically, the application interfaces supplied by KeyStore are implemented in terms of a Service Provider Interface (SPI). That is, there is a corresponding 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.

Applications can choose different types of keystore implementation from different providers, using the getInstance() factory method in the KeyStore class. A keystore type defines the storage and data format of the keystore information, 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.

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

Both the hwkeytool and jarsigner utilities support the -storetype option which can be used to specify a keystore type on the command line. For Policy Tool, a keystore type can be specified using the "Change Keystore" command in the Edit menu.

If you don't explicitly specify a keystore type, the tools choose a keystore implementation based on the value of the keystore.type property specified in the security properties file. The security properties file is called java.security, and it resides in the security properties directory, java.home/lib/security, where java.home is the runtime environment's directory (the jre directory in the SDK or the top-level directory of the Java Runtime Environment).

Each tool gets the keystore.type value and then examines all the currently-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 keystore implementation provided by Sun). This is specified by the following 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".

The JCECCARACFKS keystore implements a RACF keyring keystore. This type is available only on z/OS systems with RACF installed.

When using JCECCARACFKS keystore, you must always specify the -keystore option. There is no default value.

For JCECCARACFKS, the particular RACF keyring must be specified using the -keystore option, using the following syntax: safkeyring://userid/ringname. You must also specify the class to handle the RACF keyring using the -J-D options to specify the java.protocol.handler.pkgs property. The following example lists all entries in the keyring "myring" owned by userid "SUSAN": 

hwkeytool -list -storetype JCECCARACFKS -keystore safkeyring://SUSAN/myring -J-Djava.protocol.handler.pkgs=com.ibm.crypto.hdwrCCA.provider

PKCS11 keystores are also supported. Each PKCS11 keystore is represented by a PKCS11 token, and each PKCS11 token has a corresponding IBMPKCS11Impl configuration file.

The IBMPKCS11Impl configuration file contains at least three attributes. The name attribute is used by the JCE framework to determine the provider's instance name. The library attribute contains the full path name to the PKCS11 DLL library. The tokenLabel attribute contains the PKCS11 token label. See the z/OS IBMPKCS11Impl Guide for further information on the content and usage of the IBMPKCS11Impl configuration file.

To specify a PKCS11 keystore, specify PKCS11 for -storetype and NONE for -keystore. When the IBMPKCS11Impl provider is added to the list of security providers in the java.security file in the java.home/lib/security directory, and the IBMPKCS11Impl configuration file is specified on the IBMPKCS11Impl provider line within the java.security file, the token referenced by the tokenLabel attribute of the IBMPKCS11Impl configuration file is the PKCS11 token that will be used by hwkeytool.

For example, using the following configuration:

Provider list from java.security file in the java.home/lib/security directory 

security.provider.1=com.ibm.jsse2.IBMJSSEProvider2
security.provider.2=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
security.provider.3=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl /home/susan/susan.cfg
security.provider.4=com.ibm.crypto.provider.IBMJCE
security.provider.5=com.ibm.security.jgss.IBMJGSSProvider
security.provider.6=com.ibm.security.cert.IBMCertPath
security.provider.7=com.ibm.security.sasl.IBMSASL

IBMPKCS11Impl Configuration file, /home/susan/susan.cfg 

name=SUSAN 
library=/usr/lpp/pkcs11/lib/csnpca3x.so
tokenLabel=SUSAN

The following command lists all the entries in a PKCS11 keystore belonging to PKCS11 token labeled SUSAN 

hwkeytool -list -storetype PKCS11 -keystore NONE

If multiple IBMPKCS11Impl providers are in the list of security providers in the java.security file, only the PKCS11 token associated with the first IBMPKCS11Impl provider will be used.

Supported Algorithms and Key Sizes

hwkeytool 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 commands must be supported by a provider implementation. The default key pair generation algorithm is "RSA". 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", if the underlying private key is of type "RSA", the default signature algorithm is "SHA256withRSA", and if the underlying private key is of type "EC", the default signature algorithm is "SHA256withECDSA".

When generating a RSA key pair, the key size must be in the range from 512 to 4096 (2048 for IBM System z9 or earlier). For a DSA key pair, the range is from 512 to 1024 bits and must be a multiple of 64. For an EC key pair, the key size supported are 160, 192, 224, 256, 320, 384, 512, and 521. The default key size for the ECC key algorithm is 256 bits. EC key size of 160 is not supported when working with PKCS11 keystores. The default key size for any other key pair algorithm is 1024 bits.

Note: DSA is only supported on IBM eServer zSeries 800 (z800) and IBM eServer zSeries 900 (z900) hardware.

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 specific value.

Expanding on some of key terms in this definition:

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 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 systems 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, computer, business, bank, or something else you are trusting to some degree.

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 public keys in use. Certificates were invented as a solution to this public key distribution problem. Now a Certificate 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 Certificate Authorities, VeriSign, Thawte, Entrust, to name a few. You can also run a Certificate Authority for your organization using products such as the Netscape/Microsoft Certificate Servers or the Entrust CA product.

Using hwkeytool, it is possible to display, import, and export certificates.

hwkeytool currently handles X.509 certificates.

X.509 Certificates

The X.509 standard defines what information can go into a certificate and describes how to represent it (the data format). In addition to a digital signature, all X.509 certificates have the following data:

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. hwkeytool can generates v1 certificates and can import and export v1, v2, and v3 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 various 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 certificate 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 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. The validity period can be as short as a few seconds or almost as long as a century. The 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, Organization, and Country.)

Subject Public Key Information This is the public key of the entity being named, and an algorithm identifier that specifies the 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 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 associated with this public key, e.g. 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 certificate has the KeyUsage extension marked critical and set to "keyCertSign" then if this certificate is presented during SSL communication, it should be rejected, as the certificate extension indicates that the associated private key should only be used for signing certificates 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 (ASN.1) describes data. The Definite Encoding Rules (DER) describe a single way to store and transfer the 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 certificates. hwkeytool supports the following subparts:

When supplying a distinguished name string as the value of a -dname option, as for the -genkeypair command, 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 values and the 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=JavaSoft, O=Sun, L=Cupertino, S=California, C=US

and a sample command using such a string is 

   hwkeytool -genkeypair -dname "CN=Mark Smith, OU=JavaSoft, O=Sun, L=Cupertino,
   S=California, C=US" -alias mark

Case is not significant for these keyword abbreviations so, for example, "CN", "cn", and "Cn" are recognized as the commonName keyword.

In a distinguished name string order is significant. Each component must appear in the designated order. However, it is not necessary to specify all the subcompensate. For example: 

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

If a distinguished name string value contains a comma, the comma 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 command line. If it is needed for a command, but not supplied on the command line, the user is prompted for each of the components. 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 -importcert and -printcert commands can be in either this format or binary encoded.

By default, the -exportcert command outputs a certificate in binary encoding, but will output a certificate in printable encoding format if the -rfc option is specified.

By default, the -list command prints the MD5 fingerprint of a certificate. If the -v option is specified, the certificate is printed in human-readable format. If the -rfc option is specified, the certificate 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

hwkeytool can create and manage keystore "key" entries that each contain a private key and an associated certificate "chain". The first certificate in the chain contains the public key corresponding to the private key.

When key pairs are generated (see the -genkeypair command), the chain contains 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 -genkeypair command is called to generate a new public/private key pair, it wraps the public key into a self-signed certificate.

Later, a Certificate Signing Request (CSR) might be generated (see the -certreq command) and sent to a Certificate Authority (CA). The response from the CA is imported (see -importcert), and the self-signed certificate is replaced by a chain of certificates. At the end 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 certificate from the CA authenticating its own public key) and the last certificate in the chain. Sometimes the CA returns a chain of certificates. In this case, the last 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 certificate signed by a different CA, authenticating the public key of the CA to which you sent the CSR. 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) 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 certificate information already stored in the keystore.

A different reply format (defined by the PKCS#7 standard) includes the supporting certificate chain, in addition to the issued certificate.

Both reply formats can be handled by hwkeytool.

The top-level (root) CA certificate is self-signed. However, the trust in the root's public key does not come from the root certificate itself (anybody could generate a self-signed certificate with the distinguished name of say, the VeriSign root CA!), but from other sources like a newspaper. The root CA public key is widely known. The only reason it is stored in a certificate is because this is the format understood 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, etc.).

Importing Certificates

To import a certificate from a file, use the -importcert command, as in 

   hwkeytool -importcert -alias joe -file jcertfile.cer

This sample command imports the certificate(s) in the file jcertfile.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 command) to that CA.

The type of import intended is indicated by the value of the -alias option:

Regarding Importing Trusted Certificates

IMPORTANT: Be sure to check a certificate very carefully before importing it as a trusted certificate!

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

  hwkeytool -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

At this point you can call or otherwise contact the person who sent the certificate and compare the fingerprint(s) that you see with the ones they describe. Only if the fingerprints are equal is it guaranteed that the certificate has not been replaced in transit with somebody else's (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, such as a JAR file containing malicious class files.

Note: You may not need to execute -printcert before importing a certificate because, before adding a certificate to the list of trusted certificates in the keystore, the -importcert command prints out the certificate information and prompts you to verify it. You then have the option of cancelling the import operation. However, the certificate is only displayed for verification with the -importcert command if you do not specify 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 -exportcert command, as in 

    hwkeytool -exportcert -alias jane -file janecertfile.cer

This sample command exports jane's certificate to the file janecertfile.cer. That is, if jane is the alias for a key entry, the command exports the certificate at the end of the certificate chain in that keystore entry. This is the certificate that authenticates jane's public 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 command, as in 

    hwkeytool -list -alias joe

If you don't specify an alias, as in 

    hwkeytool -list

the contents of the entire keystore are printed.

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

    hwkeytool -printcert -file certfile.cer

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

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

Command and option notes

The hwkeytool commands and options are listed and described in the following section.

Notes:

Option defaults

Below are the defined option default values. 

-alias "mykey"

-keyalg
    "RSA"  (when using -genkeypair)
    "DES"  (when using -genseckey)

-keysize
     256  (when using -genkeypair and -keyalg is "EC")
    1024  (when using -genkeypair and -keyalg is not "EC")
     256  (when using -genseckey and -keyalg is "AES")
      56  (when using -genseckey and -keyalg is "DES" and keystore is non-PKCS11)
      64  (when using -genseckey and -keyalg is "DES" and keystore is PKCS11)
     168  (when using -genseckey and -keyalg is "DESede" and keystore is non-PKCS11)
     192  (when using -genseckey and -keyalg is "DESede" and keystore is PKCS11)

-validity 90

-keystore the file named .HWkeystore in the user's home directory,
          except when the keystore is type JCECCARACFKS or JCERACFKS.  There is
          no default value for -keystore for a RACF keystore.

-storetype the value of the "keystore.type" property in the security
           properties file that is returned by the static getDefaultType()
           method in java.security.KeyStore.

-file stdin if reading, stdout if writing

-sigalg
    "SHA1withDSA"     (when the underlying private key is type "DSA")
    "SHA256withRSA"   (when the underlying private key is type "RSA")
    "SHA256withECDSA" (when the underlying private key is type "EC")

Options that are available for most commands

The -v option is available for all commands except -help. If it appears, it signifies "verbose" mode and, for example, detailed certificate information will be output.

The -Jjavaoption option is available for any command. If it appears, the specified javaoption string is passed through directly to the Java interpreter. (hwkeytool 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.

The following options are available for most commands operating on a keystore:

-storetype storetype

This option specifies the type of keystore to be instantiated. The default keystore type is the one that is specified as the value of the "keystore.type" property in the security properties file, which is returned by the static getDefaultType() method in java.security.KeyStore.

-keystore keystore

This option specifies the keystore (database file) location. The default keystore is the file .HWkeystore in the user's home directory, as determined by the "user.home" system property. For a RACF keystore, there is no default keystore value. For a PKCS11 keystore, NONE must be specified as the value for -keystore.

If the keystore file does not yet exist, then certain hwkeytool commands may result in a new keystore file being created. For example, if hwkeytool -genkeypair is invoked and the keystore (specified or defaulted) does not exist, then it will be created. This does not apply to RACF or PKCS11 keystores.

For PKCS11, if multiple IBMPKCS11Impl providers are in the list of security providers in the java.security file, only the PKCS11 token associated with the first IBMPKCS11Impl provider will be used.

-storepass storepass

This option specifies the password used to protect the integrity of the keystore.

storepass must be at least 6 characters long. It must be provided with all commands that access the keystore contents. For these commands, if a -storepass option is not specified on 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 Regarding Passwords.

Because RACF and PKCS11 keystores do not maintain a password in the keystore itself, the -storepass option is not supported for RACF and PKCS11 keystores.

-providerName provider_name

This option specifies the cryptographic service provider's name when listed in the security properties file.

-providerClass provider_class_name

This option specifies the cryptographic service provider's master class file when the service provider is not listed in the security properties file.

-providerArg provider_arg

This option is used only in conjunction with -providerClass. If used, it specifies the string input argument for the constructor of provider_class_name.

Regarding Passwords

Most commands operating on a keystore require the store password. Some commands require a 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 a password is entered at the password prompt, the password is not echoed, that is, it is not visible on the input screen.

Commands

See also the Command and Option Notes.

Adding Data to the Keystore

-genkeypair {-alias alias} {-keyalg keyalg} {-keysize keysize} {-sigalg sigalg} [-dname dname] [-keypass keypass] {-validity valDays} {-storetype storetype} {-keystore keystore} [-storepass storepass] {-keylabel keylabel | -existinglabel existinglabel} {-hardwaretype hardwaretype} {-file cert_file} {-hardwareusage hardwareusage} {-providerName providerName} {-providerClass provider_class_name {-providerArg arg}} {-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 certificate chain and the private key are stored in a new keystore entry identified by alias.

This command was named -genkey in earlier releases. This old name is supported in this release and will be supported in future releases. For clarity, the new name, -genkeypair, is preferred going forward.

keyalg specifies the algorithm to be used to generate the key pair, and keysize specifies the size of each key to be generated. sigalg specifies the algorithm that should be used to sign the self-signed certificate; this algorithm must be compatible 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 (except for a RACF or PKCS11 keystore). 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 careful with passwords - see Regarding Passwords.

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

hardwaretype specifies the type of key pair to generate (CLEAR, PKDS). See note below regarding the meaning of the PKDS and CLEAR options and the implications for security and performance of PKDS and CLEAR keys. If no hardwaretype is specified when an RSA key pair is generated, the default value CLEAR is used. If no hardwaretype is specified when a DSA key pair is generated, the default value PKDS is used. If a hardware type is specified when a DSA key pair is generated, the value specified must be PKDS. If no hardwaretype is specified when an EC key pair is generated, the default value CLEAR is used. hardwaretype is not supported for PKCS11 keystores.

hardwareusage specifies the authority the key pair will have in CCA software. The two choices available are SIGNATURE and KEYMANAGEMENT. SIGNATURE creates a key pair that is valid for signatures only. KEYMANAGEMENT creates a key pair valid for signatures and for key management functions. If no hardwareusage is specified when an RSA key pair is generated, the default value KEYMANAGEMENT is used. If no hardwareusage is specified when a DSA key pair is generated, the default value SIGNATURE is used. If no hardwareusage is specified when an EC key pair is generated, the default value will be determined by IBMJCECCA (KEYMANAGEMENT if CCA supports the generation of Key Management EC keys, otherwise SIGNATURE). hardwareusage is not supported for PKCS11 keystores.

keylabel specifies the label that will be used to identify the hardware key within the hardware storage. By default, this label is not specified and a random label is generated.

existinglabel specifies the CCA label for an existing CCA key repository key entry, the request is to create a key object for this CCA key repository entry.

file specifies the certificate file that is associated with a CCA key repository entry.

Note: There are two levels of security and performance available. It is important to understand what level of security needed for the key pair you are generating.


-genseckey {-alias alias | -aliasrange aliasRange} [-keypass keypass] {-keyalg keyalg} {-keysize keysize} {-hardwaretype hardwaretype} {-keylabel keylabel | -existinglabel existinglabel} {-keystore keystore} [-storepass storepass] {-storetype storetype} {-providerName providerName} {-providerClass provider_class_name {-providerArg arg>}} {-v} {-Jjavaoption} {-wrappingMode mode}

Generates a secret key and stores it in a new KeyStore.SecretKeyEntry identified by alias.

aliasrange is a feature added by IBM.

The size of a symmetric key alias is limited, depending on the form used. An alias for a symmetric key may be:

Examples of acceptable aliases for keystore entries containing symmetric keys are:

   abcfrg
   ibmkey12tape
   abc000000000000000001
   abc00a0120fa000000001

aliases that would not be acceptable are:

   abcefghij1234567 - wrong length
   abcg0000000000000001 - prefix is longer than 3 characters

Examples of valid aliasrange specifiers are:

   -aliasrange ibm1-a
   -aliasrange xyz01-fff

If -aliasrange is specified and one alias in the range already exists in the keystore, hwkeytool will throw an exception and exit.

keyalg specifies the algorithm to be used to generate the secret key, and keysize specifies the size of the key to be generated. keypass is a password used to protect the secret key. 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. If specified, keypass must be at least 6 characters long. keypass is not supported for PKCS11 keystores.

hardwaretype specifies the type of key pair being generated (CLEAR, SECURE_INTERNAL_TOKEN, or CKDS). If no hardwaretype is specified, the default value CLEAR is used.

keylabel specifies the CCA key repository label to use for a new CCA key repository entry, the request is to create a new CCA key repository entry and a key object for it.

existinglabel specifies the CCA label for an existing CCA key repository key entry, the request is to create a key object for this CCA key repository key entry.

-storepass and -keypass are not supported for PKCS11 keystores.

-genseckey is not supported for RACF keystores.

-wrappingMode can be optionally used to specify the type of key wrapping that you would like to use in CCA when generating DES and DESede keys. Other key types, such as AES, do not honor the key wrapping mode value since they are always generated with the system default wrapping mode as defined by CCA. Acceptable values for mode include ECB, CBC, and DEFAULT ( case is ignored for these values ). While using this flag the user will receive an error under the following conditions:

-importcert {-v} {-noprompt} {-trustcacerts} {-alias alias} {-file cert_file} {-pkcs12} {-keypass keypass} {-keystore keystore} {-storepass storepass} {-hardwareusage hardwareusage} {-hardwaretype hardwaretype} {-storetype storetype} {-providerName providerName} {-providerClass provider_class_name {-providerArg arg>}} {-Jjavaoption}

Reads the certificate, certificate chain (supplied in a PKCS#7 formatted reply) or private key (in PKCS#12 format) from the file cert_file, and stores it in the keystore entry identified by alias. If no file is specified, the certificate, PKCS#7 reply or private key is read from stdin.

This command was named -import in earlier releases. This old name is supported in this release and will be supported in future releases. For clarity, the new name, -importcert, is preferred going forward.

hwkeytool can import X.509 v1, v2, and v3 certificates, PKCS#7 formatted chains of certificates of that type, and PKCS#12 private keys with their associated certificate chains. 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".

There are three reasons to use the -importcert command:

  1. to add a certificate to the list of trusted certificates
  2. to import a certificate reply received from a Certificate Authority (CA) as the result of submitting a Certificate Signing Request (see the -certreq command) to that CA
  3. to add a private key to the list of personal private keys

Importing a New Trusted Certificate

When importing a new trusted certificate, the specified alias must not yet exist in the keystore. Before adding the certificate to the keystore, hwkeytool verifies 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 hwkeytool fails to establish a trust path from the certificate to be imported ending with 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. The certificate can be verified 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 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, if the -trustcacerts option was specified, using the certificates configured in the "cacerts" keystore file.

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

If the public key in the certificate reply matches the user's public key already stored under alias, the old certificate chain is replaced with the new certificate chain in the reply. The old chain can be replaced only if a valid keypass, the password that protects 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 Regarding Passwords.

Importing a Private Key

To import a private key from a PKCS#12 formatted file, specify the -pkcs12 option.

The certificate chain accompanying the private key is validated using trusted certificates from the keystore and, if the -trustcacerts option was specified, using the certificates configured in the "cacerts" keystore file.

The methods of determining whether the accompanying certificate(s) is (are) trusted are described in the following:

The new certificate chain for 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 in the entry, is supplied. If no password is provided, hwkeytool cancels the operation. Be careful with passwords - see Regarding Passwords.

Note that when a private key is imported into the hardware the -hardwaretype and -hardwareusage options are used to determine the usage and type for the key. By default, an RSA key is imported with hardwaretype CLEAR and hardwareusage KEYMANAGEMENT. By default, a DSA key is imported with hardwaretype PKDS and hardwareusage SIGNATURE. By default, an EC key is imported with hardwaretype CLEAR and hardwareusage will be determined by IBMJCECCA (KEYMANAGEMENT if CCA supports the generation of Key Management EC keys, otherwise SIGNATURE). The -hardwaretype and -hardwareusage options are not supported for PKCS11 keystores.

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 environment's directory (the jre directory in the SDK or the top-level directory of the Java Runtime Environment).

The "cacerts" file represents a system-wide keystore with Certificate Authority (CA) certificates. System administrators can configure and manage this file using hwkeytool, specifying "jks" as the keystore type. The default "cacerts" keystore file ships with several root CA certificates with the following aliases and X.500 owner distinguished names:

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

IMPORTANT: Verify Your cacerts File Since you trust the Certificate Authorities (CAs) in the cacerts 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 included in the cacerts file and to make your own trust decisions. To remove an untrusted CA certificate from the cacerts file, use the hwkeytool application with the delete option. The cacerts file resides in the JRE installation directory. Contact your system administrator if you do not have permission to edit this file.

-importkeystore -srckeystore srckeystore -destkeystore destkeystore {-srcstoretype srcstoretype} {-deststoretype deststoretype} [-srcstorepass srcstorepass] [-deststorepass deststorepass] {-srcalias srcalias} {-destalias destalias} [-srckeypass srckeypass] [-destkeypass destkeypass] {-srcproviderName src_provider_name} {-destproviderName dest_provider_name} {-providerClass provider_class_name {-providerArg arg>}} {-noprompt} {-v} {-Jjavaoption}

Imports a single entry or all entries from a source keystore to a destination keystore.

When the srcalias is provided, this command imports the single entry identified by the alias to the destination keystore. If a destination alias is not provided with destalias, then srcalias is used as the destination alias. If the source entry is protected by a password, srckeypass will be used to recover the entry. If srckeypass is not provided, then hwkeytool will attempt to use srcstorepass to recover the entry. If srcstorepass either is not provided or is incorrect, the user will be prompted for a password. The destination entry will be protected using destkeypass. If destkeypass is not provided, the destination entry will be protected with the source entry password.

If the srcalias is not provided, then all entries in the source keystore are imported into the destination keystore. Each destination entry will be stored under the alias from the source entry. If the source entry is protected by a password, srcstorepass will be used to recover the entry. If srcstorepass either is not provided or is incorrect, the user will be prompted for a password. If a source keystore entry type is not supported in the destination keystore, or if an error occurs while storing an entry into the destination keystore, the user will be prompted whether to skip the entry and continue, or to quit. If the destination KeyStore is not type JCECCARACFKS then the destination entry entry will be protected with the same password as the source entry. If the destination KeyStore is type JCECCARACFKS then the destination entry will be protected with the destination KeyStore storepass.

If the destination alias already exists in the destination keystore, the user is prompted to either overwrite the entry, or to create a new entry under a different alias name.

Note that if -noprompt is specified, the user will not be prompted for a new destination alias. Existing names will automatically be overwritten with the destination alias name. Finally, entries that cannot be imported are automatically skipped and a warning is output.

-importkeystore is not supported for PKCS11 keystores.

-importseckey {-v} -keyalias keyalias {-keypass keypass}{-keystore keystore}{-storepass storepass}{-storetype storetype}{-providername provider_name} -importfile importfile

Imports a batch of secret keys from importfile into keystore. The importfile must be in the IBM-only format produced by the -exportseckey command.

A private key is obtained from the keystore entry with alias keyalias and is used to decrypt the files as they are read from importfile.

If keystore already contains an entry with an alias read from importfile, hwkeytool will throw an exception and exit. If all secret keys in importfile are imported, hwkeytool will display the total number of secret keys imported.

-storepass and -keypass are not supported for PKCS11 keystores.

-importseckey is not supported for RACF keystores.

Exporting Data

-certreq {-alias alias} {-sigalg sigalg} {-file certreq_file} [-keypass keypass] {-storetype storetype} {-keystore keystore} [-storepass storepass] {-providerName providerName} {-providerClass provider_class_name {-providerArg arg>}} {-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 (initially 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 (except for a RACF or PKCS11 keystore). 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 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.

-exportcert {-alias alias} {-pkcs12} {-file cert_file} {-storetype storetype} {-keystore keystore} [-storepass storepass] {-providerName providerName} {-providerClass provider_class_name {-providerArg arg>}} {-rfc} {-v} {-Jjavaoption}

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

This command was named -export in earlier releases. This old name is supported in this release and will be supported in future releases. For clarity, the new name, -exportcert, is preferred going forward.

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

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

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

-storepass and -keypass are not supported for PKCS11 keystores.

PKDS or RETAINED keys cannot be exported.

-exportseckey {-v} -alias alias | -aliasrange aliasRange -keypass keypass {-keyalias keyalias} {-keystore keystore} {-storepass storepass}{-storetype storetype}{-providername provider_name} -exportfile exportfile

Exports a batch of secret keys from keystore to exportfile.

A public key is obtained from the keystore entry with alias keyalias and is used to encrypt the secret keys before storing them in exportfile.

If aliasrange is specified and a secret key in the range does not exist in the keystore, hwkeytool will throw an exception and exit. All the keys prior to the missing key will be exported. After export is finished, hwkeytool will display the total number of secret keys exported.

See also: aliasRange.

-storepass and -keypass are not supported for PKCS11 keystores.

-exportseckey is not supported for RACF keystores.

Displaying Data

-list {-alias alias} {-storetype storetype} {-keystore keystore} [-storepass storepass] {-providerName providerName} {-providerClass provider_class_name {-providerArg arg>}} {-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.

By default this command prints the MD5 fingerprint of a certificate. 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

-storepass is not supported for PKCS11 keystores.

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 can 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

-storepasswd [-all] [-new new_storepass] {-storetype storetype} {-keystore keystore} [-storepass storepass] {-providerName providerName} {-providerClass provider_class_name {-providerArg arg>}} {-v} {-Jjavaoption}

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

If the -all option is provided at the command line, all key entries protected with the same password as the old KeyStore password will be changed to use the new KeyStore password.

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

Be careful with passwords - see Regarding Passwords.

Because RACF and PKCS11 keystores do not maintain a password in the keystore itself, the -storepasswd command is not supported for RACF and PKCS11 keystores.

-keypasswd [-all | -alias alias] [-keypass old_keypass] [-new new_keypass] {-storetype storetype} {-keystore keystore} [-storepass storepass] {-providerName providerName} {-providerClass provider_class_name {-providerArg arg>}} {-v} {-Jjavaoption}

If the -all option is provided at the command line, all key entries protected with the password old_keypass will be changed to use new_keypass.

If the -alias option is provided at the command line, the password under which the key entry identified by alias is protected will be changed 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 password, 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 Regarding Passwords.

Because RACF and PKCS11 keystores do not maintain a key password in the keystore itself, the -keypasswd command is not supported for RACF and PKCS11 keystores.

-delete [-alias alias] {-storetype storetype} {-keystore keystore} [-storepass storepass] {-hardwarekey} {-providerName providerName} {-providerClass provider_class_name {-providerArg arg>}} {-v} {-Jjavaoption}

Deletes the entry identified by alias from the keystore. If no alias is provided on the command line, the user is prompted for the alias.

The -hardwarekey option allows the user to delete the key (or key pair) from the keystore and from underlying storage, as applicable.

If delete is used without the -hardwarekey option, the key (or key pair) will be deleted only from the keystore and will not be deleted from any underlying storage where it might reside.

-storepass is not supported for PKCS11 keystores.

-changealias [-alias alias] [-destalias destalias] [-keypass keypass] {-storetype storetype} {-keystore keystore} [-storepass storepass] {-providerName providerName} {-providerClass provider_class_name {-providerArg arg>}} {-v} {-Jjavaoption}

This command moves an existing keystore entry from the specified alias to a new alias, destalias. If no destination alias is provided, the command will prompt for one. If the original entry is protected with an entry password, the password can be supplied with the -keypass option. In this case, if keypass is not specified then hwkeytool will attempt to use storepass to recover the entry. If storepass either is not provided or is incorrect, the user will be prompted for a password.

-storepass and -keypass are not supported for PKCS11 keystores.

RACF keystores do not support the -changealias command.

Getting Help

-help {-Jjavaoption}

Lists all the commands and their options.

Examples

Note: The commands shown in the following examples appear on multiple lines for legibility. When used, they must be typed as a single line.

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

Generating a Key Pair

The first step is to create a keystore and to generate the key pair. You can do this with the following command: 

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

If the keystore "mykeystore" does not already exist in the "working" directory, this command creates it and with the password "ab987c". It generates a public/private key pair for the entity whose "distinguished name" has common name "Mark Jones", organizational unit "JavaSoft", organization "Sun" and two-letter country code "US". It uses the default "RSA" key generation algorithm to create the keys, both 1024 bits long.

It creates a self-signed certificate (using the default "SHA256withRSA" 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 is significantly shorter if option defaults are accepted. In fact, no options are required because defaults are used for unspecified options that have default values and you are prompted for any required values. Thus, you could simply have the following: 

    hwkeytool -genkeypair

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 ".HWkeystore" 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 -genkeypair command without options specified, and that you responded to the prompts with values equal to those given in the first -genkeypair command previously described (a private key password of "kpi135", etc.)

Requesting a Signed Certificate from a Certificate Authority

So far all we have is a self-signed certificate. A certificate is more likely to be trusted by others if it is signed by a Certificate Authority (CA). To get such a signature, first generate a Certificate Signing Request (CSR), using the following command: 

    hwkeytool -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 will return a certificate, signed by them, authenticating your public key. (In some cases, the CA will 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

In this step, you 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 import command):

The "cacerts" keystore file ships with five VeriSign root CA certificates, so you probably won't need to import a VeriSign certificate as a trusted certificate in your keystore. However, if you request a signed certificate 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). For example, suppose company ABC, Inc. is a CA, and you obtain a file named "ABCCA.cer" that is purportedly a self-signed certificate 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 hwkeytool -printcert command or the hwkeytool -importcert command without the -noprompt option) and make sure the displayed certificate fingerprint(s) match the expected ones. You can telephone the person who sent the certificate and compare the fingerprint(s) that you see with the ones that they describe (or that a secure public key repository shows). Only if the fingerprints are identical is it guaranteed that the certificate has not been replaced in transit with 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 signed by the attacker.

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

    hwkeytool -importcert -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. If the CA reply is a chain, the new chain is the one returned by the CA in response to your request. If the CA reply is a single certificate, the new chain is constructed using the certificate reply, trusted certificates available in the keystore where you are importing the reply, or in the "cacerts" keystore file.

For example, suppose you sent your certificate signing request to VeriSign, a CA with a trusted certificate entry in cacerts. You can import the reply via the following, which assumes the returned certificate is named "VSMarkJ.cer": 

    hwkeytool -importcert -trustcacerts -file VSMarkJ.cer

Exporting a Certificate Authenticating Your Public Key

Suppose you have used the jarsigner tool to sign a Java ARchive (JAR) file. Clients that use the file will want to authenticate your signature.

One way they can do this is by importing your public key certificate into their keystore as a "trusted" entry. You can export the certificate and supply it to your clients. For example, you can export your certificate from a default keystore entry with alias "mykey" to a file named MJ.cer using the following command: 

    hwkeytool -exportcert -alias mykey -file MJ.cer

Given this certificate and the signed JAR file, a client can use the jarsigner tool to authenticate your signature.

Importing a Keystore

The command -importkeystore is used to import an entire keystore into another keystore, which means all entries from the source keystore, including keys and certificates, are imported to the destination keystore with a single command. During the import, all new entries in the destination keystore will have the same alias names and protection passwords (for secret keys and private keys). You can use this command to import entries from a different type of keystore.

If hwkeytool has difficulties recovering a private key or secret key from the source keystore, it will prompt you for a password. If hwkeytool detects alias duplication, it will ask you for a new destination alias. You can specify a new alias or simply allow hwkeytool to overwrite the existing one.

For example, to import entries from a JCEKS keystore keys.jce into a JCECCAKS keystore named keys.cca, you can use the command: 

    hwkeytool -importkeystore
        -srckeystore keys.jce -destkeystore keys.cca
        -srcstoretype JCEKS -deststoretype JCECCAKS
        -srcstorepass changeit -deststorepass itsasecret

The -importkeystore command can also be used to import a single entry from a source keystore to a destination keystore. In this case, besides the options in the preceding example, you also need to use the -srcalias option to specify the alias you want to import. If you want the destination alias to be different from the source alias, specify -destalias with the desired destination alias. If you also specify the key passwords for the source entry (using -srckeypass) and the destination key entry (using -destkeypass) then you can issue a hwkeytool command that will never ask you a question. This makes it very convenient to include a hwkeytool command into a script file, such as the following: 

    -hwkeytool -importkeystore
        -srckeystore keys.jce -destkeystore keys.cca
        -srcstoretype JCEKS -deststoretype JCECCAKS
        -srcstorepass changeit -deststorepass itsasecret
        -srcalias myprivatekey -destalias myoldprivatekey
        -srckeypass oldentrykeypass -destkeypass newentrykeypass
        -noprompt

Listing the Certificates in a RACF Keystore

A keystore that has a RACF keyring for its persistent data source is either type JCERACFKS or JCECCARACFKS. This type of keystore is only supported on the z/OS operating system. For these keystores, the particular RACF keyring must be specified with the -keystore option, using the syntax: 

    safkeyring:://userid/ringname

To access a JCERACFKS or JCECCARACFKS keystore, you must also set the java.protocol.handler.pkgs property using the -J keytool option and the -D java option.

For example, the following command will list all certificates in the keyring "myring" owned by userid SUSAN: 

    hwkeytool -list -storetype JCECCARACFKS
              -keystore safkeyring://SUSAN/myring
              -J-Djava.protocol.handler.pkgs=com.ibm.crypto.hdwrCCA.provider

Appendix

hwkeytool and the ICSF CSFSERV and CSFKEYS RACF classes

This section applies to z/OS only. Linux for System z does not support ICSF or RACF concepts.

If the user of hwkeytool is not authorized to create new profiles in the ICSF CSFKEYS RACF class, hwkeytool may create a key that the user is not able to access. To prevent this from happening, the user of hwkeytool should verify that they are authorized to the profiles in the ICSF CSFSERV RACF class including CSFPKG. A number of these ICSF services are used by hwkeytool. In addition, the user of hwkeytool should verify that they have authority to create new profiles in the ICSF CSFKEYS RACF class.

Developers and users of programs that invoke the Java security class KeyPairGenerator to generate an IBMJCECCA public and private key pair should also be aware of the previously described item relating to the ICSF CSFKEYS and CSFSERV RACF classes.

hwkeytool and updates to a JCECCARACFKS KeyStore

This section applies to z/OS only. Linux for System z does not support ICSF or RACF concepts.

A KeyStore is a Java object containing a collection of keys and certificates that are referenced by unique labels or alias names. For most Java keystores, the persistent data is stored in a file. However, the persistent data for a JCECCARACFKS keystore is stored in the RACF database and connected to a RACF keyring. Due to the nature of the RACF database and keyrings, the behavior of a JCECCARACFKS keystore during update operations differs from the behavior of file based keystores.

In the following discussion, "application" can refer to a user KeyStore application or can refer to the hwkeytool utility program.

KeyStore load and update operations

In order to access the contents of a keystore, an application uses the load() method to retrieve the persistent data from the keystore and create a KeyStore object. This object can be queried and updated by the application. KeyStore update methods include deleteEntry(), setEntry(), setCertificateEntry(), and setKeyEntry(). hwkeytool update commands supported for RACF keystores include -delete, -genkeypair, -importcert, and -importkeystore.

If the application intends to modify the persistent data for the keystore, it uses the store() method. The behavior of the store() method depends on the underlying storage of the persistent data.

File based keystores and the KeyStore store() method

The update model for file based keystores is a replace model. When the application uses the store() method for a file based keystore, the contents of the KeyStore object in the application memory replace the current persistent data for the keystore. In other words, any KeyStore update that has been successful will be reflected in the new version of the persistent data for the keystore.

One consequence of the replace model occurs if two applications are updating the same keystore at the same time. To illustrate, suppose application app1 and application app2 are modifying some keystore and

  1. app1 loads the keystore into a KeyStore object and makes some updates
  2. app2 loads the keystore into a KeyStore object and makes some updates
  3. app1 stores the contents of the KeyStore object into the persistent keystore data
  4. app2 stores the contents of the KeyStore object into the persistent keystore data

In this case, because the app1 changes were not stored in persistent data before app2 loaded the keystore, and because app2 replaced the persistent data after app1, updates made by app1 are overwritten by app2.

RACF keystores and the KeyStore store() method

The update model for a JCECCARACFKS keystore is an update model. It was implemented in this way to avoid the effect described previously. If a change is made to an existing KeyStore entry, the existing version of the entry is disconnected from the keyring, the data for the new entry is added to the RACF database, and then the new entry is connected to the keyring. Even if the update is a delete operation, whether deleteEntry() or hwkeytool -delete, the data is not removed from the RACF database, it is only disconnected from the keyring represented by the KeyStore. To delete data from the RACF database, you must use the RACF utility RACDCERT.

Some RACF database and keyring updates that are not permitted are:

When the IBMJCECCA security provider can detect an update that will not be allowed by RACF, an exception is thrown when the KeyStore entry update is attempted. In some cases, the IBMJCECCA security provider can not predict that a RACF database update will be unsuccessful. One consequence of this is that a KeyStore update may be successful but an error or warning is reported during the store() operation.

Some possible effects of this behavior are:

If there are unintended and undesired changes to a keystore, it might be necessary to reconnect or to update keyring entries using the RACF utility RACDCERT.

hwkeytool and RACF ICSF or PCICC Keys

This section applies to z/OS only. Linux for System z does not support ICSF or RACF concepts.

Private keys may be generated when using the RACDCERT GENCERT command to create digital certificates and an optional public/private key pair. Invocation of this command with the PCICC parameter specifies that the key pair is to be generated using a PCI-class cryptographic coprocessor; the resulting private key is generated with the RSA algorithm and stored in the ICSF private key data set (PKDS) as an ICSF RSA Chinese Remainder Theorem (CRT) key token. Invocation of this command with the ICSF parameter specifies that the key pair is to be generated using software; the resulting private key is generated with the RSA algorithm and stored in the ICSF PKDS as an ICSF RSA Modulus-Exponent (ME) key token. The IBMJCECCA provider supports key types generated using either parameter (PCICC or ICSF).

Trademarks

IBM is a trademark or registered trademark of International Business Machines Corporation in the United States, or other countries, or both.

Oracle and Java are registered trademarks of Oracle and/or its affiliates.

Other company, product, or service names may be trademarks or service marks of others.

© Portions Copyright 2003, 2019 IBM Corporation. All rights reserved.

© Portions Copyright 2003, 2019 Oracle and/or its affiliates. All rights reserved.