Free Online Course · Self-paced · Hands-on

Keytool & Java Keystore Tutorial for Beginners

Free keytool tutorial for Java keystores and truststores: PKCS12, CSRs, chain imports, cacerts, PKIX fixes, and Spring Boot and Tomcat HTTPS on JDK 21.

  • 8 chapters
  • 34 lessons
  • ~10h
  • Beginner to Intermediate
  • Tested with OpenJDK 21
  • Updated Sep 2026
Start the course View syllabus
Keytool & Java Keystore Tutorial for Beginners
By Last updated

About this course

This is a free, hands-on course on keytool, the command-line tool that ships with every JDK for managing Java keystores and truststores. It follows the Oracle keytool reference and uses PKCS12, the default keystore type since JDK 9, in every lesson, from the first self-signed certificate to HTTPS in Spring Boot, Tomcat, Docker, and Kubernetes.

Most keytool problems show up as an application stack trace rather than a keytool message, so a whole chapter works backward from the errors people actually search for, such as PKIX path building failed and Keystore was tampered with, or password was incorrect. Each fix starts from the exact error text and ends with a command that shows the problem is gone.

New to Java TLS? Start with keystore vs truststore and work through the chapters in order. If an application is already failing, go straight to the troubleshooting chapter, or find the cacerts file the JVM really loads.

What you'll learn

  • Install keytool, and explain what belongs in a keystore, what belongs in a truststore, and when OpenSSL is the better tool
  • Create PKCS12 keystores with self-signed certificates that carry localhost and IP SANs
  • Generate a CSR, import the CA-signed reply, and renew an expired certificate on the same alias
  • Import root, intermediate, and server certificates in the right order, and sign and verify JARs with jarsigner
  • Fix common keytool and JSSE errors, from PKIX path building failed to Invalid keystore format
  • List, export, convert, and clean up entries across PEM, DER, PKCS12, PFX, and JKS
  • Point a JVM at the right truststore with javax.net.ssl properties, build mTLS stores, and automate imports in Bash
  • Enable HTTPS in Spring Boot and Tomcat, and ship custom trust in Docker and Kubernetes

Who this course is for

  • Java developers who hit PKIX path building failed and need to know which truststore the JVM actually read
  • DevOps and platform engineers shipping Java services to Docker and Kubernetes with private CA trust
  • Middleware administrators enabling HTTPS on Tomcat or Spring Boot with CA-signed certificates
  • Security engineers who manage certificate renewal across Java and non-Java systems

Prerequisites

  • OpenJDK 11 or newer with keytool on the PATH. The install lesson covers this on Ubuntu
  • Comfortable on the Linux command line
  • Basic TLS ideas such as certificate, private key, and CA chain. The OpenSSL course covers them if needed
  • OpenSSL for the lessons that sign CSRs with a local CA, and Docker plus a Kubernetes cluster only for the container lesson

Versions and testing environment

Every command in this course was run on this stack

ComponentVersionNotes
OpenJDK 21 java-21-openjdk provides keytool and jarsigner in every lesson (21.0.9 in the install lesson)
OpenJDK 25 The cacerts lookup lesson also ran on 25.0.3 to check default truststore behaviour
Ubuntu 26.04 LTS Lab host OS. The install lesson and cheat sheet were run on Ubuntu 25.04
Spring Boot 3.4.x HTTPS on port 8443 with server.ssl.* properties
Apache Tomcat 10.1.x certificateKeystoreFile on the HTTPS connector in server.xml

Syllabus

8 chapters · 34 lessons · ~10h of reading

  1. 1 Fundamentals and Setup 3 lessons · ~35 min
    1. Part 1 Install keytool on Ubuntu 11 min read
    2. Part 2 Keystore vs truststore in Java 13 min read
    3. Part 3 keytool vs OpenSSL — which tool to use 11 min read
  2. 2 Create Keys and Certificates 3 lessons · ~26 min
    1. Part 4 Self-signed certificate with localhost and IP SAN 8 min read
    2. Part 5 Create a CSR and import a CA-signed certificate 9 min read
    3. Part 6 Renew or replace an expired certificate 9 min read
  3. 3 Import Certificate Chains 2 lessons · ~19 min
    1. Part 7 Import root, intermediate, and server chain 8 min read
    2. Part 8 Sign and verify a JAR with jarsigner 11 min read
  4. 4 Troubleshooting keytool Errors 9 lessons · ~1h 29m
    1. Part 9 Fix PKIX path building failed 11 min read
    2. Part 10 Fix failed to establish chain from reply 12 min read
    3. Part 11 Fix public keys in reply and keystore don't match 7 min read
    4. Part 12 Fix keystore tampered or password incorrect 11 min read
    5. Part 13 Fix UnrecoverableKeyException cannot recover key 8 min read
    6. Part 14 Fix Input not an X.509 certificate 10 min read
    7. Part 15 Fix Certificate not imported alias already exists 8 min read
    8. Part 16 Fix No subject alternative names present 11 min read
    9. Part 17 Fix Invalid keystore format 11 min read
  5. 5 Inspect, Export, and Convert 6 lessons · ~46 min
    1. Part 18 List and inspect keystore entries 7 min read
    2. Part 19 Export certificate in PEM and DER 8 min read
    3. Part 20 Import PEM certificate and private key 8 min read
    4. Part 21 Import PKCS12/PFX into Java keystore 7 min read
    5. Part 22 Convert JKS to PKCS12 8 min read
    6. Part 23 Change alias, password, and delete entries 8 min read
  6. 6 Truststores and System CAs 7 lessons · ~1h 12m
    1. Part 24 Configure javax.net.ssl.trustStore and keyStore 11 min read
    2. Part 25 Create Java mTLS keystore and truststore 12 min read
    3. Part 26 Custom truststore vs editing cacerts 9 min read
    4. Part 27 Import certificate into app-specific truststore 11 min read
    5. Part 28 Automate certificate import in Bash 9 min read
    6. Part 29 Find the correct Java cacerts file 12 min read
    7. Part 30 Import certificate into Java cacerts on Linux 8 min read
  7. 7 Spring Boot, Tomcat, and Containers 3 lessons · ~27 min
    1. Part 31 Configure Spring Boot HTTPS with keytool 9 min read
    2. Part 32 Configure Tomcat SSL with keytool 8 min read
    3. Part 33 Java truststore in Docker and Kubernetes 10 min read
  8. 8 Reference 1 lesson · ~15 min
    1. Part 34 keytool command cheat sheet 15 min read

Hands-on labs

6 guided builds you run yourself

  1. Replace a self-signed entry with a CA-signed certificate

    Generate a key pair and CSR with keytool, sign it with a local OpenSSL CA, and import the reply onto the same alias.

  2. Import a full certificate chain

    Add the root and intermediate CAs as trusted entries, attach the server reply to the private key entry, and confirm the chain with keytool -list -v.

  3. Build keystores and truststores for mutual TLS

    Create both stores for client and server, then run an HTTPS server that refuses connections without a client certificate.

  4. Enable HTTPS in Spring Boot

    Serve the application on port 8443 from a PKCS12 keystore and call its health endpoint with a Java client that trusts your CA.

  5. Script an idempotent CA import

    Back up the truststore, compare SHA-256 fingerprints, and import a CA only when it is missing, so the script is safe to rerun from CI.

  6. Ship private CA trust in Docker and Kubernetes

    Bake a truststore into an image with JAVA_TOOL_OPTIONS, or build one in an initContainer from a CA stored in a Secret.

Where to go after this course

  • keytool cheat sheetEvery keytool command from the course on one page, grouped by task.
  • keytool reference for JDK 25Oracle's manual page for the current Java LTS, with every command and option.
  • OpenSSL courseRun your own CA and handle PEM files for the non-Java services that share the same certificates.
  • Keycloak courseA Java application where the same keystore and truststore decisions come up for HTTPS and LDAPS.

Frequently Asked Questions

Should I use JKS or PKCS12?

Use PKCS12. It has been the default keystore type since JDK 9, and it is a standard format that OpenSSL, web servers, and other platforms can read. JKS is a Java-only format that you will still meet in older applications. Convert JKS to PKCS12 with keytool -importkeystore, then update the application's keystore type if it sets one explicitly.

What is the default cacerts password, and should I edit cacerts?

The default password for the JDK cacerts truststore is changeit. You can import a private CA into it, but every application on that JDK then trusts that CA, and a JDK or CA bundle update can replace the file and silently drop your change. A separate truststore passed with -Djavax.net.ssl.trustStore is easier to audit and survives upgrades. Custom truststore vs editing cacerts compares the two approaches.

Where is keytool installed?

keytool lives in the bin directory of every JDK and JRE, so it is at $JAVA_HOME/bin/keytool. On Linux the package usually adds a keytool link to the PATH. With several JDKs installed, run readlink -f "$(command -v keytool)" to see which one you are calling. Use the keytool from the same JDK that runs your application, because that JDK's defaults and cacerts are the ones that apply.

Can keytool import an existing PEM private key?

Not directly. keytool can import PEM certificates, but not a separate PEM private key. Bundle the key and certificate into a PKCS12 file with openssl pkcs12 -export, then use that file as the keystore or merge it into another one with keytool -importkeystore. The PEM private key import lesson walks through both steps.

Does the Java version change how keytool behaves?

The core commands are the same on current LTS releases, so a lesson run on JDK 21 works on 17 or 25. The difference that matters is JDK 8, where the default keystore type is still JKS and the -cacerts shortcut option does not exist. If you support JDK 8, pass -storetype PKCS12 explicitly and give the full path to cacerts.

Deepak Prasad

R&D Engineer

Founder of GoLinuxCloud with 15+ years of expertise in Linux, Python, Go, Laravel, DevOps, Kubernetes, Git, Shell scripting, OpenShift, AWS, Networking, and Security. With extensive experience, he excels across development, DevOps, networking, and security, delivering robust and efficient solutions for diverse projects.

Expertise
  • Go (programming language)
  • Python (programming language)
  • DevOps
  • Computer Security
  • Cloud Computing
  • Kubernetes
  • Linux
  • Ansible (software)