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

Minor documentation updates

pull/140/head
Richard Körber 2023-07-21 15:01:51 +02:00
parent a648a513f6
commit 79c2ab7688
No known key found for this signature in database
GPG Key ID: AAB9FD19C78AA3E0
4 changed files with 37 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
acme4j-client/src/main/java/org/shredzone/acme4j/AccountBuilder.java
View File

@ -48,6 +48,10 @@ import org.slf4j.LoggerFactory;
* <li>You might need to provide a key identifier (e.g. your customer number) and
* a shared secret via {@link #withKeyIdentifier(String, SecretKey)}.</li>
* </ul>
* <p>
* It is not possible to modify an existing account with the {@link AccountBuilder}. To
* modify an existing account, use {@link Account#modify()} and
* {@link Account#changeKey(KeyPair)}.
*/
public class AccountBuilder {
private static final Logger LOG = LoggerFactory.getLogger(AccountBuilder.class);

48
src/doc/docs/example.md
View File

@ -14,6 +14,8 @@ This chapter contains a copy of the class file, along with explanations about wh
- I recommend to read at least the chapters about [usage](usage/index.md) and [challenges](challenge/index.md), to learn more about how _acme4j_ and the ACME protocol works.
- To make the example easier to understand, I will use the specific datatypes instead of the `var` keyword.
## Running the Example
You can run the `ClientTest` class in your IDE, giving the domain names to be registered as parameters. When changing into the `acme4j-example` directory, the test client can also be invoked via maven in a command line:
@ -82,19 +84,8 @@ public void fetchCertificate(Collection<String> domains)
authorize(auth);
}
// Generate a CSR for all of the domains,
// and sign it with the domain key pair.
CSRBuilder csrb = new CSRBuilder();
csrb.addDomains(domains);
csrb.sign(domainKeyPair);
// Write the CSR to a file, for later use.
try (Writer out = new FileWriter(DOMAIN_CSR_FILE)) {
csrb.write(out);
}
// Order the certificate
order.execute(csrb.getEncoded());
order.execute(domainKeyPair);
// Wait for the order to complete
try {
@ -102,7 +93,10 @@ public void fetchCertificate(Collection<String> domains)
while (order.getStatus() != Status.VALID && attempts-- > 0) {
// Did the order fail?
if (order.getStatus() == Status.INVALID) {
LOG.error("Order has failed, reason: {}", order.getError());
LOG.error("Order has failed, reason: {}", order.getError()
.map(Problem::toString)
.orElse("unknown")
);
throw new AcmeException("Order failed... Giving up.");
}
@ -197,9 +191,9 @@ If your `KeyPair` has already been registered with the CA, no new account will b
```java
private Account findOrRegisterAccount(Session session, KeyPair accountKey) throws AcmeException {
// Ask the user to accept the TOS, if server provides us with a link.
URI tos = session.getMetadata().getTermsOfService();
if (tos != null) {
acceptAgreement(tos);
Optional<URI> tos = session.getMetadata().getTermsOfService();
if (tos.isPresent()) {
acceptAgreement(tos.get());
}
Account account = new AccountBuilder()
@ -261,7 +255,10 @@ private void authorize(Authorization auth)
while (challenge.getStatus() != Status.VALID && attempts-- > 0) {
// Did the authorization fail?
if (challenge.getStatus() == Status.INVALID) {
LOG.error("Challenge has failed, reason: {}", challenge.getError());
LOG.error("Challenge has failed, reason: {}", challenge.getError()
.map(Problem::toString)
.orElse("unknown")
);
throw new AcmeException("Challenge failed... Giving up.");
}
@ -299,10 +296,9 @@ When the authorization process is completed, the file is not used any more and c
```java
public Challenge httpChallenge(Authorization auth) throws AcmeException {
// Find a single http-01 challenge
Http01Challenge challenge = auth.findChallenge(Http01Challenge.class);
if (challenge == null) {
throw new AcmeException("Found no " + Http01Challenge.TYPE + " challenge, don't know what to do...");
}
Http01Challenge challenge = auth.findChallenge(Http01Challenge.class)
.orElseThrow(() -> new AcmeException("Found no " + Http01Challenge.TYPE
+ " challenge, don't know what to do..."));
// Output the challenge, wait for acknowledge...
LOG.info("Please create a file in your web server's base directory.");
@ -341,10 +337,10 @@ When the authorization has been completed, the `TXT` record can be safely remove
```java
public Challenge dnsChallenge(Authorization auth) throws AcmeException {
// Find a single dns-01 challenge
Dns01Challenge challenge = auth.findChallenge(Dns01Challenge.TYPE);
if (challenge == null) {
throw new AcmeException("Found no " + Dns01Challenge.TYPE + " challenge, don't know what to do...");
}
Dns01Challenge challenge = auth.findChallenge(Dns01Challenge.TYPE)
.map(Dns01Challenge.class::cast)
.orElseThrow(() -> new AcmeException("Found no " + Dns01Challenge.TYPE
+ " challenge, don't know what to do..."));
// Output the challenge, wait for acknowledge...
LOG.info("Please create a TXT record:");
@ -384,7 +380,7 @@ public void acceptChallenge(String message) throws AcmeException {
}
}
public void completeChallenge(String message) throws AcmeException {
public void completeChallenge(String message) {
JOptionPane.showMessageDialog(null,
message,
"Complete Challenge",

13
src/doc/docs/migration.md
View File

@ -4,18 +4,21 @@ This document will help you migrate your code to the latest _acme4j_ version.
## Migration to Version 3.0.0
- The `acme4j-utils` module has been removed, and its classes moved into `acme4j-client` module. If you have used it before, just remove the dependency. If your project has a `module-info.java` file, remember to remove the `requires org.shredzone.acme4j.utils` line there as well. If you haven't used the module before: `acme4j-client` now depends on Bouncy Castle, so you might need to register it as security provider at the start of your code:
Although acme4j has made a major version bump, the migration of your code should be done in a few minutes for most of you.
- The `acme4j-utils` module has been removed, and its classes moved into `acme4j-client` module. If you have used it before, just remove the dependency. If your project has a `module-info.java` file, remember to remove the `requires org.shredzone.acme4j.utils` line there as well.
- All `@Nullable` return values have been removed where possible. Returned collections may now be empty, but are never `null`. Most of the other return values are now either `Optional`, or are throwing an exception if more reasonable. If your code fails to compile because the return type has changed to `Optional`, you could simply add `.orElse(null)` to emulate the old behavior. But often your code will reveal a better way to handle the former `null` pointer instead.
- `acme4j-client` now depends on Bouncy Castle, so you might need to register it as security provider at the start of your code:
```java
Security.addProvider(new BouncyCastleProvider());
```
- All `@Nullable` return values have been reviewed. Collections may now be empty, but never `null`. Most of the other return values are now either `Optional`, or throwing an exception if more reasonable. If your code fails to compile because the return type has changed to `Optional`, you can simply add `.orElse(null)` to restore the old behavior. But often your code will reveal a better way to handle the former `null` pointer instead.
What you might also need to know:
- A new `AcmeNotSupportedException` is thrown if a feature is not supported by the server. It is a subclass of the `AcmeProtocolException` runtime exception.
- Starting with _acme4j_ v3, we will require the smallest Java SE LTS version that is still receiving premier support according to the [Oracle Java SE Support Roadmap](https://www.oracle.com/java/technologies/java-se-support-roadmap.html). At the moment of writing, these are Java 11 and Java 17, so _acme4j_ requires Java 11 starting from now. With the prospected release of Java 21 (LTS) in September 2023, we will start to require Java 17, and so on. If you still need Java 8, you can use _acme4j_ v2, which will receive bugfixes until September 2023.
- Changed to `java.net.http` client. Due to limitations of the API, HTTP errors are only thrown with the error code, but not with the error message. If you checked the message in unit tests, be prepared that the error message might have changed.
- acme4j now accepts HTTP gzip compression. It is enabled by default, but can be disabled in the `NetworkSettings` if it causes problems or impedes debugging.
- Starting with _acme4j_ v3, we will require the smallest Java SE LTS version that is still receiving premier support according to the [Oracle Java SE Support Roadmap](https://www.oracle.com/java/technologies/java-se-support-roadmap.html). At the time of writing, these are Java 11 and Java 17, so _acme4j_ requires Java 11 starting from now. With the prospected release of Java 21 (LTS) in September 2023, we will start to require Java 17, and so on. If you still need Java 8, you can use _acme4j_ v2, which will still receive security bugfixes until end of 2023.
- _acme4j_ now uses the new `java.net.http` client. Due to limitations of the API, HTTP errors are only thrown with the error code, but the respective error message is missing. If you checked the error message in your unit tests, be prepared that they might fail now.
- acme4j now accepts HTTP gzip compression. It is enabled by default, but can be disabled in the `NetworkSettings` if it should cause problems or impedes debugging.
- All deprecated methods have been removed.
## Migration to Version 2.16

3
src/doc/docs/usage/account.md
View File

@ -98,6 +98,9 @@ account.modify()
You can also get the list of contacts via` getContacts()`, and modify or remove contact `URI`s there. However, some CAs do not allow to remove all contacts.
!!! note
`AccountBuilder` only accepts contact addresses when a _new account_ is created. To modify an existing account, use `Account.modify()` as described in this section.
## Account Key Roll-Over
It is also possible to change the key pair that is associated with your account, for example if you suspect that your key has been compromised.