codeaprendiz.github.io

DevOps Essentials

View on GitHub

keytool

NAME

keytool - key and certificate management tool

SYNOPSIS

keytool [ commands ]

DESCRIPTION

keytool is a key and certificate management utility.

It enables users to administer their own public/private key pairs and associated 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 the public keys (in the form of certificates) of their communicating peers.

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

Keystore Entries

There are two different types of entries in a keystore:

Keystore Aliases

All keystore entries (key and trusted certificate entries) are accessed via unique aliases.

Aliases are case-insensitive; the aliases Hugo and hugo would refer to the same keystore entry.

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

Subsequent keytool commands must use this same alias to refer to the entity. For example, suppose you use the alias duke to generate a new public/private key pair and wrap the public key into a self-signed certificate via the following command:

keytool -genkey -alias duke -keypass dukekeypasswd

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

This changes the password from “dukekeypasswd” to “newpass”.

Keystore Location

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

Keystore Creation

Keystore Implementation

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

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

Keystore implementations are provider-based. More specifically, the application interfaces supplied by KeyStore are implemented in terms of a “Service Provider Interface” (SPI). That is, there is a 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 How to Implement a Provider for the Java Cryptography Architecture.

Applications can choose different types of keystore implementations from different providers, using the “getInstance” factory method supplied in the KeyStore class. A keystore type defines the storage and data format of the keystore information, and the algorithms used to protect private keys in the keystore and the integrity of the keystore itself.

Keystore implementations of different types are not compatible.

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

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

If you don’t explicitly specify a keystore type, the tools choose a keystore implementation based simply on the value of the keystore.type property specified in the security properties file. The security properties file is called java.security, and it resides in the JDK security properties directory, java.home/lib/security, where java.home is the JDK installation directory. Each tool gets the keystore.type value and then examines all the currently-installed providers until it finds one that implements keystores of that type. It then uses the key-store 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

OPTIONS

EXAMPLES

$ keytool -v -import -file /app/a.cer -alias iam_qa -keystore /usr/java/default/jre/lib/security/cacerts
$ keytool -v -import -file xi52-cert.cert.hosting.asda.com2018.cer -alias ukil -keystore keystore.jks
$ keytool -keystore kestore.jks -importcert -file xi52-cert.cert.hosting.asda.com2018.cer -alias ukil
$ keytool -v -list -keystore sample.truststore -alias aliasNameGiven
Enter keystore password
$ echo | openssl s_client -connect qa.iam.platform.prod.company.com:443 2>&1 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/a.cer
$ keytool -noprompt -import -file /tmp/a.cer -alias iam1233_qa -keystore /usr/java/default/jre/lib/security/cacerts -storepass changeit 
Certificate was added to keystore
$