Skip to content

Latest commit

 

History

History
93 lines (64 loc) · 5.6 KB

README.md

File metadata and controls

93 lines (64 loc) · 5.6 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)

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