github
/
acme4j
mirror of https://github.com/shred/acme4j
1
0
Fork 0
Code Issues Releases Wiki Activity

Document request of multiple domains (SAN) per certificate

pull/17/merge
Richard Körber 2016-02-21 12:29:41 +01:00
parent 9afaed1fb4
commit 37352c96a8
1 changed files with 30 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
src/site/markdown/usage/certificate.md
View File

@ -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.