Skip to content

Quick Start

Jump to bottom Edit New page
Michael edited this page Nov 14, 2018 · 33 revisions

WIP

TODO: Provide a quick tutorial-by-example of how to start using ACMESharp quickly...

The NEW Quick Start for version 0.9.0 can be found here.

(1) ACMESharp Installation

  • First, make sure the ACMESharp PowerShell module is installed.
    • The easiest way for you to get started with the PowerShell module for ACMESharp is to:
      • Install from the PowerShell Gallery
        • Starting with ACMESharp 0.8.2, the Gallery is the preferred method of installation
        • Support for PowerShell Gallery is built-in to PowerShell v5
        • Support for PowerShell Gallery is available for PowerShell v3 and v4 as an add-on from the home page
      • Install from Chocolatey starting with version 0.8.2, the chocolatey packages are no longer being updated -- please use the PS Gallery method
    • If you install from either of those two sources, then they'll install the module into your local PowerShell modules path (either global if you run as Administrator or user-specific if you don't).
    • If you can't or don't use one of the methods above, you can do a "manual" installation by grabbing the latest release of the ACMESharp-posh.zip file and extracting it to one of your PowerShell module paths yourself.

NOTE For PowerShell v5+ users: in PowerShell v5 a new cmdlet Get-Certificate was introduced in the system provided PKI module. You may get an error when you try to install or load the ACMESharp module that the command already exists and you have to specify the -AllowClobber parameter to continue.

In reality this error is safe to ignore because the ACMESharp module defines a DefaultCommandPrefix that is automatically added to every cmdlet when the module is loaded by default. So for example, the ACMESharp version of this cmdlet will be loaded as Get-ACMECertificate. So you can safely bypass this error by specifying the -AllowClobber switch. If you want to be extra careful, you can specify the -Prefix ACME parameter and value to the Import-Module cmdlet when loading the module.

  • Next, make sure the ACMESharp PowerShell module is loaded.
PS> Import-Module ACMESharp

(2) Vault Initialization

  • Start by initializing a Vault to store your Certificates and related artifacts.
    • Note, if you run as Administrator, your Vault will be created in a system-wide path, otherwise it will be created in a private, user-specific location.
PS> Initialize-ACMEVault

(3) Create a new Registration

  • Register yourself with the Let's Encrypt CA:
    • Provide a method of contact, e.g. an email (note, LE does not support the tel: contact method)
    • Accept their Terms-of-Service (TOS).
PS> New-ACMERegistration -Contacts mailto:somebody@example.org -AcceptTos

(4) Submit a new Domain Identifier

  • Submit a DNS domain name that you want to secure with a PKI certificate.
PS> New-ACMEIdentifier -Dns myserver.example.com -Alias dns1

(5) Handle the Challenge to Prove Domain Ownership

The LE server will respond with one or more Challenges that you need to complete in order to prove that you are the owner and operator of the DNS domain name you submitted. This is where you have to make some choices.

You can do this either by managing DNS records under this domain name, or by serving up HTTP content from a Web server that this domain name points to.

  • If you want to handle the HTTP Challenge using Windows IIS, use Method #1.
  • If you want to handle the HTTP Challenge manually, use Method #2.
  • If you want to handle the DNS Challenge manually, use Method #3

Method #1 - Handling the HTTP Challenge using IIS

If you are on a Web server that answers to this domain name, and you are running Windows IIS 7.0 or greater, you can use IIS to serve content that will prove domain ownership and control. Use the following cmdlet, substituting the name of the IIS Web Site that handle HTTP traffic for the DNS name you're serving up.

PS> Complete-ACMEChallenge dns1 -ChallengeType http-01 -Handler iis -HandlerParameters @{ WebSiteRef = 'Default Web Site' }

Method #2 - Handling the HTTP Challenge Manually

If you want to handle the HTTP Challenge manually, use the following cmdlet and to print out the necessary instructions that you need to follow on your Web server of choice. Implement the steps described in the instructions before moving on to the next step.

PS> (Complete-ACMEChallenge dns1 -ChallengeType http-01 -Handler manual).Challenge
== Manual Challenge Handler - HTTP ==
  * Handle Time:      [1/12/2016 1:16:34 PM]
  * Challenge Token:  [2yRd04TwqiZTh6TWLZ1azL15QIOGaiRmx8MjAoA5QH0]
To complete this Challenge please create a new file
under the server that is responding to the hostname
and path given with the following characteristics:
  * HTTP URL:     [http://myserver.example.com/.well-known/acme-challenge/2yRd04TwqiZTh6TWLZ1azL15QIOGaiRmx8MjAoA5QH0]
  * File Path:    [.well-known/acme-challenge/2yRd04TwqiZTh6TWLZ1azL15QIOGaiRmx8MjAoA5QH0]
  * File Content: [2yRd04TwqiZTh6TWLZ1azL15QIOGaiRmx8MjAoA5QH0.H3URk7qFUvhyYzqJySfc9eM25RTDN7bN4pwil37Rgms]
  * MIME Type:    [text/plain]
------------------------------------

Note: If you do not get the challenge details like file path and content in the output, you can always run step 6(b) i.e. Update-ACMEIdentifier to get the details:

PS> (Update-ACMEIdentifier dns1 -ChallengeType http-01).Challenges | Where-Object {$_.Type -eq "http-01"}
...
Status         : pending
...

Tip: In Windows you can add a directory with leading dot, by also adding a trailing dot when you create the directory. Windows will create the directory with the leading dot and delete the trailing dot automatically. For instance, to create the ".well-known" directory in Windows File Explorer, create a new directory named, ".well-known." and Windows will handle the rest.

Note: To allow IIS to serve an extensionless file, add a web.config to the "/.well-known/acme-challenge" directory with the following contents...

<?xml version="1.0" encoding="UTF-8"?>
 <configuration>
     <system.webServer>
         <staticContent>
             <mimeMap fileExtension="." mimeType="text/plain" />
         </staticContent>
     </system.webServer>
 </configuration>

Before you move to the next step, test the "Http URL" specified in the results of the Complete-ACMEChallenge command, to make sure the contents of the challenge file are rendered in your browser. If IIS isn't returning the contents of that file, then the next step will fail and you will have to go back to step 4 and submit a new Domain Identifier with a different alias before you will be successful.

Method #3 - Handling the DNS Challenge Manually

If you want to handle the DNS Challenge manually, use the following cmdlet and to print out the necessary instructions that you need to follow on your DNS server/service of choice. Implement the steps described in the instructions before moving on to the next step.

PS> Complete-ACMEChallenge dns1 -ChallengeType dns-01 -Handler manual
== Manual Challenge Handler - DNS ==
  * Handle Time:      [1/12/2016 1:41:51 PM]
  * Challenge Token:  [xfc0oQahXVqdaBlcZbk5nL8H-GSDFCoQ8LGzOL07qVI]
To complete this Challenge please create a new Resource
Record (RR) with the following characteristics:
  * RR Type:  [TXT]
  * RR Name:  [_acme-challenge.example.com]
  * RR Value: [vNx_fpLgvq0l4rqSATuxhxl9pa155SoeKvNZ98AFB_4]
------------------------------------

Note: If you do not get the challenge details like file path and content in the output, you can always run step 6(b) i.e. Update-ACMEIdentifier to get the details:

PS> (Update-ACMEIdentifier dns1 -ChallengeType dns-01).Challenges | Where-Object {$_.Type -eq "dns-01"}
...
Status         : pending
...

(6) Submit the Challenge Response to Prove Domain Ownership

Once you have handled the Challenge using one of the methods in Step #5, you need to let the LE server know so that it can perform a verification. Depending on which Challenge Type you handled, you need to issue one of these commands to submit your Challenge response.

  • If you handled an HTTP Challenge, use this cmdlet:
PS> Submit-ACMEChallenge dns1 -ChallengeType http-01
  • If you handled a DNS Challenge, use this cmdlet:
PS> Submit-ACMEChallenge dns1 -ChallengeType dns-01

Note, the LE server will accept your submission, but performs the validation asynchronously. So you will not get an immediate response as to the status of the submission.

(6b) Check the Status of the Challenge

Once the Challenge response is submitted, the validation usually takes anywhere from seconds to minutes to perform. You can perform a check to the status of the validation using one of the following commands.

  • If you submitted an HTTP Challenge response, use this cmdlet:
PS> (Update-ACMEIdentifier dns1 -ChallengeType http-01).Challenges | Where-Object {$_.Type -eq "http-01"}
...
Status         : pending
...
  • If you submitted an DNS Challenge response, use this cmdlet:
PS> (Update-ACMEIdentifier dns1 -ChallengeType dns-01).Challenges | Where-Object {$_.Type -eq "dns-01"}
...
Status         : pending
...
  • Until the Challenge has been verified, you should see a status of pending.
  • If the Challenge fails for any reason you will see a status of invalid. At this point, you cannot re-attempt the same exact Challenge without first Submitting a new DNS Identifier (Step #4).
  • If the Challenge is successful, you will see a status of valid.

Once the Challenge has been successfully validated, you can check the overall status of the Domain Identifier, which should be valid as well.

PS> Update-ACMEIdentifier dns1
...
Status         : valid
...

(7) Request and Retrieve the Certificate

After you have proved your ownership of the domain name you wish to secure, you can create a new PKI certificate request, and then submit it for issuance by the LE CA.

PS> New-ACMECertificate dns1 -Generate -Alias cert1
PS> Submit-ACMECertificate cert1
Subject Alternative Names (SAN)
If you want to generate a CSR that lists multiple names, you can use the Subject Alternative Names extension of the PKI certificate request to list multiple additional names other than the primary Subject Name. To do so you specify the -AlternativeIdentifierRefs option with a list of one or more additional Identifier references. Each Identifier reference listed should be validated as outlined in steps 4, 5 and 6. 
PS> New-ACMECertificate dns1 -Generate -AlternativeIdentifierRefs dns2,dns3,dns4 -Alias multiNameCert
PS> Submit-ACMECertificate multiNameCert

The LE CA may be able to issue the certificate immediately, in which case ACMESharp will retrieve it and store it in the Vault immediately. But this is not always possible, and so the response you see will contain missing elements for certificate's serial number if the certificate was not issued immediately.

Id                  : 8e38e529-55e2-4096-afb8-4f9947d6da6d
Alias               : cert1
Label               :
Memo                :
IdentifierRef       : 198488a7-c778-488c-978b-606a0181deb9
KeyPemFile          :
CsrPemFile          :
GenerateDetailsFile : 8e38e529-55e2-4096-afb8-4f9947d6da6d-gen.json
CertificateRequest  :
CrtPemFile          :
CrtDerFile          :
IssuerSerialNumber  :
SerialNumber        :
Thumbprint          :
Signature           :
SignatureAlgorithm  :

If the certificate could not be issued immediately, you will need to check on the status of the certificate until it has been issued. Once the certificate is issued, ACMESharp will retrieve it and store it in the Vault.

PS> Update-ACMECertificate cert1
Id                  : 9182eb22-cd57-468e-946e-e0b0d8843906
Alias               : cert1
Label               :
Memo                :
IdentifierRef       : 198488a7-c778-488c-978b-606a0181deb9
KeyPemFile          : 9182eb22-cd57-468e-946e-e0b0d8843906-key.pem
CsrPemFile          : 9182eb22-cd57-468e-946e-e0b0d8843906-csr.pem
GenerateDetailsFile : 9182eb22-cd57-468e-946e-e0b0d8843906-gen.json
CertificateRequest  : ACMESharp.CertificateRequest
CrtPemFile          : 9182eb22-cd57-468e-946e-e0b0d8843906-crt.pem
CrtDerFile          : 9182eb22-cd57-468e-946e-e0b0d8843906-crt.der
IssuerSerialNumber  :
SerialNumber        : 00FAFC7F409C770B76EB9BA7445EC27B24494A
Thumbprint          : 9A59B855EA79B3E9DE1C14307E6A21851B3C0CE8
Signature           : 9A59B855EA79B3E9DE1C14307E6A21851B3C0CE8
SignatureAlgorithm  : sha256RSA

(8) Install the Certificate

The final step is to install the issued certificate somewhere, whether it's on a local IIS Web Site, a remote Apache server, or an AWS ELB service endpoint.

ACMESharp will eventually implement a number of Installers to help simplify this process, but at the time of this writing, no Installers are implemented. You can however, export the certificate and related assets and then manually install them in whatever target server or service you wish.

Export Private Key

You can export the private key in PEM format:

PS> Get-ACMECertificate cert1 -ExportKeyPEM "path\to\cert1.key.pem"

Export CSR

You can export the Certificate Signing Request (CSR) in PEM format:

PS> Get-ACMECertificate cert1 -ExportCsrPEM "path\to\cert1.csr.pem"

Export Certificate Issued By LE

You can export your public certificate that was signed and issued by the Let's Encrypt CA in PEM or DER format.

PS> Get-ACMECertificate cert1 -ExportCertificatePEM "path\to\cert1.crt.pem" -ExportCertificateDER "path\to\cert1.crt"

Export Issuer Certificate

You can export the public certificate of the issuer, that is, the CA's signing intermediary certificate.

PS> Get-ACMECertificate cert1 -ExportIssuerPEM "path\to\cert1-issuer.crt.pem" -ExportIssuerDER "path\to\cert1-issuer.crt"

Note, if you get the error 'no issuer certificates found' you need to install them. This needs to be done only once on your machine. This can be done with:

Update-ACMECertificate cert1

Export PKCS#12 (PFX) Archive

You can export the certificate and related assets in PKCS#12 archive (.PFX used by Windows and IIS):

PS> Get-ACMECertificate cert1 -ExportPkcs12 "path\to\cert1.pfx"
PS> Get-ACMECertificate cert1 -ExportPkcs12 "path\to\cert1.pfx" -CertificatePassword 'g1Bb3Ri$h'
Add a custom footer

Home

Docs

Legacy Docs - out of date

Reference

A bit dated

Clone this wiki locally