The hwkeytool key and certificate management utility

Syntax

hwkeytool [ commands ]

Description

hwkeytool is a key and certificate management utility. You can use it to administer your own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates themselves to other users and services) or data integrity and authentication services, by using digital signatures. You can also use the utility 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 (such as a person or company), which asserts that the public key (and some other information) of a different entity has a particular value. (For more information, see Certificates.) When data is digitally signed, the signature can be verified for data integrity and authenticity. Integrity means that the data was not modified or tampered with. Authenticity means that the data comes from the expected source. You can also use the hwkeytool utility to administer secret keys that are used in symmetric encryption and decryption (for example, DES).

The hwkeytool utility 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 OpenJDK jarsigner tool uses information from a keystore to generate or verify digital signatures for .jar files. The jarsigner tool verifies the digital signature of a .jar file, by using the certificate that comes with it (in the signature block file of the .jar file), then determines whether the public key of that certificate is trusted, that is, whether the public key is contained in the specified keystore.

Keystore entries

You can create entries in a keystore by using the hwkeytool utility or by using the KeyStore APIs. If you create an entry by using the KeyStore APIs, you can create the secret key, the certificate, or the key and certificate chain that is stored in the entry, by using Java APIs, the RACF® RACDCERT command, or the ICSF KGUP utility on z/OS®.

A keystore can contain the following types of entry:

Key entries

A key entry holds sensitive cryptographic key information, which is stored in a protected format to prevent unauthorized access. Typically, a key that is stored in this type of entry is a secret key or a private key that is accompanied by a certificate "chain" for the corresponding public key. The hwkeytool and jarsigner tools handle only private keys and their associated certificate chains.

Trusted certificate entries

A trusted certificate entry contains a single public key certificate that belongs to another party. The certificate is called a trusted certificate because the keystore owner trusts that the public key in the certificate belongs to the identity that is specified by the subject (owner) of the certificate. The issuer of the certificate vouches for this ownership by signing the certificate.

Keystore aliases

All keystore entries are accessed by using unique identifiers called aliases. The JCECCARACFKS and JCERACFKS keystores on z/OS can store and retrieve certificates from a key ring honoring mixed case label and alias names.Use alias or label names that differ by at least one character from other alias or label names that are attached to the key ring. Do not use alias or label names that differ only by case because that can cause a search mismatch when information is stored or retrieved from a JCECCARACFKS and JCERACFKS keystore.

Aliases that are contained in keystores that are not based on RACF key rings are case-insensitive. For example, the aliases Hugo and hugo refer to the same keystore entry.

hwkeytool -genkeypair -alias duke -keypass dukekeypasswd

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

Keystore location

Each hwkeytool command has a -keystore option for specifying the name and location of the persistent keystore file for the keystore that is managed by the hwkeytool utility. 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 when you use a -genkeypair, -genseckey, or -importcert command to add data to a keystore (specified by the -keystore option) 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 exist, it is created. This behavior does not apply to RACF keystores. For a RACF keystore, you must specify the -keystore option.

Keystore implementation

The KeyStore class that is 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 policytool use keystore implementations. Because KeyStore is publicly available, users can write additional security applications that use it.

OpenJDK contains two keystore implementations. The default implementation is of type PKCS12, which is a cross platform keystore that is based on the RSA PKCS12 Personal Information Exchange Syntax Standard. The other implementation is a file-based keystore of type JKS, which 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, as described in the Oracle documentation How to Implement a Provider for the Java Cryptography Architecture .

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

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

Both the hwkeytool and jarsigner utilities support the -storetype option, which you can use to specify a keystore type on the command line. For the policytool utility, a keystore type can be specified by 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 that is specified in the security properties file. The security properties file is called java.security, 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 then examines all the currently-installed providers until it finds one that implements keystores of that type. The tool then uses the keystore implementation from that provider.

The KeyStore class defines a static method named getDefaultType() that applications can use to 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 keystore type is specified by the following line in the security properties file:

keystore.type=jks

To use the tools with 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 the following string:

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 key ring keystore. This type is available only on z/OS systems with RACF installed.

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

hwkeytool -list -storetype JCECCARACFKS -keystore safkeyringjcecca://SUSAN/myring

hwkeytool -list -storetype PKCS11 -keystore NONE

Supported algorithms and key sizes

You can use the hwkeytool utility to specify any key pair generation and signature algorithm that is 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. If the underlying private key is of type EC, the default signature algorithm is SHA256withECDSA.

When you generate an RSA key pair, the key size must be in the range 512-4096 bits (2048 for IBM® z z9® or earlier). For a DSA key pair, the range is 512-1024 bits and the size must be a multiple of 64. For an EC key pair, the supported key sizes are: 160, 192, 224, 256, 320, 384, 512, and 521. The default key size for the ECC key algorithm is 256 bits. The default key size for any other key pair algorithm is 1024 bits.

Note: DSA is supported only 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 was 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 other systems, the identity can be anything from a Unix UID to an email address or an X.509 distinguished name.

Signature: A signature is computed over some data by using the private key of an entity (the signer, which for 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). In a typical public key cryptography 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 were 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. 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 creates only valid and reliable certificates because 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 by using products such as the Netscape or Microsoft Certificate Servers or the Entrust CA product.

You can use the hwkeytool utility to display, import, and export certificates.

The hwkeytool utility 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 contain 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. The hwkeytool utility can generate 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 that is used by the CA to sign the certificate.

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

Validity Period: Each certificate is valid for a limited amount of time. This period is defined 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 that is chosen depends on a number of factors, such as the strength of the private key that is used to sign the certificate or the amount one is willing to pay for a certificate. This period is the expected time for which entities can rely on the public value, if the associated private key is not compromised.

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

Subject Public Key Information: This is the public key of the entity that is being named, and an algorithm identifier that specifies the public key cryptography system that 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 version.

X.509 Version 2 introduced the concept of subject and issuer unique identifiers to handle the possibility of reuse of subject and 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, such as DNS names, email addresses, and IP addresses). Extensions can be marked critical to indicate that the extension should be checked and enforced or used. For example, if a certificate has the KeyUsage extension marked critical and set to keyCertSign, if this certificate is presented during SSL communication, it should be rejected because the certificate extension indicates that the associated private key should be used only for signing certificates and not for SSL use.

All the data in a certificate is encoded by using two related standards called Abstract Syntax Notation 1 (ASN.1) and Definite Encoding Rules (DER). ASN.1 describes data. DER describes 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 that are named by the subject and issuer (signer) fields of X.509 certificates. The hwkeytool utility supports the following subparts:

• commonName: the common name of a person, for example, "Susan Jones"
• organizationUnit: a small organization (such as a department or division) name, for example, "Purchasing"
• organizationName: a large organization name, for example, "ABCSystems, Inc."
• localityName: a locality (city) name, for example, "Palo Alto"
• stateName: a state or province name, for example, "California"
• country: a two-letter country code, for example, "CH"

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 variables represent values and the keywords are abbreviations for the following strings:

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

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

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 all recognized as the commonName keyword.

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

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

You do not have to specify a distinguished name string on a command line. If the string is required for a command but not supplied on the command line, you are prompted for each of the components. In this case, a comma does not need to be preceded by a backslash.

The RFC 1421 certificate encoding standard

Certificates are often stored by using the printable encoding format that is defined by the RFC 1421 standard instead of their binary encoding. This certificate format, also known as Base 64 encoding, facilitates the export of certificates to other applications by email or through some other mechanism.

Certificates that are 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 outputs a certificate in printable encoding format if you specify the-rfc option.

By default, the -list command prints the MD5 fingerprint of a certificate. If you specify the -v option, the certificate is printed in human-readable format. If you specify the -rfc option, the certificate is output in the printable encoding format.

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

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

Certificate chains

The hwkeytool utility 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 that corresponds 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 certificate 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 that is 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 return only 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 that is 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.

The hwkeytool utility can handle both reply formats.

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 (anyone can 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 that is understood by most tools, so the certificate in this case is only used as a method for transporting the root CA's public key. Before you add the root CA certificate to your keystore, you should view it (by using the -printcert option) and compare the displayed fingerprint with the well-known fingerprint (obtained from a source such as a newspaper or the root CA's web page).

Importing certificates

hwkeytool -importcert -alias joe -file jcertfile.cer

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 that is intended is indicated by the value of the -alias option:

• If the alias points to a key entry, the hwkeytool utility assumes that you are importing a certificate reply. The hwkeytool utility checks whether the public key in the certificate reply matches the public key that is stored with the alias, and exits if they are different.
• If the alias does not point to a key entry, the hwkeytool utility assumes that you are adding a trusted certificate entry. In this case, the alias should not exist in the keystore. If the alias does exist, the hwkeytool utility outputs an error, because there is already a trusted certificate for that alias, and does not import the certificate. If the alias does not exist in the keystore, the hwkeytool utility creates a trusted certificate entry with the specified alias and associates it with the imported certificate.

Regarding importing trusted certificates

View the certificate first (by using the -printcert command, or the -importcert command without the -noprompt option), and make sure that the displayed certificate fingerprints match the expected ones. For example, suppose that 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 run a -printcert command to view its fingerprints. For example:

  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 fingerprints that you see with the ones that 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 that the attacker signed, such as a .jar file that contains malicious class files.

You might not need to run a -printcert command before you import a certificate because, before adding a certificate to the list of trusted certificates in the keystore, the -importcert command prints the certificate information then prompts you to verify it. You can then cancel 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. For example:

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. For example:

hwkeytool -list -alias joe

If you don't specify an alias, as in the following example, the contents of the entire keystore are printed:

hwkeytool -list

To display the contents of a certificate that is stored in a file, use the -printcert command. For example:

hwkeytool -printcert -file certfile.cer

This example command displays information about the certificate thah is stored in the file certfile.cer.

Note: This command works independently of a keystore; you do not need a keystore to display a certificate that is stored in a file.

Command and option notes

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

Option defaults

Here 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")
     168  (when using -genseckey and -keyalg is "DESede")

-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")
    "RSASSA-PSS"      (when the underlying private key is type "RSA")

Options that are available for most commands

The -v option is available for all commands except -help. This option signifies verbose mode and, for example, results in the output of detailed certificate information.

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 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 on the command line.

The following options are available for most commands that operate 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 the java.security.KeyStore class.

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

hwkeytool -genkeypair

-storepass storepass

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

storepass must be at least 6 characters long. This option must be provided with all commands that access the keystore contents. For these commands, if you do not specify a -storepass option on the command line, you are prompted for it.

When retrieving information from the keystore, the password is optional; if you do not supply a password, the integrity of the retrieved information cannot be checked and a warning is displayed.

Be careful with passwords; for more information, see Regarding passwords.

Because RACF keystores do not maintain a password in the keystore, the -storepass option is not supported for RACF 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 primary class file when the service provider is not listed in the security properties file.

-providerArg provider_arg

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

Regarding passwords

Most commands that operate on a keystore require the store password. Some commands require a key password.

You can specify passwords on the command line (in the -storepass and -keypass options). However, do not specify a password 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 are prompted for it. When you enter a password at the password prompt, the password 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 that is 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 you do not provide a distinguished name on the command line, you are prompted for one.

keypass is a password that is used to protect the private key of the generated key pair (except for a RACF keystore). If you do not provide a password, you are 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; for more information, see Regarding passwords.

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

hardwaretype specifies the type of key pair to generate (CLEAR, PKDS). See the later note about the meaning of the PKDS and CLEAR options and the implications for security and performance of PKDS and CLEAR keys. If you do not specify a hardwaretype when you generate an RSA key pair, the default value CLEAR is used. If you do not specify a hardwaretype when you generate a DSA key pair, the default value PKDS is used. If you specify a hardware type when a DSA key pair is generated, the value that is specified must be PKDS. If you do not specify a hardwaretype when you generate an EC key pair, the default value CLEAR is used.

hardwareusage specifies the authority that the key pair has in CCA software. The available choices are SIGNATURE and KEYMANAGEMENT. SIGNATURE creates a key pair that is valid for signatures only. KEYMANAGEMENT creates a key pair that is valid for signatures and for key management functions. If you do not specify a hardwareusage when you generate an RSA key pair, the default value KEYMANAGEMENT is used. If you do not specify a hardwareusage when you generate a DSA key pair, the default value SIGNATURE is used. If you do not specify a hardwareusage when you generate an EC key pair, the default value is determined by the IBMJCECCA provider (KEYMANAGEMENT if CCA supports the generation of key management EC keys, otherwise SIGNATURE).

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

• -keylabel cannot be specified if -existinglabel is specified.

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.

• -existinglabel requires -file to be specified.
• -existinglabel cannot be specified if -hardwaretype is specified.
• -existinglabel cannot be specified if -hardwareusage is specified.
• -existinglabel cannot be specified if -keysize is specified.
• -existinglabel cannot be specified if -dname is specified.
• -existinglabel cannot be specified if -sigalg is specified.
• -existinglabel cannot be specified if -keylabel is specified.
• -existinglabel cannot be specified if -validity is specified.

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

• -file requires -existinglabel to be specified.

-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 that is identified by alias.

aliasrange is a feature added by IBM.

The size of a symmetric key alias is limited, depending on the form that used. An alias for a symmetric key can be in one of the following forms:

• up to 12 (printable) characters long
• a 3 character prefix (alphabetic), 00 and 16 characters of hex digits

If you specify -aliasrange and one alias in the range already exists in the keystore, the hwkeytool utility throws an exception and exits.

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 that is used to protect the secret key. If you do not provide a password, you are 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.

hardwaretype specifies the type of key pair to generate (CLEAR, SECURE_INTERNAL_TOKEN, or CKDS). If you do not specify a hardwaretype, the default value CLEAR is used.

• If you specify a -hardwaretype of CKDS, a key object is generated for a key that is stored in the system CCA key repository. On z/OS, the key is stored in the CKDS (Cryptographic Key Data Set). The key material is never available in clear form outside a protected environment.
  • -hardwaretype CKDS is supported for AES, DES, and DESede keys.
  • -hardwaretype CKDS is also supported for HMACSHA1, HMACSHA224, HMACSHA256, HMACSHA384, and HMACSHA512 keys, but only in conjunction with -existinglabel and -storetype JCECCAKS.
  • If you specify -keylabel with a -hardwaretype of CKDS, the request is for a new key to be generated in the CCA key repository using the specified label as the CCA label. The specified key label must not contain spaces and must be unique in the CCA key repository. The key is generated in the CCA key repository by using the specified label, a Java key object is created by using the CCA label instead of the actual key material, and this key object is stored in the keystore.
  • If you specify -existinglabel with a -hardwaretype of CKDS, the request is to create a key object for a key that is already stored in the CCA key repository. The Java key object is created by using the CCA label instead of the actual key material, and this key object is stored in the keystore. Note that the hwkeytool utility does not verify that there is actually a CCA key repository entry for the specified label.
  • If neither -keylabel nor -existing label is specified with -hardwaretype CKDS, the request is for a new key to be generated in the in the CCA key repository by using an automatically generated CCA label. If the generated label matches a label that is already in the CCA key repository, three attempts are made to create a unique label. The key is generated in the CCA key repository by using the generated label, a Java key object is created using the CCA label instead of the actual key material, and this key object is stored in the keystore.
• If -hardwaretype PROTECTED is specified, the key is generated as a secure key, never available in clear form outside a protected environment. A protected key is a key object that is encrypted by using the system CCA host primary key.
  • -hardwaretype PROTECTED is supported for AES, DES, and DESede keys.
• The lowest level of key security is with clear keys. The key is password protected but the clear key is available outside of a protected environment. This level of security provides increased performance.

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.

• -keylabel is only valid with -genseckey when -hardwaretype CKDS is specified.
• -keylabel cannot be specified if -existinglabel is specified.
• -keylabel cannot be specified if -aliasrange is specified.

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.

• -existinglabel is only valid with -genseckey when -hardwaretype CKDS is specified.
• -existinglabel cannot be specified if -keysize is specified.
• -existinglabel cannot be specified if -aliasrange is specified.
• -existinglabel cannot be specified if -keylabel is specified.

-genseckey is not supported for RACF keystores.

-wrappingMode can be optionally used to specify the type of key wrapping to use in CCA when you generate DES and DESede keys. Other key types, such as AES, do not honor the key wrapping mode value because 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). If you use this option, an error is produced in the following scenarios:

• You generate a key that is not of type DES or DESede. Enhanced key wrapping is only supported for DES and DESede keys.
• You do not specify the value ECB, CBC, or DEFAULT value for the mode.
• You specified the -wrappingMode option when creating a CLEAR key. The enhanced key wrapping mode is supported only for generating SECURE_INTERNAL_TOKEN and CKDS types of keys.

-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 that is 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.

The hwkeytool utility 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 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 you import a new trusted certificate, the specified alias must not exist in the keystore. Before it adds the certificate to the keystore, the hwkeytool utility verifies it by attempting to construct a chain of trust from that certificate to a self-signed certificate (belonging to a root CA), by using trusted certificates that are already available in the keystore.

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

If the hwkeytool utility 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 and you are prompted to verify it. The certificate can be verified by comparing the displayed certificate fingerprints with the fingerprints that you obtain from some other (trusted) source of information, which might be the certificate owner. Be very careful to ensure the certificate is valid prior to importing it as a "trusted" certificate; for more information, see Regarding importing trusted certificates. You can then cancel the import operation. However, if you specified the -noprompt option, there is no user interaction with the utility.

Importing a certificate reply

When importing a certificate reply, the certificate reply is validated by using trusted certificates from the keystore and, if you specified the -trustcacerts option, by using the certificates that are configured in the cacerts keystore file.

• If the reply is a single X.509 certificate, the hwkeytool utility attempts to establish a trust chain, starting with the certificate reply and ending with a self-signed certificate (belonging to a root CA). The certificate reply and the hierarchy of certificates that are used to authenticate the certificate reply form the new certificate chain for alias. If a trust chain cannot be established, the certificate reply is not imported. In this case, hwkeytool does not print the certificate and prompt the user to verify it because it is difficult to determine the authenticity of the certificate reply.
• If the reply is a PKCS#7 formatted certificate chain, the chain is ordered with the user certificate first and the self-signed root CA certificate last. Using the ordered chain, the hwkeytool utility attempts to match the root CA certificate with any of the trusted certificates in the keystore or, if the -trustcacerts option was specified, in the cacerts keystore file. If no match is found, the information in the root CA certificate is printed and you are prompted to verify it. Verification can be done, for example, by comparing the displayed certificate fingerprints with fingerprints that you obtain from some other (trusted) source of information, which might be the root CA itself. You have the option of canceling the import operation. However, if you specified the -noprompt option, there is no user interaction with the utility.

If the public key in the certificate reply matches the user's public key that is 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, you are prompted for it. Be careful with passwords; for more information, 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 that accompanies the private key is validated by using trusted certificates from the keystore and, if the -trustcacerts option was specified, by using the certificates that are configured in the cacerts keystore file.

• If the chain contains a single certificate, the hwkeytool utility 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 chain and the hierarchy of certificates that are used to authenticate the certificate chain form the new certificate chain for alias. If a trust chain cannot be established, the private key is not imported.
• If the chain contains more than one certificate, the chain is ordered with the user certificate first and the self-signed root CA certificate last. Using the ordered chain, The hwkeytool utility attempts to match the root CA certificate in the reply with any of the trusted certificates in the keystore or, if the -trustcacerts option was specified, the cacerts keystore file. If no match is found, the information of the root CA certificate is printed and you are prompted to verify it. Verification can be done, for example, by comparing the displayed certificate fingerprints with the fingerprints that you obtain from some other (trusted) source of information, which might be the root CA itself. You have the option of canceling the import operation. However, if you specified the -noprompt option, there is no user interaction with the utility.

The new certificate chain for alias replaces the old certificate chain that was associated with this entry. The old chain can be replaced only if a valid keypass (the password that is used to protect the private key in the entry) is supplied. If you do not provide a password, the hwkeytool utility cancels the operation. Be careful with passwords; for more information, 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 is determined by the IBMJCECCA provider (KEYMANAGEMENT if CCA supports the generation of Key Management EC keys, otherwise SIGNATURE).

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 by using the hwkeytool utility, specifying jks as the keystore type. The default cacerts keystore file contains several root CA certificates with the following aliases and X.500 owner distinguished names:

• Alias: thawtepersonalfreemailca

  Owner DN: EmailAddress=personal-freemail@thawte.com,

  CN=Thawte Personal Freemail CA,

  OU=Certification Services Division,

  O=Thawte Consulting, L=Cape Town, ST=Western Cape, C=ZA

• Alias: thawtepersonalbasicca

  Owner DN: EmailAddress=personal-basic@thawte.com,

  CN=Thawte Personal Basic CA,

  OU=Certification Services Division,

  O=Thawte Consulting, L=Cape Town, ST=Western Cape, C=ZA

• Alias: thawtepersonalpremiumca

  Owner DN: EmailAddress=personal-premium@thawte.com,

  CN=Thawte Personal Premium CA,

  OU=Certification Services Division,

  O=Thawte Consulting, L=Cape Town, ST=Western Cape, C=ZA

• Alias: thawteserverca

  Owner DN: EmailAddress=server-certs@thawte.com,

  CN=Thawte Server CA, OU=Certification Services Division,

  O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA

• Alias: thawtepremiumserverca

  Owner DN: EmailAddress=premium-server@thawte.com,

  CN=Thawte Premium Server CA,

  OU=Certification Services Division,

  O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA

• Alias: verisignclass1ca

  Owner DN: OU=Class 1 Public Primary Certification Authority,

  O="VeriSign, Inc.", C=US

• Alias: verisignclass2ca

  Owner DN: OU=Class 2 Public Primary Certification Authority,

  O="VeriSign, Inc.", C=US

• Alias: verisignclass3ca

  Owner DN: OU=Class 3 Public Primary Certification Authority,

  O="VeriSign, Inc.", C=US

• Alias: verisignclass4ca

  Owner DN: OU=Class 4 Public Primary Certification Authority,

  O="VeriSign, Inc.", C=US

• Alias: verisignserverca

  Owner DN: OU=Secure Server Certification Authority,

  O=RSA Data Security, Inc., C=US

The initial password of the cacerts keystore file is changeit. System administrators should change this password and the default access permission of that file when they install the SDK.

-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 that is identified by the alias to the destination keystore. If a destination alias is not provided with destalias, srcalias is used as the destination alias. If the source entry is protected by a password, srckeypass is used to recover the entry. If srckeypass is not provided, the hwkeytool utility attempts to use srcstorepass to recover the entry. If srcstorepass is not provided or is incorrect, you are prompted for a password. The destination entry is protected by using destkeypass. If destkeypass is not provided, the destination entry is protected with the source entry password.

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

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

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

-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 that is 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 that is read from importfile, the hwkeytool utility throws an exception and exits. If all secret keys in importfile are imported, the hwkeytool utility displays the total number of secret keys that were imported.

-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 authenticates the certificate requester (usually offline) and returns a certificate or certificate chain, which used to replace the existing certificate chain (initially a self-signed certificate) in the keystore.

The private key and X.500 distinguished name that are associated with alias are used to create the PKCS#10 certificate request. To access the private key, the appropriate password must be provided, beause private keys are protected in the keystore with a password (except for a RACF keystore). If keypass is not provided at the command line and is different from the password that is used to protect the integrity of the keystore, you are prompted for it.

Be careful with passwords; for more information, see Regarding passwords.

sigalg specifies the algorithm to use to sign the CSR. For more information, 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 that is 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, it is 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 that is addressed by alias.

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 the keys are stored them in exportfile.

If aliasrange is specified and a secret key in the range does not exist in the keystore, the hwkeytool utility throws an exception and exits. All the keys before the missing key are exported. When the export is finished, the hwkeytool utility displays the total number of secret keys that were exported.

See also: aliasRange.

-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 that is 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 by using the printable encoding format as defined by the Internet RFC 1421 standard

You cannot specify both the -v and -rfc options.

-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 that is 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 on the command line, you are prompted for it.

Be careful with passwords; for more information, see Regarding passwords.

Because RACF keystores do not maintain a password in the keystore itself, the -storepasswd command is not supported for RACF 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 that are protected with the password old_keypass are changed to use new_keypass.

If the -alias option is provided at the command line, the password under which the key entry that is identified by alias is protected is 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, you are prompted for it.

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

Be careful with passwords; for more information, see Regarding passwords.

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

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

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

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

• If the specified key is type PKDS, the key is deleted from the keystore and from the CCA key repository. On z/OS, this behavior means that the key is removed from the ICSF PKDS data set.
• If the specified key is type CKDS, the key is deleted from the keystore and from the CCA key repository. On z/OS, this behavior means that the key is removed from the ICSF CKDS (Cryptographic Key Data Store) data set.

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

-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 prompts you for one. If the original entry is protected with an entry password, the password can be supplied by using the -keypass option. In this case, if keypass is not specified then the hwkeytool utility attempts to use storepass to recover the entry. If storepass is not provided or is incorrect, you are prompted for a password.

RACF keystores do not support the -changealias command.

Getting Help

-help {-Jjavaoption}

Lists all the commands and their options.

Examples

The following example commands are shown on multiple lines for legibility; to use them on a real system, type them on 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 exist in the working directory, this command creates it, with the password ab987c. The command generates a public/private key pair for the entity whose distinguished name has the 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.

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

hwkeytool -genkeypair

The rest of the examples assume that you ran the -genkeypair command in this way and that you responded to the prompts with the values that are shown in the first -genkeypair example (such as a private key password of kpi135).

Requesting a signed certificate from a certificate authority

So far, all you 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) by using the following command:

hwkeytool -certreq -file MarkJ.csr

This creates a CSR for the entity that is 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 authenticates you, the requester (usually offline), and returns a certificate, signed by them, authenticating your public key. (Sometimes, the CA returns 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):

• If the certificate reply is a certificate chain, you need only the certificate at the head 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 certificate for the issuing CA (the CA that signed it) and, if that certificate 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 includes five VeriSign root CA certificates, so you might not 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 that authenticates that CA's public key does not exist in the cacerts file, you must 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 that authenticates 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.

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

hwkeytool -importcert -alias abc -file ABCCA.cer

This command 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

After you import a certificate that authenticates the public key of the CA that you submitted your certificate signing request to (or if such a certificate exists 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 that the CA returned in response to your request. If the CA reply is a single certificate, the new chain is constructed by using the certificate reply, the trusted certificates in the keystore where you are importing the reply, or the certificates in the cacerts keystore file.

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

hwkeytool -importcert -trustcacerts -file VSMarkJ.cer

Exporting a certificate that authenticates your public key

Suppose you used the jarsigner tool to sign a .jar file. Clients that use the file will want to authenticate your signature.

One way that clients can authenticate your signature is by importing your public key certificate into their keystore as a trusted entry. You can export the certificate then supply it to your clients. For example, the following command exports a certificate from a default keystore entry with alias mykey to a file named MJ.cer:

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 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 the hwkeytool utility has difficulties recovering a private key or secret key from the source keystore, it prompts you for a password. If the hwkeytool utility detects alias duplication, it prompts you for a new destination alias. You can specify a new alias or allow the hwkeytool utility 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 following 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, in addition to the options in the preceding example, you must also 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 (by using -srckeypass) and the destination key entry (by using -destkeypass), you can run a hwkeytool command that does not prompt you with a question. This option makes it convenient to include a hwkeytool command such as the following into a script file:

-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 key ring for its persistent data source is either type JCERACFKS or JCECCARACFKS. This type of keystore is supported only on the z/OS operating system. For these keystores, you must specify the RACF key ring with the -keystore option, by using the following syntax:

safkeyringjcecca:://userid/ringname

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

• For example, for a JCECCARACFKS keystore:

  -J-Djava.protocol.handler.pkgs=com.ibm.crypto.hdwrCCA.provider
  

• For example, for a JCERACFKS keystore:

  -J-Djava.protocol.handler.pkgs=com.ibm.crypto.provider
  

For example, the following command lists all certificates in the key ring myring, owned by user ID SUSAN:

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

hwkeytool and the ICSF CSFSERV and CSFKEYS RACF classes

If you use the hwkeytool utility but you are not authorized to create new profiles in the ICSF CSFKEYS RACF class, the hwkeytool utility might create a key that you cannot access. To avoid this problem, verify that you are authorized to the profiles in the ICSF CSFSERV RACF class including CSFPKG.Various ICSF services are used by the hwkeytool utility. In addition, verify that you have authority to create new profiles in the ICSF CSFKEYS RACF class.

If you are a developer or a user of programs that call the KeyPairGenerator Java security class to generate an IBMJCECCA public and private key pair, see also the previous section, hwkeytool and the ICSF CSFSERV and CSFKEYS RACF classes.

hwkeytool and updates to a JCECCARACFKS keystore

The persistent data for a JCECCARACFKS keystore is stored in the RACF database and connected to a RACF key ring, which means that the behavior of a JCECCARACFKS keystore during update operations differs from the behavior of file-based keystores. For more information, see Updating a JCECCARACFKS KeyStore instance

hwkeytool and RACF ICSF or PCICC Keys

Private keys can be generated when you use the RACDCERT GENCERT command to create digital certificates and an optional public/private key pair. Running this command with the PCICC parameter specifies that the key pair is generated by 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. Running this command with the ICSF parameter specifies that the key pair is generated by 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 the key types that are generated by using either parameter (PCICC or ICSF).