Cryptography in Java. Keytool utility

Hi, Habr! I present to your attention the translation of the 10th article "Java Keytool" by Jakob Jenkov from the series of articles for beginners who want to learn the basics of cryptography in Java.

Table of contents:

1. Java cryptography
2. Java cipher
3. MessageDigest
4. Mac
5. Signature
6. KeyPair
7. KeyGenerator
8. KeyPairGenerator
9. KeyStore
10. Keytool
11. Certificate
12. CertificateFactory
13. Certpath

Keytool utility

Java Keytool is a command line tool that can generate public key / private key pairs and store them in the keystore . The executable file of the utility is distributed along with the Java SDK (or JRE), so if you have an SDK installed, it means you will also have it pre-installed.
The executable file is called keytool . To execute it, open a command prompt (cmd, console, shell, etc.). and change the current directory to the bin directory in the Java SDK installation directory. Type keytool , and then press Enter . You should see something like this:

 C:\Program Files\Java\jdk1.8.0_111\bin>keytool Key and Certificate Management Tool Commands: -certreq Generates a certificate request -changealias Changes an entry's alias -delete Deletes an entry -exportcert Exports certificate -genkeypair Generates a key pair -genseckey Generates a secret key -gencert Generates certificate from a certificate request -importcert Imports a certificate or a certificate chain -importpass Imports a password -importkeystore Imports one or all entries from another keystore -keypasswd Changes the key password of an entry -list Lists entries in a keystore -printcert Prints the content of a certificate -printcertreq Prints the content of a certificate request -printcrl Prints the content of a CRL file -storepasswd Changes the store password of a keystore Use "keytool -command_name -help" for usage of command_name C:\Program Files\Java\jdk1.8.0_111\bin> 

As you can see, the keytool utility supports a set of commands for working with keys, certificates and keystores. This guide will cover the most frequently used of these commands.

Keytool Scripts

Keytool utility commands take many arguments, the installation of which can be difficult to remember. Therefore, it is recommended to create several CMD or Shell scripts with a sequence of Keytool commands. These scripts make it easy to re-execute commands, and also allow you to go back and see how the keystore was created.

Key pair generation

Generating a key pair (public key / private key) is one of the most common tasks for which the Keytool utility is used. The generated key pair is inserted into the KeyStore file as a self-signed key pair. Here is a common command line format for generating a key pair:

 -genkeypair -alias alias -keyalg keyalg -keysize keysize -sigalg sigalg -dname dname -keypass keypass -validity valDays -storetype storetype -keystore keystore -storepass storepass -providerClass provider_class_name -providerArg provider_arg -v -protected -Jjavaoption 

The arguments are explained in the Keytool Arguments section. Not all of these arguments are needed and many are optional. The utility will inform you if you have missed a required argument. Here is an example of a command that imports a certificate in KeyStore . Remember to remove line breaks when entering commands at the command prompt.

 "C:\\Program Files\Java\jdk1.8.0_111\bin\keytool" -importcert -alias testkey -keypass 123456 -storetype JKS -keystore keystore2.jks -file cert.cert -rfc -storepass abcdef 

List of vault records

To list the entries in the keystore, you can use the list command. Below is the format for the list command. Line breaks are intended only to simplify reading. Remove line breaks before executing the command:

 -list -alias alias -storetype storetype -keystore keystore -storepass storepass -providerName provider_name -providerClass provider_class_name -providerArg provider_arg -v -rfc -protected -Jjavaoption 

Here is an example of the list command. Do not forget to remove line breaks!

 "C:\\Program Files\Java\jdk1.8.0_111\bin\keytool" -list -storetype JKS -keystore keystore.jks -storepass abcdef 

This command will list all entries in the given keystore. The output will look something like this:

 Keystore type: JKS Keystore provider: SUN Your keystore contains 1 entry testkey, 19-Dec-2017, PrivateKeyEntry, Certificate fingerprint (SHA1): 4F:4C:E2:C5:DA:36:E6:A9:93:6F:10:36:9E:E5:E8:5A:6E:F2:11:16 

If you include the alias argument in the list command, only the entry corresponding to this alias will be listed. Here is an example of a list command with an alias argument:

 "C:\\Program Files\Java\jdk1.8.0_111\bin\keytool" -list -alias testkey -storetype JKS -keystore keystore.jks -storepass abcdef 

The result of the above command:

 testkey, 15-Dec-2017, PrivateKeyEntry, Certificate fingerprint (SHA1): 71:B0:6E:F1:E9:5A:E7:F5:5E:78:71:DC:08:80:47:E9:5F:F8:6D:25 

Deleting a keystore entry

Also in the keytool utility there is a command that can delete an entry from the keystore: delete . Here is the format of this command:

 -delete -alias alias -storetype storetype -keystore keystore -storepass storepass -providerName provider_name -providerClass provider_class_name -providerArg provider_arg -v -protected -Jjavaoption 

Here is an example of calling the delete command. Remember to remove line breaks before starting!

 "C:\\Program Files\Java\jdk1.8.0_111\bin\keytool" -delete -alias testkey -storetype JKS -keystore keystore.jks -storepass abcdef 

This command deletes the storage entry with the testkey alias stored in the keystore.jks file.

Certificate Request Generation

The keytool utility can generate a certificate request using the certreq . A certificate request is a request to a certification authority (CA) to create a public certificate for your organization. After creating a certificate request, it must be sent to a certification authority in which you want to create a certificate (for example, Verisign, Thawte, or some other certification authority). Before you can generate a certificate request for a private key and a pair of public keys, you must generate this private key and a pair of public keys in the keystore (or import it). How to do this can be viewed in the relevant chapter. Here is the command format for generating the certificate request. Remember to remove all line breaks when using this command:

 -certreq -alias alias -sigalg sigalg -file certreq_file -keypass keypass -storetype storetype -keystore keystore -storepass storepass -providerName provider_name -providerClass provider_class_name -providerArg provider_arg -v -protected -Jjavaoption 

Here is an example of the -certreq :

 "C:\\Program Files\Java\jdk1.8.0_111\bin\keytool" -certreq -alias testkey -keypass 123456 -storetype JKS -keystore keystore.jks -storepass abcdef -file certreq.certreq 

This command will generate a certificate request for a key saved with the testkey alias in the testkey file and write the certificate request to a file called certreq.certreq .

Arguments of the keytool utility

Below is a list of arguments that accept various keytool . Remember that not all commands accept all these arguments. Look at a specific command to see which arguments it takes.

• -alias Alias ​​entry in the keystore. Remember alias
  may indicate only one key.
• -keyalg The name of the algorithm used to generate the key. Usually used RSA.
• -keysize key size in bits. Usually key sizes are multiples. In addition, various algorithms can only support certain predefined key sizes.
• -sigalg Signature algorithm used to sign key pairs.
• -dname A unique name from the X.500 standard. This name will be associated with
  the alias for this key pair in the keystore is also
  used as the “Issuer” and “Subject” fields in the self-signed
  certificate.
• -keypass Key pair password required for
  access to this particular key pair in the keystore.
• -validity Number of days during which the certificate is,
  attached to a pair of keys must be valid.
• -storetype The file format in which the keystore should be saved. The default is jks. Another option is the PKCS11 format.
• -keystore The file name of the repository to store the generated pair.
  keys. If the file does not exist, it will be created.
• -file File name to read or write a certificate or certificate request.
• -storepass Password from the keystore for everyone who wants to work
  with him, you will need this password. Difference of storepass from keypass in
  the first provides access to the repository, and the second to a separate
  a pair of keys. You will need both passwords to access any key
  stored in the repository.
• -rfc If you enable this flag, the utility will use a text format, not a binary format, for example, to export or import certificates. Value -rfc
  refers to the standard RFC 1421.
• -providerName The name of the cryptographic API provider that you want to use when creating a key pair. The provider name must be specified in the Java security properties files.
• -providerClass The name of the root class of the cryptographic API provider that you want to use. Used when the provider name is not specified in the Java security properties files.
• -providerArg Arguments that are passed to their own cryptographic provider during initialization (if necessary by the provider).
• -v Abbreviated from verbose, the Keytool utility will output a lot of additional information to the command line in a readable format.
• -protected Specifies whether the keystore password must be supplied by some external mechanism, such as a hardware token. Valid values ​​are true and false.
• -Jjavaoption option string for a Java VM that generates a key pair and creates a repository.