Subject Alternative Name (SAN) is a critical extension in X.509 certificates that allows multiple domain names or IP addresses to be protected by a single SSL/TLS certificate. Adding SANs helps avoid security warnings in modern browsers and enables flexibility when securing multiple hostnames.
In this comprehensive guide, you will learn what SAN is, why it matters, and how to add SANs when creating certificates using various tools such as OpenSSL and Windows Certificate Services. The guide also covers troubleshooting tips and best practices.
Understanding Subject Alternative Name (SAN)
The Subject Alternative Name extension allows you to specify additional identities bound to the certificate beyond the Common Name (CN). These identities can include domain names, IP addresses, email addresses, URIs, and even directory names.
Note: Since 2017, browsers have deprecated the use of the Common Name (CN) field for domain validation, making SAN mandatory for SSL certificates.
Without SAN, users may encounter certificate errors if they access domains not explicitly listed in the CN field. SAN provides a secure and standardized way to support multiple domains and subdomains in one certificate.
Common SAN Types
| SAN Type | Description | Example |
|---|---|---|
| DNS Name | Domain names or hostnames associated with the certificate | example.com, www.example.com |
| IP Address | IP addresses allowed to use the certificate | 192.168.1.1, 2001:db8::1 |
| Email addresses protected by the certificate | [email protected] | |
| URI | Uniform Resource Identifiers | http://example.com |
Why Add SAN to Your Certificate?
Including SANs in certificates has become a standard best practice for many reasons:
- Browser Compliance: Modern browsers require SAN to validate domains correctly.
- Multi-domain Support: One certificate can secure multiple domains and subdomains.
- IP Address Validation: Certificates can secure IP addresses directly, which is impossible with CN alone.
- Flexibility: Useful when services migrate between hostnames or use multiple aliases.
How to Add SAN Using OpenSSL
OpenSSL is a powerful open-source tool widely used for generating keys, certificate signing requests (CSRs), and certificates. Adding SAN to a certificate involves configuring OpenSSL correctly, as SAN is not included by default in CSRs.
Step 1: Create an OpenSSL Configuration File
Create a configuration file that defines the SAN extension. You can start from the default OpenSSL config or create a minimal custom config.
[ req ] default_bits = 2048 prompt = no default_md = sha256 distinguished_name = dn req_extensions = req_ext [ dn ] CN = example.com [ req_ext ] subjectAltName = @alt_names [ alt_names ] DNS.1 = example.com DNS.2 = www.example.com DNS.3 = api.example.com IP.1 = 192.168.1.100
Save this file as openssl-san.cnf (or any preferred name).
Step 2: Generate a Private Key
Use OpenSSL to generate a new RSA private key:
openssl genpkey -algorithm RSA -out example.key -pkeyopt rsa_keygen_bits:2048
This command creates a 2048-bit RSA private key named example.key.
Step 3: Generate a CSR with SAN Extension
Create a Certificate Signing Request that includes the SAN extension using the custom config file:
openssl req -new -key example.key -out example.csr -config openssl-san.cnf
The CSR will contain the SAN fields as specified in the [alt_names] section.
Step 4: Self-Sign the Certificate (Optional)
If you want to create a self-signed certificate with SAN for testing or internal use, run this command:
openssl x509 -req -in example.csr -signkey example.key -out example.crt -days 365 -extensions req_ext -extfile openssl-san.cnf
This signs the CSR using the private key and includes SAN in the resulting certificate.
How to Verify SAN in the Certificate
To check if the SAN extension is present and correct in your certificate, use:
openssl x509 -in example.crt -noout -text | grep -A 1 "Subject Alternative Name"
You should see the list of DNS names and IP addresses included.
Adding SAN When Using Windows Certificate Authority
When generating a certificate request on Windows or using Microsoft Certificate Services, adding SAN requires specific steps because the Windows certificate request wizard does not expose SAN fields directly.
Method 1: Using certreq and an INF File
Create an INF file that specifies the SAN extension explicitly.
[Version]
Signature="$Windows NT$"
[NewRequest]
Subject = "CN=example.com"
KeySpec = 1
KeyLength = 2048
Exportable = TRUE
MachineKeySet = TRUE
SMIME = FALSE
PrivateKeyArchive = FALSE
UserProtected = FALSE
UseExistingKeySet = FALSE
ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
ProviderType = 12
RequestType = PKCS10
KeyUsage = 0xa0
[Extensions]
2.5.29.17 = "{text}"
_continue_ = "dns=example.com&"
_continue_ = "dns=www.example.com&"
_continue_ = "ipaddress=192.168.1.100"
Save as sanrequest.inf.
Then generate the CSR:
certreq -new sanrequest.inf example.req
Submit this CSR to your Windows CA or external CA.
Method 2: Using PowerShell
PowerShell scripts or utilities like New-SelfSignedCertificate allow specifying SAN directly:
New-SelfSignedCertificate -DnsName "example.com","www.example.com" ` -CertStoreLocation "cert:\LocalMachine\My" ` -KeyLength 2048 -NotAfter (Get-Date).AddYears(1)
This creates a self-signed certificate with SAN in the local machine store.
How to Add SAN When Using Java Keytool
Java Keytool does not support adding SAN directly during CSR generation, which makes this process trickier.
The common approach is:
- Generate a CSR with Keytool.
- Use OpenSSL or other tools to add SAN during certificate issuance.
- Alternatively, create a custom extension file and sign the certificate externally.
For development, using OpenSSL or a dedicated CA is recommended when SAN is required.
Detailed Example: Adding SAN to a Certificate Using OpenSSL
This section walks through a complete example from scratch.
Step 1: Create the Configuration File
[ req ] default_bits = 2048 distinguished_name = req_distinguished_name req_extensions = v3_req prompt = no [ req_distinguished_name ] CN = example.com [ v3_req ] subjectAltName = @alt_names [ alt_names ] DNS.1 = example.com DNS.2 = www.example.com DNS.3 = mail.example.com IP.1 = 10.0.0.5
Step 2: Generate the Private Key
openssl genrsa -out example.key 2048
Step 3: Generate the CSR
openssl req -new -key example.key -out example.csr -config san.cnf
Step 4: Create the Self-Signed Certificate
openssl x509 -req -in example.csr -signkey example.key -out example.crt -days 365 -extensions v3_req -extfile san.cnf
Step 5: Verify SAN
openssl x509 -in example.crt -noout -text | grep -A 1 "Subject Alternative Name"
Troubleshooting Common Issues with SAN
| Issue | Possible Cause | Solution |
|---|---|---|
| SAN not present in certificate | Extension not included in CSR or certificate signing step | Ensure subjectAltName is in config and used with -extensions option |
| Browser shows SSL error for additional domain | Domain not listed in SAN | Add domain to alt_names section and regenerate CSR/certificate |
| IP address SAN ignored | Incorrect syntax or type (use IP. prefix) |
Use IP.1=xxx.xxx.xxx.xxx format in config |
| Keytool CSR lacks SAN | Keytool does not support SAN in CSRs | Use OpenSSL or external CA tools to add SAN |
Best Practices When Working with SAN
- Always Specify SAN Explicitly: Never rely solely on the Common Name field for domain validation.
- Use Meaningful Aliases: Include all domain variations users may access, including
wwwand non-wwwversions. - Keep SAN List Up to Date: Remove unused domains and add new ones as needed to avoid security warnings.
- Use Wildcards Carefully: Wildcard SANs (e.g.,
*.example.com) can simplify management but may not cover all subdomains. - Test Certificates Thoroughly: Use tools like
opensslor online SSL checkers to verify SAN presence and correctness.
Summary
Adding Subject Alternative Name is essential for creating valid and trustworthy SSL/TLS certificates. Whether you use OpenSSL, Windows Certificate Authority, or other tools, explicitly specifying SAN ensures your certificate will be accepted by modern browsers and clients.
This guide detailed the process of adding SAN using configuration files, command line tools, and scripts. It also highlighted common pitfalls and troubleshooting techniques to streamline your certificate generation workflow.
Remember: Modern security standards mandate SAN usage. Always plan your certificate generation with SAN in mind to avoid costly reissues and client errors.
