[WIP] Quick Start

NOTE: This documentation applies to ACMESharp version 0.9.0 and later

This document outlines the basic steps to get up and running quickly with the ACMESharp PowerShell client. This is for users that want to generate and install PKI certificates, for example, from the Let's Encrypt CA project.

This document will show these basic steps to get up and running:

1. Install ACMESharp - installing the ACMESharp PowerShell client
2. Initialize Vault - initializing a local Vault to store generated assets
3. Register Account - register a new ACME account
4. Validate Identifiers - prove you control one or more DNS domains
5. Generate Certificate - request and retrieve a PKI certificate
6. Install Certificate - install the PKI certificate to a server or service

Quick Start Scenario

Because there are many variations for each of the steps outlined above depending on your particular use case, we will define a fairly common scenario as an example to follow in this guide. Within each section corresponding to the steps above, we will link to more detailed instructions that describe other options that may suit your needs better.

The scenario that we will follow in this Quick Start guide will be as follows:

• You are an Administrator with elevated privileges on a Windows Server
• You have IIS running on the local server and you want to obtain and install a PKI certificate
• Your IIS is accessible publicly on the Internet at the following DNS addresses:
  • www.example.com
  • www.example.net
  • example.com
• Your IIS site is named MyExampleSite
• Your IIS site is listening on port 80
• You want to obtain a free certificate from the Let's Encrypt CA server.
• You want the certificate to identify www.example.com as the primary DNS name of your server, but also allow all the other names as alternatives.
• You want to install the free certificate into your IIS site and enable HTTPS traffic over the standard port (443).

Let's begin...

Step 1: Install ACMESharp

The ACMESharp PowerShell client is published to the PowerShell Gallery as a set of PowerShell Modules. This is the official way that the client is distributed, and it's also the easiest way to install it.

In order to install ACMESharp from the Gallery, you need to have support for PowerShellGet in your PowerShell environment. Since PowerShell v5, this is included by default. If you are using an earlier version of PowerShell, you can install support separately for v3 and v4.

We will need to install two (2) PowerShell modules from the Gallery:

• ACMESharp core module
• ACMESharp Provider Extension for IIS

In an elevated PowerShell prompt, execute:

Admin PS> Install-Module -Name ACMESharp -AllowClobber
## Add support for working with IIS
Admin PS> Install-Module -Name ACMESharp.Providers.IIS

Why do we need to specify the -AllowClobber flag? The explanation is here >TODO<

Next, you need to enable the Provider Extension module:

Admin PS> Import-Module ACMESharp
Admin PS> Enable-ACMEExtensionModule -ModuleName ACMESharp.Providers.IIS
## Verify the module was enabled
Admin PS> Get-ACMEExtensionModule | Select-Object -Expand Name
ACMESharp.Providers.IIS

For more details about installation and alternative variations, please see the installation docs >TODO<.

Step 2: Initialize Vault

ACMESharp needs a place to store various state and assets while interacting with an ACME server. The PowerShell client uses a virtual storage provider simply called a Vault. The simplest type of Vault is the local Vault, which just stores all of its assets on the local file system at a well-known path by default. Because we are assuming running as an elevated user, the path will be restricted only to local Administrators.

A Vault instance is tied to a specific ACME server endpoint. That is, when you initialize the Vault you specify the default base URL that will be used for all ACME communication going forward. If you don't specify an endpoint, the default is the Let's Encrypt production endpoint, which is what we want to use for this scenario.

## Make sure ACMESharp module is loaded in the current PS session
Admin PS> Import-Module ACMESharp
Admin PS> Initialize-ACMESharp

This will use the default Vault profile for Administrators, which defines the path to the Vault storage directory as C:\ProgramData\ACMESharp\sysVault. For more details about Vault profiles and configuration alternatives, please see the Vault Details >TODO< documentation.