From bc0338bcabbd46d3ad3d2d92fdec6d8d04b1db16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Richard=20K=C3=B6rber?= Date: Thu, 21 Jul 2016 00:59:20 +0200 Subject: [PATCH] Review documentation --- README.md | 1 + .../shredzone/acme4j/util/CertificateUtilsTest.java | 4 ++-- src/site/markdown/index.md.vm | 4 ++-- src/site/markdown/migration.md | 4 ++-- src/site/markdown/usage/authorization.md | 11 ++++------- src/site/markdown/usage/index.md | 2 +- src/site/markdown/usage/session.md | 2 +- 7 files changed, 13 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index d3efc4cd..0eb6f4e8 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ It is an independent open source implementation that is not affiliated with or e ## Features +* Supports ACME protocol up to [draft 02](https://tools.ietf.org/html/draft-ietf-acme-acme-02) * Easy to use Java API * Requires JRE 7 or higher * Built with maven, packages available at [Maven Central](http://search.maven.org/#search|ga|1|g%3A%22org.shredzone.acme4j%22) diff --git a/acme4j-utils/src/test/java/org/shredzone/acme4j/util/CertificateUtilsTest.java b/acme4j-utils/src/test/java/org/shredzone/acme4j/util/CertificateUtilsTest.java index a0b84128..90924924 100644 --- a/acme4j-utils/src/test/java/org/shredzone/acme4j/util/CertificateUtilsTest.java +++ b/acme4j-utils/src/test/java/org/shredzone/acme4j/util/CertificateUtilsTest.java @@ -110,8 +110,8 @@ public class CertificateUtilsTest { } /** - * Test if {@link CertificateUtils#createTlsSni02Certificate(KeyPair, String)} creates - * a good certificate. + * Test if {@link CertificateUtils#createTlsSni02Certificate(KeyPair, String, String)} + * creates a good certificate. */ @Test public void testCreateTlsSni02Certificate() throws IOException, CertificateParsingException { diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm index d169d1ea..4e94f5c1 100644 --- a/src/site/markdown/index.md.vm +++ b/src/site/markdown/index.md.vm @@ -1,11 +1,11 @@ acme4j ====== -A Java client for the [Automatic Certificate Management Environment (ACME)](https://tools.ietf.org/html/draft-ietf-acme-acme-01) protocol. +A Java client for the _Automatic Certificate Management Environment_ (ACME) protocol. ACME is a protocol that a certificate authority (CA) and an applicant can use to automate the process of verification and certificate issuance. -This Java client helps connecting to an ACME server, and performing all necessary steps to manage certificates. +This Java client helps connecting to an ACME server, and performing all necessary steps to manage certificates. It supports the ACME protocol up to [draft 02](https://tools.ietf.org/html/draft-ietf-acme-acme-02). It is an independent open source implementation that is not affiliated with or endorsed by _Let's Encrypt_. diff --git a/src/site/markdown/migration.md b/src/site/markdown/migration.md index 3bdb3969..1aca579b 100644 --- a/src/site/markdown/migration.md +++ b/src/site/markdown/migration.md @@ -1,6 +1,6 @@ # Migration Guide -With version 0.6, _acme4j_ underwent a massive change to the API. +With version 0.6, _acme4j_ underwent a major change to the API. This document will help you migrate your code to the latest API when coming from a pre-0.6 release. It should be a matter of a few minutes in most cases. @@ -91,7 +91,7 @@ In previous versions, _acme4j_ used a client centric approach, with dumb data tr This approach turned out to have major disadvantages. For example, the data transport classes contained setter methods that were supposed to be used only by _acme4j_ itself. Some other setters had to be used by the library user, but only under certain circumstances. To make a long story short: The API was not self-explanatory about when to use what setters. -Also, the old API was too limited to reflect coming features of the ACME specifications. `AcmeClient` would soon become a bottleneck. +Also, the old API was too limited to reflect some features of the ACME specifications. `AcmeClient` would have become a bottleneck. As _acme4j_ is still in beta state, I prefered to make a hard cut and do a major API makeover. Trying to maintain backward compatibility by all means would end up with an overly complicated library. diff --git a/src/site/markdown/usage/authorization.md b/src/site/markdown/usage/authorization.md index 58b9edad..2a0e25d7 100644 --- a/src/site/markdown/usage/authorization.md +++ b/src/site/markdown/usage/authorization.md @@ -19,7 +19,7 @@ Collection combination = auth.findCombination( Http01Challenge.TYPE, Dns01Challenge.TYPE); ``` -The returned `combination` contains a single combination of challenges you would have to perform. If the combination consists of more than one challenge, you would have to perform _all of them_ in order to successfully authorize your domain. If `null` is returned, it means that none of your offered challenge types are acceptable to the CA. +The returned `combination` contains a single combination of challenges you would have to perform. If the combination consists of more than one challenge, you will have to perform _all of them_ in order to successfully authorize your domain. If `null` is returned, it means that none of your offered challenge types are acceptable to the CA. If your software only implements a single challenge type, `findChallenge()` may be a little easier to use: @@ -56,20 +56,17 @@ If your final certificate will contain further domains or subdomains, repeat the ## Update an Authorization -For an existing Authorization object, you can always invoke `update()` to read the current server state. - -The server also provides an authorization URI. It can be retrieved from `Authorization.getLocation()`. You can recreate the `Authorization` object at a later time just by binding it to your `Session` and invoking `update()`: +The server also provides an authorization URI. It can be retrieved from `Authorization.getLocation()`. You can recreate the `Authorization` object at a later time just by binding it to your `Session`: ```java URI authUri = ... // Authorization URI Authorization auth = Authorization.bind(session, authUri); -auth.update(); ``` -After invoking `update()`, the `Authorization` object contains the current server state about your authorization, including the domain name, the overall status, and an expiry date. +As soon as you invoke a getter, the `Authorization` object lazily loads the current server state of your authorization, including the domain name, the overall status, and an expiry date. -`update()` may throw an `AcmeRetryAfterException`, giving an estimated time in `getRetryAfter()` for when all challenges are completed. You should then wait until that moment has been reached, before trying again. The authorization state is still updated when this exception is thrown. +You can always invoke `update()` to read the current server state again. It may throw an `AcmeRetryAfterException`, giving an estimated time in `getRetryAfter()` for when all challenges are completed. The authorization state is still updated even when this exception is thrown. If you invoke `update()` for polling the authorization state, you should wait until the moment given in the exception has been reached before trying again. ## Deactivate an Authorization diff --git a/src/site/markdown/usage/index.md b/src/site/markdown/usage/index.md index fe7ef102..e1c8d8c9 100644 --- a/src/site/markdown/usage/index.md +++ b/src/site/markdown/usage/index.md @@ -16,7 +16,7 @@ You can also create an elliptic curve key pair: KeyPair keyPair = KeyPairUtils.createECKeyPair("secp256r1"); ``` -> **CAUTION**: Your KeyPair is the only key to your account. If you should lose it, you will be locked out from your account and certificates. The API does currently not offer a way to regain access after a key loss. The only way is to contact the CA and ask for assistance. **It is strongly recommended to keep your key pair in a safe place!** +> **CAUTION**: Your KeyPair is the only key to your account. If you should lose it, you will be locked out from your account and certificates. The API does currently not offer a way to recover access after a key loss. The only way is to contact the CA and ask for assistance. **It is strongly recommended to keep your key pair in a safe place!** To save a `KeyPair` (actually, the private key of the key pair) to a pem file, use this snippet: diff --git a/src/site/markdown/usage/session.md b/src/site/markdown/usage/session.md index 7f590d3c..db415b35 100644 --- a/src/site/markdown/usage/session.md +++ b/src/site/markdown/usage/session.md @@ -18,7 +18,7 @@ Session session = new Session("https://acme-staging.api.letsencrypt.org/directory", keyPair); ``` -However, such an URI is hard to remember and might even change in the future. Java also does not accept the certificate used by the _Let's Encrypt_ server, so calls to their servers are likely to throw a certificate exception. +However, such an URI is hard to remember and might even change in the future. Also, Java accepts the certificate used by the _Let's Encrypt_ server since JDK 8u101, calls to their servers are likely to throw a certificate exception on older versions. For this reason, special ACME URIs should be preferred: