sambsamb/posh-acme

ACME v2 protocol client for generating certificates using Let's Encrypt (or other ACME v2 compliant CA)

Posh-ACME

An ACME v2 (RFC 8555) client implemented as a Windows PowerShell module that enables you to generate publicly trusted SSL/TLS certificates from an ACME capable certificate authority such as Let's Encrypt.

Notable Features

• ACME v2 protocol support which allows generating wildcard certificates (*.example.com)
• Single command for new certs, New-PACertificate
• Easy renewals via Submit-Renewal
• RSA and ECC private keys supported for accounts and certificates
• Support for using existing certificate request (CSR)
• Account key rollover support
• OCSP Must-Staple support
• DNS challenge plugins for various DNS providers (pull requests welcome)
• DNS challenge CNAME support
• Help system for DNS plugins using Get-DnsPlugins and Get-DnsPluginHelp
• DNS plugins support batch updates
• Multiple accounts supported per user profile which allows different certs to have different contact emails
• PEM and PFX output files
• No elevated Windows privileges required (unless using -Install switch)
• Cross platform PowerShell Core support! (FAQ)
• Manual HTTP challenge support (Guide)

Install

Release

The latest release version can found in the PowerShell Gallery or the GitHub releases page. Installing from the gallery is easiest using Install-Module from the PowerShellGet module. See Installing PowerShellGet if you don't already have it installed.

# install for all users (requires elevated privs)
Install-Module -Name Posh-ACME -Scope AllUsers

# install for current user
Install-Module -Name Posh-ACME -Scope CurrentUser

NOTE: If you use PowerShell 5.1 or earlier, Install-Module may throw an error depending on your Windows and .NET version due to a change PowerShell Gallery made to their TLS settings. For more info and a workaround, see the official blog post.

Development

To install the latest development version from the git master branch, use the following PowerShell command. This method assumes a default PowerShell environment that includes the PSModulePath environment variable. You must also make sure Get-ExecutionPolicy does not return Restricted or AllSigned.

# If necessary, set less restrictive execution policy.
# Not needed on non-Windows
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

# install latest dev version
iex (irm https://raw.githubusercontent.com/rmbolger/Posh-ACME/master/instdev.ps1)

Quick Start

If you're starting from a fresh install, the minimum parameters you need are the domain name for your cert and the -AcceptTOS flag.

New-PACertificate site1.example.com -AcceptTOS

This uses the default Manual DNS plugin which requires you to manually edit your DNS server to create the TXT records required for challenge validation. Here's a more complete example with a typical wildcard cert utilizing a hypothetical Flurbog DNS plugin that also adds a contact email address to the account for expiration notifications.

New-PACertificate '*.example.com','example.com' -AcceptTOS -Contact [e-mail] -DnsPlugin Flurbog `
                  -PluginArgs @{FBServer='fb.example.com'; FBCred=(Get-Credential)}

To learn how to use the supported DNS plugins, check out Get-DnsPlugins and Get-DnsPluginHelp. There's also a tutorial for a more in-depth guide to using the module.

The output of New-PACertificate is an object that contains various properties about the certificate you generated. Only a subset of the properties are displayed by default. To see the full list including the filesystem paths to any certificate files that were generated, pipe the original output to Format-List or use Get-PACertificate | Format-List. The root config folder for all data saved by the module is either %LOCALAPPDATA%\Posh-ACME on Windows, ~/.config/Posh-ACME on Linux, or ~/Library/Preferences/Posh-ACME on Mac OS.

Requirements and Platform Support

• Supports Windows PowerShell 5.1 or later (Desktop edition) with .NET Framework 4.7.1 or later
• Supports PowerShell Core 6.0 or later (Core edition) on all supported OS platforms.
• Requires FullLanguage language mode

Changelog

See CHANGELOG.md