[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 access to an email address [email protected]
• 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.

Up to this point, everything we have done has been confined to the local machine. In the next step, we begin interacting with the ACME server and formally begin the ACME workflow.

Step 3: Register Account

The ACME protocol defines a resource known as an Account which is essentially a logical container for metadata and other resources that are managed by ACME, such as Contacts, Identifiers and Certificates. An Account is uniquely identified using a key pair - the private key is kept secret and maintained securely in the ACMESharp Vault. The public key is shared with the ACME server when the Account is first Registered. Afterwards, all actions under a given account are securely authenticated using the private key.

There are three (3) things that are required to successfully register a new Account:

1. A public/private key pair - as described above, used for future authentication. ACMESharp automatically generate a new key pair an securely store it in the Vault. All future operations will be automatically authenticated using the private key.
2. A contact list - used by an ACME server to notify an Account owner of various events such as an expiring Certificate or security incident. A contact is defined using a URI format that defines the contact type and contact details. While the ACME protocol is open-ended about the types of contacts that can be specified (e.g. email, telephone), the Let's Encrypt CA only supports email contact types, specified as URIs of the format mailto:<email-address>
3. An agreement to Terms-of-Service - the ACME server can publish a URL that defines its terms and conditions for using its services. A client is required to agree to these terms of service in order to proceed.

To register a new Account, execute:

## Make sure ACMESharp module is loaded in the current PS session
Admin PS> Import-Module ACMESharp
Admin PS> New-ACMERegistration -Contacts mailto:[email protected] -AcceptTos

This will register a new Account and agree to the ToS in one step. If you want more details about the registration process and and how to update Account attributes, see the Account Registration details >TODO< documentation.