README.md in acme-client-2.0.0 vs README.md in acme-client-2.0.1
- old
+ new
@@ -39,11 +39,11 @@
The client is initialized with a private key and the directory of your ACME provider.
LetsEncrypt's `directory` is `https://acme-v02.api.letsencrypt.org/directory`.
-They also have a staging enpoind at `https://acme-staging-v02.api.letsencrypt.org/directory`.
+They also have a staging endpoint at `https://acme-staging-v02.api.letsencrypt.org/directory`.
`acme-ruby` expects `OpenSSL::PKey::RSA` or `OpenSSL::PKey::EC`
You can generate one in Ruby using OpenSSL.
@@ -87,18 +87,28 @@
client = Acme::Client.new(private_key: private_key, directory: 'https://acme-staging-v02.api.letsencrypt.org/directory')
account = client.new_account(contact: 'mailto:info@example.com', terms_of_service_agreed: true)
account.kid # => <kid string>
```
+If you already have an existing account (for example one created in ACME v1) please note that unless the `kid` is provided at initialization, the client will lazy load the `kid` by doing a `POST` to `newAccount` whenever the `kid` is required. Therefore, you can easily get your `kid` for an existing account and (if needed) store it for reuse:
+
+```
+client = Acme::Client.new(private_key: private_key, directory: 'https://acme-staging-v02.api.letsencrypt.org/directory')
+
+# kid is not set, therefore a call to newAccount is made to lazy-initialize the kid
+client.kid
+=> "https://acme-staging-v02.api.letsencrypt.org/acme/acct/000000"
+```
+
## Obtaining a certificate
### Ordering a certificate
To order a new certificate, the client must provide a list of identifiers.
The returned order will contain a list of `Authorization` that need to be completed in other to finalize the order, generally one per identifier.
-Each authorization contains multiple challenges, typically a `dns-01` and a `http-01` challenge. The applicant is only required to complete one the challenges.
+Each authorization contains multiple challenges, typically a `dns-01` and a `http-01` challenge. The applicant is only required to complete one of the challenges.
You can access the challenge you wish to complete using the `#dns` or `#http` method.
```ruby
order = client.new_order(identifiers: ['example.com'])
@@ -149,11 +159,11 @@
challenge.request_validation
```
The validation is performed asynchronously and can take some time to be performed by the server.
-You can poll until its status change.
+You can poll until its status changes.
```ruby
while challenge.status == 'pending'
sleep(2)
challenge.reload
@@ -163,15 +173,15 @@
### Downloading a certificate
Once all required authorizations have been validated through challenges, the order can be finalized using a CSR ([Certificate Signing Request](https://en.wikipedia.org/wiki/Certificate_signing_request)).
-A CSR can be slightly tricky to generate using OpenSSL from Ruby standard library. `acme-client` provide a utility class `CertificateRequest` to help with that.
+A CSR can be slightly tricky to generate using OpenSSL from Ruby standard library. `acme-client` provide a utility class `CertificateRequest` to help with that. You'll need to use a different private key for the certificate request than the one you use for your `Acme::Client` account.
Certificate generation happens asynchronously. You may need to poll.
```ruby
-csr = Acme::Client::CertificateRequest.new(private_key: private_key, subject: { common_name: 'example.com' })
+csr = Acme::Client::CertificateRequest.new(private_key: a_different_private_key, subject: { common_name: 'example.com' })
order.finalize(csr: csr)
sleep(1) while order.status == 'processing'
order.certificate # => PEM-formatted certificate
```