Adding Subject Alternative Names to SSL Certificates: A Deep Dive into the -ext Parameter with keytool

Dec 03, 2025 · Programming · 13 views · 7.8

Keywords: SSL certificates | Subject Alternative Names | keytool

Abstract: This article explores how to add Subject Alternative Names (SAN) to SSL certificates to resolve common errors like "No subject alternative names present." Focusing on the keytool utility in Java 7 and above, it details the use of the -ext parameter to specify DNS or IP SAN entries, with complete command examples and configuration guidelines. It also briefly contrasts alternative methods with OpenSSL and emphasizes the importance of SAN in modern TLS/SSL communications.

Introduction

In securing network communications, SSL/TLS certificates are pivotal. However, developers often encounter a typical error: javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No subject alternative names present. This indicates the certificate lacks Subject Alternative Names (SAN), which modern clients (e.g., Java applications) often require for server identity verification. Based on high-scoring answers from Stack Overflow, this article delves into using the keytool utility to add SAN, ensuring certificate compatibility and security.

Importance of Subject Alternative Names (SAN)

Subject Alternative Names are an extension field in X.509 certificates, allowing multiple identifiers like domain names (DNS) or IP addresses to be bound to a certificate. Traditionally, certificates relied solely on the Common Name (CN) in the Subject field, but this approach is being superseded by SAN due to its flexibility and compliance with RFC 5280 standards. For instance, a certificate can include both DNS:www.example.com and IP:192.168.1.1 to support various access methods. Absence of SAN leads to client verification failures, especially when using IP addresses or non-standard domain names.

Steps to Add SAN Using keytool

Starting from Java 7, the keytool utility introduced the -ext parameter specifically for specifying certificate extensions, including SAN. Here is a complete command example based on the scenario in the question:

keytool -genkeypair -keystore /root/.keystore -dname "CN=192.168.x.xxx, OU=I, O=I, L=T, ST=On, C=CA" -alias tomcat -validity 3650 -keyalg RSA -keypass abcd -storepass abcd -ext SAN=dns:example.com,ip:192.168.x.xxx

In this command:

After executing this command, the generated certificate will include the SAN extension, thereby avoiding the "No subject alternative names present" error. Note that even if the certificate is generated with Java 7's keytool, it can be used in older Java environments, as the SAN extension is a standard X.509 feature.

Additional Notes and Alternative Methods

Beyond this method, other answers provide similar insights. For example, multiple SAN entries can be specified simultaneously, such as -ext SAN=dns:test.abc.com,ip:1.1.1.1, enhancing certificate applicability. If using OpenSSL tools, adding SAN requires editing configuration files (e.g., openssl.cnf) and specifying the subjectAltName field, but this process is more complex and not suitable for keytool scenarios. In practice, it is recommended to prioritize the -ext parameter with keytool, as it is straightforward and officially supported by the Java platform.

Conclusion

Through this analysis, we see that adding Subject Alternative Names to SSL certificates is key to resolving client verification errors. Leveraging the keytool utility in Java 7 and above, developers can easily integrate SAN via the -ext parameter, improving certificate compatibility and security. As TLS protocols evolve, the importance of SAN will grow, making mastery of its configuration essential for building robust encrypted communication systems.

Copyright Notice: All rights in this article are reserved by the operators of DevGex. Reasonable sharing and citation are welcome; any reproduction, excerpting, or re-publication without prior permission is prohibited.