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 ```