Skip to content

Latest commit

 

History

History
94 lines (65 loc) · 5.71 KB

README.md

File metadata and controls

94 lines (65 loc) · 5.71 KB
Raw

Posh-ACME

A PowerShell module and ACME client to create publicly trusted SSL/TLS certificates from an ACME capable certificate authority such as Let's Encrypt.

Notable Features

  • Multi-domain (SAN) and wildcard (*.example.com) certificates supported
  • IP Address certificates (RFC 8738) (Requires ACME CA support)
  • All-in-one command for new certs, New-PACertificate
  • Easy renewals with Submit-Renewal
  • RSA and ECDSA keys supported for accounts and certificates
  • Built-in validation plugins for DNS and HTTP based challenges. (pull requests welcome)
  • Support for pre-created certificate requests (CSR)
  • PEM and PFX output files
  • No elevated Windows privileges required (unless using -Install switch)
  • Cross platform PowerShell support. (FAQ)
  • Account key rollover support
  • OCSP Must-Staple support
  • DNS challenge CNAME support
  • Multiple ACME accounts supported per ACME CA.
  • External Account Binding support for ACME CAs that require it (Guide)
  • Preferred Chain support to use alternative CA trust chains (Guide)
  • PowerShell SecretManagement support (Guide)
  • ARI (ACME Renewal Information) support based on draft 04.

Installation (Stable)

The latest release can found in the PowerShell Gallery or the GitHub releases page. Installing is easiest from the gallery using Install-Module. See Installing PowerShellGet if you run into problems with it.

# 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.

Installation (Development)

Pester Tests badge

Use the following PowerShell command to install the latest development version from the git main branch. This method assumes a default PSModulePath environment variable and installs to the CurrentUser scope.

iex (irm https://raw.githubusercontent.com/rmbolger/Posh-ACME/main/instdev.ps1)

You can also download the source manually from GitHub and extract the Posh-ACME folder to your desired module location.

Quick Start

The minimum parameters you need for a cert are the domain name and the -AcceptTOS flag. 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.

New-PACertificate example.com -AcceptTOS

NOTE: On Windows, you may need to set a less restrictive PowerShell execution policy before you can import the module.

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
Import-Module Posh-ACME

Here's a more complete example with a typical wildcard cert utilizing a hypothetical FakeDNS DNS plugin that also adds a contact email address to the account for expiration notifications.

$certNames = '*.example.com','example.com'
$email = '[email protected]'
$pArgs = @{
    FDToken = (Read-Host 'FakeDNS API Token' -AsSecureString)
}
New-PACertificate $certNames -AcceptTOS -Contact $email -Plugin FakeDNS -PluginArgs $pArgs

To learn how to use a specific plugins, check out Get-PAPlugin <PluginName> -Guide. 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. You can also get the path to the server's config using (Get-PAServer).Folder.

Requirements and Platform Support

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

NOTE: PowerShell 6.0-6.1 should also work, but there are known issues when using SecureString or PSCredential plugin args on non-Windows platforms.

Changelog

See CHANGELOG.md