From 37352c96a8a0c762c6c3ae08dc4ae000a29338c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Richard=20K=C3=B6rber?= <github@shredzone.org>
Date: Sun, 21 Feb 2016 12:29:41 +0100
Subject: [PATCH] Document request of multiple domains (SAN) per certificate

---
 src/site/markdown/usage/certificate.md | 32 ++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/src/site/markdown/usage/certificate.md b/src/site/markdown/usage/certificate.md
index 89d8796a..59da3f41 100644
--- a/src/site/markdown/usage/certificate.md
+++ b/src/site/markdown/usage/certificate.md
@@ -8,12 +8,13 @@ To do so, prepare a PKCS#10 CSR file. A single domain may be set as _Common Name
 
 CSR files can be generated with command line tools like `openssl`. Unfortunately the standard Java does not offer classes for that, so you'd have to resort to [Bouncy Castle](http://www.bouncycastle.org/java.html) if you want to create a CSR programmatically. In the `acme4j-utils` module, there is also a [`CSRBuilder`](../apidocs/org/shredzone/acme4j/util/CSRBuilder.html) for your convenience. You can also use [`KeyPairUtils`](../apidocs/org/shredzone/acme4j/util/KeyPairUtils.html) for generating the domain key pair.
 
+Do not just use your account key pair as domain key pair, but generate a separate pair of keys!
+
 ```java
 KeyPair domainKeyPair = ... // KeyPair to be used for HTTPS encryption
 
 CSRBuilder csrb = new CSRBuilder();
 csrb.addDomain("example.org");
-csrb.addDomain("www.example.org");
 csrb.setOrganization("The Example Organization")
 csrb.sign(domainKeyPair);
 byte[] csr = csrb.getEncoded();
@@ -35,6 +36,33 @@ X509Certificate cert = client.downloadCertificate(certUri);
 
 Congratulations! You have just created your first certificate via _acme4j_.
 
+### Multiple Domains
+
+The example above generates a certificate per domain. However, you would usually prefer to use a single certificate for multiple domains (for example, the domain itself and the `www.` subdomain).
+
+You first need to [authorize](./authorization.html) each (sub)domain separately.
+
+After all the domains are authorized, generate a single CSR with all the domains provided as _Subject Alternative Name_ (SAN). If you use the `CSRBuilder`, just add all of the domains to the builder:
+
+```java
+KeyPair domainKeyPair = ... // KeyPair to be used for HTTPS encryption
+
+CSRBuilder csrb = new CSRBuilder();
+csrb.addDomain("example.org");
+csrb.addDomain("www.example.org");
+csrb.addDomain("m.example.org");
+// add more domains if required...
+
+csrb.sign(domainKeyPair);
+byte[] csr = csrb.getEncoded();
+```
+
+The generated certificate will be valid for all of the domains.
+
+Note that wildcard certificates are currently not supported by the ACME protocol.
+
+The number of domains per certificate may also be limited (_Let's Encrypt_ currently has a limit of 100 SANs per certificate).
+
 ## Renewal
 
 Renewing your certificate depends on the CA. Some may require you to go through the authorization process again, while others may just provide an updated certificate for download at the `certUri` above.
@@ -56,4 +84,4 @@ X509Certificate cert = ... // certificate to be revoked
 client.revokeCertificate(new Registration(domainKeyPair), cert);
 ```
 
-If you have the choice, you should always prefer to use your account key.
+If you have the choice, you should always prefer to use your account key. In a future version of _acme4j_, this hack might stop working.