diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e4da428..e455db9a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,9 +10,34 @@ I'm the first to admit that I don't test nearly as much as I should. If you run ### DNS Plugins -If you want your provider supported but can't write the plugin yourself, submit an issue with the request and I'm happy to give it a try. But the hardest part about writing new DNS plugins is usually getting an account with the provider to test with. Providers with free trials or sandbox/test environments are great. Otherwise, I just need temporary access to an existing account **or** a [donation](https://paypal.me/rmbolger) to cover the cost of setting up a new account with the provider. +If you want your provider supported but can't write the plugin yourself, submit an issue with the request and I'm happy to give it a try. But the hardest part about writing new DNS plugins is usually getting an account with the provider to test with. Providers with free trials or sandbox/test environments are great. Otherwise, I just need temporary access to an existing account **or** a [donation](https://github.com/sponsors/rmbolger?frequency=one-time) to cover the cost of setting up a new account with the provider. -Pull requests for plugins you've written are also encouraged. I still tend to try and test them myself before merging them which goes back to the hassles of getting an account with the provider to test with. But that's mostly so that I'm confident I can support the plugin long term without needing to pull you back in to support it if someone submits and issue with it. +Pull requests for plugins you've written are also encouraged. I still try and test them myself before merging them which goes back to the hassles of getting an account with the provider to test with. But that's mostly so that I'm confident I can support the plugin long term without needing to pull you back in to support it if someone submits and issue with it. + +## Native Module Help + +The native module help is now generated by [platyPS](https://github.com/PowerShell/platyPS) from the Markdown files in [docs/Functions](https://github.com/rmbolger/Posh-ACME/tree/main/docs/Functions). So if you want to contribute fixes or improvements, submit a pull request with changes to those files. + +If you are editing the files locally, you can optionally install and generate the updated MAML XML help with platyPS as follows. + +- Make sure the latest platyPS release is installed +- From the repository root folder run `.\gen-maml.ps1` +- Force re-import the module from the repository folder or run `.\instdev.ps1` to install the dev version to the current user's profile +- Run `Get-Help ` to see your changes + +Including the updated MAML with your pull request is appreciated but not required. + +## Documentation Website + +In addition to the native module help, we have a documentation website at [https://poshac.me/docs/](https://poshac.me/docs) that is generated by [MkDocs](https://www.mkdocs.org/) from the Markdown files in [docs/](https://github.com/rmbolger/Posh-ACME/tree/main/docs/). Fixes, improvements, new guides, and new links to external articles are all welcome additions. So feel free to submit a pull request for those as well. + +Testing the doc site changes locally is a bit more involved because MkDocs is written in Python. You'll need a recent Python 3.x environment plus some additional packages. Follow the [MkDocs install guide](https://www.mkdocs.org/user-guide/installation/) and add the following additional packages with `pip install `. + +- mkdocs-material +- mkdocs-awesome-pages-plugin +- mike + +Checkout the main branch of the repository and run `mkdocs serve` to self-host a copy of the current documentation site. The output of the command should tell you the URL to use. ## Unit Tests @@ -30,10 +55,6 @@ pwsh.exe -C "Invoke-Pester" Keep in mind, the tests should be able to pass on both Windows PowerShell 5.1 and PowerShell 6+ on any OS. -## The Wiki - -Is there some documentation you wish you had when you were first playing with the module? Did I make a spelling mistake? Is my grammar poor? Did you write a blog post or article somewhere about using the module. Submit an issue and tell me about any of these things. - ## Features and Functionality I know there are loads of use cases I haven't considered. If you have an idea for a new feature or functionality change, submit an issue first so we can discuss it. I'd hate for you to waste time implementing a feature that I may never pull into the project. diff --git a/Posh-ACME/Plugins/README.md b/Posh-ACME/Plugins/README.md index a4ad1bd2..fb264aa3 100644 --- a/Posh-ACME/Plugins/README.md +++ b/Posh-ACME/Plugins/README.md @@ -1,206 +1,5 @@ -# Writing a Validation Plugin for Posh-ACME +# Plugin Development Guide -A validation plugin for Posh-ACME is a standard PowerShell PS1 script file located in the module's `Plugins` folder. Its file name is what users will use to reference it when specifying a plugin, so it should be related to the provider it is publishing against. +The plugin development guide has been moved to here: -All plugins must contain a function called `Get-CurrentPluginType` which returns a string indicating the type of ACME challenge they support. Posh-ACME currently supports the `dns-01` and `http-01` challenge types. - -DNS plugins must contain the following additional functions: - -- `Add-DnsTxt` -- `Remove-DnsTxt` -- `Save-DnsTxt` - -HTTP plugins must contain the following additional functions: - -- `Add-HttpChallenge` -- `Remove-HttpChallenge` -- `Save-HttpChallenge` - -The easiest way to get started is to make a copy of `_Example-DNS.ps1` or `_Example-HTTP.ps1` depending on the type of plugin you are making and rename it for your purposes. - -**Pull Requests for new plugins are quite welcome.** - - -## Function Details - -### `Add-DnsTxt` and `Remove-DnsTxt` - -These are responsible for adding/removing TXT records to/from a DNS server/provider. There are two mandatory and positional string parameters, `$RecordName` and `$TxtValue`. RecordName is the fully qualified domain name (FQDN) of the record we will be adding a TXT value for. TxtValue is the actual value that will be set in the TXT record. Do not modify or remove these first -two parameters. - -Additional parameters should be added as necessary for the specific DNS provider such as credentials or API keys. In addition to standard PowerShell naming standards, their names must also not conflict with any other plugin's parameters. A good way to do that is to use a unique prefix on all of the parameters. It doesn't have to match the plugin name exactly as long as it's unique and reasonably related to the plugin. Common parameters that can be shared between this plugin's functions should be named the same as each other. - -The last parameter should always be `$ExtraParams` with the `ValueFromRemainingArguments` parameter attribute. This allows callers to [splat](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting?view=powershell-5.1) the combined collection of plugin parameters to each plugin without errors for parameters that don't exist. - -Many DNS providers will only need the Add and Remove functions. In those cases, remember to remove all but the `$ExtraParams` parameter in the Save function and just leave the function body empty. For other providers, it is may be more efficient to stage changes in bulk and then perform what is effectively a Save or Commit operation on those changes. In those cases, implement the Save function as described below. - -### `Add-HttpChallenge` and `Remove-HttpChallenge` - -These are responsible for publishing/unpublishing the ACME challenge body text at a specific HTTP URL. There are three mandatory and positional string parameters, `$Domain`, `$Token`, and `$Body`. Domain and Token are what the validation server will use to build the URL it will check against (`http:///.well-known/acme-challenge/`). Body is the text value it expects to get in response to that query. Do not modify or remove these first three parameters. - -Additional parameters should be added as necessary for the specific HTTP provider such as filesystem paths, credentials, or API keys. In addition to standard PowerShell naming standards, their names must also not conflict with any other plugin's parameters. A good way to do that is to use a unique prefix on all of the parameters. It doesn't have to match the plugin name exactly as long as it's unique and reasonably related to the plugin. Common parameters that can be shared between this plugin's functions should be named the same as each other. - -The last parameter should always be `$ExtraParams` with the `ValueFromRemainingArguments` parameter attribute. This allows callers to [splat](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting?view=powershell-5.1) the combined collection of plugin parameters to each plugin without errors for parameters that -don't exist. - -Many HTTP providers will only need the Add and Remove functions. In those cases, remember to remove all but the `$ExtraParams` parameter in the Save function and just leave the function body empty. For other providers, it is may be more efficient to stage changes in bulk and then perform what is effectively a Save or Commit operation on those changes. In those cases, implement the Save function as described below. - -### `Save-DnsTxt` and `Save-HttpChallenge` - -These functions are optional for DNS/HTTP plugins where it is more efficient to stage changes in bulk before Saving or Committing the changes. There are no required parameters except `$ExtraParams` which should always be last and have the `ValueFromRemainingArguments` parameter attribute. - -### Parameter Types - -Try to limit parameters to simple data types like `[string]`, `[int]`, and `[switch]`. Arrays and Hashtables are fine as long as the contents are also simple types. Hashtables in particular should not be nested. The parameters should be able to convert nicely back and forth using `Convert-ToJson` and `Convert-FromJson`. - -Secrets such as passwords and API keys/tokens should use `[SecureString]` or `[PSCredential]` parameters even if you ultimately need them in plain text within the plugin. This ensures the values are encrypted when saved to disk for later renewals. Here are some examples for how to convert them back to plain text in the plugin code. - -```powershell -# get the username and password from a PSCredential called $cred -$username = $cred.Username -$password = $cred.GetNetworkCredential().Password - -# get the plain text from a SecureString called $secString -$plainText = [pscredential]::new('a',$secString).GetNetworkCredential().Password -``` - -## Usage Guides - -In addition to the native function help, it can be very helpful to new users to have a plugin specific readme. It should be a Markdown formatted file also in the Plugins folder called `-Readme.md`. For people who may be setting up automation against their provider for the first time, it can be helpful to add guidance on creating service accounts, limited access roles, or any prerequisite setup that the plugin requires to work properly. It should also have a section with an example on how to use the plugin with `New-PACertificate`. - - -## General Development Tips and Tricks - -### No Write-Host - -Unless your plugin requires interactive user input which should be rare, do not use `Write-Host` to display informational messages or debug output. Use `Write-Verbose` for messages you would want a potential user to see. Use `Write-Debug` for things only the plugin developer would likely care about or a user trying to troubleshoot a plugin that is not working. - -When testing your module, use `-Verbose` to see your verbose messages. And run `$DebugPreference = 'Continue'` to make the debug messages show up without prompting for confirmation *(which happens if you use `-Debug`)*. - -### No Pipeline Output - -Do not output any objects to the pipeline from your plugin. This will interfere with scripts and workflows that use the normal output of public functions. You can use `Out-Null` on internal calls that would normally output to the pipeline when you don't care about that data. - -### UseBasicParsing - -Any time you call `Invoke-WebRequest` or `Invoke-RestMethod`, you should always add `@script:UseBasic` to the end. - -By default in PowerShell 5.1, those two functions use Internet Explorer's DOM parser to process the response body which can cause errors in cases where IE is not installed or hasn't gone through its first-run sequence yet. Both functions have a `-UseBasicParsing` parameter that switches the parser to a PowerShell native parser and is the new default functionality in PowerShell 6+. The parameter is also deprecated because they don't plan on bringing back IE DOM parsing in future PowerShell versions. So the module creates a variable when it is first loaded that checks whether `-UseBasicParsing` is still available or not and adds it to the `$script:UseBasic` hashtable. That way, you can just [splat](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting) it on all your calls to those two functions which will future proof your plugin. - -### Testing Plugins - -As mentioned earlier, the plugin file must reside in the module's `Plugins` folder prior to running `Import-Module` implicitly or explicitly. If the module is already loaded in the session, you will need to re-import it using `Import-Module -Force`. There is a helper script called `instdev.ps1` in the root of the git repository that can make this process a lot easier as you are developing the plugin. - -First make sure any existing copies of the module are uninstalled (or at least don't reside in your `$env:PSModulePath`). Clone the git repository (or your fork) to a folder on your local system and add your plugin file to the `Posh-Acme\Plugins` folder if it's not already there. Open a new PowerShell session to the repository root folder and run `.\instdev.ps1` which will do the following: - -- Copy the module files to the current user's default PowerShell modules folder. -- Run `Import-Module Posh-ACME -Force` -- Display the available module commands - -If there are no problems, your plugin should now be listed in the output of `Get-PAPlugin`. - -Testing a plugin can be done without requesting a new certificate. All you need is an existing ACME account created with `New-PAAccount` and the `Publish-Challenge`, `Unpublish-Challenge`, and `Save-Challenge` functions. They call the Add, Remove, and Save functions from the plugin. Here are some examples of how I generally call them while testing. - -```powershell -$DebugPreference = 'Continue' -$pArgs = @{MyParam1='asdf';MyParam2='qwer'} - -# multiple calls to publish/unpublish are generally more useful for DNS plugins -Publish-Challenge example.com (Get-PAAccount) test1 MyPlugin $pArgs -Verbose -Publish-Challenge example.com (Get-PAAccount) test2 MyPlugin $pArgs -Verbose -Publish-Challenge example.com (Get-PAAccount) test3 MyPlugin $pArgs -Verbose - -# save is only necessary if your plugin implements it -Save-Challenge MyPlugin $pArgs -Verbose - -Unpublish-Challenge example.com (Get-PAAccount) test1 MyPlugin $pArgs -Verbose -Unpublish-Challenge example.com (Get-PAAccount) test2 MyPlugin $pArgs -Verbose -Unpublish-Challenge example.com (Get-PAAccount) test3 MyPlugin $pArgs -Verbose - -# save is only necessary if your plugin implements it -Save-Challenge MyPlugin $pArgs -Verbose -``` - -Alternatively, you can [dot source](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_scripts?view=powershell-5.1#script-scope-and-dot-sourcing) the plugin file and call the functions directly. But this can be difficult if the functions depend on module-scoped variables like `$script:UseBasic` or internal module functions. Also, remember to dot source again each time you make a change to the plugin. - -## DNS Specific Tips and Tricks - -### Multiple TXT Values Per Record - -It is both supported and expected that a given TXT record may have multiple values. It's most common with wildcard certificates that contain both the wildcard name (`*.example.com`) and the root domain (`example.com`). Both names require TXT records be added for the same FQDN (`_acme-challenge.example.com`). This can also happen if the user is using CNAME challenge aliases. - -The Add/Remove functions need to support all potential states of the particular TXT record. But how the record is represented by a given provider seems to vary. Some represent it as a single record with multiple values that you need to add to or remove from. Others have distinct records for each value that can be created/deleted individually. So make sure you can both create a new record that doesn't exist *and* add a value to a record that already does. - -### Remove Only Specific TxtValue - -Related to having multiple TXT values per record, the remove function must not blindly delete any record that matches `$RecordName`. It should be able to remove only the `$TxtValue` on a record that may have multiple values. But if the record only contains a single value, the record should be deleted entirely. - -### Zone Matching - -A particular DNS provider may be hosting both domain apex zones (`example.com`) and sub-zones (`sub1.example.com`). One of the first things a plugin usually has to do is figure out which zone `$RecordName` needs to be added to. This should be the deepest sub-zone that would still contain `$RecordName`. Here are some examples assuming only the two previously mentioned zones exist. - -`$RecordName` | Matching Zone ---- | --- -_acme-challenge.example.com | example.com -_acme-challenge.site1.example.com | example.com -_acme-challenge.sub1.example.com | sub1.example.com -_acme-challenge.site1.sub1.example.com | sub1.example.com -_acme-challenge.site1.sub3.sub2.sub1.example.com | sub1.example.com - -Many of the existing plugins have a helper function to handle this. Copy and modify their code where it makes sense but make sure helper function names are unique. - -### DNS Aliases and Domain Apex - -Don't forget to test your functions against the domain apex which can happen when users are using DNS challenge aliases. There's often a special way to represent records in the domain apex from an API perspective, commonly with the `@` character or an empty string instead of a record short name. - -```powershell -# The my.cname.tld record doesn't actually need to exist for the test to work. -# The plugin will only be writing to example.com -Publish-Challenge my.cname.tld (Get-PAAccount) test1 MyPlugin $pArgs -DnsAlias example.com -Verbose -Unpublish-Challenge my.cname.tld (Get-PAAccount) test1 MyPlugin $pArgs -DnsAlias example.com -Verbose -``` - -### Deriving Object IDs - -Many providers assign ID values to object types like zones and records that you need to use to manipulate those objects. A user should ideally not have to know or provide any zone, record, or object IDs in order to use the plugin. All of that should be discovered by the plugin code and the only thing the user should need to provide is whatever credentials or tokens the API requires for authentication. - -In the rare cases that you do need the user to provide something like a zone ID, make sure you allow for multiple values. A single certificate can contain names from many different zones and the plugin parameters that get passed to the plugin are the same for each TXT record that needs to be created. - -### Trailing Dots - -Be aware how your particular DNS provider represents zone and record names. Some include the trailing dot (`example.com.`). Others don't. This can affect string matching when finding zones and existing records. - -### Internationalized Domain Name (IDN) - -Many DNS providers and registrars support [IDN domains](https://en.wikipedia.org/wiki/Internationalized_domain_name) which contain non-ascii unicode characters (or even emojis). When using IDN domains with ACME, the IDN names must be specified as [Punycode](https://en.wikipedia.org/wiki/Punycode). But the DNS providers may still send or receive the unicode version of the name. Particularly if your provider is not US-based, be aware of and try to account for how the provider handles IDN names. - -The .NET [System.Globalization.IdnMapping](https://docs.microsoft.com/en-us/dotnet/api/system.globalization.idnmapping) class can help convert back and for between IDN and punycode names like this: - -```powershell -# create an instance of the class -$idn = [System.Globalization.IdnMapping]::new() - -# convert an IDN name to punycode -$idn.GetAscii('bücher.example') - -# convert a punycode name back to IDN -$idn.GetUnicode('xn--bcher-kva.example') -``` - -## HTTP Specific Tips and Tricks - -### Validation Timing - -When DNS plugins are used, there's a user customizable sleep timer between when the TXT records are published and the module asks the ACME server to validate those records because records are not typically available instantaneously worldwide. However, that sleep timer does not exist when an order is only using HTTP plugins because HTTP resources are typically available instantly. - -If your particular HTTP provider requires a delay between when the challenges are published and when they are validated, you should add that delay in the `Save-HttpChallenge` function of your plugin. - -## Migrating DNS Plugins from 3.x to 4.x - -In case you have been using your own private DNS plugin in 3.x, here's how to migrate it to the 4.x format. - -* Add `function Get-CurrentPluginType { 'dns-01' }` to the top of the file. -* Replace instances of `Add-DnsTxt` with `Add-DnsTxt` -* Replace instances of `Remove-DnsTxt` with `Remove-DnsTxt` -* Replace instances of `Save-DnsTxt` with `Save-DnsTxt` -* Replace instances of `-DnsPlugin` with `-Plugin` in usage guides. +https://poshac.me/docs/latest/Plugins/Plugin-Development-Guide/ diff --git a/Posh-ACME/Public/Complete-PAOrder.ps1 b/Posh-ACME/Public/Complete-PAOrder.ps1 index 80a01701..5569c4f0 100644 --- a/Posh-ACME/Public/Complete-PAOrder.ps1 +++ b/Posh-ACME/Public/Complete-PAOrder.ps1 @@ -81,36 +81,4 @@ function Complete-PAOrder { # output cert details return $cert } - - - <# - .SYNOPSIS - Exports cert files for a completed order and adds suggested renewal window to the order. - - .DESCRIPTION - Once an ACME order is finalized, the signed certificate and chain can be downloaded and combined with the local private key to generate the supported PEM and PFX files on disk. This function will also calculate the renewal window based on the signed certificate's expiration date and update the order object with that info. If the Install flag is set, this function will attempt to import the certificate into the Windows certificate store. - - .PARAMETER Order - The ACME order to complete. The order object must be associated with the currently active ACME account. - - .EXAMPLE - Complete-PAOrder - - Complete the current order. - - .EXAMPLE - Get-PAOrder example.com | Complete-PAOrder - - Complete the specified order. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAOrder - - .LINK - New-PAOrder - - #> } diff --git a/Posh-ACME/Public/Export-PAAccountKey.ps1 b/Posh-ACME/Public/Export-PAAccountKey.ps1 index 7fd695e5..9acd24f1 100644 --- a/Posh-ACME/Public/Export-PAAccountKey.ps1 +++ b/Posh-ACME/Public/Export-PAAccountKey.ps1 @@ -55,48 +55,4 @@ function Export-PAAccountKey { Export-Pem $keypair $OutputFile } - - - <# - .SYNOPSIS - Export an ACME account private key. - - .DESCRIPTION - The account key is saved as an unencrypted Base64 encoded PEM file. - - .PARAMETER ID - The ACME account ID value. - - .PARAMETER OutputFile - The path to the file to write the key data to. - - .PARAMETER Force - If specified and the output file already exists, it will be overwritten. Without the switch, a confirmation prompt will be presented. - - .EXAMPLE - Export-PAAccountKey -OutputFile .\mykey.pem - - Exports the current ACME account's key to the specified file. - - .EXAMPLE - Export-PAAccountKey 12345 -OutputFile .\mykey.pem -Force - - Exports the specified ACME account's key to the specified file and overwrites it if necessary. - - .EXAMPLE - $fldr = Join-Path ([Environment]::GetFolderPath('Desktop')) 'AcmeAccountKeys' - PS C:\>New-Item -ItemType Directory -Force -Path $fldr | Out-Null - PS C:\>Get-PAAccount -List | %{ - PS C:\> Export-PAAccountKey $_.ID -OutputFile "$fldr\$($_.ID).key" -Force - PS C:\>} - - Backup all account keys for this ACME server to a folder on the desktop. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAAccount - - #> } diff --git a/Posh-ACME/Public/Get-KeyAuthorization.ps1 b/Posh-ACME/Public/Get-KeyAuthorization.ps1 index 125214aa..9c98cc0d 100644 --- a/Posh-ACME/Public/Get-KeyAuthorization.ps1 +++ b/Posh-ACME/Public/Get-KeyAuthorization.ps1 @@ -75,44 +75,4 @@ function Get-KeyAuthorization { return $keyAuth } } - - - - - <# - .SYNOPSIS - Calculate a key authorization string for a challenge token. - - .DESCRIPTION - A key authorization is a string that expresses a domain holder's authorization for a specified key to satisfy a specified challenge, by concatenating the token for the challenge with a key fingerprint. - - .PARAMETER Token - The token string for an ACME challenge. - - .PARAMETER Account - The ACME account associated with the challenge. - - .PARAMETER ForDNS - Enable this switch if you're using the key authorization value for the 'dns-01' challenge type. It will do a few additional manipulation steps on the value that are required for a DNS TXT record. - - .EXAMPLE - Get-KeyAuthorization 'XxXxXxXxXxXx' - - Get the key authorization for the specified token using the current account. - - .EXAMPLE - (Get-PAOrder | Get-PAAuthorization).DNS01Token | Get-KeyAuthorization - - Get all key authorizations for the DNS challenges in the current order using the current account. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAAuthorization - - .LINK - Submit-ChallengeValidation - - #> } diff --git a/Posh-ACME/Public/Get-PAAccount.ps1 b/Posh-ACME/Public/Get-PAAccount.ps1 index fc3d01e9..6ae07f10 100644 --- a/Posh-ACME/Public/Get-PAAccount.ps1 +++ b/Posh-ACME/Public/Get-PAAccount.ps1 @@ -131,77 +131,4 @@ function Get-PAAccount { } } } - - - - - - <# - .SYNOPSIS - Get ACME account details. - - .DESCRIPTION - Returns details such as Email, key length, and status for one or more ACME accounts previously created. - - .PARAMETER ID - The account id value as returned by the ACME server. 'Name' is also an alias for this parameter. - - .PARAMETER List - If specified, the details for all accounts will be returned. - - .PARAMETER Status - A Status string to filter the list of accounts with. - - .PARAMETER Contact - One or more email addresses to filter the list of accounts with. Returned accounts must match exactly (not including the order). - - .PARAMETER KeyLength - The type and size of private key to filter the list of accounts with. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. - - .PARAMETER Refresh - If specified, any account details returned will be freshly queried from the ACME server (excluding deactivated accounts). Otherwise, cached details will be returned. - - .PARAMETER ExtraParams - This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. - - .EXAMPLE - Get-PAAccount - - Get cached ACME account details for the currently selected account. - - .EXAMPLE - Get-PAAccount -ID 1234567 - - Get cached ACME account details for the specified account ID. - - .EXAMPLE - Get-PAAccount -List - - Get all cached ACME account details. - - .EXAMPLE - Get-PAAccount -Refresh - - Get fresh ACME account details for the currently selected account. - - .EXAMPLE - Get-PAAccount -List -Refresh - - Get fresh ACME account details for all accounts. - - .EXAMPLE - Get-PAAccount -List -Contact user1@example.com - - Get cached ACME account details for all accounts that have user1@example.com as the only contact. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Set-PAAccount - - .LINK - New-PAAccount - - #> } diff --git a/Posh-ACME/Public/Get-PAAuthorization.ps1 b/Posh-ACME/Public/Get-PAAuthorization.ps1 index 0980567e..2c62972f 100644 --- a/Posh-ACME/Public/Get-PAAuthorization.ps1 +++ b/Posh-ACME/Public/Get-PAAuthorization.ps1 @@ -53,47 +53,4 @@ function Get-PAAuthorization { ConvertTo-PAAuthorization $response.Content $AuthUrl } } - - - - - - <# - .SYNOPSIS - Get the authorizations associated with a particular order or set of authorization URLs. - - .DESCRIPTION - Returns details such as fqdn, status, expiration, and challenges for one or more ACME authorizations. - - .PARAMETER AuthURLs - One or more authorization URLs. These will be picked up automatically if you send PoshACME.PAOrder objects through the pipeline. - - .PARAMETER Account - An existing ACME account object such as the output from Get-PAAccount. If no account is specified, the current account will be used. - - .EXAMPLE - Get-PAAuthorization https://acme.example.com/authz/1234567 - - Get the authorization for the specified URL. - - .EXAMPLE - Get-PAOrder | Get-PAAuthorization - - Get the authorization(s) for the current order on the current account. - - .EXAMPLE - Get-PAOrder -List | Get-PAAuthorization - - Get the authorization(s) for all orders on the current account. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAOrder - - .LINK - New-PAOrder - - #> } diff --git a/Posh-ACME/Public/Get-PACertificate.ps1 b/Posh-ACME/Public/Get-PACertificate.ps1 index 397c8f6a..895c6046 100644 --- a/Posh-ACME/Public/Get-PACertificate.ps1 +++ b/Posh-ACME/Public/Get-PACertificate.ps1 @@ -94,47 +94,4 @@ function Get-PACertificate { } } - - - - - - <# - .SYNOPSIS - Get ACME certificate details. - - .DESCRIPTION - Returns details such as Thumbprint, Subject, Validity, SANs, and file locations for one or more ACME certificates previously created. - - .PARAMETER MainDomain - The primary domain associated with the certificate. This is the domain that goes in the certificate's subject. - - .PARAMETER Name - The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. - - .PARAMETER List - If specified, the details for all completed certificates will be returned for the current account. - - .EXAMPLE - Get-PACertificate - - Get cached ACME order details for the currently selected order. - - .EXAMPLE - Get-PACertificate site.example.com - - Get cached ACME order details for the specified domain. - - .EXAMPLE - Get-PACertificate -List - - Get all cached ACME order details. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - New-PACertificate - - #> } diff --git a/Posh-ACME/Public/Get-PAOrder.ps1 b/Posh-ACME/Public/Get-PAOrder.ps1 index 4f9a646b..9996381c 100644 --- a/Posh-ACME/Public/Get-PAOrder.ps1 +++ b/Posh-ACME/Public/Get-PAOrder.ps1 @@ -105,63 +105,4 @@ function Get-PAOrder { } } - - - - - - <# - .SYNOPSIS - Get ACME order details. - - .DESCRIPTION - Returns details such as Domains, key length, expiration, and status for one or more ACME orders previously created. - - .PARAMETER MainDomain - The primary domain associated with the order. This is the domain that goes in the certificate's subject. - - .PARAMETER Name - The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. - - .PARAMETER List - If specified, the details for all orders will be returned. - - .PARAMETER Refresh - If specified, any order details returned will be freshly queried from the ACME server. Otherwise, cached details will be returned. - - .EXAMPLE - Get-PAOrder - - Get cached ACME order details for the currently selected order. - - .EXAMPLE - Get-PAOrder site.example.com - - Get cached ACME order details for the specified domain. - - .EXAMPLE - Get-PAOrder -List - - Get all cached ACME order details. - - .EXAMPLE - Get-PAOrder -Refresh - - Get fresh ACME order details for the currently selected order. - - .EXAMPLE - Get-PAOrder -List -Refresh - - Get fresh ACME order details for all orders. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Set-PAOrder - - .LINK - New-PAOrder - - #> } diff --git a/Posh-ACME/Public/Get-PAPlugin.ps1 b/Posh-ACME/Public/Get-PAPlugin.ps1 index f1c1ecc3..1d430c40 100644 --- a/Posh-ACME/Public/Get-PAPlugin.ps1 +++ b/Posh-ACME/Public/Get-PAPlugin.ps1 @@ -79,7 +79,7 @@ function Get-PAPlugin { # the future. # https://github.com/PowerShell/PowerShell/issues/7201 - $url = "https://github.com/rmbolger/Posh-ACME/blob/main/Posh-ACME/Plugins/$($pluginDetail.Name)-Readme.md" + $url = "https://poshac.me/docs/v4/Plugins/$($pluginDetail.Name)/" try { # launch the browser to the guide @@ -100,48 +100,4 @@ function Get-PAPlugin { } return } - - - - <# - .SYNOPSIS - Show plugin details, help, or launch the online guide. - - .DESCRIPTION - With no parameters, this function will return a list of built-in validation plugins and their details. - - With a Plugin specified, this function will return that plugin's details, help, or launch the online guide depending on which switches are specified. - - .PARAMETER Plugin - The name of a validation plugin. - - .PARAMETER Help - If specified, display the help contents for the specified plugin. - - .PARAMETER Guide - If specified, launch the default web browser to the specified plugin's online guide. This currently only works on Windows and will simply display the URL on other OSes. - - .PARAMETER Params - If specified, returns the plugin-specific parameter sets associated with this plugin. - - .EXAMPLE - Get-PAPlugin - - Get the list of available validation plugins - - .EXAMPLE - Get-PAPlugin Route53 -Guide - - Launch the user's default web browser to the online guide for the specified plugin. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - New-PACertificate - - .LINK - Publish-Challenge - - #> } diff --git a/Posh-ACME/Public/Get-PAPluginArgs.ps1 b/Posh-ACME/Public/Get-PAPluginArgs.ps1 index 5f9f32d7..ef3c914d 100644 --- a/Posh-ACME/Public/Get-PAPluginArgs.ps1 +++ b/Posh-ACME/Public/Get-PAPluginArgs.ps1 @@ -81,39 +81,4 @@ function Get-PAPluginArgs { $pData } - - <# - .SYNOPSIS - Retrieve the plugin args for the current or specified order. - - .DESCRIPTION - An easy way to recall the plugin args used for a given order. - - .PARAMETER MainDomain - The primary domain for the order. For a SAN order, this was the first domain in the list when creating the order. - - .PARAMETER Name - The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. - - .EXAMPLE - Get-PAPluginArgs - - Retrieve the plugin args for the current order. - - .EXAMPLE - Get-PAPluginArgs -Name myorder - - Retrieve the plugin args for the specified order. - - .EXAMPLE - Get-PAOrder -Name myorder | Get-PAPluginArgs - - Retrieve the plugin args for the order passed via the pipeline. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Gew-PAOrder - #> } diff --git a/Posh-ACME/Public/Get-PAServer.ps1 b/Posh-ACME/Public/Get-PAServer.ps1 index beb22ce1..74ee698c 100644 --- a/Posh-ACME/Public/Get-PAServer.ps1 +++ b/Posh-ACME/Public/Get-PAServer.ps1 @@ -89,68 +89,4 @@ function Get-PAServer { } } } - - - - - - <# - .SYNOPSIS - Get ACME server details. - - .DESCRIPTION - The primary use for this function is checking which ACME server is currently configured. New Account and Cert requests will be directed to this server. It may also be used to refresh server details and list additional servers that have previously been used. - - .PARAMETER DirectoryUrl - Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2), LE_STAGE (LetsEncrypt Staging v2), BUYPASS_PROD (BuyPass.com Production), and BUYPASS_TEST (BuyPass.com Testing). - - .PARAMETER Name - The name of the ACME server. The parameter is ignored if DirectoryUrl is specified. - - .PARAMETER List - If specified, the details for all previously used servers will be returned. - - .PARAMETER Refresh - If specified, any server details returned will be freshly queried from the ACME server. Otherwise, cached details will be returned. - - .PARAMETER Quiet - If specified, no warning will be thrown if a specified server is not found. - - .EXAMPLE - Get-PAServer - - Get cached ACME server details for the currently selected server. - - .EXAMPLE - Get-PAServer -DirectoryUrl LE_PROD - - Get cached LetsEncrypt production server details using the short name. - - .EXAMPLE - Get-PAServer -List - - Get all cached ACME server details. - - .EXAMPLE - Get-PAServer -DirectoryUrl https://myacme.example.com/directory - - Get cached ACME server details for the specified directory URL. - - .EXAMPLE - Get-PAServer -Refresh - - Get fresh ACME server details for the currently selected server. - - .EXAMPLE - Get-PAServer -List -Refresh - - Get fresh ACME server details for all previously used servers. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Set-PAServer - - #> } diff --git a/Posh-ACME/Public/Install-PACertificate.ps1 b/Posh-ACME/Public/Install-PACertificate.ps1 index 1f186e27..c52f56d8 100644 --- a/Posh-ACME/Public/Install-PACertificate.ps1 +++ b/Posh-ACME/Public/Install-PACertificate.ps1 @@ -36,46 +36,4 @@ function Install-PACertificate { } Import-PfxCertInternal @importArgs } - - - <# - .SYNOPSIS - Install a Posh-ACME certificate into a Windows certificate store. - - .DESCRIPTION - This can be used instead of the -Install parameter on New-PACertificate to import a certificate with more configurable options. - - .PARAMETER PACertificate - The PACertificate object you want to import. This can be retrieved using Get-PACertificate and is also returned from things like New-PACertificate and Submit-Renewal. - - .PARAMETER StoreLocation - Either 'LocalMachine' or 'CurrentUser'. Defaults to 'LocalMachine'. - - .PARAMETER StoreName - The name of the certificate store to import to. Defaults to 'My'. The store must already exist and will not be created automatically. - - .PARAMETER NotExportable - If specified, the private key will not be marked as Exportable. - - .EXAMPLE - Install-PACertificate - - Install the certificate for the currently selected order to the default LocalMachine\My store. - - .EXAMPLE - Get-PACertificate example.com | Install-PACertificate - - Install the specified certificate to the default LocalMachine\My store. - - .EXAMPLE - Install-PACertificate -StoreLocation 'CurrentUser' -NotExportable - - Install the certificate for the currently selected order to the CurrentUser\My store and mark the private key as not exportable. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PACertificate - #> } diff --git a/Posh-ACME/Public/Invoke-HttpChallengeListener.ps1 b/Posh-ACME/Public/Invoke-HttpChallengeListener.ps1 index 0936cfbc..f25587e8 100644 --- a/Posh-ACME/Public/Invoke-HttpChallengeListener.ps1 +++ b/Posh-ACME/Public/Invoke-HttpChallengeListener.ps1 @@ -212,56 +212,4 @@ function Invoke-HttpChallengeListener { $order | Get-PAAuthorization -Verbose:$false } } - - <# - .SYNOPSIS - Starts a local web server to answer pending http-01 ACME challenges. - - .DESCRIPTION - Uses System.Net.HttpListener to answer http-01 ACME challenges for the current or specified order. If MainDomain is not specified, the current Order is used. - - If running on Windows with non-admin privileges, Access Denied errors may be thrown unless a URL reservation is added using netsh that matches the HttpListener prefix that will be used. The default wildcard prefix is http://+/.well-known/acme-challenge and the netsh command might look something like this: - - netsh http add urlacl url=http://+/.well-known/acme-challenge/ user=Everyone - - .PARAMETER MainDomain - The primary domain associated with an order. - - .PARAMETER Name - The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. - - .PARAMETER ListenerTimeout - The timeout in seconds for the webserver. When reached, the http listener stops regardless of challenge status. - - .PARAMETER Port - The TCP port on which the http listener is listening. 80 by default. This parameter is ignored when ListenerPrefixes is specified. - - .PARAMETER ListenerPrefixes - Overrides the default wildcard listener prefix with the specified prefixes instead. Be sure to include the port if necessary and a trailing '/' on all included prefixes. See https://docs.microsoft.com/en-us/dotnet/api/system.net.httplistener for details. - - .EXAMPLE - Invoke-HttpChallengeListener - - Start listener on default port 80 for pending challenges for the current order. - - .EXAMPLE - Invoke-HttpChallengeListener -MainDomain 'test.example.com' -Port 8080 -ListenerTimeout 30 - - Start listener on port 8080 with a timeout of 30 seconds for the specified order. - - .EXAMPLE - $prefixes = 'http://example.com/.well-known/acme-challenge/','http://www.example.com/.well-known/acme-challenge' - PS C:\>Invoke-HttpChallengeListener -ListenerPrefixes $prefixes - - Start listener using the specified prefixes for the current order. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAOrder - - .LINK - Get-PAAuthorization - #> } diff --git a/Posh-ACME/Public/New-PAAccount.ps1 b/Posh-ACME/Public/New-PAAccount.ps1 index 9f5c64ae..02e560c9 100644 --- a/Posh-ACME/Public/New-PAAccount.ps1 +++ b/Posh-ACME/Public/New-PAAccount.ps1 @@ -213,86 +213,4 @@ function New-PAAccount { $acct | Select-Object -Exclude id,Folder | ConvertTo-Json -Depth 5 | Out-File (Join-Path $acct.Folder 'acct.json') -Force -EA Stop return $acct - - - - - <# - .SYNOPSIS - Create a new account on the current ACME server. - - .DESCRIPTION - All certificate requests require a valid account on an ACME server. Adding an email contact is not required. But without one, certificate expiration notices will not be sent. The account KeyLength is personal preference and doesn't correspond to the KeyLength of the generated certificates. - - .PARAMETER Contact - One or more email addresses to associate with this account. These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. - - .PARAMETER KeyLength - The type and size of private key to use. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to 'ec-256'. - - .PARAMETER KeyFile - The path to an existing EC or RSA private key file. This will attempt to create the account using the specified key as the ACME account key. This can be used to recover/import an existing ACME account if one is already associated with the key. - - .PARAMETER ID - The name of the ACME acccount. - - .PARAMETER AcceptTOS - If not specified, the ACME server will throw an error with a link to the current Terms of Service. Using this switch indicates acceptance of those Terms of Service and is required for successful account creation. - - .PARAMETER OnlyReturnExisting - If specified, the ACME server will only return the account details if they already exist for the given private key. Otherwise, an error will be thrown. This can be useful to check whether an existing private key is associated with an ACME acount and recover the account details without creating a new account. - - .PARAMETER Force - If specified, confirmation prompts that may have been generated will be skipped. - - .PARAMETER ExtAcctKID - The external account key identifier supplied by the CA. This is required for ACME CAs that require external account binding. - - .PARAMETER ExtAcctHMACKey - The external account HMAC key supplied by the CA and encoded as Base64Url. This is required for ACME CAs that require external account binding. - - .PARAMETER ExtAcctAlgorithm - The HMAC algorithm to use. Defaults to 'HS256'. - - .PARAMETER UseAltPluginEncryption - If specified, the account will be configured to use a randomly generated AES key to encrypt sensitive plugin parameters on disk instead of using the OS's native encryption methods. This can be useful if the config is being shared across systems or platforms. You can revert to OS native encryption using -UseAltPluginEncryption:$false. - - .PARAMETER ExtraParams - This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. - - .EXAMPLE - New-PAAccount -AcceptTOS - - Create a new account with no contact email and the default key length. - - .EXAMPLE - New-PAAccount -Contact user1@example.com -AcceptTOS - - Create a new account with the specified email and the default key length. - - .EXAMPLE - New-PAAccount -Contact user1@example.com -KeyLength 4096 -AcceptTOS - - Create a new account with the specified email and an RSA 4096 bit key. - - .EXAMPLE - New-PAAccount -KeyLength 'ec-384' -AcceptTOS -Force - - Create a new account with no contact email and an ECC key using P-384 curve that ignores any confirmations. - - .Example - New-PAAccount -KeyFile .\mykey.key -AcceptTOS - - Create a new account using a pre-generated private key file. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAAccount - - .LINK - Set-PAAccount - - #> } diff --git a/Posh-ACME/Public/New-PAAuthorization.ps1 b/Posh-ACME/Public/New-PAAuthorization.ps1 index 67ddcd41..d1baa6c3 100644 --- a/Posh-ACME/Public/New-PAAuthorization.ps1 +++ b/Posh-ACME/Public/New-PAAuthorization.ps1 @@ -85,44 +85,4 @@ function New-PAAuthorization { } } - - - - - - <# - .SYNOPSIS - Create a pre-authorization for an ACME identifier. - - .DESCRIPTION - Instead of creating an ACME order object and satisfying the associated authorization challenges on demand, users may choose to pre-authorize one or more identifiers in advance. When a user later creates an order with pre-authorized identifiers, it will be immediately ready to finalize. - - NOTE: Not all ACME servers support pre-authorization. The authorizations created this way also expire the same way they do when associated directly with an order. - - .PARAMETER Domain - One or more ACME identifiers (usually domain names). - - .PARAMETER Account - An existing ACME account object such as the output from Get-PAAccount. If no account is specified, the current account will be used. - - .EXAMPLE - $auth = New-PAAuthorization example.com - - Create a new authorization for the specified domain using the current account. - - .EXAMPLE - $auths = 'example.com','www.example.com' | New-PAAuthorization -Account (Get-PAAccount 123) - - Create new authorizations for the specified domains via the pipeline and using the specified account. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAAuthorization - - .LINK - New-PAOrder - - #> } diff --git a/Posh-ACME/Public/New-PACertificate.ps1 b/Posh-ACME/Public/New-PACertificate.ps1 index 10a51651..1908e37f 100644 --- a/Posh-ACME/Public/New-PACertificate.ps1 +++ b/Posh-ACME/Public/New-PACertificate.ps1 @@ -263,119 +263,4 @@ function New-PACertificate { } elseif ($order.CertExpires) { Write-Warning "This certificate order has already been completed. Use -Force to overwrite the current certificate." } - - - - - - <# - .SYNOPSIS - Request a new certificate - - .DESCRIPTION - This is the primary function for this module and is capable executing the entire ACME certificate request process from start to finish without any prerequisite steps. However, utilizing the module's other functions can enable more complicated workflows and reduce the number of parameters you need to supply to this function. - - .PARAMETER Domain - One or more domain names to include in this order/certificate. The first one in the list will be considered the "MainDomain" and be set as the subject of the finalized certificate. - - .PARAMETER CSRPath - The path to a pre-made certificate request file in PEM (Base64) format. This is useful for appliances that need to generate their own keys and cert requests. - - .PARAMETER Name - The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. - - .PARAMETER Contact - One or more email addresses to associate with this certificate. These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. - - .PARAMETER CertKeyLength - The type and size of private key to use for the certificate. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to '2048'. - - .PARAMETER AlwaysNewKey - If specified, the order will be configured to always generate a new private key during each renewal. Otherwise, the old key is re-used if it exists. - - .PARAMETER AcceptTOS - This switch is required when creating a new account as part of a certificate request. It implies you have read and accepted the Terms of Service for the ACME server you are connected to. The first time you connect to an ACME server, a link to the Terms of Service should have been displayed. - - .PARAMETER AccountKeyLength - The type and size of private key to use for the account associated with this certificate. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to 'ec-256'. - - .PARAMETER DirectoryUrl - Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2) and LE_STAGE (LetsEncrypt Staging v2). Defaults to 'LE_PROD'. - - .PARAMETER Plugin - One or more validation plugin names to use for this order's challenges. If no plugin is specified, the DNS "Manual" plugin will be used. If the same plugin is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. - - .PARAMETER PluginArgs - A hashtable containing the plugin arguments to use with the specified Plugin list. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. - - .PARAMETER DnsAlias - One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. If the same alias is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. - - .PARAMETER OCSPMustStaple - If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. - - .PARAMETER FriendlyName - Set a friendly name for the certificate. This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. Defaults to the first item in the Domain parameter. - - .PARAMETER PfxPass - Set the export password for generated PFX files. Defaults to 'poshacme'. When the PfxPassSecure parameter is specified, this parameter is ignored. - - .PARAMETER PfxPassSecure - Set the export password for generated PFX files using a SecureString value. When this parameter is specified, the PfxPass parameter is ignored. - - .PARAMETER Install - If specified, the certificate generated for this order will be imported to the local computer's Personal certificate store. Using this switch requires running the command from an elevated PowerShell session. - - .PARAMETER UseSerialValidation - If specified, the names in the order will be validated individually rather than all at once. This can significantly increase the time it takes to process validations and should only be used for plugins that require it. The plugin's usage guide should indicate whether it is required. - - .PARAMETER Force - If specified, a new certificate order will always be created regardless of the status of a previous order for the same primary domain. Otherwise, the previous order still in progress will be used instead. - - .PARAMETER DnsSleep - Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. Default is 120. - - .PARAMETER ValidationTimeout - Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. Default is 60. If the timeout is exceeded, an error will be thrown. - - .PARAMETER PreferredChain - If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. - - .EXAMPLE - New-PACertificate site1.example.com -AcceptTOS - - This is the minimum parameters needed to generate a certificate for the specified site if you haven't already setup an ACME account. It will prompt you to add the required DNS TXT record manually. Once you have an account created, you can omit the -AcceptTOS parameter. - - .EXAMPLE - New-PACertificate 'site1.example.com','site2.example.com' -Contact admin@example.com - - Request a SAN certificate with multiple names and have notifications sent to the specified email address. - - .EXAMPLE - New-PACertificate '*.example.com','example.com' - - Request a wildcard certificate that includes the root domain as a SAN. - - .EXAMPLE - $pluginArgs = @{FBServer='fb.example.com'; FBCred=(Get-Credential)} - PS C:\>New-PACertificate site1.example.com -Plugin Flurbog -PluginArgs $pluginArgs - - Request a certificate using the hypothetical Flurbog DNS plugin that requires a server name and set of credentials. - - .EXAMPLE - $pluginArgs = @{FBServer='fb.example.com'; FBCred=(Get-Credential)} - PS C:\>New-PACertificate site1.example.com -Plugin Flurbog -PluginArgs $pluginArgs -DnsAlias validate.alt-example.com - - This is the same as the previous example except that it's telling the Flurbog plugin to write to an alias domain. This only works if you have already created a CNAME record for _acme-challenge.site1.example.com that points to validate.alt-example.com. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Submit-Renewal - - .LINK - Get-PAPlugin - - #> } diff --git a/Posh-ACME/Public/New-PAOrder.ps1 b/Posh-ACME/Public/New-PAOrder.ps1 index 5aafc10d..a1b73bde 100644 --- a/Posh-ACME/Public/New-PAOrder.ps1 +++ b/Posh-ACME/Public/New-PAOrder.ps1 @@ -318,104 +318,4 @@ function New-PAOrder { } return $order - - - - - <# - .SYNOPSIS - Create a new order on the current ACME account. - - .DESCRIPTION - Creating an ACME order is the first step of the certificate request process. To create a SAN certificate with multiple names, include them all in an array for the -Domain parameter. The first name in the list will be considered the "MainDomain" and will also be in the certificate subject field. LetsEncrypt currently limits SAN certificates to 100 names. - - Be aware that only one order per MainDomain per ACME Account can exist with this module. Subsequent orders that have the same MainDomain will overwrite previous orders and certificates under the assumption that you are trying to renew or update the certificate with additional names. - - .PARAMETER Domain - One or more domain names to include in this order/certificate. The first one in the list will be considered the "MainDomain" and be set as the subject of the finalized certificate. - - .PARAMETER CSRPath - The path to a pre-made certificate request file in PEM (Base64) format. This is useful for appliances that need to generate their own keys and cert requests. - - .PARAMETER KeyLength - The type and size of private key to use. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to '2048'. - - .PARAMETER KeyFile - The path to an existing EC or RSA private key file. This will attempt to create the order using the specified key as the certificate's private key. - - .PARAMETER Name - The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. If not specified, defaults to the first domain in the order. - - .PARAMETER Plugin - One or more validation plugin names to use for this order's challenges. If no plugin is specified, the DNS "Manual" plugin will be used. If the same plugin is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. - - .PARAMETER PluginArgs - A hashtable containing the plugin arguments to use with the specified Plugin list. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. - - .PARAMETER DnsAlias - One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. If the same alias is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. - - .PARAMETER OCSPMustStaple - If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. - - .PARAMETER AlwaysNewKey - If specified, the order will be configured to always generate a new private key during each renewal. Otherwise, the old key is re-used if it exists. - - .PARAMETER FriendlyName - Set a friendly name for the certificate. This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. Defaults to the first item in the Domain parameter. - - .PARAMETER PfxPass - Set the export password for generated PFX files. Defaults to 'poshacme'. When the PfxPassSecure parameter is specified, this parameter is ignored. - - .PARAMETER PfxPassSecure - Set the export password for generated PFX files using a SecureString value. When this parameter is specified, the PfxPass parameter is ignored. - - .PARAMETER Install - If specified, the certificate generated for this order will be imported to the local computer's Personal certificate store. - - .PARAMETER UseSerialValidation - If specified, the names in the order will be validated individually rather than all at once. This can significantly increase the time it takes to process validations and should only be used for plugins that require it. The plugin's usage guide should indicate whether it is required. - - .PARAMETER DnsSleep - Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. - - .PARAMETER ValidationTimeout - Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. If the timeout is exceeded, an error will be thrown. - - .PARAMETER PreferredChain - If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. - - .PARAMETER Force - If specified, confirmation prompts that may have been generated will be skipped. - - .EXAMPLE - New-PAOrder site1.example.com - - Create a new order for the specified domain using the default key length. - - .EXAMPLE - New-PAOrder -Domain 'site1.example.com','site2.example.com','site3.example.com' - - Create a new SAN order for the specified domains using the default key length. - - .EXAMPLE - New-PAOrder site1.example.com 4096 - - Create a new order for the specified domain using an RSA 4096 bit key. - - .EXAMPLE - New-PAOrder 'site1.example.com','site2.example.com' ec-384 -Force - - Create a new SAN order for the specified domains using an ECC key using P-384 curve that ignores any confirmations. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAOrder - - .LINK - Set-PAOrder - - #> } diff --git a/Posh-ACME/Public/Publish-Challenge.ps1 b/Posh-ACME/Public/Publish-Challenge.ps1 index 9c72b7d7..7aa33258 100644 --- a/Posh-ACME/Public/Publish-Challenge.ps1 +++ b/Posh-ACME/Public/Publish-Challenge.ps1 @@ -56,60 +56,4 @@ function Publish-Challenge { Add-HttpChallenge -Domain $Domain -Token $Token -Body $keyAuth @PluginArgs } - - - - <# - .SYNOPSIS - Publish a challenge using the specified plugin. - - .DESCRIPTION - Based on the type of validation plugin specified, this function will publish either a DNS TXT record or an HTTP challenge file for the given domain and token value that satisfies the dns-01 or http-01 challenge specification. - - Depending on the plugin, calling Save-Challenge may be required to commit changes made by Publish-Challenge. If multiple challenges are being published, make all Publish-Challenge calls first. Then, Save-Challenge once to commit them all. - - .PARAMETER Domain - The domain name that the challenge will be published for. Wildcard domains should have the "*." removed and can only be used with DNS based validation plugins. - - .PARAMETER Account - The account object associated with the order that requires the challenge. - - .PARAMETER Token - The token value from the appropriate challenge in an authorization object that matches the plugin type. - - .PARAMETER Plugin - The name of the validation plugin to use. Use Get-PAPlugin to display a list of available plugins. - - .PARAMETER PluginArgs - A hashtable containing the plugin arguments to use with the specified plugin. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. - - .PARAMETER DnsAlias - When using DNS Alias support with DNS validation plugins, the alias domain that the TXT record will be written to. This should be the complete FQDN including the '_acme-challenge.' prefix if necessary. This field is ignored for non-DNS validation plugins. - - .EXAMPLE - $auths = Get-PAOrder | Get-PAAuthorization - PS C:\>Publish-Challenge $auths[0].DNSId (Get-PAAccount) $auths[0].DNS01Token Manual @{} - - Publish a DNS challenge for the first authorization in the current order using the Manual DNS plugin. - - .EXAMPLE - $pArgs = @{Param1='asdf';Param2=1234} - PS C:\>$acct = Get-PAAccount - PS C:\>Publish-Challenge example.com $acct MyPlugin $pArgs -Token faketoken - - Publish a challenge for example.com using a fictitious plugin and arguments. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Unpublish-Challenge - - .LINK - Save-Challenge - - .LINK - Get-PAPlugin - - #> } diff --git a/Posh-ACME/Public/Remove-PAAccount.ps1 b/Posh-ACME/Public/Remove-PAAccount.ps1 index 52e5879e..99466e97 100644 --- a/Posh-ACME/Public/Remove-PAAccount.ps1 +++ b/Posh-ACME/Public/Remove-PAAccount.ps1 @@ -53,45 +53,4 @@ function Remove-PAAccount { } } - - - - - - <# - .SYNOPSIS - Remove an ACME account and all associated orders and certificates from the local profile. - - .DESCRIPTION - This function removes the ACME account from the local profile which also removes any associated orders and certificates. It will not remove or cleanup copies of certificates that have been exported or installed elsewhere. It will also not deactivate the account on the ACME server without using -Deactivate. However, with the account's private key it can't be recovered from the server. - - .PARAMETER ID - The account id value as returned by the ACME server. - - .PARAMETER Deactivate - If specified, a request will be sent to the associated ACME server to deactivate the account. Clients may wish to do this if the account key is compromised or decommissioned. - - .PARAMETER Force - If specified, interactive confirmation prompts will be skipped. - - .EXAMPLE - Remove-PAAccount 12345 - - Remove the specified account without deactivation. - - .EXAMPLE - Get-PAAccount | Remove-PAAccount -Deactivate -Force - - Remove the current account after deactivating it and skip confirmation prompts. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAAccount - - .LINK - New-PAAccount - - #> } diff --git a/Posh-ACME/Public/Remove-PAOrder.ps1 b/Posh-ACME/Public/Remove-PAOrder.ps1 index c01974f3..29e3373f 100644 --- a/Posh-ACME/Public/Remove-PAOrder.ps1 +++ b/Posh-ACME/Public/Remove-PAOrder.ps1 @@ -74,44 +74,4 @@ function Remove-PAOrder { } } - - <# - .SYNOPSIS - Remove an ACME order from the local profile. - - .DESCRIPTION - This function removes the reference to the order from the local profile which also removes any associated certificate and private key. It will not remove or cleanup copies of the certificate that have been exported or installed elsewhere. It will also not revoke the certificate unless -RevokeCert is used. The ACME server may retain a reference to the order until it decides to delete it. - - .PARAMETER MainDomain - The primary domain for the order. For a SAN order, this was the first domain in the list when creating the order. - - .PARAMETER Name - The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. - - .PARAMETER RevokeCert - If specified and there is a currently valid certificate associated with the order, the certificate will be revoked before deleting the order. This is not required, but generally a good practice if the certificate is no longer being used. - - .PARAMETER Force - If specified, interactive confirmation prompts will be skipped. - - .EXAMPLE - Remove-PAOrder site1.example.com - - Remove the specified order without revoking the certificate. - - .EXAMPLE - Get-PAOrder -List | Remove-PAOrder -RevokeCert -Force - - Remove all orders associated with the current account, revoke all certificates, and skip confirmation prompts. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAOrder - - .LINK - New-PAOrder - - #> } diff --git a/Posh-ACME/Public/Remove-PAServer.ps1 b/Posh-ACME/Public/Remove-PAServer.ps1 index 704092f0..4ce9ee3f 100644 --- a/Posh-ACME/Public/Remove-PAServer.ps1 +++ b/Posh-ACME/Public/Remove-PAServer.ps1 @@ -97,43 +97,4 @@ function Remove-PAServer { Import-PAConfig -Level 'Server' } } - - - - - - <# - .SYNOPSIS - Remove an ACME server and all associated accounts, orders, and certificates from the local profile. - - .DESCRIPTION - This function removes the ACME server from the local profile which also removes any associated accounts, orders and certificates. It will not remove or cleanup copies of certificates that have been exported or installed elsewhere. It will not revoke any certificates that are still valid. It will not deactivate the accounts on the ACME server unless the -DeactivateAccounts switch is specified. - - .PARAMETER DirectoryUrl - Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2) and LE_STAGE (LetsEncrypt Staging v2). - - .PARAMETER Name - The name of the ACME server. The parameter is ignored if DirectoryUrl is specified. - - .PARAMETER DeactivateAccounts - If specified, an attempt will be made to deactivate the accounts in this profile before deletion. Clients may wish to do this if the account key is compromised or being decommissioned. - - .PARAMETER Force - If specified, interactive confirmation prompts will be skipped. - - .EXAMPLE - Remove-PAServer LE_STAGE - - Remove the staging server without deactivating accounts. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAServer - - .LINK - Set-PAServer - - #> } diff --git a/Posh-ACME/Public/Revoke-PAAuthorization.ps1 b/Posh-ACME/Public/Revoke-PAAuthorization.ps1 index 9586fb82..90557740 100644 --- a/Posh-ACME/Public/Revoke-PAAuthorization.ps1 +++ b/Posh-ACME/Public/Revoke-PAAuthorization.ps1 @@ -92,50 +92,4 @@ function Revoke-PAAuthorization { } } - - - - <# - .SYNOPSIS - Revoke the authorization associated with an ACME identifier. - - .DESCRIPTION - Many ACME server implementations cache succesful authorizations for a certain amount of time to avoid requiring an account to re-authorize identifiers for additional orders submitted during the cache window. - - This can make testing authorization challenges in a client more cumbersome by having to create new orders with uncached identifiers. This function allows you to revoke those cached authorizations so that subsequent orders will go through the full challenge validation process. - - .PARAMETER AuthURLs - One or more authorization URLs. You also pipe in one or more PoshACME.PAOrder objects. - - .PARAMETER Account - An existing ACME account object such as the output from Get-PAAccount. If no account is specified, the current account will be used. - - .PARAMETER Force - If specified, no confirmation prompts will be presented. - - .EXAMPLE - Revoke-PAAuthorization https://acme.example.com/authz/1234567 - - Revoke the authorization for the specified URL using the current account. - - .EXAMPLE - Get-PAOrder | Revoke-PAAuthorization -Force - - Revoke all authorizations for the current order on the current account without confirmation prompts. - - .EXAMPLE - Get-PAOrder -List | Revoke-PAAuthorizations - - Revoke all authorizations for all orders on the current account. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAAuthorization - - .LINK - Get-PAOrder - - #> } diff --git a/Posh-ACME/Public/Revoke-PACertificate.ps1 b/Posh-ACME/Public/Revoke-PACertificate.ps1 index a28e7472..cd9d6dbd 100644 --- a/Posh-ACME/Public/Revoke-PACertificate.ps1 +++ b/Posh-ACME/Public/Revoke-PACertificate.ps1 @@ -165,59 +165,6 @@ function Revoke-PACertificate { } } - - <# - .SYNOPSIS - Revoke an ACME certificate - - .DESCRIPTION - Revokes a previously created ACME certificate. - - .PARAMETER MainDomain - The primary domain associated with the certificate to be revoked. - - .PARAMETER Name - The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. - - .PARAMETER CertFile - A PEM-encoded certificate file to be revoked. - - .PARAMETER KeyFile - The PEM-encoded private key associated with CertFile. If not specified, the current ACME account will be used to sign the request. - - .PARAMETER Reason - The reason for cert revocation. This must be one of the reasons defined in RFC 5280 including keyCompromise, cACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, removeFromCRL, privilegeWithdrawn, and aACompromise. NOTE: Not all reason codes are supported by all ACME certificate authorities. - - .PARAMETER Force - If specified, the revocation confirmation prompt will be skipped. - - .EXAMPLE - Revoke-PACertificate example.com - - Revokes the certificate for the specified domain. - - .EXAMPLE - Get-PAOrder | Revoke-PACertificate -Force - - Revokes the certificate associated with the current order and skips the confirmation prompt. - - .EXAMPLE - Get-PACertificate | Revoke-PACertificate -Reason keyCompromise - - Revokes the current certificate with the specified reason. - - .EXAMPLE - Revoke-PACertificate -CertFile mycert.crt -KeyFile mycert.key - - Revokes the specified cert using the specified private key. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - New-PACertificate - - #> } # Define an enum to represent the revocations reasons defined in RFC 5280 diff --git a/Posh-ACME/Public/Save-Challenge.ps1 b/Posh-ACME/Public/Save-Challenge.ps1 index 37facf84..6d011556 100644 --- a/Posh-ACME/Public/Save-Challenge.ps1 +++ b/Posh-ACME/Public/Save-Challenge.ps1 @@ -33,45 +33,4 @@ function Save-Challenge { Save-HttpChallenge @PluginArgs } - - - - <# - .SYNOPSIS - Commit changes made by Publish-Challenge or Unpublish-Challenge. - - .DESCRIPTION - Some validation plugins require a finalization step after the Publish or Unpublish functionality to commit and make the changes live. This function should be called once after running all of the Publish-Challenge or Unpublish-Challenge commands. - - For plugins that don't require a commit step, this function may still be run without causing an error, but does nothing. - - .PARAMETER Plugin - The name of the validation plugin to use. Use Get-PAPlugin to display a list of available plugins. - - .PARAMETER PluginArgs - A hashtable containing the plugin arguments to use with the specified plugin. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. - - .EXAMPLE - Save-Challenge Manual @{} - - Commit changes using the Manual DNS plugin that requires no plugin arguments. - - .EXAMPLE - Save-Challenge MyPlugin @{Param1='asdf';Param2=1234} - - Commit changes for a set of challenges using a fictitious plugin and arguments. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Publish-Challenge - - .LINK - Unpublish-Challenge - - .LINK - Get-PAPlugin - - #> } diff --git a/Posh-ACME/Public/Send-ChallengeAck.ps1 b/Posh-ACME/Public/Send-ChallengeAck.ps1 index 1cf72dcb..588f326b 100644 --- a/Posh-ACME/Public/Send-ChallengeAck.ps1 +++ b/Posh-ACME/Public/Send-ChallengeAck.ps1 @@ -44,47 +44,4 @@ function Send-ChallengeAck { } catch { throw } } - - - - - <# - .SYNOPSIS - Notify the ACME server to proceed validating a challenge. - - .DESCRIPTION - Use this after publishing the required resource for one of the challenges from an authorization object. It lets the ACME server know that it should proceed validating that challenge. - - .PARAMETER ChallengeUrl - The URL of the challenge to be validated. - - .PARAMETER Account - The ACME account associated with the challenge. - - .EXAMPLE - $auths = Get-PAOrder | Get-PAAuthorization - - PS C:\>Send-ChallengeAck $auths[0].DNS01Url - - Tell the ACME server to validate the first DNS challenge in the current order. - - .EXAMPLE - $auths = Get-PAOrder | Get-PAAuthorization - - PS C:\>$httpUrls = ($auths | ?{ $_.status -eq 'pending' }).HTTP01Url - PS C:\>$httpUrls | Send-ChallengeAck - - Tell the ACME server to validate all pending HTTP challenges in the current order. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAAuthorization - - .LINK - Submit-ChallengeValidation - - #> - } diff --git a/Posh-ACME/Public/Set-PAAccount.ps1 b/Posh-ACME/Public/Set-PAAccount.ps1 index 37a0cba3..ea75fd9a 100644 --- a/Posh-ACME/Public/Set-PAAccount.ps1 +++ b/Posh-ACME/Public/Set-PAAccount.ps1 @@ -289,94 +289,4 @@ function Set-PAAccount { } } - - - - - - <# - .SYNOPSIS - Set the current ACME account and/or update account details. - - .DESCRIPTION - This function allows you to switch between ACME accounts for a particular server. It also allows you to update the contact information associated with an account, deactivate the account, or replace the account key with a new one. - - .PARAMETER ID - The account id value as returned by the ACME server. If not specified, the function will attempt to use the currently active account. - - .PARAMETER Contact - One or more email addresses to associate with this account. These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. - - .PARAMETER NewName - The new name (id) of this ACME account. - - .PARAMETER UseAltPluginEncryption - If specified, the account will be configured to use a randomly generated AES key to encrypt sensitive plugin parameters on disk instead of using the OS's native encryption methods. This can be useful if the config is being shared across systems or platforms. You can revert to OS native encryption using -UseAltPluginEncryption:$false. - - .PARAMETER ResetAltPluginEncryption - If specified, the existing AES key will be replaced with a new one and existing plugin parameters on disk will be re-encrypted with the new key. If there is no existing key, this parameter is ignored. - - .PARAMETER Deactivate - If specified, a request will be sent to the associated ACME server to deactivate the account. Clients may wish to do this if the account key is compromised or decommissioned. - - .PARAMETER Force - If specified, confirmation prompts for account deactivation will be skipped. - - .PARAMETER KeyRollover - If specified, generate a new account key and replace the current one with it. Clients may choose to do this to recover from a key compromise or proactively mitigate the impact of an unnoticed key compromise. - - .PARAMETER KeyLength - The type and size of private key to use. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to 'ec-256'. - - .PARAMETER KeyFile - The path to an existing EC or RSA private key file. This will attempt to use the specified key as the new ACME account key. - - .PARAMETER NoSwitch - If specified, the currently active account will not change. Useful primarily for bulk updating contact information across accounts. This switch is ignored if no ID is specified. - - .EXAMPLE - Set-PAAccount -ID 1234567 - - Switch to the specified account. - - .EXAMPLE - Set-PAAccount -Contact 'user1@example.com','user2@example.com' - - Set new contacts for the current account. - - .EXAMPLE - Set-PAAccount -ID 1234567 -Contact 'user1@example.com','user2@example.com' - - Set new contacts for the specified account. - - .EXAMPLE - Get-PAAccount -List | Set-PAAccount -Contact user1@example.com -NoSwitch - - Set a new contact for all known accounts without switching from the current. - - .EXAMPLE - Set-PAAccount -Deactivate - - Deactivate the current account. - - .EXAMPLE - Set-PAAccount -KeyRollover -KeyLength ec-384 - - Replace the current account key with a new ECC key using P-384 curve. - - .EXAMPLE - Set-PAAccount -KeyRollover -KeyFile .\mykey.key - - Replace the current account key with a pre-generated private key. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAAccount - - .LINK - New-PAAccount - - #> } diff --git a/Posh-ACME/Public/Set-PAOrder.ps1 b/Posh-ACME/Public/Set-PAOrder.ps1 index 47a3a59b..be293cc8 100644 --- a/Posh-ACME/Public/Set-PAOrder.ps1 +++ b/Posh-ACME/Public/Set-PAOrder.ps1 @@ -320,98 +320,4 @@ function Set-PAOrder { } } - - - - - - <# - .SYNOPSIS - Set the current ACME order, edits an orders properties, or revokes an order's certificate. - - .DESCRIPTION - Switch to a specific ACME order and edit its properties or revoke its certificate. Revoked certificate orders are not deleted and can be re-requested using Submit-Renewal or New-PACertificate. - - .PARAMETER MainDomain - The primary domain for the order. For a SAN order, this was the first domain in the list when creating the order. - - .PARAMETER Name - The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. - - .PARAMETER RevokeCert - If specified, a request will be sent to the associated ACME server to revoke the certificate on this order. Clients may wish to do this if the certificate is decommissioned or the private key has been compromised. A warning will be displayed if the order is not currently valid or the existing certificate file can't be found. - - .PARAMETER Force - If specified, confirmation prompts for certificate revocation will be skipped. - - .PARAMETER NoSwitch - If specified, the currently selected order will not change. Useful primarily for bulk certificate revocation. This switch is ignored if no MainDomain is specified. - - .PARAMETER Plugin - One or more validation plugin names to use for this order's challenges. If no plugin is specified, the DNS "Manual" plugin will be used. If the same plugin is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. - - .PARAMETER PluginArgs - A hashtable containing the plugin arguments to use with the specified Plugin list. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. - - .PARAMETER DnsAlias - One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. If the same alias is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. - - .PARAMETER NewName - The new name for this ACME order. - - .PARAMETER FriendlyName - The friendly name for the certificate and subsequent renewals. This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. Must not be an empty string. - - .PARAMETER PfxPass - The PFX password for the certificate and subsequent renewals. When the PfxPassSecure parameter is specified, this parameter is ignored. - - .PARAMETER PfxPassSecure - The PFX password for the certificate and subsequent renewals using a SecureString value. When this parameter is specified, the PfxPass parameter is ignored. - - .PARAMETER Install - Enables the Install switch for the order. Use -Install:$false to disable the switch on the order. This affects whether the module will automatically import the certificate to the Windows certificate store on subsequent renewals. It will not import the current certificate if it exists. Use Install-PACertificate for that purpose. - - .PARAMETER OCSPMustStaple - If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. - - .PARAMETER DnsSleep - Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. - - .PARAMETER ValidationTimeout - Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. If the timeout is exceeded, an error will be thrown. - - .PARAMETER PreferredChain - If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. - - .PARAMETER AlwaysNewKey - If specified, the order will be configured to always generate a new private key during each renewal. Otherwise, the old key is re-used if it exists. - - .PARAMETER UseSerialValidation - If specified, the names in the order will be validated individually rather than all at once. This can significantly increase the time it takes to process validations and should only be used for plugins that require it. The plugin's usage guide should indicate whether it is required. - - .EXAMPLE - Set-PAOrder site1.example.com - - Switch to the specified domain's order. - - .EXAMPLE - Set-PAOrder -RevokeCert - - Revoke the current order's certificate. - - .EXAMPLE - Set-PAOrder -FriendlyName 'new friendly name' - - Edit the friendly name for the current order and certificate if it exists. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAOrder - - .LINK - New-PAOrder - - #> } diff --git a/Posh-ACME/Public/Set-PAServer.ps1 b/Posh-ACME/Public/Set-PAServer.ps1 index 984faa87..03eb6d9a 100644 --- a/Posh-ACME/Public/Set-PAServer.ps1 +++ b/Posh-ACME/Public/Set-PAServer.ps1 @@ -193,56 +193,4 @@ function Set-PAServer { Write-Host "Please review the Terms of Service here: $($script:Dir.meta.termsOfService)" } } - - - <# - .SYNOPSIS - Set the current ACME server and/or its configuration. - - .DESCRIPTION - Use this function to set the current ACME server or change a server's configuration settings. - - .PARAMETER DirectoryUrl - Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2), LE_STAGE (LetsEncrypt Staging v2), BUYPASS_PROD (BuyPass.com Production), and BUYPASS_TEST (BuyPass.com Testing). - - .PARAMETER Name - The name of the ACME server. The parameter is ignored if DirectoryUrl is specified. - - .PARAMETER NewName - The new name of this ACME server. - - .PARAMETER SkipCertificateCheck - If specified, disable certificate validation while using this server. This should not be necessary except in development environments where you are connecting to a self-hosted ACME server. - - .PARAMETER DisableTelemetry - If specified, telemetry data will not be sent to the Posh-ACME team for actions associated with this server. The telemetry data that gets sent by default includes Posh-ACME version, PowerShell version, and generic OS platform (Windows/Linux/MacOS). - - .PARAMETER NoRefresh - If specified, the ACME server will not be re-queried for updated endpoints or a fresh nonce. - - .PARAMETER NoSwitch - If specified, the currently active ACME server will not be changed to the server being modified. - - .EXAMPLE - Set-PAServer LE_PROD - - Switch to the LetsEncrypt production server using the short name. - - .EXAMPLE - Set-PAServer -DirectoryUrl https://myacme.example.com/directory - - Switch to the specified ACME server using the directory URL. - - .EXAMPLE - (Get-PAServer -List)[0] | Set-PAServer - - Switch to the first ACME server returned by "Get-PAServer -List" - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAServer - - #> } diff --git a/Posh-ACME/Public/Submit-ChallengeValidation.ps1 b/Posh-ACME/Public/Submit-ChallengeValidation.ps1 index 0d1d5e75..179f0818 100644 --- a/Posh-ACME/Public/Submit-ChallengeValidation.ps1 +++ b/Posh-ACME/Public/Submit-ChallengeValidation.ps1 @@ -207,39 +207,4 @@ function Submit-ChallengeValidation { } } - - - - - - <# - .SYNOPSIS - Respond to authorization challenges for an ACME order and wait for the ACME server to validate them. - - .DESCRIPTION - An ACME order contains an authorization object for each domain in the order. The client must complete at least one of a set of challenges for each authorization in order to prove they own the domain. Once complete, the client asks the server to validate each challenge and waits for the server to do so and update the authorization status. - - .PARAMETER Order - The ACME order to perform the validations against. The order object must be associated with the currently active ACME account. - - .EXAMPLE - Submit-ChallengeValidation - - Begin challenge validation on the current order. - - .EXAMPLE - Get-PAOrder | Submit-ChallengeValidation - - Begin challenge validation on the current order. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAOrder - - .LINK - New-PAOrder - - #> } diff --git a/Posh-ACME/Public/Submit-OrderFinalize.ps1 b/Posh-ACME/Public/Submit-OrderFinalize.ps1 index 203e3a7e..82e6dc2e 100644 --- a/Posh-ACME/Public/Submit-OrderFinalize.ps1 +++ b/Posh-ACME/Public/Submit-OrderFinalize.ps1 @@ -111,37 +111,4 @@ function Submit-OrderFinalize { catch { $PSCmdlet.ThrowTerminatingError($_) } } - - - - <# - .SYNOPSIS - Finalize a certificate order - - .DESCRIPTION - Finalizing a certificate order will send a new certificate request to the server and then wait for it to become valid or invalid. - - .PARAMETER Order - The ACME order to finalize. The order object must be associated with the currently active ACME account. - - .EXAMPLE - Submit-OrderFinalize - - Finalize the current order. - - .EXAMPLE - Get-PAOrder example.com | Submit-OrderFinalize - - Finalize the specified order. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Get-PAOrder - - .LINK - Submit-ChallengeValidation - - #> } diff --git a/Posh-ACME/Public/Submit-Renewal.ps1 b/Posh-ACME/Public/Submit-Renewal.ps1 index e88a2414..1941ac95 100644 --- a/Posh-ACME/Public/Submit-Renewal.ps1 +++ b/Posh-ACME/Public/Submit-Renewal.ps1 @@ -164,72 +164,4 @@ function Submit-Renewal { } } - - - - - - <# - .SYNOPSIS - Renew one or more certificates. - - .DESCRIPTION - This function allows you to renew one more more previously completed certificate orders. You can choose to renew a specific order or set of orders, all orders for the current account, or all orders for all accounts. - - .PARAMETER MainDomain - The primary domain associated with an order. This is the domain that goes in the certificate's subject. - - .PARAMETER Name - The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. - - .PARAMETER AllOrders - If specified, renew all valid orders on the current account. Orders that have not reached the renewal window will be skipped unless -Force is used. - - .PARAMETER AllAccounts - If specified, renew all valid orders on all valid accounts in this profile. Orders that have not reached the renewal window will be skipped unless -Force is used. - - .PARAMETER Force - If specified, an order that hasn't reached its renewal window will not throw an error and will not be skipped when using either of the -All parameters. - - .PARAMETER NoSkipManualDns - If specified, orders that utilize the Manual DNS plugin will not be skipped and user interaction may be required to complete the process. Otherwise, orders that utilize the Manual DNS plugin will be skipped. - - .PARAMETER PluginArgs - A hashtable containing an updated set of plugin arguments to use with the renewal. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. - - .EXAMPLE - Submit-Renewal - - Renew the current order on the current account. - - .EXAMPLE - Submit-Renewal -Force - - Renew the current order on the current account even if it hasn't reached its suggested renewal window. - - .EXAMPLE - Submit-Renewal -AllOrders - - Renew all valid orders on the current account that have reached their suggested renewal window. - - .EXAMPLE - Submit-Renewal -AllAccounts - - Renew all valid orders on all valid accounts that have reached their suggested renewal window. - - .EXAMPLE - Submit-Renewal site1.example.com -Force - - Renew the order for the specified site regardless of its renewal window. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - New-PACertificate - - .LINK - Get-PAOrder - - #> } diff --git a/Posh-ACME/Public/Unpublish-Challenge.ps1 b/Posh-ACME/Public/Unpublish-Challenge.ps1 index e6176cda..397ca5df 100644 --- a/Posh-ACME/Public/Unpublish-Challenge.ps1 +++ b/Posh-ACME/Public/Unpublish-Challenge.ps1 @@ -56,60 +56,4 @@ function Unpublish-Challenge { Remove-HttpChallenge -Domain $Domain -Token $Token -Body $keyAuth @PluginArgs } - - - - <# - .SYNOPSIS - Unpublish a challenge using the specified plugin. - - .DESCRIPTION - Based on the type of validation plugin specified, this function will unpublish either a DNS TXT record or an HTTP challenge file for the given domain and token value that satisfies the dns-01 or http-01 challenge specification. - - Depending on the plugin, calling Save-Challenge may be required to commit changes made by Unpublish-Challenge. If multiple challenges are being unpublished, make all Unpublish-Challenge calls first. Then, Save-Challenge once to commit them all. - - .PARAMETER Domain - The domain name that the challenge will be unpublished for. Wildcard domains should have the "*." removed and can only be used with DNS based validation plugins. - - .PARAMETER Account - The account object associated with the order that required the challenge. - - .PARAMETER Token - The token value from the appropriate challenge in an authorization object that matches the plugin type. - - .PARAMETER Plugin - The name of the validation plugin to use. Use Get-PAPlugin to display a list of available plugins. - - .PARAMETER PluginArgs - A hashtable containing the plugin arguments to use with the specified plugin. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. - - .PARAMETER DnsAlias - When using DNS Alias support with DNS validation plugins, the alias domain that the TXT record will be removed from. This should be the complete FQDN including the '_acme-challenge.' prefix if necessary. This field is ignored for non-DNS validation plugins. - - .EXAMPLE - $auths = Get-PAOrder | Get-PAAuthorization - PS C:\>Unpublish-Challenge $auths[0].DNSId (Get-PAAccount) $auths[0].DNS01Token Manual @{} - - Unpublish a DNS challenge for the first authorization in the current order using the Manual DNS plugin. - - .EXAMPLE - $pArgs = @{Param1='asdf';Param2=1234} - PS C:\>$acct = Get-PAAccount - PS C:\>Unpublish-Challenge example.com $acct MyPlugin $pArgs -Token faketoken - - Unpublish a challenge for example.com using a fictitious plugin and arguments. - - .LINK - Project: https://github.com/rmbolger/Posh-ACME - - .LINK - Publish-Challenge - - .LINK - Save-Challenge - - .LINK - Get-PAPlugin - - #> } diff --git a/Posh-ACME/en-US/Posh-ACME-help.xml b/Posh-ACME/en-US/Posh-ACME-help.xml new file mode 100644 index 00000000..ae2b29ae --- /dev/null +++ b/Posh-ACME/en-US/Posh-ACME-help.xml @@ -0,0 +1,8107 @@ + + + + + Complete-PAOrder + Complete + PAOrder + + Exports cert files for a completed order and adds suggested renewal window to the order. + + + + Once an ACME order is finalized, the signed certificate and chain can be downloaded and combined with the local private key to generate the supported PEM and PFX files on disk. This function will also calculate the renewal window based on the signed certificate's expiration date and update the order object with that info. If the Install flag is set, this function will attempt to import the certificate into the Windows certificate store. + + + + Complete-PAOrder + + Order + + The order object to complete which must be associated with the currently active ACME account. + + Object + + Object + + + None + + + + + + Order + + The order object to complete which must be associated with the currently active ACME account. + + Object + + Object + + + None + + + + + + PoshACME.PAOrder + + + An order object as returned by Get-PAOrder. + + + + + + + PoshACME.PACertificate + + + The certificate object for the order. + + + + + + + + + ------------ Example 1: Complete the current order ------------ + Complete-PAOrder + + + + + + + ------------- Example 2: Complete a specific order ------------- + Get-PAOrder example.com | Complete-PAOrder + + + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Complete-PAOrder/ + + + Get-PAOrder + + + + New-PAOrder + + + + + + + Export-PAAccountKey + Export + PAAccountKey + + Export an ACME account private key. + + + + The account key is saved as an unencrypted Base64 encoded PEM file. + + + + Export-PAAccountKey + + ID + + The ACME account ID value. + + String + + String + + + None + + + OutputFile + + The path to the file to write the key data to. + + String + + String + + + None + + + Force + + If specified and the output file already exists, it will be overwritten. Without the switch, a confirmation prompt will be presented. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + + + ID + + The ACME account ID value. + + String + + String + + + None + + + OutputFile + + The path to the file to write the key data to. + + String + + String + + + None + + + Force + + If specified and the output file already exists, it will be overwritten. Without the switch, a confirmation prompt will be presented. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + + + + ---------- Example 1: Export the current account key ---------- + Export-PAAccountKey -OutputFile .\mykey.pem + + Exports the current ACME account's key to the specified file. + + + + + --------- Example 2: Export the specified account key --------- + Export-PAAccountKey 12345 -OutputFile .\mykey.pem -Force + + Exports the specified ACME account's key to the specified file and overwrites it if necessary. + + + + + ------ Example 3: Backup all account keys to the desktop ------ + $fldr = Join-Path ([Environment]::GetFolderPath('Desktop')) 'AcmeAccountKeys' +New-Item -ItemType Directory -Force -Path $fldr | Out-Null +Get-PAAccount -List | %{ + Export-PAAccountKey $_.ID -OutputFile "$fldr\$($_.ID).key" -Force +} + + Backup all account keys for this ACME server to a folder on the desktop. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Export-PAAccountKey/ + + + Get-PAAccount + + + + + + + Get-KeyAuthorization + Get + KeyAuthorization + + Calculate a key authorization string for a challenge token. + + + + A key authorization is a string that expresses a domain holder's authorization for a specified key to satisfy a specified challenge, by concatenating the token for the challenge with a key fingerprint. + + + + Get-KeyAuthorization + + Token + + The token string for an ACME challenge. + + String + + String + + + None + + + Account + + The ACME account associated with the challenge. + + Object + + Object + + + None + + + ForDNS + + Enable this switch if you're using the key authorization value for the 'dns-01' challenge type. It will do a few additional manipulation steps on the value that are required for a DNS TXT record. + + + SwitchParameter + + + False + + + + + + Token + + The token string for an ACME challenge. + + String + + String + + + None + + + Account + + The ACME account associated with the challenge. + + Object + + Object + + + None + + + ForDNS + + Enable this switch if you're using the key authorization value for the 'dns-01' challenge type. It will do a few additional manipulation steps on the value that are required for a DNS TXT record. + + SwitchParameter + + SwitchParameter + + + False + + + + + + System.String + + + The token value from an ACME challenge object. + + + + + + + System.String + + + The key authorization value. + + + + + + + + + -------------------------- Example 1 -------------------------- + Get-KeyAuthorization 'XxXxXxXxXxXx' + + Get the key authorization for the specified token using the current account. + + + + + -------------------------- Example 2 -------------------------- + (Get-PAOrder | Get-PAAuthorization).DNS01Token | Get-KeyAuthorization + + Get all key authorizations for the DNS challenges in the current order using the current account. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Get-KeyAuthorization/ + + + Get-PAAuthorization + + + + Submit-ChallengeValidation + + + + + + + Get-PAAccount + Get + PAAccount + + Get ACME account details. + + + + Returns details such as Email, key length, and status for one or more ACME accounts previously created. + + + + Get-PAAccount + + ID + + The account id value as returned by the ACME server. 'Name' is also an alias for this parameter. + + String + + String + + + None + + + Refresh + + If specified, any account details returned will be freshly queried from the ACME server (excluding deactivated accounts). Otherwise, cached details will be returned. + + + SwitchParameter + + + False + + + ExtraParams + + This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. + + Object + + Object + + + None + + + + Get-PAAccount + + List + + If specified, the details for all accounts will be returned. + + + SwitchParameter + + + False + + + Status + + A Status string to filter the list of accounts with. + + String + + String + + + None + + + Contact + + One or more email addresses to filter the list of accounts with. Returned accounts must match exactly (not including the order). + + String[] + + String[] + + + None + + + KeyLength + + The type and size of private key to filter the list of accounts with. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. + + String[] + + String[] + + + None + + + Refresh + + If specified, any account details returned will be freshly queried from the ACME server (excluding deactivated accounts). Otherwise, cached details will be returned. + + + SwitchParameter + + + False + + + ExtraParams + + This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. + + Object + + Object + + + None + + + + + + ID + + The account id value as returned by the ACME server. 'Name' is also an alias for this parameter. + + String + + String + + + None + + + List + + If specified, the details for all accounts will be returned. + + SwitchParameter + + SwitchParameter + + + False + + + Status + + A Status string to filter the list of accounts with. + + String + + String + + + None + + + Contact + + One or more email addresses to filter the list of accounts with. Returned accounts must match exactly (not including the order). + + String[] + + String[] + + + None + + + KeyLength + + The type and size of private key to filter the list of accounts with. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. + + String[] + + String[] + + + None + + + Refresh + + If specified, any account details returned will be freshly queried from the ACME server (excluding deactivated accounts). Otherwise, cached details will be returned. + + SwitchParameter + + SwitchParameter + + + False + + + ExtraParams + + This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. + + Object + + Object + + + None + + + + + + + PoshACME.PAAccount + + + An account object. + + + + + + + + + -------------------------- Example 1 -------------------------- + Get-PAAccount + + Get cached ACME account details for the currently selected account. + + + + + -------------------------- Example 2 -------------------------- + Get-PAAccount -ID 1234567 + + Get cached ACME account details for the specified account ID. + + + + + -------------------------- Example 3 -------------------------- + Get-PAAccount -List + + Get all cached ACME account details. + + + + + -------------------------- Example 4 -------------------------- + Get-PAAccount -Refresh + + Get fresh ACME account details for the currently selected account. + + + + + -------------------------- Example 5 -------------------------- + Get-PAAccount -List -Refresh + + Get fresh ACME account details for all accounts. + + + + + -------------------------- Example 6 -------------------------- + Get-PAAccount -List -Contact user1@example.com + + Get cached ACME account details for all accounts that have user1@example.com as the only contact. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Get-PAAccount/ + + + Set-PAAccount + + + + New-PAAccount + + + + + + + Get-PAAuthorization + Get + PAAuthorization + + Get the authorizations associated with a particular order or set of authorization URLs. + + + + Returns details such as fqdn, status, expiration, and challenges for one or more ACME authorizations. + + + + Get-PAAuthorization + + AuthURLs + + One or more authorization URLs. You also pipe in one or more PoshACME.PAOrder objects. + + String[] + + String[] + + + None + + + Account + + An existing ACME account object such as the output from Get-PAAccount. If no account is specified, the current account will be used. + + Object + + Object + + + None + + + + + + AuthURLs + + One or more authorization URLs. You also pipe in one or more PoshACME.PAOrder objects. + + String[] + + String[] + + + None + + + Account + + An existing ACME account object such as the output from Get-PAAccount. If no account is specified, the current account will be used. + + Object + + Object + + + None + + + + + + System.String + + + The URI of the authorization object. + + + + + + + PoshACME.PAAuthorization + + + An authorization object. + + + + + + + + + -------------------------- Example 1 -------------------------- + Get-PAAuthorization https://acme.example.com/authz/1234567 + + Get the authorization for the specified URL. + + + + + -------------------------- Example 2 -------------------------- + Get-PAOrder | Get-PAAuthorization + + Get the authorizations for the current order on the current account. + + + + + -------------------------- Example 3 -------------------------- + Get-PAOrder -List | Get-PAAuthorization + + Get the authorizations for all orders on the current account. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Get-PAAuthorization/ + + + Get-PAOrder + + + + New-PAOrder + + + + + + + Get-PACertificate + Get + PACertificate + + Get ACME certificate details. + + + + Returns details such as Thumbprint, Subject, Validity, SANs, and file locations for one or more ACME certificates previously created. + + + + Get-PACertificate + + MainDomain + + The primary domain associated with the certificate. This is the domain that goes in the certificate's subject. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + + Get-PACertificate + + List + + If specified, the details for all completed certificates will be returned for the current account. + + + SwitchParameter + + + False + + + + + + MainDomain + + The primary domain associated with the certificate. This is the domain that goes in the certificate's subject. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + List + + If specified, the details for all completed certificates will be returned for the current account. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + PoshACME.PACertificate + + + A certificate object. + + + + + + + + + -------------------------- Example 1 -------------------------- + Get-PACertificate + + Get cached ACME order details for the currently selected order. + + + + + -------------------------- Example 2 -------------------------- + Get-PACertificate site.example.com + + Get cached ACME order details for the specified domain. + + + + + -------------------------- Example 3 -------------------------- + Get-PACertificate -List + + Get all cached ACME order details. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Get-PACertificate/ + + + New-PACertificate + + + + + + + Get-PAOrder + Get + PAOrder + + Get ACME order details. + + + + Returns details such as Domains, key length, expiration, and status for one or more ACME orders previously created. + + + + Get-PAOrder + + MainDomain + + The primary domain associated with the order. This is the domain that goes in the certificate's subject. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + Refresh + + If specified, any order details returned will be freshly queried from the ACME server. Otherwise, cached details will be returned. + + + SwitchParameter + + + False + + + + Get-PAOrder + + List + + If specified, the details for all orders will be returned. + + + SwitchParameter + + + False + + + Refresh + + If specified, any order details returned will be freshly queried from the ACME server. Otherwise, cached details will be returned. + + + SwitchParameter + + + False + + + + + + MainDomain + + The primary domain associated with the order. This is the domain that goes in the certificate's subject. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + List + + If specified, the details for all orders will be returned. + + SwitchParameter + + SwitchParameter + + + False + + + Refresh + + If specified, any order details returned will be freshly queried from the ACME server. Otherwise, cached details will be returned. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + PoshACME.PAOrder + + + An order object. + + + + + + + + + -------------------------- Example 1 -------------------------- + Get-PAOrder + + Get cached ACME order details for the currently selected order. + + + + + -------------------------- Example 2 -------------------------- + Get-PAOrder site.example.com + + Get cached ACME order details for the specified domain. + + + + + -------------------------- Example 3 -------------------------- + Get-PAOrder -List + + Get all cached ACME order details. + + + + + -------------------------- Example 4 -------------------------- + Get-PAOrder -Refresh + + Get fresh ACME order details for the currently selected order. + + + + + -------------------------- Example 5 -------------------------- + Get-PAOrder -List -Refresh + + Get fresh ACME order details for all orders. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Get-PAOrder/ + + + Set-PAOrder + + + + New-PAOrder + + + + + + + Get-PAPlugin + Get + PAPlugin + + Show plugin details, help, or launch the online guide. + + + + With no parameters, this function will return a list of built-in validation plugins and their details. + With a Plugin specified, this function will return that plugin's details, help, or launch the online guide depending on which switches are specified. + + + + Get-PAPlugin + + Plugin + + The name of a validation plugin. + + String + + String + + + None + + + + Get-PAPlugin + + Plugin + + The name of a validation plugin. + + String + + String + + + None + + + Params + + If specified, returns the plugin-specific parameter sets associated with this plugin. + + + SwitchParameter + + + False + + + + Get-PAPlugin + + Plugin + + The name of a validation plugin. + + String + + String + + + None + + + Guide + + If specified, launch the default web browser to the specified plugin's online guide. This currently only works on Windows and will simply display the URL on other OSes. + + + SwitchParameter + + + False + + + + Get-PAPlugin + + Plugin + + The name of a validation plugin. + + String + + String + + + None + + + Help + + If specified, display the help contents for the specified plugin. + + + SwitchParameter + + + False + + + + + + Plugin + + The name of a validation plugin. + + String + + String + + + None + + + Help + + If specified, display the help contents for the specified plugin. + + SwitchParameter + + SwitchParameter + + + False + + + Guide + + If specified, launch the default web browser to the specified plugin's online guide. This currently only works on Windows and will simply display the URL on other OSes. + + SwitchParameter + + SwitchParameter + + + False + + + Params + + If specified, returns the plugin-specific parameter sets associated with this plugin. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + + + + -------------------------- Example 1 -------------------------- + Get-PAPlugin + + Get the list of available validation plugins + + + + + -------------------------- Example 2 -------------------------- + Get-PAPlugin Route53 -Guide + + Launch the user's default web browser to the online guide for the specified plugin. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Get-PAPlugin/ + + + New-PACertificate + + + + Publish-Challenge + + + + + + + Get-PAPluginArgs + Get + PAPluginArgs + + Retrieve the plugin args for the current or specified order. + + + + An easy way to recall the plugin args used for a given order. + + + + Get-PAPluginArgs + + MainDomain + + The primary domain for the order. For a SAN order, this was the first domain in the list when creating the order. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + + + + MainDomain + + The primary domain for the order. For a SAN order, this was the first domain in the list when creating the order. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + + + + + System.Collections.Hashtable + + + A hashtable containing saved plugin parameters. + + + + + + + + + -------------------------- Example 1 -------------------------- + Get-PAPluginArgs + + Retrieve the plugin args for the current order. + + + + + -------------------------- Example 2 -------------------------- + Get-PAPluginArgs -Name myorder + + Retrieve the plugin args for the specified order. + + + + + -------------------------- Example 3 -------------------------- + Get-PAOrder -Name myorder | Get-PAPluginArgs + + Retrieve the plugin args for the order passed via the pipeline. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Get-PAPluginArgs/ + + + Gew-PAOrder + + + + + + + Get-PAServer + Get + PAServer + + Get ACME server details. + + + + The primary use for this function is checking which ACME server is currently configured. New Account and Cert requests will be directed to this server. It may also be used to refresh server details and list additional servers that have previously been used. + + + + Get-PAServer + + DirectoryUrl + + Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2), LE_STAGE (LetsEncrypt Staging v2), BUYPASS_PROD (BuyPass.com Production), and BUYPASS_TEST (BuyPass.com Testing). + + String + + String + + + None + + + Name + + The name of the ACME server. The parameter is ignored if DirectoryUrl is specified. + + String + + String + + + None + + + Refresh + + If specified, any server details returned will be freshly queried from the ACME server. Otherwise, cached details will be returned. + + + SwitchParameter + + + False + + + Quiet + + If specified, no warning will be thrown if a specified server is not found. + + + SwitchParameter + + + False + + + + Get-PAServer + + List + + If specified, the details for all previously used servers will be returned. + + + SwitchParameter + + + False + + + Refresh + + If specified, any server details returned will be freshly queried from the ACME server. Otherwise, cached details will be returned. + + + SwitchParameter + + + False + + + + + + DirectoryUrl + + Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2), LE_STAGE (LetsEncrypt Staging v2), BUYPASS_PROD (BuyPass.com Production), and BUYPASS_TEST (BuyPass.com Testing). + + String + + String + + + None + + + Name + + The name of the ACME server. The parameter is ignored if DirectoryUrl is specified. + + String + + String + + + None + + + List + + If specified, the details for all previously used servers will be returned. + + SwitchParameter + + SwitchParameter + + + False + + + Refresh + + If specified, any server details returned will be freshly queried from the ACME server. Otherwise, cached details will be returned. + + SwitchParameter + + SwitchParameter + + + False + + + Quiet + + If specified, no warning will be thrown if a specified server is not found. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + PoshACME.PAServer + + + A server object. + + + + + + + + + -------------------------- Example 1 -------------------------- + Get-PAServer + + Get cached ACME server details for the currently selected server. + + + + + -------------------------- Example 2 -------------------------- + Get-PAServer -DirectoryUrl LE_PROD + + Get cached LetsEncrypt production server details using the short name. + + + + + -------------------------- Example 3 -------------------------- + Get-PAServer -List + + Get all cached ACME server details. + + + + + -------------------------- Example 4 -------------------------- + Get-PAServer -DirectoryUrl https://myacme.example.com/directory + + Get cached ACME server details for the specified directory URL. + + + + + -------------------------- Example 5 -------------------------- + Get-PAServer -Refresh + + Get fresh ACME server details for the currently selected server. + + + + + -------------------------- Example 6 -------------------------- + Get-PAServer -List -Refresh + + Get fresh ACME server details for all previously used servers. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Get-PAServer/ + + + Set-PAServer + + + + + + + Install-PACertificate + Install + PACertificate + + Install a Posh-ACME certificate into a Windows certificate store. + + + + This can be used instead of the -Install parameter on New-PACertificate to import a certificate with more configurable options. + + + + Install-PACertificate + + PACertificate + + The PACertificate object you want to import. This can be retrieved using Get-PACertificate and is also returned from things like New-PACertificate and Submit-Renewal. + + Object + + Object + + + None + + + StoreLocation + + Either 'LocalMachine' or 'CurrentUser'. Defaults to 'LocalMachine'. + + String + + String + + + LocalMachine + + + StoreName + + The name of the certificate store to import to. Defaults to 'My'. The store must already exist and will not be created automatically. + + String + + String + + + My + + + NotExportable + + If specified, the private key will not be marked as Exportable. + + + SwitchParameter + + + False + + + + + + PACertificate + + The PACertificate object you want to import. This can be retrieved using Get-PACertificate and is also returned from things like New-PACertificate and Submit-Renewal. + + Object + + Object + + + None + + + StoreLocation + + Either 'LocalMachine' or 'CurrentUser'. Defaults to 'LocalMachine'. + + String + + String + + + LocalMachine + + + StoreName + + The name of the certificate store to import to. Defaults to 'My'. The store must already exist and will not be created automatically. + + String + + String + + + My + + + NotExportable + + If specified, the private key will not be marked as Exportable. + + SwitchParameter + + SwitchParameter + + + False + + + + + + PoshACME.PACertificate + + + A certificate object as returned by Get-PACertificate. + + + + + + + This function only currently works on Windows OSes. A warning will be thrown on other OSes. + + + + + -------------------------- Example 1 -------------------------- + Install-PACertificate + + Install the certificate for the currently selected order to the default LocalMachine\My store. + + + + + -------------------------- Example 2 -------------------------- + Get-PACertificate example.com | Install-PACertificate + + Install the specified certificate to the default LocalMachine\My store. + + + + + -------------------------- Example 3 -------------------------- + Install-PACertificate -StoreLocation 'CurrentUser' -NotExportable + + Install the certificate for the currently selected order to the CurrentUser\My store and mark the private key as not exportable. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Install-PACertificate/ + + + Get-PACertificate + + + + + + + Invoke-HttpChallengeListener + Invoke + HttpChallengeListener + + Starts a local web server to answer pending http-01 ACME challenges. + + + + Uses System.Net.HttpListener to answer http-01 ACME challenges for the current or specified order. If MainDomain is not specified, the current Order is used. + If running on Windows with non-admin privileges, Access Denied errors may be thrown unless a URL reservation is added using `netsh` that matches the HttpListener prefix that will be used. The default wildcard prefix is `http://+/.well-known/acme-challenge` and the netsh command might look something like this: + netsh http add urlacl url=http://+/.well-known/acme-challenge/ user=Everyone + + + + Invoke-HttpChallengeListener + + MainDomain + + The primary domain associated with an order. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + ListenerTimeout + + The timeout in seconds for the webserver. When reached, the http listener stops regardless of challenge status. + + Int32 + + Int32 + + + 120 + + + Port + + The TCP port on which the http listener is listening. 80 by default. This parameter is ignored when ListenerPrefixes is specified. + + Int32 + + Int32 + + + 0 + + + ListenerPrefixes + + Overrides the default wildcard listener prefix with the specified prefixes instead. Be sure to include the port if necessary and a trailing '/' on all included prefixes. See https://docs.microsoft.com/en-us/dotnet/api/system.net.httplistener for details. + + String[] + + String[] + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + + + MainDomain + + The primary domain associated with an order. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + ListenerTimeout + + The timeout in seconds for the webserver. When reached, the http listener stops regardless of challenge status. + + Int32 + + Int32 + + + 120 + + + Port + + The TCP port on which the http listener is listening. 80 by default. This parameter is ignored when ListenerPrefixes is specified. + + Int32 + + Int32 + + + 0 + + + ListenerPrefixes + + Overrides the default wildcard listener prefix with the specified prefixes instead. Be sure to include the port if necessary and a trailing '/' on all included prefixes. See https://docs.microsoft.com/en-us/dotnet/api/system.net.httplistener for details. + + String[] + + String[] + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + PoshACME.PAAuthorization + + + The authorization object associated with the order. + + + + + + > DEPRECATION NOTICE: This function is deprecated and may be removed in a future major version. Please migrate your scripts to use the `WebSelfHost` plugin. + + + + + -------------------------- Example 1 -------------------------- + Invoke-HttpChallengeListener + + Start listener on default port 80 for pending challenges for the current order. + + + + + -------------------------- Example 2 -------------------------- + Invoke-HttpChallengeListener -MainDomain 'test.example.com' -Port 8080 -ListenerTimeout 30 + + Start listener on port 8080 with a timeout of 30 seconds for the specified order. + + + + + -------------------------- Example 3 -------------------------- + $prefixes = 'http://example.com/.well-known/acme-challenge/','http://www.example.com/.well-known/acme-challenge' +Invoke-HttpChallengeListener -ListenerPrefixes $prefixes + + Start listener using the specified prefixes for the current order. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Invoke-HttpChallengeListener/ + + + Get-PAOrder + + + + Get-PAAuthorization + + + + + + + New-PAAccount + New + PAAccount + + Create a new account on the current ACME server. + + + + All certificate requests require a valid account on an ACME server. An contact email address is not required for Let's Encrypt, but other CAs may require it. Without an email address, certificate expiration notices will not be sent. The account KeyLength is a personal preference and does not relate to the KeyLength of the certificates. + + + + New-PAAccount + + Contact + + One or more email addresses to associate with this account. These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. + + String[] + + String[] + + + None + + + KeyLength + + The type and size of private key to use. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to 'ec-256'. + + String + + String + + + Ec-256 + + + ID + + The name of the ACME acccount. + + String + + String + + + None + + + AcceptTOS + + If not specified, the ACME server will throw an error with a link to the current Terms of Service. Using this switch indicates acceptance of those Terms of Service and is required for successful account creation. + + + SwitchParameter + + + False + + + Force + + If specified, confirmation prompts that may have been generated will be skipped. + + + SwitchParameter + + + False + + + ExtAcctKID + + The external account key identifier supplied by the CA. This is required for ACME CAs that require external account binding. + + String + + String + + + None + + + ExtAcctHMACKey + + The external account HMAC key supplied by the CA and encoded as Base64Url. This is required for ACME CAs that require external account binding. + + String + + String + + + None + + + ExtAcctAlgorithm + + The HMAC algorithm to use. Defaults to 'HS256'. + + String + + String + + + HS256 + + + UseAltPluginEncryption + + If specified, the account will be configured to use a randomly generated AES key to encrypt sensitive plugin parameters on disk instead of using the OS's native encryption methods. This can be useful if the config is being shared across systems or platforms. You can revert to OS native encryption using -UseAltPluginEncryption:$false. + + + SwitchParameter + + + False + + + ExtraParams + + This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. + + Object + + Object + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + New-PAAccount + + Contact + + One or more email addresses to associate with this account. These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. + + String[] + + String[] + + + None + + + KeyFile + + The path to an existing EC or RSA private key file. This will attempt to create the account using the specified key as the ACME account key. This can be used to recover/import an existing ACME account if one is already associated with the key. + + String + + String + + + None + + + ID + + The name of the ACME acccount. + + String + + String + + + None + + + AcceptTOS + + If not specified, the ACME server will throw an error with a link to the current Terms of Service. Using this switch indicates acceptance of those Terms of Service and is required for successful account creation. + + + SwitchParameter + + + False + + + OnlyReturnExisting + + If specified, the ACME server will only return the account details if they already exist for the given private key. Otherwise, an error will be thrown. This can be useful to check whether an existing private key is associated with an ACME acount and recover the account details without creating a new account. + + + SwitchParameter + + + False + + + Force + + If specified, confirmation prompts that may have been generated will be skipped. + + + SwitchParameter + + + False + + + ExtAcctKID + + The external account key identifier supplied by the CA. This is required for ACME CAs that require external account binding. + + String + + String + + + None + + + ExtAcctHMACKey + + The external account HMAC key supplied by the CA and encoded as Base64Url. This is required for ACME CAs that require external account binding. + + String + + String + + + None + + + ExtAcctAlgorithm + + The HMAC algorithm to use. Defaults to 'HS256'. + + String + + String + + + HS256 + + + UseAltPluginEncryption + + If specified, the account will be configured to use a randomly generated AES key to encrypt sensitive plugin parameters on disk instead of using the OS's native encryption methods. This can be useful if the config is being shared across systems or platforms. You can revert to OS native encryption using -UseAltPluginEncryption:$false. + + + SwitchParameter + + + False + + + ExtraParams + + This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. + + Object + + Object + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + + + Contact + + One or more email addresses to associate with this account. These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. + + String[] + + String[] + + + None + + + KeyLength + + The type and size of private key to use. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to 'ec-256'. + + String + + String + + + Ec-256 + + + KeyFile + + The path to an existing EC or RSA private key file. This will attempt to create the account using the specified key as the ACME account key. This can be used to recover/import an existing ACME account if one is already associated with the key. + + String + + String + + + None + + + ID + + The name of the ACME acccount. + + String + + String + + + None + + + AcceptTOS + + If not specified, the ACME server will throw an error with a link to the current Terms of Service. Using this switch indicates acceptance of those Terms of Service and is required for successful account creation. + + SwitchParameter + + SwitchParameter + + + False + + + OnlyReturnExisting + + If specified, the ACME server will only return the account details if they already exist for the given private key. Otherwise, an error will be thrown. This can be useful to check whether an existing private key is associated with an ACME acount and recover the account details without creating a new account. + + SwitchParameter + + SwitchParameter + + + False + + + Force + + If specified, confirmation prompts that may have been generated will be skipped. + + SwitchParameter + + SwitchParameter + + + False + + + ExtAcctKID + + The external account key identifier supplied by the CA. This is required for ACME CAs that require external account binding. + + String + + String + + + None + + + ExtAcctHMACKey + + The external account HMAC key supplied by the CA and encoded as Base64Url. This is required for ACME CAs that require external account binding. + + String + + String + + + None + + + ExtAcctAlgorithm + + The HMAC algorithm to use. Defaults to 'HS256'. + + String + + String + + + HS256 + + + UseAltPluginEncryption + + If specified, the account will be configured to use a randomly generated AES key to encrypt sensitive plugin parameters on disk instead of using the OS's native encryption methods. This can be useful if the config is being shared across systems or platforms. You can revert to OS native encryption using -UseAltPluginEncryption:$false. + + SwitchParameter + + SwitchParameter + + + False + + + ExtraParams + + This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. + + Object + + Object + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + PoshACME.PAAccount + + + An account object. + + + + + + + + + -------------------------- Example 1 -------------------------- + New-PAAccount -AcceptTOS + + Create a new account with no contact email and the default key length. + + + + + -------------------------- Example 2 -------------------------- + New-PAAccount -Contact user1@example.com -AcceptTOS + + Create a new account with the specified email and the default key length. + + + + + -------------------------- Example 3 -------------------------- + New-PAAccount -Contact user1@example.com -KeyLength 4096 -AcceptTOS + + Create a new account with the specified email and an RSA 4096 bit key. + + + + + -------------------------- Example 4 -------------------------- + New-PAAccount -KeyLength 'ec-384' -AcceptTOS -Force + + Create a new account with no contact email and an ECC key using P-384 curve that ignores any confirmations. + + + + + -------------------------- Example 5 -------------------------- + New-PAAccount -KeyFile .\mykey.key -AcceptTOS + + Create a new account using a pre-generated private key file. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/New-PAAccount/ + + + Get-PAAccount + + + + Set-PAAccount + + + + + + + New-PAAuthorization + New + PAAuthorization + + Create a pre-authorization for an ACME identifier. + + + + Instead of creating an ACME order object and satisfying the associated authorization challenges on demand, users may choose to pre-authorize one or more identifiers in advance. When a user later creates an order with pre-authorized identifiers, it will be immediately ready to finalize. + NOTE: Not all ACME servers support pre-authorization. The authorizations created this way also expire the same way they do when associated directly with an order. + + + + New-PAAuthorization + + Domain + + One or more ACME identifiers (usually domain names). + + String[] + + String[] + + + None + + + Account + + An existing ACME account object such as the output from Get-PAAccount. If no account is specified, the current account will be used. + + Object + + Object + + + None + + + + + + Domain + + One or more ACME identifiers (usually domain names). + + String[] + + String[] + + + None + + + Account + + An existing ACME account object such as the output from Get-PAAccount. If no account is specified, the current account will be used. + + Object + + Object + + + None + + + + + + System.String + + + The domain or IP address identifier to authorize. + + + + + + + PoshACME.PAAuthorization + + + An authorization object. + + + + + + + + + -------------------------- Example 1 -------------------------- + $auth = New-PAAuthorization example.com + + Create a new authorization for the specified domain using the current account. + + + + + -------------------------- Example 2 -------------------------- + $auths = 'example.com','www.example.com' | New-PAAuthorization -Account (Get-PAAccount 123) + + Create new authorizations for the specified domains via the pipeline and using the specified account. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/New-PAAuthorization/ + + + Get-PAAuthorization + + + + New-PAOrder + + + + + + + New-PACertificate + New + PACertificate + + Request a new certificate + + + + This is the primary function for this module and is capable executing the entire ACME certificate request process from start to finish without any prerequisite steps. However, utilizing the module's other functions can enable more complicated workflows and reduce the number of parameters you need to supply to this function. + + + + New-PACertificate + + Domain + + One or more domain names to include in this order/certificate. The first one in the list will be considered the "MainDomain" and be set as the subject of the finalized certificate. + + String[] + + String[] + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + Contact + + One or more email addresses to associate with this certificate. These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. + + String[] + + String[] + + + None + + + CertKeyLength + + The type and size of private key to use for the certificate. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to '2048'. + + String + + String + + + 2048 + + + AlwaysNewKey + + If specified, the order will be configured to always generate a new private key during each renewal. Otherwise, the old key is re-used if it exists. + + + SwitchParameter + + + False + + + AcceptTOS + + This switch is required when creating a new account as part of a certificate request. It implies you have read and accepted the Terms of Service for the ACME server you are connected to. The first time you connect to an ACME server, a link to the Terms of Service should have been displayed. + + + SwitchParameter + + + False + + + AccountKeyLength + + The type and size of private key to use for the account associated with this certificate. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to 'ec-256'. + + String + + String + + + Ec-256 + + + DirectoryUrl + + Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2) and LE_STAGE (LetsEncrypt Staging v2). Defaults to 'LE_PROD'. + + String + + String + + + LE_PROD + + + Plugin + + One or more validation plugin names to use for this order's challenges. If no plugin is specified, the DNS "Manual" plugin will be used. If the same plugin is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified Plugin list. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. If the same alias is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + OCSPMustStaple + + If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. + + + SwitchParameter + + + False + + + FriendlyName + + Set a friendly name for the certificate. This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. Defaults to the first item in the Domain parameter. + + String + + String + + + None + + + PfxPass + + Set the export password for generated PFX files. Defaults to 'poshacme'. When the PfxPassSecure parameter is specified, this parameter is ignored. + + String + + String + + + Poshacme + + + PfxPassSecure + + Set the export password for generated PFX files using a SecureString value. When this parameter is specified, the PfxPass parameter is ignored. + + SecureString + + SecureString + + + None + + + Install + + If specified, the certificate generated for this order will be imported to the local computer's Personal certificate store. Using this switch requires running the command from an elevated PowerShell session. + + + SwitchParameter + + + False + + + UseSerialValidation + + If specified, the names in the order will be validated individually rather than all at once. This can significantly increase the time it takes to process validations and should only be used for plugins that require it. The plugin's usage guide should indicate whether it is required. + + + SwitchParameter + + + False + + + Force + + If specified, a new certificate order will always be created regardless of the status of a previous order for the same primary domain. Otherwise, the previous order still in progress will be used instead. + + + SwitchParameter + + + False + + + DnsSleep + + Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. Default is 120. + + Int32 + + Int32 + + + 120 + + + ValidationTimeout + + Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. Default is 60. If the timeout is exceeded, an error will be thrown. + + Int32 + + Int32 + + + 60 + + + PreferredChain + + If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. + + String + + String + + + None + + + + New-PACertificate + + CSRPath + + The path to a pre-made certificate request file in PEM (Base64) format. This is useful for appliances that need to generate their own keys and cert requests. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + Contact + + One or more email addresses to associate with this certificate. These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. + + String[] + + String[] + + + None + + + AcceptTOS + + This switch is required when creating a new account as part of a certificate request. It implies you have read and accepted the Terms of Service for the ACME server you are connected to. The first time you connect to an ACME server, a link to the Terms of Service should have been displayed. + + + SwitchParameter + + + False + + + AccountKeyLength + + The type and size of private key to use for the account associated with this certificate. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to 'ec-256'. + + String + + String + + + Ec-256 + + + DirectoryUrl + + Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2) and LE_STAGE (LetsEncrypt Staging v2). Defaults to 'LE_PROD'. + + String + + String + + + LE_PROD + + + Plugin + + One or more validation plugin names to use for this order's challenges. If no plugin is specified, the DNS "Manual" plugin will be used. If the same plugin is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified Plugin list. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. If the same alias is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + UseSerialValidation + + If specified, the names in the order will be validated individually rather than all at once. This can significantly increase the time it takes to process validations and should only be used for plugins that require it. The plugin's usage guide should indicate whether it is required. + + + SwitchParameter + + + False + + + Force + + If specified, a new certificate order will always be created regardless of the status of a previous order for the same primary domain. Otherwise, the previous order still in progress will be used instead. + + + SwitchParameter + + + False + + + DnsSleep + + Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. Default is 120. + + Int32 + + Int32 + + + 120 + + + ValidationTimeout + + Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. Default is 60. If the timeout is exceeded, an error will be thrown. + + Int32 + + Int32 + + + 60 + + + PreferredChain + + If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. + + String + + String + + + None + + + + + + Domain + + One or more domain names to include in this order/certificate. The first one in the list will be considered the "MainDomain" and be set as the subject of the finalized certificate. + + String[] + + String[] + + + None + + + CSRPath + + The path to a pre-made certificate request file in PEM (Base64) format. This is useful for appliances that need to generate their own keys and cert requests. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + Contact + + One or more email addresses to associate with this certificate. These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. + + String[] + + String[] + + + None + + + CertKeyLength + + The type and size of private key to use for the certificate. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to '2048'. + + String + + String + + + 2048 + + + AlwaysNewKey + + If specified, the order will be configured to always generate a new private key during each renewal. Otherwise, the old key is re-used if it exists. + + SwitchParameter + + SwitchParameter + + + False + + + AcceptTOS + + This switch is required when creating a new account as part of a certificate request. It implies you have read and accepted the Terms of Service for the ACME server you are connected to. The first time you connect to an ACME server, a link to the Terms of Service should have been displayed. + + SwitchParameter + + SwitchParameter + + + False + + + AccountKeyLength + + The type and size of private key to use for the account associated with this certificate. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to 'ec-256'. + + String + + String + + + Ec-256 + + + DirectoryUrl + + Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2) and LE_STAGE (LetsEncrypt Staging v2). Defaults to 'LE_PROD'. + + String + + String + + + LE_PROD + + + Plugin + + One or more validation plugin names to use for this order's challenges. If no plugin is specified, the DNS "Manual" plugin will be used. If the same plugin is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified Plugin list. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. If the same alias is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + OCSPMustStaple + + If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. + + SwitchParameter + + SwitchParameter + + + False + + + FriendlyName + + Set a friendly name for the certificate. This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. Defaults to the first item in the Domain parameter. + + String + + String + + + None + + + PfxPass + + Set the export password for generated PFX files. Defaults to 'poshacme'. When the PfxPassSecure parameter is specified, this parameter is ignored. + + String + + String + + + Poshacme + + + PfxPassSecure + + Set the export password for generated PFX files using a SecureString value. When this parameter is specified, the PfxPass parameter is ignored. + + SecureString + + SecureString + + + None + + + Install + + If specified, the certificate generated for this order will be imported to the local computer's Personal certificate store. Using this switch requires running the command from an elevated PowerShell session. + + SwitchParameter + + SwitchParameter + + + False + + + UseSerialValidation + + If specified, the names in the order will be validated individually rather than all at once. This can significantly increase the time it takes to process validations and should only be used for plugins that require it. The plugin's usage guide should indicate whether it is required. + + SwitchParameter + + SwitchParameter + + + False + + + Force + + If specified, a new certificate order will always be created regardless of the status of a previous order for the same primary domain. Otherwise, the previous order still in progress will be used instead. + + SwitchParameter + + SwitchParameter + + + False + + + DnsSleep + + Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. Default is 120. + + Int32 + + Int32 + + + 120 + + + ValidationTimeout + + Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. Default is 60. If the timeout is exceeded, an error will be thrown. + + Int32 + + Int32 + + + 60 + + + PreferredChain + + If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. + + String + + String + + + None + + + + + + + PoshACME.PACertificate + + + A certificate object. + + + + + + + + + ------------- Example 1: Basic Manual Certificate ------------- + New-PACertificate 'example.com','www.example.com' -AcceptTOS + + This is the bare minimum necessary to create a certificate for a basic domain (plus the `www` alt name). It prompt you to add the required DNS TXT record manually. You can omit the `-AcceptTOS` parameter if you already have an ACME account configured. + + + + + --------- Example 2: Wildcard Certificate with Contact --------- + New-PACertificate '*.example.com','example.com' -Contact 'admin@example.com' + + Wildcard certificates generally include the non-wildcard root as a SAN because the wildcard doesn't match it. The contact email address is typically used by the CA to send expiration warnings. + + + + + ------------------ Example 3: Using a plugin ------------------ + $pArgs = @{ + FDToken = (Read-Host 'FakeDNS API Token' -AsSecureString) +} +New-PACertificate 'example.com' -Plugin FakeDNS -PluginArgs $pArgs + + Plugin parameters are passed as a basic hashtable object. Some parameters may require SecureString or PSCredential objects to protect sensitive API credentials, tokens, and keys. + + + + + -------------- Example 4: Using multiple plugins -------------- + $pArgs = @{ + FDToken = (Read-Host 'FakeDNS API Token' -AsSecureString) + WSHPort = 8080 +} +New-PACertificate '*.example.com','example.com' -Plugin FakeDNS,WebSelfHost -PluginArgs $pArgs + + Each name in a certificate can use a different plugin if necessary. Be sure the specified plugin order matches the order of the names they are associated with. If there are fewer plugins specified than names, the last plugin in the list will be applied to all remaining names. + Each plugin's parameters should be combined into the same hashtable object. + + + + + ------------ Example 5: Using a DNS Challenge Alias ------------ + $pArgs = @{ + FDToken = (Read-Host 'FakeDNS API Token' -AsSecureString) +} +New-PACertificate 'example.com' -Plugin FakeDNS -PluginArgs $pArgs -DnsAlias 'acme.example.net' + + Using `DnsAlias` tells the plugin to create the required TXT record to an alternate hostname. It requires having added a CNAME record for each name in the cert pointing to the alternate record location. In this case, `_acme-challenge.example.com` is pointing to `acme.example.net`. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/New-PACertificate/ + + + Submit-Renewal + + + + Get-PAPlugin + + + + + + + New-PAOrder + New + PAOrder + + Create a new order on the current ACME account. + + + + Creating an ACME order is the first step of the certificate request process. To create a SAN certificate with multiple names, include them all in an array for the -Domain parameter. The first name in the list will be considered the "MainDomain" and will also be in the certificate subject field. Different CAs have different policies regarding the number of SANs a certificate may have. + Be aware that new orders that share the same MainDomain as a previous order will overwrite the previous order unless the `Name` paraemter is specified and there are no other order matches for that name. + + + + New-PAOrder + + Domain + + One or more domain names to include in this order/certificate. The first one in the list will be considered the "MainDomain" and be set as the subject of the finalized certificate. + + String[] + + String[] + + + None + + + KeyLength + + The type and size of private key to use. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to '2048'. + + String + + String + + + 2048 + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. If not specified, defaults to the first domain in the order. + + String + + String + + + None + + + Plugin + + One or more validation plugin names to use for this order's challenges. If no plugin is specified, the DNS "Manual" plugin will be used. If the same plugin is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified Plugin list. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. If the same alias is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + OCSPMustStaple + + If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. + + + SwitchParameter + + + False + + + AlwaysNewKey + + If specified, the order will be configured to always generate a new private key during each renewal. Otherwise, the old key is re-used if it exists. + + + SwitchParameter + + + False + + + FriendlyName + + Set a friendly name for the certificate. This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. Defaults to the first item in the Domain parameter. + + String + + String + + + None + + + PfxPass + + Set the export password for generated PFX files. Defaults to 'poshacme'. When the PfxPassSecure parameter is specified, this parameter is ignored. + + String + + String + + + Poshacme + + + PfxPassSecure + + Set the export password for generated PFX files using a SecureString value. When this parameter is specified, the PfxPass parameter is ignored. + + SecureString + + SecureString + + + None + + + Install + + If specified, the certificate generated for this order will be imported to the local computer's Personal certificate store. + + + SwitchParameter + + + False + + + UseSerialValidation + + If specified, the names in the order will be validated individually rather than all at once. This can significantly increase the time it takes to process validations and should only be used for plugins that require it. The plugin's usage guide should indicate whether it is required. + + + SwitchParameter + + + False + + + DnsSleep + + Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. + + Int32 + + Int32 + + + 120 + + + ValidationTimeout + + Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. If the timeout is exceeded, an error will be thrown. + + Int32 + + Int32 + + + 60 + + + PreferredChain + + If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. + + String + + String + + + None + + + Force + + If specified, confirmation prompts that may have been generated will be skipped. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + New-PAOrder + + Domain + + One or more domain names to include in this order/certificate. The first one in the list will be considered the "MainDomain" and be set as the subject of the finalized certificate. + + String[] + + String[] + + + None + + + KeyFile + + The path to an existing EC or RSA private key file. This will attempt to create the order using the specified key as the certificate's private key. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. If not specified, defaults to the first domain in the order. + + String + + String + + + None + + + Plugin + + One or more validation plugin names to use for this order's challenges. If no plugin is specified, the DNS "Manual" plugin will be used. If the same plugin is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified Plugin list. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. If the same alias is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + OCSPMustStaple + + If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. + + + SwitchParameter + + + False + + + AlwaysNewKey + + If specified, the order will be configured to always generate a new private key during each renewal. Otherwise, the old key is re-used if it exists. + + + SwitchParameter + + + False + + + FriendlyName + + Set a friendly name for the certificate. This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. Defaults to the first item in the Domain parameter. + + String + + String + + + None + + + PfxPass + + Set the export password for generated PFX files. Defaults to 'poshacme'. When the PfxPassSecure parameter is specified, this parameter is ignored. + + String + + String + + + Poshacme + + + PfxPassSecure + + Set the export password for generated PFX files using a SecureString value. When this parameter is specified, the PfxPass parameter is ignored. + + SecureString + + SecureString + + + None + + + Install + + If specified, the certificate generated for this order will be imported to the local computer's Personal certificate store. + + + SwitchParameter + + + False + + + UseSerialValidation + + If specified, the names in the order will be validated individually rather than all at once. This can significantly increase the time it takes to process validations and should only be used for plugins that require it. The plugin's usage guide should indicate whether it is required. + + + SwitchParameter + + + False + + + DnsSleep + + Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. + + Int32 + + Int32 + + + 120 + + + ValidationTimeout + + Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. If the timeout is exceeded, an error will be thrown. + + Int32 + + Int32 + + + 60 + + + PreferredChain + + If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. + + String + + String + + + None + + + Force + + If specified, confirmation prompts that may have been generated will be skipped. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + New-PAOrder + + CSRPath + + The path to a pre-made certificate request file in PEM (Base64) format. This is useful for appliances that need to generate their own keys and cert requests. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. If not specified, defaults to the first domain in the order. + + String + + String + + + None + + + Plugin + + One or more validation plugin names to use for this order's challenges. If no plugin is specified, the DNS "Manual" plugin will be used. If the same plugin is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified Plugin list. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. If the same alias is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + UseSerialValidation + + If specified, the names in the order will be validated individually rather than all at once. This can significantly increase the time it takes to process validations and should only be used for plugins that require it. The plugin's usage guide should indicate whether it is required. + + + SwitchParameter + + + False + + + DnsSleep + + Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. + + Int32 + + Int32 + + + 120 + + + ValidationTimeout + + Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. If the timeout is exceeded, an error will be thrown. + + Int32 + + Int32 + + + 60 + + + PreferredChain + + If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. + + String + + String + + + None + + + Force + + If specified, confirmation prompts that may have been generated will be skipped. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + + + Domain + + One or more domain names to include in this order/certificate. The first one in the list will be considered the "MainDomain" and be set as the subject of the finalized certificate. + + String[] + + String[] + + + None + + + CSRPath + + The path to a pre-made certificate request file in PEM (Base64) format. This is useful for appliances that need to generate their own keys and cert requests. + + String + + String + + + None + + + KeyLength + + The type and size of private key to use. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to '2048'. + + String + + String + + + 2048 + + + KeyFile + + The path to an existing EC or RSA private key file. This will attempt to create the order using the specified key as the certificate's private key. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. If not specified, defaults to the first domain in the order. + + String + + String + + + None + + + Plugin + + One or more validation plugin names to use for this order's challenges. If no plugin is specified, the DNS "Manual" plugin will be used. If the same plugin is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified Plugin list. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. If the same alias is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + OCSPMustStaple + + If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. + + SwitchParameter + + SwitchParameter + + + False + + + AlwaysNewKey + + If specified, the order will be configured to always generate a new private key during each renewal. Otherwise, the old key is re-used if it exists. + + SwitchParameter + + SwitchParameter + + + False + + + FriendlyName + + Set a friendly name for the certificate. This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. Defaults to the first item in the Domain parameter. + + String + + String + + + None + + + PfxPass + + Set the export password for generated PFX files. Defaults to 'poshacme'. When the PfxPassSecure parameter is specified, this parameter is ignored. + + String + + String + + + Poshacme + + + PfxPassSecure + + Set the export password for generated PFX files using a SecureString value. When this parameter is specified, the PfxPass parameter is ignored. + + SecureString + + SecureString + + + None + + + Install + + If specified, the certificate generated for this order will be imported to the local computer's Personal certificate store. + + SwitchParameter + + SwitchParameter + + + False + + + UseSerialValidation + + If specified, the names in the order will be validated individually rather than all at once. This can significantly increase the time it takes to process validations and should only be used for plugins that require it. The plugin's usage guide should indicate whether it is required. + + SwitchParameter + + SwitchParameter + + + False + + + DnsSleep + + Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. + + Int32 + + Int32 + + + 120 + + + ValidationTimeout + + Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. If the timeout is exceeded, an error will be thrown. + + Int32 + + Int32 + + + 60 + + + PreferredChain + + If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. + + String + + String + + + None + + + Force + + If specified, confirmation prompts that may have been generated will be skipped. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + PoshACME.PAOrder + + + An order object. + + + + + + + + + -------------------------- Example 1 -------------------------- + New-PAOrder site1.example.com + + Create a new order for the specified domain using the default key length. + + + + + -------------------------- Example 2 -------------------------- + New-PAOrder -Domain 'site1.example.com','site2.example.com','site3.example.com' + + Create a new SAN order for the specified domains using the default key length. + + + + + -------------------------- Example 3 -------------------------- + New-PAOrder site1.example.com 4096 + + Create a new order for the specified domain using an RSA 4096 bit key. + + + + + -------------------------- Example 4 -------------------------- + New-PAOrder 'site1.example.com','site2.example.com' ec-384 -Force + + Create a new SAN order for the specified domains using an ECC key using P-384 curve that ignores any confirmations. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/New-PAOrder/ + + + Get-PAOrder + + + + Set-PAOrder + + + + + + + Publish-Challenge + Publish + Challenge + + Publish a challenge using the specified plugin. + + + + Based on the type of validation plugin specified, this function will publish either a DNS TXT record or an HTTP challenge file for the given domain and token value that satisfies the dns-01 or http-01 challenge specification. + Depending on the plugin, calling `Save-Challenge` may be required to commit changes made by `Publish-Challenge`. If multiple challenges are being published, make all `Publish-Challenge` calls first. Then, `Save-Challenge` once to commit them all. + + + + Publish-Challenge + + Domain + + The domain name that the challenge will be published for. Wildcard domains should have the "*." removed and can only be used with DNS based validation plugins. + + String + + String + + + None + + + Account + + The account object associated with the order that requires the challenge. + + Object + + Object + + + None + + + Token + + The token value from the appropriate challenge in an authorization object that matches the plugin type. + + String + + String + + + None + + + Plugin + + The name of the validation plugin to use. Use Get-PAPlugin to display a list of available plugins. + + String + + String + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified plugin. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + When using DNS Alias support with DNS validation plugins, the alias domain that the TXT record will be written to. This should be the complete FQDN including the '_acme-challenge.' prefix if necessary. This field is ignored for non-DNS validation plugins. + + String + + String + + + None + + + + + + Domain + + The domain name that the challenge will be published for. Wildcard domains should have the "*." removed and can only be used with DNS based validation plugins. + + String + + String + + + None + + + Account + + The account object associated with the order that requires the challenge. + + Object + + Object + + + None + + + Token + + The token value from the appropriate challenge in an authorization object that matches the plugin type. + + String + + String + + + None + + + Plugin + + The name of the validation plugin to use. Use Get-PAPlugin to display a list of available plugins. + + String + + String + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified plugin. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + When using DNS Alias support with DNS validation plugins, the alias domain that the TXT record will be written to. This should be the complete FQDN including the '_acme-challenge.' prefix if necessary. This field is ignored for non-DNS validation plugins. + + String + + String + + + None + + + + + + + + + + -------------------------- Example 1 -------------------------- + $auths = Get-PAOrder | Get-PAAuthorization +Publish-Challenge $auths[0].DNSId (Get-PAAccount) $auths[0].DNS01Token Manual @{} + + Publish a DNS challenge for the first authorization in the current order using the Manual DNS plugin. + + + + + -------------------------- Example 2 -------------------------- + $pArgs = @{Param1='asdf';Param2=1234} +$acct = Get-PAAccount +Publish-Challenge example.com $acct MyPlugin $pArgs -Token faketoken + + Publish a challenge for example.com using a fictitious plugin and arguments. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Publish-Challenge/ + + + Unpublish-Challenge + + + + Save-Challenge + + + + Get-PAPlugin + + + + + + + Remove-PAAccount + Remove + PAAccount + + Remove an ACME account and all associated orders and certificates from the local profile. + + + + This function removes the ACME account from the local profile which also removes any associated orders and certificates. It will not remove or cleanup copies of certificates that have been exported or installed elsewhere. It will not deactivate the account on the ACME server unless `-Deactivate` is specified. But you won't be able to re-use the account on another system without an export of the account's key such as the one generated with `Export-PAAccountKey`. + + + + Remove-PAAccount + + ID + + The account id value as returned by the ACME server. + + String + + String + + + None + + + Deactivate + + If specified, a request will be sent to the associated ACME server to deactivate the account. Clients may wish to do this if the account key is compromised or decommissioned. + + + SwitchParameter + + + False + + + Force + + If specified, interactive confirmation prompts will be skipped. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + + + ID + + The account id value as returned by the ACME server. + + String + + String + + + None + + + Deactivate + + If specified, a request will be sent to the associated ACME server to deactivate the account. Clients may wish to do this if the account key is compromised or decommissioned. + + SwitchParameter + + SwitchParameter + + + False + + + Force + + If specified, interactive confirmation prompts will be skipped. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + + + + -------------------------- Example 1 -------------------------- + Remove-PAAccount 12345 + + Remove the specified account without deactivation. + + + + + -------------------------- Example 2 -------------------------- + Get-PAAccount | Remove-PAAccount -Deactivate -Force + + Remove the current account after deactivating it and skip confirmation prompts. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Remove-PAAccount/ + + + Get-PAAccount + + + + New-PAAccount + + + + + + + Remove-PAOrder + Remove + PAOrder + + Remove an ACME order from the local profile. + + + + This function removes the order from the local profile which also removes any associated certificate/key. It will not remove or cleanup copies of the certificate that have been exported or installed elsewhere. It will not revoke the certificate unless `-RevokeCert` is specified. The ACME server may retain a reference to the order until it decides to delete it. + + + + Remove-PAOrder + + MainDomain + + The primary domain for the order. For a SAN order, this was the first domain in the list when creating the order. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + RevokeCert + + If specified and there is a currently valid certificate associated with the order, the certificate will be revoked before deleting the order. This is not required, but generally a good practice if the certificate is no longer being used. + + + SwitchParameter + + + False + + + Force + + If specified, interactive confirmation prompts will be skipped. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + + + MainDomain + + The primary domain for the order. For a SAN order, this was the first domain in the list when creating the order. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + RevokeCert + + If specified and there is a currently valid certificate associated with the order, the certificate will be revoked before deleting the order. This is not required, but generally a good practice if the certificate is no longer being used. + + SwitchParameter + + SwitchParameter + + + False + + + Force + + If specified, interactive confirmation prompts will be skipped. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + + + + -------------------------- Example 1 -------------------------- + Remove-PAOrder site1.example.com + + Remove the specified order without revoking the certificate. + + + + + -------------------------- Example 2 -------------------------- + Get-PAOrder -List | Remove-PAOrder -RevokeCert -Force + + Remove all orders associated with the current account, revoke all certificates, and skip confirmation prompts. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Remove-PAOrder/ + + + Get-PAOrder + + + + New-PAOrder + + + + + + + Remove-PAServer + Remove + PAServer + + Remove an ACME server and all associated accounts, orders, and certificates from the local profile. + + + + This function removes the ACME server from the local profile which also removes any associated accounts, orders and certificates. It will not remove or cleanup copies of certificates that have been exported or installed elsewhere. It will not revoke any certificates. It will not deactivate the accounts on the ACME server unless the `-DeactivateAccounts` switch is specified. + + + + Remove-PAServer + + DirectoryUrl + + Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2) and LE_STAGE (LetsEncrypt Staging v2). + + String + + String + + + None + + + Name + + The name of the ACME server. The parameter is ignored if DirectoryUrl is specified. + + String + + String + + + None + + + DeactivateAccounts + + If specified, an attempt will be made to deactivate the accounts in this profile before deletion. Clients may wish to do this if the account key is compromised or being decommissioned. + + + SwitchParameter + + + False + + + Force + + If specified, interactive confirmation prompts will be skipped. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + + + DirectoryUrl + + Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2) and LE_STAGE (LetsEncrypt Staging v2). + + String + + String + + + None + + + Name + + The name of the ACME server. The parameter is ignored if DirectoryUrl is specified. + + String + + String + + + None + + + DeactivateAccounts + + If specified, an attempt will be made to deactivate the accounts in this profile before deletion. Clients may wish to do this if the account key is compromised or being decommissioned. + + SwitchParameter + + SwitchParameter + + + False + + + Force + + If specified, interactive confirmation prompts will be skipped. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + + + + -------------------------- Example 1 -------------------------- + Remove-PAServer LE_STAGE + + Remove the staging server without deactivating accounts. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Remove-PAServer/ + + + Get-PAServer + + + + Set-PAServer + + + + + + + Revoke-PAAuthorization + Revoke + PAAuthorization + + Revoke the authorization associated with an ACME identifier. + + + + Many ACME server implementations cache succesful authorizations for a certain amount of time to avoid requiring an account to re-authorize identifiers for additional orders submitted during the cache window. This can make testing authorization challenges in a client more cumbersome by having to create new orders with uncached identifiers. + This function allows you to revoke those cached authorizations so that subsequent orders will go through the full challenge validation process. + + + + Revoke-PAAuthorization + + AuthURLs + + One or more authorization URLs. You also pipe in one or more PoshACME.PAOrder objects. + + String[] + + String[] + + + None + + + Account + + An existing ACME account object such as the output from Get-PAAccount. If no account is specified, the current account will be used. + + Object + + Object + + + None + + + Force + + If specified, no confirmation prompts will be presented. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + + + AuthURLs + + One or more authorization URLs. You also pipe in one or more PoshACME.PAOrder objects. + + String[] + + String[] + + + None + + + Account + + An existing ACME account object such as the output from Get-PAAccount. If no account is specified, the current account will be used. + + Object + + Object + + + None + + + Force + + If specified, no confirmation prompts will be presented. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + + + + System.String + + + The URI of the authorization object. + + + + + + + + + + -------------------------- Example 1 -------------------------- + Revoke-PAAuthorization https://acme.example.com/authz/1234567 + + Revoke the authorization for the specified URL using the current account. + + + + + -------------------------- Example 2 -------------------------- + Get-PAOrder | Revoke-PAAuthorization -Force + + Revoke all authorizations for the current order on the current account without confirmation prompts. + + + + + -------------------------- Example 3 -------------------------- + Get-PAOrder -List | Revoke-PAAuthorizations + + Revoke all authorizations for all orders on the current account. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Revoke-PAAuthorization/ + + + Get-PAAuthorization + + + + Get-PAOrder + + + + + + + Revoke-PACertificate + Revoke + PACertificate + + Revoke an ACME certificate + + + + Any certificate created with the current ACME account can be revoked. If you need to revoke a certificate not created with the current account, you either need to specify both `CertFile` and `KeyFile`. If you don't have the private key, you will need to go through the authorization process on this account for all names in the certificate and just specify `CertFile`. + + + + Revoke-PACertificate + + MainDomain + + The primary domain associated with the certificate to be revoked. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + Reason + + The reason for cert revocation. This must be one of the reasons defined in RFC 5280 including keyCompromise, cACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, removeFromCRL, privilegeWithdrawn, and aACompromise. NOTE: Some reason codes are not supported by some ACME CAs. + + + keyCompromise + cACompromise + affiliationChanged + superseded + cessationOfOperation + certificateHold + removeFromCRL + privilegeWithdrawn + aACompromise + + RevocationReasons + + RevocationReasons + + + None + + + Force + + If specified, the revocation confirmation prompt will be skipped. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + Revoke-PACertificate + + CertFile + + A PEM-encoded certificate file to be revoked. + + String + + String + + + None + + + KeyFile + + The PEM-encoded private key associated with CertFile. If not specified, the current ACME account will be used to sign the request. + + String + + String + + + None + + + Reason + + The reason for cert revocation. This must be one of the reasons defined in RFC 5280 including keyCompromise, cACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, removeFromCRL, privilegeWithdrawn, and aACompromise. NOTE: Some reason codes are not supported by some ACME CAs. + + + keyCompromise + cACompromise + affiliationChanged + superseded + cessationOfOperation + certificateHold + removeFromCRL + privilegeWithdrawn + aACompromise + + RevocationReasons + + RevocationReasons + + + None + + + Force + + If specified, the revocation confirmation prompt will be skipped. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + + + MainDomain + + The primary domain associated with the certificate to be revoked. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + CertFile + + A PEM-encoded certificate file to be revoked. + + String + + String + + + None + + + KeyFile + + The PEM-encoded private key associated with CertFile. If not specified, the current ACME account will be used to sign the request. + + String + + String + + + None + + + Reason + + The reason for cert revocation. This must be one of the reasons defined in RFC 5280 including keyCompromise, cACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, removeFromCRL, privilegeWithdrawn, and aACompromise. NOTE: Some reason codes are not supported by some ACME CAs. + + RevocationReasons + + RevocationReasons + + + None + + + Force + + If specified, the revocation confirmation prompt will be skipped. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + + + + -------------------------- Example 1 -------------------------- + Revoke-PACertificate example.com + + Revokes the certificate for the specified domain. + + + + + -------------------------- Example 2 -------------------------- + Get-PAOrder | Revoke-PACertificate -Force + + Revokes the certificate associated with the current order and skips the confirmation prompt. + + + + + -------------------------- Example 3 -------------------------- + Get-PACertificate | Revoke-PACertificate -Reason keyCompromise + + Revokes the current certificate with the specified reason. + + + + + -------------------------- Example 4 -------------------------- + Revoke-PACertificate -CertFile mycert.crt -KeyFile mycert.key + + Revokes the specified cert using the specified private key. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Revoke-PACertificate/ + + + New-PACertificate + + + + + + + Save-Challenge + Save + Challenge + + Commit changes made by Publish-Challenge or Unpublish-Challenge. + + + + Some validation plugins require a finalization step after the Publish or Unpublish functionality to commit and make the changes live. This function should be called once after running all of the `Publish-Challenge` or `Unpublish-Challenge` commands. + For plugins that don't require a commit step, this function may still be run without causing an error, but does nothing. + + + + Save-Challenge + + Plugin + + The name of the validation plugin to use. Use Get-PAPlugin to display a list of available plugins. + + String + + String + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified plugin. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + + + + Plugin + + The name of the validation plugin to use. Use Get-PAPlugin to display a list of available plugins. + + String + + String + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified plugin. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + + + + + + + + -------------------------- Example 1 -------------------------- + Save-Challenge Manual @{} + + Commit changes using the Manual DNS plugin that requires no plugin arguments. + + + + + -------------------------- Example 2 -------------------------- + Save-Challenge MyPlugin @{Param1='asdf';Param2=1234} + + Commit changes for a set of challenges using a fictitious plugin and arguments. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Save-Challenge/ + + + Publish-Challenge + + + + Unpublish-Challenge + + + + Get-PAPlugin + + + + + + + Send-ChallengeAck + Send + ChallengeAck + + Notify the ACME server to try validating a challenge. + + + + Use this after publishing the required resource for one of the challenges from an authorization object. It lets the ACME server know that it should proceed validating that challenge. + + + + Send-ChallengeAck + + ChallengeUrl + + The URL of the challenge to be validated. + + String + + String + + + None + + + Account + + The ACME account associated with the challenge. + + Object + + Object + + + None + + + + + + ChallengeUrl + + The URL of the challenge to be validated. + + String + + String + + + None + + + Account + + The ACME account associated with the challenge. + + Object + + Object + + + None + + + + + + System.String + + + The URI of an ACME challenge object. + + + + + + + + + + -------------------------- Example 1 -------------------------- + $auths = Get-PAOrder | Get-PAAuthorization +Send-ChallengeAck $auths\[0\].DNS01Url + + Tell the ACME server to validate the first DNS challenge in the current order. + + + + + -------------------------- Example 2 -------------------------- + $auths = Get-PAOrder | Get-PAAuthorization +$httpUrls = ($auths | ?{ $_.status -eq 'pending' }).HTTP01Url +$httpUrls | Send-ChallengeAck + + Tell the ACME server to validate all pending HTTP challenges in the current order. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Send-ChallengeAck/ + + + Get-PAAuthorization + + + + Submit-ChallengeValidation + + + + + + + Set-PAAccount + Set + PAAccount + + Set the current ACME account and/or update account details. + + + + This function allows you to switch between ACME accounts for a particular server. It also allows you to update the contact information associated with an account, deactivate the account, or replace the account key with a new one. + + + + Set-PAAccount + + ID + + The account id value as returned by the ACME server. If not specified, the function will attempt to use the currently active account. + + String + + String + + + None + + + Contact + + One or more email addresses to associate with this account. These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. + + String[] + + String[] + + + None + + + NewName + + The new name (id) of this ACME account. + + String + + String + + + None + + + UseAltPluginEncryption + + If specified, the account will be configured to use a randomly generated AES key to encrypt sensitive plugin parameters on disk instead of using the OS's native encryption methods. This can be useful if the config is being shared across systems or platforms. You can revert to OS native encryption using -UseAltPluginEncryption:$false. + + + SwitchParameter + + + False + + + ResetAltPluginEncryption + + If specified, the existing AES key will be replaced with a new one and existing plugin parameters on disk will be re-encrypted with the new key. If there is no existing key, this parameter is ignored. + + + SwitchParameter + + + False + + + Deactivate + + If specified, a request will be sent to the associated ACME server to deactivate the account. Clients may wish to do this if the account key is compromised or decommissioned. + + + SwitchParameter + + + False + + + Force + + If specified, confirmation prompts for account deactivation will be skipped. + + + SwitchParameter + + + False + + + NoSwitch + + If specified, the currently active account will not change. Useful primarily for bulk updating contact information across accounts. This switch is ignored if no ID is specified. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + Set-PAAccount + + ID + + The account id value as returned by the ACME server. If not specified, the function will attempt to use the currently active account. + + String + + String + + + None + + + KeyRollover + + If specified, generate a new account key and replace the current one with it. Clients may choose to do this to recover from a key compromise or proactively mitigate the impact of an unnoticed key compromise. + + + SwitchParameter + + + False + + + KeyFile + + The path to an existing EC or RSA private key file. This will attempt to use the specified key as the new ACME account key. + + String + + String + + + None + + + NoSwitch + + If specified, the currently active account will not change. Useful primarily for bulk updating contact information across accounts. This switch is ignored if no ID is specified. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + Set-PAAccount + + ID + + The account id value as returned by the ACME server. If not specified, the function will attempt to use the currently active account. + + String + + String + + + None + + + KeyRollover + + If specified, generate a new account key and replace the current one with it. Clients may choose to do this to recover from a key compromise or proactively mitigate the impact of an unnoticed key compromise. + + + SwitchParameter + + + False + + + KeyLength + + The type and size of private key to use. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to 'ec-256'. + + String + + String + + + Ec-256 + + + NoSwitch + + If specified, the currently active account will not change. Useful primarily for bulk updating contact information across accounts. This switch is ignored if no ID is specified. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + + + ID + + The account id value as returned by the ACME server. If not specified, the function will attempt to use the currently active account. + + String + + String + + + None + + + Contact + + One or more email addresses to associate with this account. These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. + + String[] + + String[] + + + None + + + NewName + + The new name (id) of this ACME account. + + String + + String + + + None + + + UseAltPluginEncryption + + If specified, the account will be configured to use a randomly generated AES key to encrypt sensitive plugin parameters on disk instead of using the OS's native encryption methods. This can be useful if the config is being shared across systems or platforms. You can revert to OS native encryption using -UseAltPluginEncryption:$false. + + SwitchParameter + + SwitchParameter + + + False + + + ResetAltPluginEncryption + + If specified, the existing AES key will be replaced with a new one and existing plugin parameters on disk will be re-encrypted with the new key. If there is no existing key, this parameter is ignored. + + SwitchParameter + + SwitchParameter + + + False + + + Deactivate + + If specified, a request will be sent to the associated ACME server to deactivate the account. Clients may wish to do this if the account key is compromised or decommissioned. + + SwitchParameter + + SwitchParameter + + + False + + + Force + + If specified, confirmation prompts for account deactivation will be skipped. + + SwitchParameter + + SwitchParameter + + + False + + + KeyRollover + + If specified, generate a new account key and replace the current one with it. Clients may choose to do this to recover from a key compromise or proactively mitigate the impact of an unnoticed key compromise. + + SwitchParameter + + SwitchParameter + + + False + + + KeyLength + + The type and size of private key to use. For RSA keys, specify a number between 2048-4096 (divisible by 128). For ECC keys, specify either 'ec-256' or 'ec-384'. Defaults to 'ec-256'. + + String + + String + + + Ec-256 + + + KeyFile + + The path to an existing EC or RSA private key file. This will attempt to use the specified key as the new ACME account key. + + String + + String + + + None + + + NoSwitch + + If specified, the currently active account will not change. Useful primarily for bulk updating contact information across accounts. This switch is ignored if no ID is specified. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + + + + -------------------------- Example 1 -------------------------- + Set-PAAccount -ID 1234567 + + Switch to the specified account. + + + + + -------------------------- Example 2 -------------------------- + Set-PAAccount -Contact 'user1@example.com','user2@example.com' + + Set new contacts for the current account. + + + + + -------------------------- Example 3 -------------------------- + Set-PAAccount -ID 1234567 -Contact 'user1@example.com','user2@example.com' + + Set new contacts for the specified account. + + + + + -------------------------- Example 4 -------------------------- + Get-PAAccount -List | Set-PAAccount -Contact user1@example.com -NoSwitch + + Set a new contact for all known accounts without switching from the current. + + + + + -------------------------- Example 5 -------------------------- + Set-PAAccount -Deactivate + + Deactivate the current account. + + + + + -------------------------- Example 6 -------------------------- + Set-PAAccount -KeyRollover -KeyLength ec-384 + + Replace the current account key with a new ECC key using P-384 curve. + + + + + -------------------------- Example 7 -------------------------- + Set-PAAccount -KeyRollover -KeyFile .\mykey.key + + Replace the current account key with a pre-generated private key. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Set-PAAccount/ + + + Get-PAAccount + + + + New-PAAccount + + + + + + + Set-PAOrder + Set + PAOrder + + Set the current ACME order, edits an orders properties, or revokes an order's certificate. + + + + Switch to a specific ACME order and edit its properties or revoke its certificate. Revoked certificate orders are not deleted and can be re-requested using Submit-Renewal or New-PACertificate. + + + + Set-PAOrder + + MainDomain + + The primary domain for the order. For a SAN order, this was the first domain in the list when creating the order. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + RevokeCert + + If specified, a request will be sent to the associated ACME server to revoke the certificate on this order. Clients may wish to do this if the certificate is decommissioned or the private key has been compromised. A warning will be displayed if the order is not currently valid or the existing certificate file can't be found. + + + SwitchParameter + + + False + + + Force + + If specified, confirmation prompts for certificate revocation will be skipped. + + + SwitchParameter + + + False + + + NoSwitch + + If specified, the currently selected order will not change. Useful primarily for bulk certificate revocation. This switch is ignored if no MainDomain is specified. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + Set-PAOrder + + MainDomain + + The primary domain for the order. For a SAN order, this was the first domain in the list when creating the order. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + NoSwitch + + If specified, the currently selected order will not change. Useful primarily for bulk certificate revocation. This switch is ignored if no MainDomain is specified. + + + SwitchParameter + + + False + + + Plugin + + One or more validation plugin names to use for this order's challenges. If no plugin is specified, the DNS "Manual" plugin will be used. If the same plugin is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified Plugin list. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. If the same alias is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + NewName + + The new name for this ACME order. + + String + + String + + + None + + + FriendlyName + + The friendly name for the certificate and subsequent renewals. This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. Must not be an empty string. + + String + + String + + + None + + + PfxPass + + The PFX password for the certificate and subsequent renewals. When the PfxPassSecure parameter is specified, this parameter is ignored. + + String + + String + + + None + + + PfxPassSecure + + The PFX password for the certificate and subsequent renewals using a SecureString value. When this parameter is specified, the PfxPass parameter is ignored. + + SecureString + + SecureString + + + None + + + Install + + Enables the Install switch for the order. Use -Install:$false to disable the switch on the order. This affects whether the module will automatically import the certificate to the Windows certificate store on subsequent renewals. It will not import the current certificate if it exists. Use Install-PACertificate for that purpose. + + + SwitchParameter + + + False + + + OCSPMustStaple + + If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. + + + SwitchParameter + + + False + + + DnsSleep + + Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. + + Int32 + + Int32 + + + 0 + + + ValidationTimeout + + Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. If the timeout is exceeded, an error will be thrown. + + Int32 + + Int32 + + + 0 + + + PreferredChain + + If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. + + String + + String + + + None + + + AlwaysNewKey + + If specified, the order will be configured to always generate a new private key during each renewal. Otherwise, the old key is re-used if it exists. + + + SwitchParameter + + + False + + + UseSerialValidation + + If specified, the names in the order will be validated individually rather than all at once. This can significantly increase the time it takes to process validations and should only be used for plugins that require it. The plugin's usage guide should indicate whether it is required. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + + + MainDomain + + The primary domain for the order. For a SAN order, this was the first domain in the list when creating the order. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + RevokeCert + + If specified, a request will be sent to the associated ACME server to revoke the certificate on this order. Clients may wish to do this if the certificate is decommissioned or the private key has been compromised. A warning will be displayed if the order is not currently valid or the existing certificate file can't be found. + + SwitchParameter + + SwitchParameter + + + False + + + Force + + If specified, confirmation prompts for certificate revocation will be skipped. + + SwitchParameter + + SwitchParameter + + + False + + + NoSwitch + + If specified, the currently selected order will not change. Useful primarily for bulk certificate revocation. This switch is ignored if no MainDomain is specified. + + SwitchParameter + + SwitchParameter + + + False + + + Plugin + + One or more validation plugin names to use for this order's challenges. If no plugin is specified, the DNS "Manual" plugin will be used. If the same plugin is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified Plugin list. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. If the same alias is used for all domains in the order, you can just specify it once. Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. + + String[] + + String[] + + + None + + + NewName + + The new name for this ACME order. + + String + + String + + + None + + + FriendlyName + + The friendly name for the certificate and subsequent renewals. This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. Must not be an empty string. + + String + + String + + + None + + + PfxPass + + The PFX password for the certificate and subsequent renewals. When the PfxPassSecure parameter is specified, this parameter is ignored. + + String + + String + + + None + + + PfxPassSecure + + The PFX password for the certificate and subsequent renewals using a SecureString value. When this parameter is specified, the PfxPass parameter is ignored. + + SecureString + + SecureString + + + None + + + Install + + Enables the Install switch for the order. Use -Install:$false to disable the switch on the order. This affects whether the module will automatically import the certificate to the Windows certificate store on subsequent renewals. It will not import the current certificate if it exists. Use Install-PACertificate for that purpose. + + SwitchParameter + + SwitchParameter + + + False + + + OCSPMustStaple + + If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. + + SwitchParameter + + SwitchParameter + + + False + + + DnsSleep + + Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. + + Int32 + + Int32 + + + 0 + + + ValidationTimeout + + Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. If the timeout is exceeded, an error will be thrown. + + Int32 + + Int32 + + + 0 + + + PreferredChain + + If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. + + String + + String + + + None + + + AlwaysNewKey + + If specified, the order will be configured to always generate a new private key during each renewal. Otherwise, the old key is re-used if it exists. + + SwitchParameter + + SwitchParameter + + + False + + + UseSerialValidation + + If specified, the names in the order will be validated individually rather than all at once. This can significantly increase the time it takes to process validations and should only be used for plugins that require it. The plugin's usage guide should indicate whether it is required. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + + + + -------------------------- Example 1 -------------------------- + Set-PAOrder site1.example.com + + Switch to the specified domain's order. + + + + + -------------------------- Example 2 -------------------------- + Set-PAOrder -RevokeCert + + Revoke the current order's certificate. + + + + + -------------------------- Example 3 -------------------------- + Set-PAOrder -FriendlyName 'new friendly name' + + Edit the friendly name for the current order and certificate if it exists. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Set-PAOrder/ + + + Get-PAOrder + + + + New-PAOrder + + + + + + + Set-PAServer + Set + PAServer + + Set the current ACME server and/or its configuration. + + + + Use this function to set the current ACME server or change a server's configuration settings. + + + + Set-PAServer + + DirectoryUrl + + Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2), LE_STAGE (LetsEncrypt Staging v2), BUYPASS_PROD (BuyPass.com Production), and BUYPASS_TEST (BuyPass.com Testing). + + String + + String + + + None + + + Name + + The name of the ACME server. The parameter is ignored if DirectoryUrl is specified. + + String + + String + + + None + + + NewName + + The new name of this ACME server. + + String + + String + + + None + + + SkipCertificateCheck + + If specified, disable certificate validation while using this server. This should not be necessary except in development environments where you are connecting to a self-hosted ACME server. + + + SwitchParameter + + + False + + + DisableTelemetry + + If specified, telemetry data will not be sent to the Posh-ACME team for actions associated with this server. The telemetry data that gets sent by default includes Posh-ACME version, PowerShell version, and generic OS platform (Windows/Linux/MacOS). + + + SwitchParameter + + + False + + + NoRefresh + + If specified, the ACME server will not be re-queried for updated endpoints or a fresh nonce. + + + SwitchParameter + + + False + + + NoSwitch + + If specified, the currently active ACME server will not be changed to the server being modified. + + + SwitchParameter + + + False + + + + + + DirectoryUrl + + Either the URL to an ACME server's "directory" endpoint or one of the supported short names. Currently supported short names include LE_PROD (LetsEncrypt Production v2), LE_STAGE (LetsEncrypt Staging v2), BUYPASS_PROD (BuyPass.com Production), and BUYPASS_TEST (BuyPass.com Testing). + + String + + String + + + None + + + Name + + The name of the ACME server. The parameter is ignored if DirectoryUrl is specified. + + String + + String + + + None + + + NewName + + The new name of this ACME server. + + String + + String + + + None + + + SkipCertificateCheck + + If specified, disable certificate validation while using this server. This should not be necessary except in development environments where you are connecting to a self-hosted ACME server. + + SwitchParameter + + SwitchParameter + + + False + + + DisableTelemetry + + If specified, telemetry data will not be sent to the Posh-ACME team for actions associated with this server. The telemetry data that gets sent by default includes Posh-ACME version, PowerShell version, and generic OS platform (Windows/Linux/MacOS). + + SwitchParameter + + SwitchParameter + + + False + + + NoRefresh + + If specified, the ACME server will not be re-queried for updated endpoints or a fresh nonce. + + SwitchParameter + + SwitchParameter + + + False + + + NoSwitch + + If specified, the currently active ACME server will not be changed to the server being modified. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + + + + -------------------------- Example 1 -------------------------- + Set-PAServer LE_PROD + + Switch to the LetsEncrypt production server using the short name. + + + + + -------------------------- Example 2 -------------------------- + Set-PAServer -DirectoryUrl https://myacme.example.com/directory + + Switch to the specified ACME server using the directory URL. + + + + + -------------------------- Example 3 -------------------------- + (Get-PAServer -List)[0] | Set-PAServer + + Switch to the first ACME server returned by "Get-PAServer -List" + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Set-PAServer/ + + + Get-PAServer + + + + + + + Submit-ChallengeValidation + Submit + ChallengeValidation + + Respond to authorization challenges for an ACME order and wait for the ACME server to validate them. + + + + An ACME order contains an authorization object for each domain in the order. Each authorization contains one or more challenge types. The client must complete at least one challenge for each authorization in order to prove they control the domain. Once complete, the client asks the server to validate each challenge and waits for the server to do so and update the authorization status. + + + + Submit-ChallengeValidation + + Order + + The ACME order to perform the validations against. The order object must be associated with the currently active ACME account. + + Object + + Object + + + None + + + + + + Order + + The ACME order to perform the validations against. The order object must be associated with the currently active ACME account. + + Object + + Object + + + None + + + + + + PoshACME.PAOrder + + + An order object. + + + + + + + + + + -------------------------- Example 1 -------------------------- + Submit-ChallengeValidation + + Begin challenge validation on the current order. + + + + + -------------------------- Example 2 -------------------------- + Get-PAOrder -Name myorder | Submit-ChallengeValidation + + Begin challenge validation on the specified order. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Submit-ChallengeValidation/ + + + Get-PAOrder + + + + New-PAOrder + + + + + + + Submit-OrderFinalize + Submit + OrderFinalize + + Finalize a certificate order + + + + An ACME order that has reached the `ready` state is ready to be finalized which involves sending the certificate request to the ACME server so it can sign the certificate and transition the order into the `valid` state. + + + + Submit-OrderFinalize + + Order + + The ACME order to finalize. The order object must be associated with the currently active ACME account. + + Object + + Object + + + None + + + + + + Order + + The ACME order to finalize. The order object must be associated with the currently active ACME account. + + Object + + Object + + + None + + + + + + PoshACME.PAOrder + + + An order object. + + + + + + + + + + -------------------------- Example 1 -------------------------- + Submit-OrderFinalize + + Finalize the current order. + + + + + -------------------------- Example 2 -------------------------- + Get-PAOrder example.com | Submit-OrderFinalize + + Finalize the specified order. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Submit-OrderFinalize/ + + + Get-PAOrder + + + + Submit-ChallengeValidation + + + + + + + Submit-Renewal + Submit + Renewal + + Renew one or more certificates. + + + + This function allows you to renew one more more previously completed certificate orders. You can choose to renew a specific order, set of orders, all orders for the current account, or all orders for all accounts. + + + + Submit-Renewal + + MainDomain + + The primary domain associated with an order. This is the domain that goes in the certificate's subject. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + Force + + If specified, an order that hasn't reached its renewal window will not throw an error and will not be skipped when using either of the -All parameters. + + + SwitchParameter + + + False + + + NoSkipManualDns + + If specified, orders that utilize the Manual DNS plugin will not be skipped and user interaction may be required to complete the process. Otherwise, orders that utilize the Manual DNS plugin will be skipped. + + + SwitchParameter + + + False + + + PluginArgs + + A hashtable containing an updated set of plugin arguments to use with the renewal. So if a plugin has a `MyText` string and `MyNumber` integer parameter, you could specify them as `@{MyText='text';MyNumber=1234}`. + + Hashtable + + Hashtable + + + None + + + + Submit-Renewal + + AllOrders + + If specified, renew all valid orders on the current account. Orders that have not reached the renewal window will be skipped unless -Force is used. + + + SwitchParameter + + + False + + + Force + + If specified, an order that hasn't reached its renewal window will not throw an error and will not be skipped when using either of the -All parameters. + + + SwitchParameter + + + False + + + NoSkipManualDns + + If specified, orders that utilize the Manual DNS plugin will not be skipped and user interaction may be required to complete the process. Otherwise, orders that utilize the Manual DNS plugin will be skipped. + + + SwitchParameter + + + False + + + PluginArgs + + A hashtable containing an updated set of plugin arguments to use with the renewal. So if a plugin has a `MyText` string and `MyNumber` integer parameter, you could specify them as `@{MyText='text';MyNumber=1234}`. + + Hashtable + + Hashtable + + + None + + + + Submit-Renewal + + AllAccounts + + If specified, renew all valid orders on all valid accounts in this profile. Orders that have not reached the renewal window will be skipped unless -Force is used. + + + SwitchParameter + + + False + + + Force + + If specified, an order that hasn't reached its renewal window will not throw an error and will not be skipped when using either of the -All parameters. + + + SwitchParameter + + + False + + + NoSkipManualDns + + If specified, orders that utilize the Manual DNS plugin will not be skipped and user interaction may be required to complete the process. Otherwise, orders that utilize the Manual DNS plugin will be skipped. + + + SwitchParameter + + + False + + + PluginArgs + + A hashtable containing an updated set of plugin arguments to use with the renewal. So if a plugin has a `MyText` string and `MyNumber` integer parameter, you could specify them as `@{MyText='text';MyNumber=1234}`. + + Hashtable + + Hashtable + + + None + + + + + + MainDomain + + The primary domain associated with an order. This is the domain that goes in the certificate's subject. + + String + + String + + + None + + + Name + + The name of the ACME order. This can be useful to distinguish between two orders that have the same MainDomain. + + String + + String + + + None + + + AllOrders + + If specified, renew all valid orders on the current account. Orders that have not reached the renewal window will be skipped unless -Force is used. + + SwitchParameter + + SwitchParameter + + + False + + + AllAccounts + + If specified, renew all valid orders on all valid accounts in this profile. Orders that have not reached the renewal window will be skipped unless -Force is used. + + SwitchParameter + + SwitchParameter + + + False + + + Force + + If specified, an order that hasn't reached its renewal window will not throw an error and will not be skipped when using either of the -All parameters. + + SwitchParameter + + SwitchParameter + + + False + + + NoSkipManualDns + + If specified, orders that utilize the Manual DNS plugin will not be skipped and user interaction may be required to complete the process. Otherwise, orders that utilize the Manual DNS plugin will be skipped. + + SwitchParameter + + SwitchParameter + + + False + + + PluginArgs + + A hashtable containing an updated set of plugin arguments to use with the renewal. So if a plugin has a `MyText` string and `MyNumber` integer parameter, you could specify them as `@{MyText='text';MyNumber=1234}`. + + Hashtable + + Hashtable + + + None + + + + + + + PoshACME.PACertificate + + + A certificate object. + + + + + + Certificate objects are only returned for orders that were actually renewed successfully. Any orders that have not reached the suggested renewal window are skipped unless `-Force` is specified. + + + + + -------------------------- Example 1 -------------------------- + Submit-Renewal + + Renew the current order on the current account. + + + + + -------------------------- Example 2 -------------------------- + Submit-Renewal -Force + + Renew the current order on the current account even if it hasn't reached its suggested renewal window. + + + + + -------------------------- Example 3 -------------------------- + Submit-Renewal -AllOrders + + Renew all valid orders on the current account that have reached their suggested renewal window. + + + + + -------------------------- Example 4 -------------------------- + Submit-Renewal -AllAccounts + + Renew all valid orders on all valid accounts that have reached their suggested renewal window. + + + + + -------------------------- Example 5 -------------------------- + Submit-Renewal site1.example.com -Force + + Renew the order for the specified site regardless of its renewal window. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Submit-Renewal/ + + + New-PACertificate + + + + Get-PAOrder + + + + + + + Unpublish-Challenge + Unpublish + Challenge + + Unpublish a challenge using the specified plugin. + + + + Based on the type of validation plugin specified, this function will unpublish either a DNS TXT record or an HTTP challenge file for the given domain and token value that satisfies the dns-01 or http-01 challenge specification. + Depending on the plugin, calling `Save-Challenge` may be required to commit changes made by `Unpublish-Challenge`. If multiple challenges are being unpublished, make all `Unpublish-Challenge` calls first. Then, `Save-Challenge` once to commit them all. + + + + Unpublish-Challenge + + Domain + + The domain name that the challenge will be unpublished for. Wildcard domains should have the "*." removed and can only be used with DNS based validation plugins. + + String + + String + + + None + + + Account + + The account object associated with the order that required the challenge. + + Object + + Object + + + None + + + Token + + The token value from the appropriate challenge in an authorization object that matches the plugin type. + + String + + String + + + None + + + Plugin + + The name of the validation plugin to use. Use Get-PAPlugin to display a list of available plugins. + + String + + String + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified plugin. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + When using DNS Alias support with DNS validation plugins, the alias domain that the TXT record will be removed from. This should be the complete FQDN including the '_acme-challenge.' prefix if necessary. This field is ignored for non-DNS validation plugins. + + String + + String + + + None + + + + + + Domain + + The domain name that the challenge will be unpublished for. Wildcard domains should have the "*." removed and can only be used with DNS based validation plugins. + + String + + String + + + None + + + Account + + The account object associated with the order that required the challenge. + + Object + + Object + + + None + + + Token + + The token value from the appropriate challenge in an authorization object that matches the plugin type. + + String + + String + + + None + + + Plugin + + The name of the validation plugin to use. Use Get-PAPlugin to display a list of available plugins. + + String + + String + + + None + + + PluginArgs + + A hashtable containing the plugin arguments to use with the specified plugin. So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + + Hashtable + + Hashtable + + + None + + + DnsAlias + + When using DNS Alias support with DNS validation plugins, the alias domain that the TXT record will be removed from. This should be the complete FQDN including the '_acme-challenge.' prefix if necessary. This field is ignored for non-DNS validation plugins. + + String + + String + + + None + + + + + + + + + + -------------------------- Example 1 -------------------------- + $auths = Get-PAOrder | Get-PAAuthorization +Unpublish-Challenge $auths[0].DNSId (Get-PAAccount) $auths[0].DNS01Token Manual @{} + + Unpublish a DNS challenge for the first authorization in the current order using the Manual DNS plugin. + + + + + -------------------------- Example 2 -------------------------- + $pArgs = @{Param1='asdf';Param2=1234} +$acct = Get-PAAccount +Unpublish-Challenge example.com $acct MyPlugin $pArgs -Token faketoken + + Unpublish a challenge for example.com using a fictitious plugin and arguments. + + + + + + + Online Version: + https://poshac.me/docs/v4/Functions/Unpublish-Challenge/ + + + Publish-Challenge + + + + Save-Challenge + + + + Get-PAPlugin + + + + + diff --git a/README.md b/README.md index 9253e99a..6f48d6d5 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,29 @@ # Posh-ACME -An [ACME (RFC 8555)](https://tools.ietf.org/html/rfc8555) client implemented as a [PowerShell](#requirements-and-platform-support) module that enables you to generate publicly trusted SSL/TLS certificates from an ACME capable certificate authority such as [Let's Encrypt](https://letsencrypt.org/). +A [PowerShell](#requirements-and-platform-support) module and [ACME](https://tools.ietf.org/html/rfc8555) client to create publicly trusted SSL/TLS certificates from an ACME capable certificate authority such as [Let's Encrypt](https://letsencrypt.org/). -# Notable Features +## Notable Features -- Multi-domain (SAN) and wildcard (*.example.com) certificates supported. -- [RFC 8738](https://tools.ietf.org/html/rfc8738) support for generating certificates for IP addresses (if your ACME CA supports it). -- Single command for new certs, `New-PACertificate` -- Easy renewals via `Submit-Renewal` -- RSA and ECC private keys supported for accounts and certificates -- Built-in validation plugins for [DNS](https://github.com/rmbolger/Posh-ACME/wiki/List-of-Supported-DNS-Providers) and [HTTP](https://github.com/rmbolger/Posh-ACME/wiki/List-of-Supported-HTTP-Plugins) based challenges. (pull requests welcome) -- Support for using existing certificate request (CSR) +- Multi-domain (SAN) and wildcard (*.example.com) certificates supported +- IP Address certificates ([RFC 8738](https://tools.ietf.org/html/rfc8738)) *(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](https://poshac.me/docs/latest/Plugins/) 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)](https://github.com/rmbolger/Posh-ACME/wiki/Frequently-Asked-Questions-(FAQ)#does-posh-acme-work-cross-platform-on-powershell-core) +- No elevated Windows privileges required *(unless using `-Install` switch)* +- Cross platform PowerShell support. [(FAQ)](https://poshac.me/docs/latest/FAQ/#does-posh-acme-work-cross-platform-on-powershell-core) - Account key rollover support - [OCSP Must-Staple](https://scotthelme.co.uk/ocsp-must-staple/) support -- DNS challenge [CNAME support](https://github.com/rmbolger/Posh-ACME/blob/main/Tutorial.md#advanced-dns-challenge-aliases) -- Multiple accounts supported per certificate authority which allows different certs to have different contact emails -- Help system for DNS plugins using `Get-PAPlugin` -- External Account Binding support for CAs that require it +- DNS challenge [CNAME support](https://poshac.me/docs/latest/Guides/Using-DNS-Challenge-Aliases/) +- Multiple ACME accounts supported per ACME CA. +- External Account Binding support for ACME CAs that require it - Preferred Chain support to use alternative CA trust chains -# Install +## Installation (Stable) -## Release - -The latest release version can found in the [PowerShell Gallery](https://www.powershellgallery.com/packages/Posh-ACME/) or the [GitHub releases page](https://github.com/rmbolger/Posh-ACME/releases). Installing from the gallery is easiest using `Install-Module` from the PowerShellGet module. See [Installing PowerShellGet](https://docs.microsoft.com/en-us/powershell/scripting/gallery/installing-psget) if you don't already have it installed. +The latest release can found in the [PowerShell Gallery](https://www.powershellgallery.com/packages/Posh-ACME/) or the [GitHub releases page](https://github.com/rmbolger/Posh-ACME/releases). Installing is easiest from the gallery using `Install-Module`. *See [Installing PowerShellGet](https://docs.microsoft.com/en-us/powershell/scripting/gallery/installing-psget) if you run into problems with it.* ```powershell # install for all users (requires elevated privs) @@ -38,53 +35,57 @@ 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](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/).* -## Development +## Installation (Development) [![Pester Tests badge](https://github.com/rmbolger/Posh-ACME/workflows/Pester%20Tests/badge.svg)](https://github.com/rmbolger/Posh-ACME/actions) -To install the latest *development* version from the git main branch, use the following PowerShell command. This method assumes a default [`PSModulePath`](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_psmodulepath) environment variable. +Use the following PowerShell command to install the latest *development* version from the git `main` branch. This method assumes a default [`PSModulePath`](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_psmodulepath) environment variable and installs to the CurrentUser scope. ```powershell -# install latest dev version iex (irm https://raw.githubusercontent.com/rmbolger/Posh-ACME/main/instdev.ps1) ``` -# Quick Start +You can also download the source manually from GitHub and extract the `Posh-ACME` folder to your desired module location. + +## Quick Start -On Windows, you may need to set a less restrictive PowerShell execution policy before you can import the module. +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. ```powershell -Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force -Import-Module Posh-ACME +New-PACertificate example.com -AcceptTOS ``` -The minimum parameters you need for a cert are the domain name and the `-AcceptTOS` flag. +NOTE: On Windows, you may need to set a less restrictive PowerShell execution policy before you can import the module. ```powershell -New-PACertificate example.com -AcceptTOS +Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force +Import-Module Posh-ACME ``` -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. + 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. ```powershell $certNames = '*.example.com','example.com' $email = 'admin@example.com' -$pArgs = @{FBCred=(Get-Credential)} - -New-PACertificate $certNames -AcceptTOS -Contact $email -Plugin Flurbog -PluginArgs $pArgs +$pArgs = @{ + FDToken = (Read-Host 'FakeDNS API Token' -AsSecureString) +} +New-PACertificate $certNames -AcceptTOS -Contact $email -Plugin FakeDNS -PluginArgs $pArgs ``` -To learn how to use the supported DNS plugins, check out `Get-PAPlugin -Guide`. There's also a [tutorial](/Tutorial.md) for a more in-depth guide to using the module. +To learn how to use a specific plugins, check out `Get-PAPlugin -Guide`. There's also a [tutorial](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. +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 +## Requirements and Platform Support * Supports Windows PowerShell 5.1 (Desktop edition) **with .NET Framework 4.7.1** or later -* Supports [PowerShell Core](https://docs.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-core-60) 6.2 or later (Core edition) on all supported OS platforms. *NOTE: 6.0-6.1 will also work, but there are known issues when using SecureString or PSCredential plugin args on non-Windows platforms.* +* Supports PowerShell 6.2 or later ([Core edition](https://docs.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell)) on all supported OS platforms. * Requires `FullLanguage` [language mode](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_language_modes) -# Changelog +*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](/CHANGELOG.md) diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 00000000..d3cf0f99 --- /dev/null +++ b/docs/.pages @@ -0,0 +1,7 @@ +nav: + - index.md + - Tutorial.md + - Functions + - Plugins + - Guides + - 'FAQ': 'FAQ.md' diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 00000000..7e2e70a2 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,109 @@ +# Frequently Asked Questions (FAQ) + +## Where is my config? Where is my cert? + +Unless you have [changed the default](Guides/Using-an-Alternate-Config-Location.md), all Posh-ACME config is in your user profile depending on the OS: + +- Windows: `%LOCALAPPDATA%\Posh-ACME` +- Linux: `$HOME/.config/Posh-ACME` +- MacOS: `$HOME/Library/Preferences/Posh-ACME` + +The full paths to all cert files for the current order is in the detailed output of `Get-PACertificate`. + +```powershell +Get-PACertificate | Format-List +``` + +## How Do I Upgrade From 3.x to 4.x? + +If your certificate renewals are using `Submit-Renewal`, no changes should be necessary in order to upgrade from 3.x to 4.0 unless you were using the `-NewKey` parameter which has been removed. Orders can now be configured to always generate a new private key using `Set-PAOrder -AlwaysNewKey`. For example, you can set the flag for all orders in an account like this: + +```powershell +Get-PAOrder -List | Set-PAOrder -AlwaysNewKey +``` + +For custom scripts that use more of the module's functions be aware of the following changes: + +* `Invoke-HttpChallengeListener` is deprecated and may be removed in a future release. Users should migrate to the `WebSelfHost` plugin. +* `Publish/Unpublish/Save-DnsChallenge` functions have been renamed to `Publish/Unpublish/Save-Challenge`. +* All references to the `DnsPlugin` parameter should be replaced with `Plugin`. +* `NewKey` has been removed from `Submit-Renewal`. +* `NewKey`/`NewCertKey` have been replaced by `AlwaysNewKey` in `New-PACertificate` and `New-PAOrder`. +* `AlwaysNewKey` has been added to `Set-PAOrder`. +* `DnsPlugin`, `PluginArgs`, `DnsAlias`, `DnsSleep`, `ValidationTimeout` and `Account` parameters have been removed from `Submit-ChallengeValidation`. The account associated with the order must be the currently active account. The rest of the parameters are read directly from the order object and can be modified in advance with `Set-PAOrder` if necessary. +* The `NoPrefix` switch in `Publish/Unpublish-Challenge` has been replaced with a `DnsAlias` parameter that will override the `Domain` parameter if specified. "_acme-challenge." will not be automatically added to `DnsAlias` values. For example: + +```powershell +# Old 3.x method to publish an alias +Publish-DnsChallenge -Domain alias.example.com -NoPrefix -DnsPlugin MyPlugin -Account (Get-PAAccount) -Token xxxx -PluginArgs $pArgs + +# New 4.x method to publish an alias +Publish-DnsChallenge -Domain example.com -DnsAlias alias.example.com -Plugin MyPlugin -Account (Get-PAAccount) -Token xxxx -PluginArgs $pArgs +``` + +If your workflow relied on new orders automatically using the plugin args from previously configured orders, that no longer works and you will have to explicitly set the `-PluginArgs` parameter for each new order. However, you can use `Get-PAPluginArgs` to make it easier. For example: + +```powershell +# Old 3.x method where new order uses old plugin args automatically +New-PACertificate www1.example.com -Plugin MyPlugin -PluginArgs @{MyArg='xxxx'} +New-PACertificate www2.example.com -Plugin MyPlugin + +# New 4.x method +New-PACertificate www1.example.com -Plugin MyPlugin -PluginArgs @{MyArg='xxxx'} +$pArgs = Get-PAPluginArgs www1.example.com +New-PACertificate www2.example.com -Plugin MyPlugin -PluginArgs $pArgs +``` + +## How have Plugins changed in 4.x? + +See the [Migrating DNS Plugins from 3x to 4x](Plugins/Plugin-Development-Guide.md#migrating-dns-plugins-from-3x-to-4x) section of the plugin development guide. + +## Does Posh-ACME work cross platform on PowerShell Core? + +Yes as of 2.2.0!...with a few caveats. + +The `-Install` parameter in `New-PACertificate` is not supported on non-Windows platforms and will throw an error if used because there's no certificate store equivalent to install to. + +On non-Windows OSes, `[securestring]` and `[pscredential]` plugins are not encrypted on disk by default because the encryption APIs used on Windows aren't available. However, you can enable AES based encryption that is also portable between OSes on a per-account level. This can be done during account creation or after the fact and you can switch between native and AES encryption at any time as in the following examples: + +```powershell +# enable AES encryption during account creation +New-PAAccount -AcceptTOS -Contact me@example.com -UseAltPluginEncryption + +# enable AES encryption on an existing account +Set-PAAccount -UseAltPluginEncryption + +# switch back to OS-native encryption on an existing account +Set-PAAccount -UseAltPluginEncryption:$false +``` + +## Key not valid for use in specified state + +This can happen on Windows if you try to copy the Posh-ACME profile folder to a different Windows computer or a different user's profile on the same computer. The underlying APIs used to encrypt plugin parameters using `SecureString` and `PSCredential` objects are tied to both the current computer and user and are not portable. However, you can use the `Set-PAAccount -UseAltPluginEncryption` to change the encryption used for the account to a portable AES based method and then copy the profile. + + +## The underlying connection was closed: Cloud not establish trust relationship for the SSL/TLS secure channel. + +This shouldn't ever happen when using a publicly trusted certificate authority such as Let's Encrypt. If it does, an attacker or malware might be trying to [MitM](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) your connection. + +However if you're doing development against a test ACME server like [Pebble](https://github.com/letsencrypt/pebble) or a private instance of [Boulder](https://github.com/letsencrypt/boulder), this is normal because the server is likely using a self-signed certificate. You can work around the problem by adding the `-SkipCertificateCheck` parameter to `Set-PAServer`. + +If the error seems to originate from one of the plugins, submit an [issue](https://github.com/rmbolger/Posh-ACME/issues) and we can figure it out. + +## Access is denied + +The most common reason this error shows up is that you used the `-Install` parameter with `New-PACertificate` and you're not running PowerShell as an elevated process (Run as Administrator). Both the original call to `New-PACertificate` and any subsequent calls to `Submit-Renewal` need to run elevated for the module to install the resulting certificate. + +## Refer to sub-problems for more information. + +This is generally part of a longer error message and most often shows up when you're trying to create a certificate with multiple names. It means that the error body has additional detail that can help identify what went wrong. You can access the sub-problem data from the Exception object like this. + +```powershell +# If you haven't caught the error in a try/catch block, it should be in the first index in the error object +$Error[0].Exception.Data.subproblems | Format-List + +# If you did catch the error, it will be in the $_ object +catch { + $_.Exception.Data.subproblems | Format-List +} +``` diff --git a/docs/Functions/Complete-PAOrder.md b/docs/Functions/Complete-PAOrder.md new file mode 100644 index 00000000..576957fe --- /dev/null +++ b/docs/Functions/Complete-PAOrder.md @@ -0,0 +1,75 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Complete-PAOrder/ +schema: 2.0.0 +--- + +# Complete-PAOrder + +## Synopsis + +Exports cert files for a completed order and adds suggested renewal window to the order. + +## Syntax + +```powershell +Complete-PAOrder [[-Order] ] [] +``` + +## Description + +Once an ACME order is finalized, the signed certificate and chain can be downloaded and combined with the local private key to generate the supported PEM and PFX files on disk. +This function will also calculate the renewal window based on the signed certificate's expiration date and update the order object with that info. +If the Install flag is set, this function will attempt to import the certificate into the Windows certificate store. + +## Examples + +### Example 1: Complete the current order + +```powershell +Complete-PAOrder +``` + +### Example 2: Complete a specific order + +```powershell +Get-PAOrder example.com | Complete-PAOrder +``` + +## Parameters + +### -Order +The order object to complete which must be associated with the currently active ACME account. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### PoshACME.PAOrder +An order object as returned by Get-PAOrder. + +## Outputs + +### PoshACME.PACertificate +The certificate object for the order. + +## Related Links + +[Get-PAOrder](Get-PAOrder.md) + +[New-PAOrder](New-PAOrder.md) diff --git a/docs/Functions/Export-PAAccountKey.md b/docs/Functions/Export-PAAccountKey.md new file mode 100644 index 00000000..49cdb5d6 --- /dev/null +++ b/docs/Functions/Export-PAAccountKey.md @@ -0,0 +1,139 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Export-PAAccountKey/ +schema: 2.0.0 +--- + +# Export-PAAccountKey + +## Synopsis + +Export an ACME account private key. + +## Syntax + +```powershell +Export-PAAccountKey [[-ID] ] -OutputFile [-Force] [-WhatIf] [-Confirm] [] +``` + +## Description + +The account key is saved as an unencrypted Base64 encoded PEM file. + +## Examples + +### Example 1: Export the current account key + +```powershell +Export-PAAccountKey -OutputFile .\mykey.pem +``` + +Exports the current ACME account's key to the specified file. + +### Example 2: Export the specified account key + +```powershell +Export-PAAccountKey 12345 -OutputFile .\mykey.pem -Force +``` + +Exports the specified ACME account's key to the specified file and overwrites it if necessary. + +### Example 3: Backup all account keys to the desktop + +```powershell +$fldr = Join-Path ([Environment]::GetFolderPath('Desktop')) 'AcmeAccountKeys' +New-Item -ItemType Directory -Force -Path $fldr | Out-Null +Get-PAAccount -List | %{ + Export-PAAccountKey $_.ID -OutputFile "$fldr\$($_.ID).key" -Force +} +``` + +Backup all account keys for this ACME server to a folder on the desktop. + +## Parameters + +### -ID +The ACME account ID value. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: Name + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OutputFile +The path to the file to write the key data to. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +If specified and the output file already exists, it will be overwritten. +Without the switch, a confirmation prompt will be presented. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Related Links + +[Get-PAAccount](Get-PAAccount.md) diff --git a/docs/Functions/Get-KeyAuthorization.md b/docs/Functions/Get-KeyAuthorization.md new file mode 100644 index 00000000..217443d5 --- /dev/null +++ b/docs/Functions/Get-KeyAuthorization.md @@ -0,0 +1,108 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Get-KeyAuthorization/ +schema: 2.0.0 +--- + +# Get-KeyAuthorization + +## Synopsis + +Calculate a key authorization string for a challenge token. + +## Syntax + +```powershell +Get-KeyAuthorization [-Token] [[-Account] ] [-ForDNS] [] +``` + +## Description + +A key authorization is a string that expresses a domain holder's authorization for a specified key to satisfy a specified challenge, by concatenating the token for the challenge with a key fingerprint. + +## Examples + +### Example 1 + +```powershell +Get-KeyAuthorization 'XxXxXxXxXxXx' +``` + +Get the key authorization for the specified token using the current account. + +### Example 2 + +```powershell +(Get-PAOrder | Get-PAAuthorization).DNS01Token | Get-KeyAuthorization +``` + +Get all key authorizations for the DNS challenges in the current order using the current account. + +## Parameters + +### -Token +The token string for an ACME challenge. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Account +The ACME account associated with the challenge. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForDNS +Enable this switch if you're using the key authorization value for the 'dns-01' challenge type. +It will do a few additional manipulation steps on the value that are required for a DNS TXT record. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### System.String +The token value from an ACME challenge object. + +## Outputs + +### System.String +The key authorization value. + +## Related Links + +[Get-PAAuthorization](Get-PAAuthorization.md) + +[Submit-ChallengeValidation](Submit-ChallengeValidation.md) diff --git a/docs/Functions/Get-PAAccount.md b/docs/Functions/Get-PAAccount.md new file mode 100644 index 00000000..7324b1b7 --- /dev/null +++ b/docs/Functions/Get-PAAccount.md @@ -0,0 +1,208 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Get-PAAccount/ +schema: 2.0.0 +--- + +# Get-PAAccount + +## Synopsis + +Get ACME account details. + +## Syntax + +### Specific + +```powershell +Get-PAAccount [[-ID] ] [-Refresh] [-ExtraParams ] [] +``` + +### List + +```powershell +Get-PAAccount [-List] [-Status ] [-Contact ] [-KeyLength ] [-Refresh] + [-ExtraParams ] [] +``` + +## Description + +Returns details such as Email, key length, and status for one or more ACME accounts previously created. + +## Examples + +### Example 1 + +```powershell +Get-PAAccount +``` + +Get cached ACME account details for the currently selected account. + +### Example 2 + +```powershell +Get-PAAccount -ID 1234567 +``` + +Get cached ACME account details for the specified account ID. + +### Example 3 + +```powershell +Get-PAAccount -List +``` + +Get all cached ACME account details. + +### Example 4 + +```powershell +Get-PAAccount -Refresh +``` + +Get fresh ACME account details for the currently selected account. + +### Example 5 + +```powershell +Get-PAAccount -List -Refresh +``` + +Get fresh ACME account details for all accounts. + +### Example 6 + +```powershell +Get-PAAccount -List -Contact user1@example.com +``` + +Get cached ACME account details for all accounts that have user1@example.com as the only contact. + +## Parameters + +### -ID +The account id value as returned by the ACME server. +'Name' is also an alias for this parameter. + +```yaml +Type: String +Parameter Sets: Specific +Aliases: Name + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -List +If specified, the details for all accounts will be returned. + +```yaml +Type: SwitchParameter +Parameter Sets: List +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Status +A Status string to filter the list of accounts with. + +```yaml +Type: String +Parameter Sets: List +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Contact +One or more email addresses to filter the list of accounts with. +Returned accounts must match exactly (not including the order). + +```yaml +Type: String[] +Parameter Sets: List +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -KeyLength +The type and size of private key to filter the list of accounts with. +For RSA keys, specify a number between 2048-4096 (divisible by 128). +For ECC keys, specify either 'ec-256' or 'ec-384'. + +```yaml +Type: String[] +Parameter Sets: List +Aliases: AccountKeyLength + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Refresh +If specified, any account details returned will be freshly queried from the ACME server (excluding deactivated accounts). +Otherwise, cached details will be returned. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExtraParams +This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Outputs + +### PoshACME.PAAccount +An account object. + +## Related Links + +[Set-PAAccount](Set-PAAccount.md) + +[New-PAAccount](New-PAAccount.md) diff --git a/docs/Functions/Get-PAAuthorization.md b/docs/Functions/Get-PAAuthorization.md new file mode 100644 index 00000000..b0fe189a --- /dev/null +++ b/docs/Functions/Get-PAAuthorization.md @@ -0,0 +1,102 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Get-PAAuthorization/ +schema: 2.0.0 +--- + +# Get-PAAuthorization + +## Synopsis + +Get the authorizations associated with a particular order or set of authorization URLs. + +## Syntax + +```powershell +Get-PAAuthorization [-AuthURLs] [[-Account] ] [] +``` + +## Description + +Returns details such as fqdn, status, expiration, and challenges for one or more ACME authorizations. + +## Examples + +### Example 1 + +```powershell +Get-PAAuthorization https://acme.example.com/authz/1234567 +``` + +Get the authorization for the specified URL. + +### Example 2 + +```powershell +Get-PAOrder | Get-PAAuthorization +``` + +Get the authorizations for the current order on the current account. + +### Example 3 + +```powershell +Get-PAOrder -List | Get-PAAuthorization +``` + +Get the authorizations for all orders on the current account. + +## Parameters + +### -AuthURLs +One or more authorization URLs. +You also pipe in one or more PoshACME.PAOrder objects. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: authorizations + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Account +An existing ACME account object such as the output from Get-PAAccount. +If no account is specified, the current account will be used. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### System.String +The URI of the authorization object. + +## Outputs + +### PoshACME.PAAuthorization +An authorization object. + +## Related Links + +[Get-PAOrder](Get-PAOrder.md) + +[New-PAOrder](New-PAOrder.md) diff --git a/docs/Functions/Get-PACertificate.md b/docs/Functions/Get-PACertificate.md new file mode 100644 index 00000000..280bbdfd --- /dev/null +++ b/docs/Functions/Get-PACertificate.md @@ -0,0 +1,118 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Get-PACertificate/ +schema: 2.0.0 +--- + +# Get-PACertificate + +## Synopsis + +Get ACME certificate details. + +## Syntax + +### Specific + +```powershell +Get-PACertificate [[-MainDomain] ] [-Name ] [] +``` + +### List + +```powershell +Get-PACertificate [-List] [] +``` + +## Description + +Returns details such as Thumbprint, Subject, Validity, SANs, and file locations for one or more ACME certificates previously created. + +## Examples + +### Example 1 + +```powershell +Get-PACertificate +``` + +Get cached ACME order details for the currently selected order. + +### Example 2 + +```powershell +Get-PACertificate site.example.com +``` + +Get cached ACME order details for the specified domain. + +### Example 3 + +```powershell +Get-PACertificate -List +``` + +Get all cached ACME order details. + +## Parameters + +### -MainDomain +The primary domain associated with the certificate. +This is the domain that goes in the certificate's subject. + +```yaml +Type: String +Parameter Sets: Specific +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Name +The name of the ACME order. +This can be useful to distinguish between two orders that have the same MainDomain. + +```yaml +Type: String +Parameter Sets: Specific +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -List +If specified, the details for all completed certificates will be returned for the current account. + +```yaml +Type: SwitchParameter +Parameter Sets: List +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Outputs + +### PoshACME.PACertificate +A certificate object. + +## Related Links + +[New-PACertificate](New-PACertificate.md) diff --git a/docs/Functions/Get-PAOrder.md b/docs/Functions/Get-PAOrder.md new file mode 100644 index 00000000..11e75eb0 --- /dev/null +++ b/docs/Functions/Get-PAOrder.md @@ -0,0 +1,152 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Get-PAOrder/ +schema: 2.0.0 +--- + +# Get-PAOrder + +## Synopsis + +Get ACME order details. + +## Syntax + +### Specific + +```powershell +Get-PAOrder [[-MainDomain] ] [-Name ] [-Refresh] [] +``` + +### List + +```powershell +Get-PAOrder [-List] [-Refresh] [] +``` + +## Description + +Returns details such as Domains, key length, expiration, and status for one or more ACME orders previously created. + +## Examples + +### Example 1 + +```powershell +Get-PAOrder +``` + +Get cached ACME order details for the currently selected order. + +### Example 2 + +```powershell +Get-PAOrder site.example.com +``` + +Get cached ACME order details for the specified domain. + +### Example 3 + +```powershell +Get-PAOrder -List +``` + +Get all cached ACME order details. + +### Example 4 + +```powershell +Get-PAOrder -Refresh +``` + +Get fresh ACME order details for the currently selected order. + +### Example 5 + +```powershell +Get-PAOrder -List -Refresh +``` + +Get fresh ACME order details for all orders. + +## Parameters + +### -MainDomain +The primary domain associated with the order. +This is the domain that goes in the certificate's subject. + +```yaml +Type: String +Parameter Sets: Specific +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Name +The name of the ACME order. +This can be useful to distinguish between two orders that have the same MainDomain. + +```yaml +Type: String +Parameter Sets: Specific +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -List +If specified, the details for all orders will be returned. + +```yaml +Type: SwitchParameter +Parameter Sets: List +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Refresh +If specified, any order details returned will be freshly queried from the ACME server. +Otherwise, cached details will be returned. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Outputs + +### PoshACME.PAOrder +An order object. + +## Related Links + +[Set-PAOrder](Set-PAOrder.md) + +[New-PAOrder](New-PAOrder.md) diff --git a/docs/Functions/Get-PAPlugin.md b/docs/Functions/Get-PAPlugin.md new file mode 100644 index 00000000..abbb2510 --- /dev/null +++ b/docs/Functions/Get-PAPlugin.md @@ -0,0 +1,147 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Get-PAPlugin/ +schema: 2.0.0 +--- + +# Get-PAPlugin + +## Synopsis + +Show plugin details, help, or launch the online guide. + +## Syntax + +### Basic (Default) + +```powershell +Get-PAPlugin [[-Plugin] ] [] +``` + +### Params + +```powershell +Get-PAPlugin [-Plugin] [-Params] [] +``` + +### Guide + +```powershell +Get-PAPlugin [-Plugin] [-Guide] [] +``` + +### Help + +```powershell +Get-PAPlugin [-Plugin] [-Help] [] +``` + +## Description + +With no parameters, this function will return a list of built-in validation plugins and their details. + +With a Plugin specified, this function will return that plugin's details, help, or launch the online guide depending on which switches are specified. + +## Examples + +### Example 1 + +```powershell +Get-PAPlugin +``` + +Get the list of available validation plugins + +### Example 2 + +```powershell +Get-PAPlugin Route53 -Guide +``` + +Launch the user's default web browser to the online guide for the specified plugin. + +## Parameters + +### -Plugin +The name of a validation plugin. + +```yaml +Type: String +Parameter Sets: Basic +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +```yaml +Type: String +Parameter Sets: Params, Guide, Help +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Help +If specified, display the help contents for the specified plugin. + +```yaml +Type: SwitchParameter +Parameter Sets: Help +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Guide +If specified, launch the default web browser to the specified plugin's online guide. +This currently only works on Windows and will simply display the URL on other OSes. + +```yaml +Type: SwitchParameter +Parameter Sets: Guide +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Params +If specified, returns the plugin-specific parameter sets associated with this plugin. + +```yaml +Type: SwitchParameter +Parameter Sets: Params +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Related Links + +[New-PACertificate](New-PACertificate.md) + +[Publish-Challenge](Publish-Challenge.md) diff --git a/docs/Functions/Get-PAPluginArgs.md b/docs/Functions/Get-PAPluginArgs.md new file mode 100644 index 00000000..eeb30280 --- /dev/null +++ b/docs/Functions/Get-PAPluginArgs.md @@ -0,0 +1,95 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Get-PAPluginArgs/ +schema: 2.0.0 +--- + +# Get-PAPluginArgs + +## Synopsis + +Retrieve the plugin args for the current or specified order. + +## Syntax + +```powershell +Get-PAPluginArgs [[-MainDomain] ] [-Name ] [] +``` + +## Description + +An easy way to recall the plugin args used for a given order. + +## Examples + +### Example 1 + +```powershell +Get-PAPluginArgs +``` + +Retrieve the plugin args for the current order. + +### Example 2 + +```powershell +Get-PAPluginArgs -Name myorder +``` + +Retrieve the plugin args for the specified order. + +### Example 3 + +```powershell +Get-PAOrder -Name myorder | Get-PAPluginArgs +``` + +Retrieve the plugin args for the order passed via the pipeline. + +## Parameters + +### -MainDomain +The primary domain for the order. +For a SAN order, this was the first domain in the list when creating the order. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Name +The name of the ACME order. +This can be useful to distinguish between two orders that have the same MainDomain. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Outputs + +### System.Collections.Hashtable +A hashtable containing saved plugin parameters. + +## Related Links + +[Gew-PAOrder](Get-PAOrder.md) diff --git a/docs/Functions/Get-PAServer.md b/docs/Functions/Get-PAServer.md new file mode 100644 index 00000000..27a60621 --- /dev/null +++ b/docs/Functions/Get-PAServer.md @@ -0,0 +1,175 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Get-PAServer/ +schema: 2.0.0 +--- + +# Get-PAServer + +## Synopsis + +Get ACME server details. + +## Syntax + +### Specific (Default) + +```powershell +Get-PAServer [[-DirectoryUrl] ] [-Name ] [-Refresh] [-Quiet] [] +``` + +### List + +```powershell +Get-PAServer [-List] [-Refresh] [] +``` + +## Description + +The primary use for this function is checking which ACME server is currently configured. +New Account and Cert requests will be directed to this server. +It may also be used to refresh server details and list additional servers that have previously been used. + +## Examples + +### Example 1 + +```powershell +Get-PAServer +``` + +Get cached ACME server details for the currently selected server. + +### Example 2 + +```powershell +Get-PAServer -DirectoryUrl LE_PROD +``` + +Get cached LetsEncrypt production server details using the short name. + +### Example 3 + +```powershell +Get-PAServer -List +``` + +Get all cached ACME server details. + +### Example 4 + +```powershell +Get-PAServer -DirectoryUrl https://myacme.example.com/directory +``` + +Get cached ACME server details for the specified directory URL. + +### Example 5 + +```powershell +Get-PAServer -Refresh +``` + +Get fresh ACME server details for the currently selected server. + +### Example 6 + +```powershell +Get-PAServer -List -Refresh +``` + +Get fresh ACME server details for all previously used servers. + +## Parameters + +### -DirectoryUrl +Either the URL to an ACME server's "directory" endpoint or one of the supported short names. +Currently supported short names include LE_PROD (LetsEncrypt Production v2), LE_STAGE (LetsEncrypt Staging v2), BUYPASS_PROD (BuyPass.com Production), and BUYPASS_TEST (BuyPass.com Testing). + +```yaml +Type: String +Parameter Sets: Specific +Aliases: location + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Name +The name of the ACME server. +The parameter is ignored if DirectoryUrl is specified. + +```yaml +Type: String +Parameter Sets: Specific +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -List +If specified, the details for all previously used servers will be returned. + +```yaml +Type: SwitchParameter +Parameter Sets: List +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Refresh +If specified, any server details returned will be freshly queried from the ACME server. +Otherwise, cached details will be returned. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Quiet +If specified, no warning will be thrown if a specified server is not found. + +```yaml +Type: SwitchParameter +Parameter Sets: Specific +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Outputs + +### PoshACME.PAServer +A server object. + +## Related Links + +[Set-PAServer](Set-PAServer.md) diff --git a/docs/Functions/Install-PACertificate.md b/docs/Functions/Install-PACertificate.md new file mode 100644 index 00000000..19f656fe --- /dev/null +++ b/docs/Functions/Install-PACertificate.md @@ -0,0 +1,132 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Install-PACertificate/ +schema: 2.0.0 +--- + +# Install-PACertificate + +## Synopsis + +Install a Posh-ACME certificate into a Windows certificate store. + +## Syntax + +```powershell +Install-PACertificate [[-PACertificate] ] [[-StoreLocation] ] [[-StoreName] ] + [-NotExportable] [] +``` + +## Description + +This can be used instead of the -Install parameter on New-PACertificate to import a certificate with more configurable options. + +## Examples + +### Example 1 + +```powershell +Install-PACertificate +``` + +Install the certificate for the currently selected order to the default LocalMachine\My store. + +### Example 2 + +```powershell +Get-PACertificate example.com | Install-PACertificate +``` + +Install the specified certificate to the default LocalMachine\My store. + +### Example 3 + +```powershell +Install-PACertificate -StoreLocation 'CurrentUser' -NotExportable +``` + +Install the certificate for the currently selected order to the CurrentUser\My store and mark the private key as not exportable. + +## Parameters + +### -PACertificate +The PACertificate object you want to import. +This can be retrieved using Get-PACertificate and is also returned from things like New-PACertificate and Submit-Renewal. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -StoreLocation +Either 'LocalMachine' or 'CurrentUser'. +Defaults to 'LocalMachine'. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: LocalMachine +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -StoreName +The name of the certificate store to import to. +Defaults to 'My'. +The store must already exist and will not be created automatically. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: My +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NotExportable +If specified, the private key will not be marked as Exportable. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### PoshACME.PACertificate +A certificate object as returned by Get-PACertificate. + +## Notes + +This function only currently works on Windows OSes. A warning will be thrown on other OSes. + +## Related Links + +[Get-PACertificate](Get-PACertificate.md) diff --git a/docs/Functions/Invoke-HttpChallengeListener.md b/docs/Functions/Invoke-HttpChallengeListener.md new file mode 100644 index 00000000..2b67784e --- /dev/null +++ b/docs/Functions/Invoke-HttpChallengeListener.md @@ -0,0 +1,188 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Invoke-HttpChallengeListener/ +schema: 2.0.0 +--- + +# Invoke-HttpChallengeListener + +## Synopsis + +Starts a local web server to answer pending http-01 ACME challenges. + +## Syntax + +```powershell +Invoke-HttpChallengeListener [[-MainDomain] ] [[-Name] ] [-ListenerTimeout ] + [-Port ] [-ListenerPrefixes ] [-WhatIf] [-Confirm] [] +``` + +## Description + +Uses System.Net.HttpListener to answer http-01 ACME challenges for the current or specified order. +If MainDomain is not specified, the current Order is used. + +If running on Windows with non-admin privileges, Access Denied errors may be thrown unless a URL reservation is added using `netsh` that matches the HttpListener prefix that will be used. The default wildcard prefix is `http://+/.well-known/acme-challenge` and the netsh command might look something like this: + + netsh http add urlacl url=http://+/.well-known/acme-challenge/ user=Everyone + +## Examples + +### Example 1 + +```powershell +Invoke-HttpChallengeListener +``` + +Start listener on default port 80 for pending challenges for the current order. + +### Example 2 + +```powershell +Invoke-HttpChallengeListener -MainDomain 'test.example.com' -Port 8080 -ListenerTimeout 30 +``` + +Start listener on port 8080 with a timeout of 30 seconds for the specified order. + +### Example 3 + +```powershell +$prefixes = 'http://example.com/.well-known/acme-challenge/','http://www.example.com/.well-known/acme-challenge' +Invoke-HttpChallengeListener -ListenerPrefixes $prefixes +``` + +Start listener using the specified prefixes for the current order. + +## Parameters + +### -MainDomain +The primary domain associated with an order. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: domain, fqdn + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Name +The name of the ACME order. +This can be useful to distinguish between two orders that have the same MainDomain. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ListenerTimeout +The timeout in seconds for the webserver. +When reached, the http listener stops regardless of challenge status. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: TTL + +Required: False +Position: Named +Default value: 120 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Port +The TCP port on which the http listener is listening. +80 by default. +This parameter is ignored when ListenerPrefixes is specified. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ListenerPrefixes +Overrides the default wildcard listener prefix with the specified prefixes instead. +Be sure to include the port if necessary and a trailing '/' on all included prefixes. +See https://docs.microsoft.com/en-us/dotnet/api/system.net.httplistener for details. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Outputs + +### PoshACME.PAAuthorization +The authorization object associated with the order. + +## Notes + +> **DEPRECATION NOTICE:** This function is deprecated and may be removed in a future major version. Please migrate your scripts to use the `WebSelfHost` plugin. + +## Related Links + +[Get-PAOrder](Get-PAOrder.md) + +[Get-PAAuthorization](Get-PAAuthorization.md) diff --git a/docs/Functions/New-PAAccount.md b/docs/Functions/New-PAAccount.md new file mode 100644 index 00000000..9d247236 --- /dev/null +++ b/docs/Functions/New-PAAccount.md @@ -0,0 +1,316 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/New-PAAccount/ +schema: 2.0.0 +--- + +# New-PAAccount + +## Synopsis + +Create a new account on the current ACME server. + +## Syntax + +### Generate (Default) + +```powershell +New-PAAccount [[-Contact] ] [[-KeyLength] ] [-ID ] [-AcceptTOS] [-Force] + [-ExtAcctKID ] [-ExtAcctHMACKey ] [-ExtAcctAlgorithm ] [-UseAltPluginEncryption] + [-ExtraParams ] [-WhatIf] [-Confirm] [] +``` + +### ImportKey + +```powershell +New-PAAccount [[-Contact] ] -KeyFile [-ID ] [-AcceptTOS] [-OnlyReturnExisting] + [-Force] [-ExtAcctKID ] [-ExtAcctHMACKey ] [-ExtAcctAlgorithm ] + [-UseAltPluginEncryption] [-ExtraParams ] [-WhatIf] [-Confirm] [] +``` + +## Description + +All certificate requests require a valid account on an ACME server. An contact email address is not required for Let's Encrypt, but other CAs may require it. Without an email address, certificate expiration notices will not be sent. The account KeyLength is a personal preference and does not relate to the KeyLength of the certificates. + +## Examples + +### Example 1 + +```powershell +New-PAAccount -AcceptTOS +``` + +Create a new account with no contact email and the default key length. + +### Example 2 + +```powershell +New-PAAccount -Contact user1@example.com -AcceptTOS +``` + +Create a new account with the specified email and the default key length. + +### Example 3 + +```powershell +New-PAAccount -Contact user1@example.com -KeyLength 4096 -AcceptTOS +``` + +Create a new account with the specified email and an RSA 4096 bit key. + +### Example 4 + +```powershell +New-PAAccount -KeyLength 'ec-384' -AcceptTOS -Force +``` + +Create a new account with no contact email and an ECC key using P-384 curve that ignores any confirmations. + +### Example 5 + +```powershell +New-PAAccount -KeyFile .\mykey.key -AcceptTOS +``` + +Create a new account using a pre-generated private key file. + +## Parameters + +### -Contact +One or more email addresses to associate with this account. +These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -KeyLength +The type and size of private key to use. +For RSA keys, specify a number between 2048-4096 (divisible by 128). +For ECC keys, specify either 'ec-256' or 'ec-384'. +Defaults to 'ec-256'. + +```yaml +Type: String +Parameter Sets: Generate +Aliases: AccountKeyLength + +Required: False +Position: 2 +Default value: Ec-256 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -KeyFile +The path to an existing EC or RSA private key file. +This will attempt to create the account using the specified key as the ACME account key. +This can be used to recover/import an existing ACME account if one is already associated with the key. + +```yaml +Type: String +Parameter Sets: ImportKey +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ID +The name of the ACME acccount. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: Name + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -AcceptTOS +If not specified, the ACME server will throw an error with a link to the current Terms of Service. +Using this switch indicates acceptance of those Terms of Service and is required for successful account creation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OnlyReturnExisting +If specified, the ACME server will only return the account details if they already exist for the given private key. Otherwise, an error will be thrown. This can be useful to check whether an existing private key is associated with an ACME acount and recover the account details without creating a new account. + +```yaml +Type: SwitchParameter +Parameter Sets: ImportKey +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +If specified, confirmation prompts that may have been generated will be skipped. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExtAcctKID +The external account key identifier supplied by the CA. +This is required for ACME CAs that require external account binding. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExtAcctHMACKey +The external account HMAC key supplied by the CA and encoded as Base64Url. +This is required for ACME CAs that require external account binding. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExtAcctAlgorithm +The HMAC algorithm to use. +Defaults to 'HS256'. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: HS256 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UseAltPluginEncryption +If specified, the account will be configured to use a randomly generated AES key to encrypt sensitive plugin parameters on disk instead of using the OS's native encryption methods. +This can be useful if the config is being shared across systems or platforms. +You can revert to OS native encryption using -UseAltPluginEncryption:$false. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExtraParams +This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Outputs + +### PoshACME.PAAccount +An account object. + +## Related Links + +[Get-PAAccount](Get-PAAccount.md) + +[Set-PAAccount](Set-PAAccount.md) diff --git a/docs/Functions/New-PAAuthorization.md b/docs/Functions/New-PAAuthorization.md new file mode 100644 index 00000000..4c6d40ae --- /dev/null +++ b/docs/Functions/New-PAAuthorization.md @@ -0,0 +1,97 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/New-PAAuthorization/ +schema: 2.0.0 +--- + +# New-PAAuthorization + +## Synopsis + +Create a pre-authorization for an ACME identifier. + +## Syntax + +```powershell +New-PAAuthorization [-Domain] [[-Account] ] [] +``` + +## Description + +Instead of creating an ACME order object and satisfying the associated authorization challenges on demand, users may choose to pre-authorize one or more identifiers in advance. +When a user later creates an order with pre-authorized identifiers, it will be immediately ready to finalize. + +NOTE: Not all ACME servers support pre-authorization. +The authorizations created this way also expire the same way they do when associated directly with an order. + +## Examples + +### Example 1 + +```powershell +$auth = New-PAAuthorization example.com +``` + +Create a new authorization for the specified domain using the current account. + +### Example 2 + +```powershell +$auths = 'example.com','www.example.com' | New-PAAuthorization -Account (Get-PAAccount 123) +``` + +Create new authorizations for the specified domains via the pipeline and using the specified account. + +## Parameters + +### -Domain +One or more ACME identifiers (usually domain names). + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Account +An existing ACME account object such as the output from Get-PAAccount. +If no account is specified, the current account will be used. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### System.String +The domain or IP address identifier to authorize. + +## Outputs + +### PoshACME.PAAuthorization +An authorization object. + +## Related Links + +[Get-PAAuthorization](Get-PAAuthorization.md) + +[New-PAOrder](New-PAOrder.md) diff --git a/docs/Functions/New-PACertificate.md b/docs/Functions/New-PACertificate.md new file mode 100644 index 00000000..bd74059f --- /dev/null +++ b/docs/Functions/New-PACertificate.md @@ -0,0 +1,495 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/New-PACertificate/ +schema: 2.0.0 +--- + +# New-PACertificate + +## Synopsis + +Request a new certificate + +## Syntax + +### FromScratch (Default) + +```powershell +New-PACertificate [-Domain] [-Name ] [-Contact ] [-CertKeyLength ] + [-AlwaysNewKey] [-AcceptTOS] [-AccountKeyLength ] [-DirectoryUrl ] [-Plugin ] + [-PluginArgs ] [-DnsAlias ] [-OCSPMustStaple] [-FriendlyName ] + [-PfxPass ] [-PfxPassSecure ] [-Install] [-UseSerialValidation] [-Force] + [-DnsSleep ] [-ValidationTimeout ] [-PreferredChain ] [] +``` + +### FromCSR + +```powershell +New-PACertificate [-CSRPath] [-Name ] [-Contact ] [-AcceptTOS] + [-AccountKeyLength ] [-DirectoryUrl ] [-Plugin ] [-PluginArgs ] + [-DnsAlias ] [-UseSerialValidation] [-Force] [-DnsSleep ] [-ValidationTimeout ] + [-PreferredChain ] [] +``` + +## Description +This is the primary function for this module and is capable executing the entire ACME certificate request process from start to finish without any prerequisite steps. +However, utilizing the module's other functions can enable more complicated workflows and reduce the number of parameters you need to supply to this function. + +## Examples + +### Example 1: Basic Manual Certificate + +```powershell +New-PACertificate 'example.com','www.example.com' -AcceptTOS +``` + +This is the bare minimum necessary to create a certificate for a basic domain (plus the `www` alt name). It prompt you to add the required DNS TXT record manually. You can omit the `-AcceptTOS` parameter if you already have an ACME account configured. + +### Example 2: Wildcard Certificate with Contact + +```powershell +New-PACertificate '*.example.com','example.com' -Contact 'admin@example.com' +``` + +Wildcard certificates generally include the non-wildcard root as a SAN because the wildcard doesn't match it. The contact email address is typically used by the CA to send expiration warnings. + +### Example 3: Using a plugin + +```powershell +$pArgs = @{ + FDToken = (Read-Host 'FakeDNS API Token' -AsSecureString) +} +New-PACertificate 'example.com' -Plugin FakeDNS -PluginArgs $pArgs +``` + +Plugin parameters are passed as a basic hashtable object. Some parameters may require SecureString or PSCredential objects to protect sensitive API credentials, tokens, and keys. + +### Example 4: Using multiple plugins + +```powershell +$pArgs = @{ + FDToken = (Read-Host 'FakeDNS API Token' -AsSecureString) + WSHPort = 8080 +} +New-PACertificate '*.example.com','example.com' -Plugin FakeDNS,WebSelfHost -PluginArgs $pArgs +``` + +Each name in a certificate can use a different plugin if necessary. Be sure the specified plugin order matches the order of the names they are associated with. If there are fewer plugins specified than names, the last plugin in the list will be applied to all remaining names. + +Each plugin's parameters should be combined into the same hashtable object. + +### Example 5: Using a DNS Challenge Alias + +```powershell +$pArgs = @{ + FDToken = (Read-Host 'FakeDNS API Token' -AsSecureString) +} +New-PACertificate 'example.com' -Plugin FakeDNS -PluginArgs $pArgs -DnsAlias 'acme.example.net' +``` + +Using `DnsAlias` tells the plugin to create the required TXT record to an alternate hostname. It requires having added a CNAME record for each name in the cert pointing to the alternate record location. In this case, `_acme-challenge.example.com` is pointing to `acme.example.net`. + +## Parameters + +### -Domain + +One or more domain names to include in this order/certificate. +The first one in the list will be considered the "MainDomain" and be set as the subject of the finalized certificate. + +```yaml +Type: String[] +Parameter Sets: FromScratch +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CSRPath + +The path to a pre-made certificate request file in PEM (Base64) format. +This is useful for appliances that need to generate their own keys and cert requests. + +```yaml +Type: String +Parameter Sets: FromCSR +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name + +The name of the ACME order. +This can be useful to distinguish between two orders that have the same MainDomain. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Contact + +One or more email addresses to associate with this certificate. +These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CertKeyLength + +The type and size of private key to use for the certificate. +For RSA keys, specify a number between 2048-4096 (divisible by 128). +For ECC keys, specify either 'ec-256' or 'ec-384'. +Defaults to '2048'. + +```yaml +Type: String +Parameter Sets: FromScratch +Aliases: + +Required: False +Position: Named +Default value: 2048 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -AlwaysNewKey + +If specified, the order will be configured to always generate a new private key during each renewal. +Otherwise, the old key is re-used if it exists. + +```yaml +Type: SwitchParameter +Parameter Sets: FromScratch +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -AcceptTOS + +This switch is required when creating a new account as part of a certificate request. +It implies you have read and accepted the Terms of Service for the ACME server you are connected to. +The first time you connect to an ACME server, a link to the Terms of Service should have been displayed. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -AccountKeyLength + +The type and size of private key to use for the account associated with this certificate. +For RSA keys, specify a number between 2048-4096 (divisible by 128). +For ECC keys, specify either 'ec-256' or 'ec-384'. +Defaults to 'ec-256'. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: Ec-256 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DirectoryUrl + +Either the URL to an ACME server's "directory" endpoint or one of the supported short names. +Currently supported short names include LE_PROD (LetsEncrypt Production v2) and LE_STAGE (LetsEncrypt Staging v2). +Defaults to 'LE_PROD'. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: location + +Required: False +Position: Named +Default value: LE_PROD +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Plugin + +One or more validation plugin names to use for this order's challenges. +If no plugin is specified, the DNS "Manual" plugin will be used. +If the same plugin is used for all domains in the order, you can just specify it once. +Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: DnsPlugin + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PluginArgs + +A hashtable containing the plugin arguments to use with the specified Plugin list. +So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + +```yaml +Type: Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DnsAlias + +One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. +This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. +If the same alias is used for all domains in the order, you can just specify it once. +Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OCSPMustStaple + +If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. + +```yaml +Type: SwitchParameter +Parameter Sets: FromScratch +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FriendlyName + +Set a friendly name for the certificate. +This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. +Defaults to the first item in the Domain parameter. + +```yaml +Type: String +Parameter Sets: FromScratch +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PfxPass + +Set the export password for generated PFX files. +Defaults to 'poshacme'. +When the PfxPassSecure parameter is specified, this parameter is ignored. + +```yaml +Type: String +Parameter Sets: FromScratch +Aliases: + +Required: False +Position: Named +Default value: Poshacme +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PfxPassSecure + +Set the export password for generated PFX files using a SecureString value. +When this parameter is specified, the PfxPass parameter is ignored. + +```yaml +Type: SecureString +Parameter Sets: FromScratch +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Install + +If specified, the certificate generated for this order will be imported to the local computer's Personal certificate store. +Using this switch requires running the command from an elevated PowerShell session. + +```yaml +Type: SwitchParameter +Parameter Sets: FromScratch +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UseSerialValidation + +If specified, the names in the order will be validated individually rather than all at once. +This can significantly increase the time it takes to process validations and should only be used for plugins that require it. +The plugin's usage guide should indicate whether it is required. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +If specified, a new certificate order will always be created regardless of the status of a previous order for the same primary domain. +Otherwise, the previous order still in progress will be used instead. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DnsSleep + +Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. +Default is 120. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 120 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ValidationTimeout + +Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. +Default is 60. +If the timeout is exceeded, an error will be thrown. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 60 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PreferredChain + +If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. +If no match, the default offered chain will be used. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Outputs + +### PoshACME.PACertificate +A certificate object. + +## Related Links + +[Submit-Renewal](Submit-Renewal.md) + +[Get-PAPlugin](Get-PAPlugin.md) diff --git a/docs/Functions/New-PAOrder.md b/docs/Functions/New-PAOrder.md new file mode 100644 index 00000000..558adb1a --- /dev/null +++ b/docs/Functions/New-PAOrder.md @@ -0,0 +1,441 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/New-PAOrder/ +schema: 2.0.0 +--- + +# New-PAOrder + +## Synopsis + +Create a new order on the current ACME account. + +## Syntax + +### FromScratch (Default) + +```powershell +New-PAOrder [-Domain] [[-KeyLength] ] [-Name ] [-Plugin ] + [-PluginArgs ] [-DnsAlias ] [-OCSPMustStaple] [-AlwaysNewKey] [-FriendlyName ] + [-PfxPass ] [-PfxPassSecure ] [-Install] [-UseSerialValidation] [-DnsSleep ] + [-ValidationTimeout ] [-PreferredChain ] [-Force] [-WhatIf] [-Confirm] [] +``` + +### ImportKey + +```powershell +New-PAOrder [-Domain] -KeyFile [-Name ] [-Plugin ] + [-PluginArgs ] [-DnsAlias ] [-OCSPMustStaple] [-AlwaysNewKey] [-FriendlyName ] + [-PfxPass ] [-PfxPassSecure ] [-Install] [-UseSerialValidation] [-DnsSleep ] + [-ValidationTimeout ] [-PreferredChain ] [-Force] [-WhatIf] [-Confirm] [] +``` + +### FromCSR + +```powershell +New-PAOrder [-CSRPath] [-Name ] [-Plugin ] [-PluginArgs ] + [-DnsAlias ] [-UseSerialValidation] [-DnsSleep ] [-ValidationTimeout ] + [-PreferredChain ] [-Force] [-WhatIf] [-Confirm] [] +``` + +## Description + +Creating an ACME order is the first step of the certificate request process. +To create a SAN certificate with multiple names, include them all in an array for the -Domain parameter. +The first name in the list will be considered the "MainDomain" and will also be in the certificate subject field. +Different CAs have different policies regarding the number of SANs a certificate may have. + +Be aware that new orders that share the same MainDomain as a previous order will overwrite the previous order unless the `Name` paraemter is specified and there are no other order matches for that name. + +## Examples + +### Example 1 + +```powershell +New-PAOrder site1.example.com +``` + +Create a new order for the specified domain using the default key length. + +### Example 2 + +```powershell +New-PAOrder -Domain 'site1.example.com','site2.example.com','site3.example.com' +``` + +Create a new SAN order for the specified domains using the default key length. + +### Example 3 + +```powershell +New-PAOrder site1.example.com 4096 +``` + +Create a new order for the specified domain using an RSA 4096 bit key. + +### Example 4 + +```powershell +New-PAOrder 'site1.example.com','site2.example.com' ec-384 -Force +``` + +Create a new SAN order for the specified domains using an ECC key using P-384 curve that ignores any confirmations. + +## Parameters + +### -Domain +One or more domain names to include in this order/certificate. +The first one in the list will be considered the "MainDomain" and be set as the subject of the finalized certificate. + +```yaml +Type: String[] +Parameter Sets: FromScratch, ImportKey +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CSRPath +The path to a pre-made certificate request file in PEM (Base64) format. +This is useful for appliances that need to generate their own keys and cert requests. + +```yaml +Type: String +Parameter Sets: FromCSR +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -KeyLength +The type and size of private key to use. +For RSA keys, specify a number between 2048-4096 (divisible by 128). +For ECC keys, specify either 'ec-256' or 'ec-384'. +Defaults to '2048'. + +```yaml +Type: String +Parameter Sets: FromScratch +Aliases: + +Required: False +Position: 2 +Default value: 2048 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -KeyFile +The path to an existing EC or RSA private key file. +This will attempt to create the order using the specified key as the certificate's private key. + +```yaml +Type: String +Parameter Sets: ImportKey +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name +The name of the ACME order. +This can be useful to distinguish between two orders that have the same MainDomain. +If not specified, defaults to the first domain in the order. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Plugin +One or more validation plugin names to use for this order's challenges. +If no plugin is specified, the DNS "Manual" plugin will be used. +If the same plugin is used for all domains in the order, you can just specify it once. +Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PluginArgs +A hashtable containing the plugin arguments to use with the specified Plugin list. +So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + +```yaml +Type: Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DnsAlias +One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. +This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. +If the same alias is used for all domains in the order, you can just specify it once. +Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OCSPMustStaple +If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. + +```yaml +Type: SwitchParameter +Parameter Sets: FromScratch, ImportKey +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -AlwaysNewKey +If specified, the order will be configured to always generate a new private key during each renewal. +Otherwise, the old key is re-used if it exists. + +```yaml +Type: SwitchParameter +Parameter Sets: FromScratch, ImportKey +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FriendlyName +Set a friendly name for the certificate. +This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. +Defaults to the first item in the Domain parameter. + +```yaml +Type: String +Parameter Sets: FromScratch, ImportKey +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PfxPass +Set the export password for generated PFX files. +Defaults to 'poshacme'. +When the PfxPassSecure parameter is specified, this parameter is ignored. + +```yaml +Type: String +Parameter Sets: FromScratch, ImportKey +Aliases: + +Required: False +Position: Named +Default value: Poshacme +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PfxPassSecure +Set the export password for generated PFX files using a SecureString value. +When this parameter is specified, the PfxPass parameter is ignored. + +```yaml +Type: SecureString +Parameter Sets: FromScratch, ImportKey +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Install +If specified, the certificate generated for this order will be imported to the local computer's Personal certificate store. + +```yaml +Type: SwitchParameter +Parameter Sets: FromScratch, ImportKey +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UseSerialValidation +If specified, the names in the order will be validated individually rather than all at once. +This can significantly increase the time it takes to process validations and should only be used for plugins that require it. +The plugin's usage guide should indicate whether it is required. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DnsSleep +Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 120 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ValidationTimeout +Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. +If the timeout is exceeded, an error will be thrown. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 60 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PreferredChain +If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. +If no match, the default offered chain will be used. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +If specified, confirmation prompts that may have been generated will be skipped. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Outputs + +### PoshACME.PAOrder +An order object. + +## Related Links + +[Get-PAOrder](Get-PAOrder.md) + +[Set-PAOrder](Set-PAOrder.md) diff --git a/docs/Functions/Publish-Challenge.md b/docs/Functions/Publish-Challenge.md new file mode 100644 index 00000000..aedcb055 --- /dev/null +++ b/docs/Functions/Publish-Challenge.md @@ -0,0 +1,157 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Publish-Challenge/ +schema: 2.0.0 +--- + +# Publish-Challenge + +## Synopsis + +Publish a challenge using the specified plugin. + +## Syntax + +```powershell +Publish-Challenge [-Domain] [-Account] [-Token] [-Plugin] + [[-PluginArgs] ] [-DnsAlias ] [] +``` + +## Description + +Based on the type of validation plugin specified, this function will publish either a DNS TXT record or an HTTP challenge file for the given domain and token value that satisfies the dns-01 or http-01 challenge specification. + +Depending on the plugin, calling `Save-Challenge` may be required to commit changes made by `Publish-Challenge`. +If multiple challenges are being published, make all `Publish-Challenge` calls first. +Then, `Save-Challenge` once to commit them all. + +## Examples + +### Example 1 + +```powershell +$auths = Get-PAOrder | Get-PAAuthorization +Publish-Challenge $auths[0].DNSId (Get-PAAccount) $auths[0].DNS01Token Manual @{} +``` + +Publish a DNS challenge for the first authorization in the current order using the Manual DNS plugin. + +### Example 2 + +```powershell +$pArgs = @{Param1='asdf';Param2=1234} +$acct = Get-PAAccount +Publish-Challenge example.com $acct MyPlugin $pArgs -Token faketoken +``` + +Publish a challenge for example.com using a fictitious plugin and arguments. + +## Parameters + +### -Domain +The domain name that the challenge will be published for. +Wildcard domains should have the "*." removed and can only be used with DNS based validation plugins. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Account +The account object associated with the order that requires the challenge. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Token +The token value from the appropriate challenge in an authorization object that matches the plugin type. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Plugin +The name of the validation plugin to use. +Use Get-PAPlugin to display a list of available plugins. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 4 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PluginArgs +A hashtable containing the plugin arguments to use with the specified plugin. +So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + +```yaml +Type: Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: 5 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DnsAlias +When using DNS Alias support with DNS validation plugins, the alias domain that the TXT record will be written to. +This should be the complete FQDN including the '_acme-challenge.' prefix if necessary. +This field is ignored for non-DNS validation plugins. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Related Links + +[Unpublish-Challenge](Unpublish-Challenge.md) + +[Save-Challenge](Save-Challenge.md) + +[Get-PAPlugin](Get-PAPlugin.md) diff --git a/docs/Functions/Remove-PAAccount.md b/docs/Functions/Remove-PAAccount.md new file mode 100644 index 00000000..4a36d948 --- /dev/null +++ b/docs/Functions/Remove-PAAccount.md @@ -0,0 +1,131 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Remove-PAAccount/ +schema: 2.0.0 +--- + +# Remove-PAAccount + +## Synopsis + +Remove an ACME account and all associated orders and certificates from the local profile. + +## Syntax + +```powershell +Remove-PAAccount [-ID] [-Deactivate] [-Force] [-WhatIf] [-Confirm] [] +``` + +## Description + +This function removes the ACME account from the local profile which also removes any associated orders and certificates. +It will not remove or cleanup copies of certificates that have been exported or installed elsewhere. +It will not deactivate the account on the ACME server unless `-Deactivate` is specified. But you won't be able to re-use the account on another system without an export of the account's key such as the one generated with `Export-PAAccountKey`. + +## Examples + +### Example 1 + +```powershell +Remove-PAAccount 12345 +``` + +Remove the specified account without deactivation. + +### Example 2 + +```powershell +Get-PAAccount | Remove-PAAccount -Deactivate -Force +``` + +Remove the current account after deactivating it and skip confirmation prompts. + +## Parameters + +### -ID +The account id value as returned by the ACME server. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: Name + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Deactivate +If specified, a request will be sent to the associated ACME server to deactivate the account. +Clients may wish to do this if the account key is compromised or decommissioned. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +If specified, interactive confirmation prompts will be skipped. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Related Links + +[Get-PAAccount](Get-PAAccount.md) + +[New-PAAccount](New-PAAccount.md) diff --git a/docs/Functions/Remove-PAOrder.md b/docs/Functions/Remove-PAOrder.md new file mode 100644 index 00000000..20954125 --- /dev/null +++ b/docs/Functions/Remove-PAOrder.md @@ -0,0 +1,150 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Remove-PAOrder/ +schema: 2.0.0 +--- + +# Remove-PAOrder + +## Synopsis + +Remove an ACME order from the local profile. + +## Syntax + +```powershell +Remove-PAOrder [[-MainDomain] ] [[-Name] ] [-RevokeCert] [-Force] [-WhatIf] [-Confirm] + [] +``` + +## Description + +This function removes the order from the local profile which also removes any associated certificate/key. +It will not remove or cleanup copies of the certificate that have been exported or installed elsewhere. +It will not revoke the certificate unless `-RevokeCert` is specified. +The ACME server may retain a reference to the order until it decides to delete it. + +## Examples + +### Example 1 + +```powershell +Remove-PAOrder site1.example.com +``` + +Remove the specified order without revoking the certificate. + +### Example 2 + +```powershell +Get-PAOrder -List | Remove-PAOrder -RevokeCert -Force +``` + +Remove all orders associated with the current account, revoke all certificates, and skip confirmation prompts. + +## Parameters + +### -MainDomain +The primary domain for the order. +For a SAN order, this was the first domain in the list when creating the order. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Name +The name of the ACME order. +This can be useful to distinguish between two orders that have the same MainDomain. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -RevokeCert +If specified and there is a currently valid certificate associated with the order, the certificate will be revoked before deleting the order. +This is not required, but generally a good practice if the certificate is no longer being used. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +If specified, interactive confirmation prompts will be skipped. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Related Links + +[Get-PAOrder](Get-PAOrder.md) + +[New-PAOrder](New-PAOrder.md) diff --git a/docs/Functions/Remove-PAServer.md b/docs/Functions/Remove-PAServer.md new file mode 100644 index 00000000..8b1c745b --- /dev/null +++ b/docs/Functions/Remove-PAServer.md @@ -0,0 +1,142 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Remove-PAServer/ +schema: 2.0.0 +--- + +# Remove-PAServer + +## Synopsis + +Remove an ACME server and all associated accounts, orders, and certificates from the local profile. + +## Syntax + +```powershell +Remove-PAServer [[-DirectoryUrl] ] [-Name ] [-DeactivateAccounts] [-Force] [-WhatIf] [-Confirm] + [] +``` + +## Description + +This function removes the ACME server from the local profile which also removes any associated accounts, orders and certificates. +It will not remove or cleanup copies of certificates that have been exported or installed elsewhere. +It will not revoke any certificates. +It will not deactivate the accounts on the ACME server unless the `-DeactivateAccounts` switch is specified. + +## Examples + +### Example 1 + +```powershell +Remove-PAServer LE_STAGE +``` + +Remove the staging server without deactivating accounts. + +## Parameters + +### -DirectoryUrl +Either the URL to an ACME server's "directory" endpoint or one of the supported short names. +Currently supported short names include LE_PROD (LetsEncrypt Production v2) and LE_STAGE (LetsEncrypt Staging v2). + +```yaml +Type: String +Parameter Sets: (All) +Aliases: location + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Name +The name of the ACME server. +The parameter is ignored if DirectoryUrl is specified. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -DeactivateAccounts +If specified, an attempt will be made to deactivate the accounts in this profile before deletion. +Clients may wish to do this if the account key is compromised or being decommissioned. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +If specified, interactive confirmation prompts will be skipped. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Related Links + +[Get-PAServer](Get-PAServer.md) + +[Set-PAServer](Set-PAServer.md) diff --git a/docs/Functions/Revoke-PAAuthorization.md b/docs/Functions/Revoke-PAAuthorization.md new file mode 100644 index 00000000..4649564d --- /dev/null +++ b/docs/Functions/Revoke-PAAuthorization.md @@ -0,0 +1,146 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Revoke-PAAuthorization/ +schema: 2.0.0 +--- + +# Revoke-PAAuthorization + +## Synopsis + +Revoke the authorization associated with an ACME identifier. + +## Syntax + +```powershell +Revoke-PAAuthorization [-AuthURLs] [[-Account] ] [-Force] [-WhatIf] [-Confirm] + [] +``` + +## Description + +Many ACME server implementations cache succesful authorizations for a certain amount of time to avoid requiring an account to re-authorize identifiers for additional orders submitted during the cache window. This can make testing authorization challenges in a client more cumbersome by having to create new orders with uncached identifiers. + +This function allows you to revoke those cached authorizations so that subsequent orders will go through the full challenge validation process. + +## Examples + +### Example 1 + +```powershell +Revoke-PAAuthorization https://acme.example.com/authz/1234567 +``` + +Revoke the authorization for the specified URL using the current account. + +### Example 2 + +```powershell +Get-PAOrder | Revoke-PAAuthorization -Force +``` + +Revoke all authorizations for the current order on the current account without confirmation prompts. + +### Example 3 + +```powershell +Get-PAOrder -List | Revoke-PAAuthorizations +``` + +Revoke all authorizations for all orders on the current account. + +## Parameters + +### -AuthURLs +One or more authorization URLs. +You also pipe in one or more PoshACME.PAOrder objects. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: authorizations + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Account +An existing ACME account object such as the output from Get-PAAccount. +If no account is specified, the current account will be used. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +If specified, no confirmation prompts will be presented. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### System.String +The URI of the authorization object. + +## Related Links + +[Get-PAAuthorization](Get-PAAuthorization.md) + +[Get-PAOrder](Get-PAOrder.md) diff --git a/docs/Functions/Revoke-PACertificate.md b/docs/Functions/Revoke-PACertificate.md new file mode 100644 index 00000000..d6af0e92 --- /dev/null +++ b/docs/Functions/Revoke-PACertificate.md @@ -0,0 +1,202 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Revoke-PACertificate/ +schema: 2.0.0 +--- + +# Revoke-PACertificate + +## Synopsis + +Revoke an ACME certificate + +## Syntax + +### MainDomain (Default) + +```powershell +Revoke-PACertificate [[-MainDomain] ] [-Name ] [-Reason ] [-Force] [-WhatIf] + [-Confirm] [] +``` + +### CertFile + +```powershell +Revoke-PACertificate -CertFile [-KeyFile ] [-Reason ] [-Force] [-WhatIf] + [-Confirm] [] +``` + +## Description + +Any certificate created with the current ACME account can be revoked. If you need to revoke a certificate not created with the current account, you either need to specify both `CertFile` and `KeyFile`. If you don't have the private key, you will need to go through the authorization process on this account for all names in the certificate and just specify `CertFile`. + +## Examples + +### Example 1 + +```powershell +Revoke-PACertificate example.com +``` + +Revokes the certificate for the specified domain. + +### Example 2 + +```powershell +Get-PAOrder | Revoke-PACertificate -Force +``` + +Revokes the certificate associated with the current order and skips the confirmation prompt. + +### Example 3 + +```powershell +Get-PACertificate | Revoke-PACertificate -Reason keyCompromise +``` + +Revokes the current certificate with the specified reason. + +### Example 4 + +```powershell +Revoke-PACertificate -CertFile mycert.crt -KeyFile mycert.key +``` + +Revokes the specified cert using the specified private key. + +## Parameters + +### -MainDomain +The primary domain associated with the certificate to be revoked. + +```yaml +Type: String +Parameter Sets: MainDomain +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Name +The name of the ACME order. +This can be useful to distinguish between two orders that have the same MainDomain. + +```yaml +Type: String +Parameter Sets: MainDomain +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -CertFile +A PEM-encoded certificate file to be revoked. + +```yaml +Type: String +Parameter Sets: CertFile +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -KeyFile +The PEM-encoded private key associated with CertFile. +If not specified, the current ACME account will be used to sign the request. + +```yaml +Type: String +Parameter Sets: CertFile +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Reason +The reason for cert revocation. +This must be one of the reasons defined in RFC 5280 including keyCompromise, cACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, removeFromCRL, privilegeWithdrawn, and aACompromise. +NOTE: Some reason codes are not supported by some ACME CAs. + +```yaml +Type: RevocationReasons +Parameter Sets: (All) +Aliases: +Accepted values: keyCompromise, cACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, removeFromCRL, privilegeWithdrawn, aACompromise + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +If specified, the revocation confirmation prompt will be skipped. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Related Links + +[New-PACertificate](New-PACertificate.md) diff --git a/docs/Functions/Save-Challenge.md b/docs/Functions/Save-Challenge.md new file mode 100644 index 00000000..c1c48ffb --- /dev/null +++ b/docs/Functions/Save-Challenge.md @@ -0,0 +1,88 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Save-Challenge/ +schema: 2.0.0 +--- + +# Save-Challenge + +## Synopsis + +Commit changes made by Publish-Challenge or Unpublish-Challenge. + +## Syntax + +```powershell +Save-Challenge [-Plugin] [[-PluginArgs] ] [] +``` + +## Description + +Some validation plugins require a finalization step after the Publish or Unpublish functionality to commit and make the changes live. This function should be called once after running all of the `Publish-Challenge` or `Unpublish-Challenge` commands. + +For plugins that don't require a commit step, this function may still be run without causing an error, but does nothing. + +## Examples + +### Example 1 + +```powershell +Save-Challenge Manual @{} +``` + +Commit changes using the Manual DNS plugin that requires no plugin arguments. + +### Example 2 + +```powershell +Save-Challenge MyPlugin @{Param1='asdf';Param2=1234} +``` + +Commit changes for a set of challenges using a fictitious plugin and arguments. + +## Parameters + +### -Plugin +The name of the validation plugin to use. +Use Get-PAPlugin to display a list of available plugins. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PluginArgs +A hashtable containing the plugin arguments to use with the specified plugin. +So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + +```yaml +Type: Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Related Links + +[Publish-Challenge](Publish-Challenge.md) + +[Unpublish-Challenge](Unpublish-Challenge.md) + +[Get-PAPlugin](Get-PAPlugin.md) diff --git a/docs/Functions/Send-ChallengeAck.md b/docs/Functions/Send-ChallengeAck.md new file mode 100644 index 00000000..149931e5 --- /dev/null +++ b/docs/Functions/Send-ChallengeAck.md @@ -0,0 +1,91 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Send-ChallengeAck/ +schema: 2.0.0 +--- + +# Send-ChallengeAck + +## Synopsis + +Notify the ACME server to try validating a challenge. + +## Syntax + +```powershell +Send-ChallengeAck [-ChallengeUrl] [[-Account] ] [] +``` + +## Description + +Use this after publishing the required resource for one of the challenges from an authorization object. +It lets the ACME server know that it should proceed validating that challenge. + +## Examples + +### Example 1 + +```powershell +$auths = Get-PAOrder | Get-PAAuthorization +Send-ChallengeAck $auths\[0\].DNS01Url +``` + +Tell the ACME server to validate the first DNS challenge in the current order. + +### Example 2 + +```powershell +$auths = Get-PAOrder | Get-PAAuthorization +$httpUrls = ($auths | ?{ $_.status -eq 'pending' }).HTTP01Url +$httpUrls | Send-ChallengeAck +``` + +Tell the ACME server to validate all pending HTTP challenges in the current order. + +## Parameters + +### -ChallengeUrl +The URL of the challenge to be validated. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Account +The ACME account associated with the challenge. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### System.String +The URI of an ACME challenge object. + +## Related Links + +[Get-PAAuthorization](Get-PAAuthorization.md) + +[Submit-ChallengeValidation](Submit-ChallengeValidation.md) diff --git a/docs/Functions/Set-PAAccount.md b/docs/Functions/Set-PAAccount.md new file mode 100644 index 00000000..f62fbe21 --- /dev/null +++ b/docs/Functions/Set-PAAccount.md @@ -0,0 +1,319 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Set-PAAccount/ +schema: 2.0.0 +--- + +# Set-PAAccount + +## Synopsis + +Set the current ACME account and/or update account details. + +## Syntax + +### Edit (Default) + +```powershell +Set-PAAccount [[-ID] ] [[-Contact] ] [-NewName ] [-UseAltPluginEncryption] + [-ResetAltPluginEncryption] [-Deactivate] [-Force] [-NoSwitch] [-WhatIf] [-Confirm] [] +``` + +### RolloverImportKey + +```powershell +Set-PAAccount [[-ID] ] [-KeyRollover] -KeyFile [-NoSwitch] [-WhatIf] [-Confirm] + [] +``` + +### Rollover + +```powershell +Set-PAAccount [[-ID] ] [-KeyRollover] [-KeyLength ] [-NoSwitch] [-WhatIf] [-Confirm] + [] +``` + +## Description + +This function allows you to switch between ACME accounts for a particular server. +It also allows you to update the contact information associated with an account, deactivate the account, or replace the account key with a new one. + +## Examples + +### Example 1 + +```powershell +Set-PAAccount -ID 1234567 +``` + +Switch to the specified account. + +### Example 2 + +```powershell +Set-PAAccount -Contact 'user1@example.com','user2@example.com' +``` + +Set new contacts for the current account. + +### Example 3 + +```powershell +Set-PAAccount -ID 1234567 -Contact 'user1@example.com','user2@example.com' +``` + +Set new contacts for the specified account. + +### Example 4 + +```powershell +Get-PAAccount -List | Set-PAAccount -Contact user1@example.com -NoSwitch +``` + +Set a new contact for all known accounts without switching from the current. + +### Example 5 + +```powershell +Set-PAAccount -Deactivate +``` + +Deactivate the current account. + +### Example 6 + +```powershell +Set-PAAccount -KeyRollover -KeyLength ec-384 +``` + +Replace the current account key with a new ECC key using P-384 curve. + +### Example 7 + +```powershell +Set-PAAccount -KeyRollover -KeyFile .\mykey.key +``` + +Replace the current account key with a pre-generated private key. + +## Parameters + +### -ID +The account id value as returned by the ACME server. +If not specified, the function will attempt to use the currently active account. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: Name + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Contact +One or more email addresses to associate with this account. +These addresses will be used by the ACME server to send certificate expiration notifications or other important account notices. + +```yaml +Type: String[] +Parameter Sets: Edit +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NewName +The new name (id) of this ACME account. + +```yaml +Type: String +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UseAltPluginEncryption +If specified, the account will be configured to use a randomly generated AES key to encrypt sensitive plugin parameters on disk instead of using the OS's native encryption methods. +This can be useful if the config is being shared across systems or platforms. +You can revert to OS native encryption using -UseAltPluginEncryption:$false. + +```yaml +Type: SwitchParameter +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ResetAltPluginEncryption +If specified, the existing AES key will be replaced with a new one and existing plugin parameters on disk will be re-encrypted with the new key. +If there is no existing key, this parameter is ignored. + +```yaml +Type: SwitchParameter +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Deactivate +If specified, a request will be sent to the associated ACME server to deactivate the account. +Clients may wish to do this if the account key is compromised or decommissioned. + +```yaml +Type: SwitchParameter +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +If specified, confirmation prompts for account deactivation will be skipped. + +```yaml +Type: SwitchParameter +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -KeyRollover +If specified, generate a new account key and replace the current one with it. +Clients may choose to do this to recover from a key compromise or proactively mitigate the impact of an unnoticed key compromise. + +```yaml +Type: SwitchParameter +Parameter Sets: RolloverImportKey, Rollover +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -KeyLength +The type and size of private key to use. +For RSA keys, specify a number between 2048-4096 (divisible by 128). +For ECC keys, specify either 'ec-256' or 'ec-384'. +Defaults to 'ec-256'. + +```yaml +Type: String +Parameter Sets: Rollover +Aliases: AccountKeyLength + +Required: False +Position: Named +Default value: Ec-256 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -KeyFile +The path to an existing EC or RSA private key file. +This will attempt to use the specified key as the new ACME account key. + +```yaml +Type: String +Parameter Sets: RolloverImportKey +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoSwitch +If specified, the currently active account will not change. +Useful primarily for bulk updating contact information across accounts. +This switch is ignored if no ID is specified. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Related Links + +[Get-PAAccount](Get-PAAccount.md) + +[New-PAAccount](New-PAAccount.md) diff --git a/docs/Functions/Set-PAOrder.md b/docs/Functions/Set-PAOrder.md new file mode 100644 index 00000000..b4bf2e82 --- /dev/null +++ b/docs/Functions/Set-PAOrder.md @@ -0,0 +1,416 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Set-PAOrder/ +schema: 2.0.0 +--- + +# Set-PAOrder + +## Synopsis + +Set the current ACME order, edits an orders properties, or revokes an order's certificate. + +## Syntax + +### Edit (Default) + +```powershell +Set-PAOrder [[-MainDomain] ] [-Name ] [-NoSwitch] [-Plugin ] + [-PluginArgs ] [-DnsAlias ] [-NewName ] [-FriendlyName ] + [-PfxPass ] [-PfxPassSecure ] [-Install] [-OCSPMustStaple] [-DnsSleep ] + [-ValidationTimeout ] [-PreferredChain ] [-AlwaysNewKey] [-UseSerialValidation] [-WhatIf] + [-Confirm] [] +``` + +### Revoke + +```powershell +Set-PAOrder [[-MainDomain] ] [-Name ] [-RevokeCert] [-Force] [-NoSwitch] [-WhatIf] [-Confirm] + [] +``` + +## Description + +Switch to a specific ACME order and edit its properties or revoke its certificate. +Revoked certificate orders are not deleted and can be re-requested using Submit-Renewal or New-PACertificate. + +## Examples + +### Example 1 + +```powershell +Set-PAOrder site1.example.com +``` + +Switch to the specified domain's order. + +### Example 2 + +```powershell +Set-PAOrder -RevokeCert +``` + +Revoke the current order's certificate. + +### Example 3 + +```powershell +Set-PAOrder -FriendlyName 'new friendly name' +``` + +Edit the friendly name for the current order and certificate if it exists. + +## Parameters + +### -MainDomain +The primary domain for the order. +For a SAN order, this was the first domain in the list when creating the order. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Name +The name of the ACME order. +This can be useful to distinguish between two orders that have the same MainDomain. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -RevokeCert +If specified, a request will be sent to the associated ACME server to revoke the certificate on this order. +Clients may wish to do this if the certificate is decommissioned or the private key has been compromised. +A warning will be displayed if the order is not currently valid or the existing certificate file can't be found. + +```yaml +Type: SwitchParameter +Parameter Sets: Revoke +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +If specified, confirmation prompts for certificate revocation will be skipped. + +```yaml +Type: SwitchParameter +Parameter Sets: Revoke +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoSwitch +If specified, the currently selected order will not change. +Useful primarily for bulk certificate revocation. +This switch is ignored if no MainDomain is specified. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Plugin +One or more validation plugin names to use for this order's challenges. +If no plugin is specified, the DNS "Manual" plugin will be used. +If the same plugin is used for all domains in the order, you can just specify it once. +Otherwise, you should specify as many plugin names as there are domains in the order and in the same sequence as the order. + +```yaml +Type: String[] +Parameter Sets: Edit +Aliases: DnsPlugin + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PluginArgs +A hashtable containing the plugin arguments to use with the specified Plugin list. +So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + +```yaml +Type: Hashtable +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DnsAlias +One or more FQDNs that DNS challenges should be published to instead of the certificate domain's zone. +This is used in advanced setups where a CNAME in the certificate domain's zone has been pre-created to point to the alias's FQDN which makes the ACME server check the alias domain when validation challenge TXT records. +If the same alias is used for all domains in the order, you can just specify it once. +Otherwise, you should specify as many alias FQDNs as there are domains in the order and in the same sequence as the order. + +```yaml +Type: String[] +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NewName +The new name for this ACME order. + +```yaml +Type: String +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FriendlyName +The friendly name for the certificate and subsequent renewals. +This will populate the "Friendly Name" field in the Windows certificate store when the PFX is imported. +Must not be an empty string. + +```yaml +Type: String +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PfxPass +The PFX password for the certificate and subsequent renewals. +When the PfxPassSecure parameter is specified, this parameter is ignored. + +```yaml +Type: String +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PfxPassSecure +The PFX password for the certificate and subsequent renewals using a SecureString value. +When this parameter is specified, the PfxPass parameter is ignored. + +```yaml +Type: SecureString +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Install +Enables the Install switch for the order. +Use -Install:$false to disable the switch on the order. +This affects whether the module will automatically import the certificate to the Windows certificate store on subsequent renewals. +It will not import the current certificate if it exists. +Use Install-PACertificate for that purpose. + +```yaml +Type: SwitchParameter +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OCSPMustStaple +If specified, the certificate generated for this order will have the OCSP Must-Staple flag set. + +```yaml +Type: SwitchParameter +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DnsSleep +Number of seconds to wait for DNS changes to propagate before asking the ACME server to validate DNS challenges. + +```yaml +Type: Int32 +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ValidationTimeout +Number of seconds to wait for the ACME server to validate the challenges after asking it to do so. +If the timeout is exceeded, an error will be thrown. + +```yaml +Type: Int32 +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PreferredChain +If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. +If no match, the default offered chain will be used. + +```yaml +Type: String +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -AlwaysNewKey +If specified, the order will be configured to always generate a new private key during each renewal. +Otherwise, the old key is re-used if it exists. + +```yaml +Type: SwitchParameter +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UseSerialValidation +If specified, the names in the order will be validated individually rather than all at once. +This can significantly increase the time it takes to process validations and should only be used for plugins that require it. +The plugin's usage guide should indicate whether it is required. + +```yaml +Type: SwitchParameter +Parameter Sets: Edit +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Related Links + +[Get-PAOrder](Get-PAOrder.md) + +[New-PAOrder](New-PAOrder.md) diff --git a/docs/Functions/Set-PAServer.md b/docs/Functions/Set-PAServer.md new file mode 100644 index 00000000..2884e69e --- /dev/null +++ b/docs/Functions/Set-PAServer.md @@ -0,0 +1,168 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Set-PAServer/ +schema: 2.0.0 +--- + +# Set-PAServer + +## Synopsis + +Set the current ACME server and/or its configuration. + +## Syntax + +```powershell +Set-PAServer [[-DirectoryUrl] ] [-Name ] [-NewName ] [-SkipCertificateCheck] + [-DisableTelemetry] [-NoRefresh] [-NoSwitch] [] +``` + +## Description + +Use this function to set the current ACME server or change a server's configuration settings. + +## Examples + +### Example 1 + +```powershell +Set-PAServer LE_PROD +``` + +Switch to the LetsEncrypt production server using the short name. + +### Example 2 + +```powershell +Set-PAServer -DirectoryUrl https://myacme.example.com/directory +``` + +Switch to the specified ACME server using the directory URL. + +### Example 3 + +```powershell +(Get-PAServer -List)[0] | Set-PAServer +``` + +Switch to the first ACME server returned by "Get-PAServer -List" + +## Parameters + +### -DirectoryUrl +Either the URL to an ACME server's "directory" endpoint or one of the supported short names. +Currently supported short names include LE_PROD (LetsEncrypt Production v2), LE_STAGE (LetsEncrypt Staging v2), BUYPASS_PROD (BuyPass.com Production), and BUYPASS_TEST (BuyPass.com Testing). + +```yaml +Type: String +Parameter Sets: (All) +Aliases: location + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Name +The name of the ACME server. +The parameter is ignored if DirectoryUrl is specified. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -NewName +The new name of this ACME server. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipCertificateCheck +If specified, disable certificate validation while using this server. +This should not be necessary except in development environments where you are connecting to a self-hosted ACME server. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -DisableTelemetry +If specified, telemetry data will not be sent to the Posh-ACME team for actions associated with this server. +The telemetry data that gets sent by default includes Posh-ACME version, PowerShell version, and generic OS platform (Windows/Linux/MacOS). + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -NoRefresh +If specified, the ACME server will not be re-queried for updated endpoints or a fresh nonce. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoSwitch +If specified, the currently active ACME server will not be changed to the server being modified. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Related Links + +[Get-PAServer](Get-PAServer.md) diff --git a/docs/Functions/Submit-ChallengeValidation.md b/docs/Functions/Submit-ChallengeValidation.md new file mode 100644 index 00000000..acbdd735 --- /dev/null +++ b/docs/Functions/Submit-ChallengeValidation.md @@ -0,0 +1,73 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Submit-ChallengeValidation/ +schema: 2.0.0 +--- + +# Submit-ChallengeValidation + +## Synopsis + +Respond to authorization challenges for an ACME order and wait for the ACME server to validate them. + +## Syntax + +```powershell +Submit-ChallengeValidation [[-Order] ] [] +``` + +## Description + +An ACME order contains an authorization object for each domain in the order. Each authorization contains one or more challenge types. The client must complete at least one challenge for each authorization in order to prove they control the domain. Once complete, the client asks the server to validate each challenge and waits for the server to do so and update the authorization status. + +## Examples + +### Example 1 + +```powershell +Submit-ChallengeValidation +``` + +Begin challenge validation on the current order. + +### Example 2 + +```powershell +Get-PAOrder -Name myorder | Submit-ChallengeValidation +``` + +Begin challenge validation on the specified order. + +## Parameters + +### -Order +The ACME order to perform the validations against. +The order object must be associated with the currently active ACME account. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### PoshACME.PAOrder +An order object. + +## Related Links + +[Get-PAOrder](Get-PAOrder.md) + +[New-PAOrder](New-PAOrder.md) diff --git a/docs/Functions/Submit-OrderFinalize.md b/docs/Functions/Submit-OrderFinalize.md new file mode 100644 index 00000000..080c0621 --- /dev/null +++ b/docs/Functions/Submit-OrderFinalize.md @@ -0,0 +1,73 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Submit-OrderFinalize/ +schema: 2.0.0 +--- + +# Submit-OrderFinalize + +## Synopsis + +Finalize a certificate order + +## Syntax + +```powershell +Submit-OrderFinalize [[-Order] ] [] +``` + +## Description + +An ACME order that has reached the `ready` state is ready to be finalized which involves sending the certificate request to the ACME server so it can sign the certificate and transition the order into the `valid` state. + +## Examples + +### Example 1 + +```powershell +Submit-OrderFinalize +``` + +Finalize the current order. + +### Example 2 + +```powershell +Get-PAOrder example.com | Submit-OrderFinalize +``` + +Finalize the specified order. + +## Parameters + +### -Order +The ACME order to finalize. +The order object must be associated with the currently active ACME account. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### PoshACME.PAOrder +An order object. + +## Related Links + +[Get-PAOrder](Get-PAOrder.md) + +[Submit-ChallengeValidation](Submit-ChallengeValidation.md) diff --git a/docs/Functions/Submit-Renewal.md b/docs/Functions/Submit-Renewal.md new file mode 100644 index 00000000..5927140d --- /dev/null +++ b/docs/Functions/Submit-Renewal.md @@ -0,0 +1,212 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Submit-Renewal/ +schema: 2.0.0 +--- + +# Submit-Renewal + +## Synopsis + +Renew one or more certificates. + +## Syntax + +### Specific + +```powershell +Submit-Renewal [[-MainDomain] ] [[-Name] ] [-Force] [-NoSkipManualDns] + [-PluginArgs ] [] +``` + +### AllOrders + +```powershell +Submit-Renewal [-AllOrders] [-Force] [-NoSkipManualDns] [-PluginArgs ] [] +``` + +### AllAccounts + +```powershell +Submit-Renewal [-AllAccounts] [-Force] [-NoSkipManualDns] [-PluginArgs ] [] +``` + +## Description + +This function allows you to renew one more more previously completed certificate orders. +You can choose to renew a specific order, set of orders, all orders for the current account, or all orders for all accounts. + +## Examples + +### Example 1 + +```powershell +Submit-Renewal +``` + +Renew the current order on the current account. + +### Example 2 + +```powershell +Submit-Renewal -Force +``` + +Renew the current order on the current account even if it hasn't reached its suggested renewal window. + +### Example 3 + +```powershell +Submit-Renewal -AllOrders +``` + +Renew all valid orders on the current account that have reached their suggested renewal window. + +### Example 4 + +```powershell +Submit-Renewal -AllAccounts +``` + +Renew all valid orders on all valid accounts that have reached their suggested renewal window. + +### Example 5 + +```powershell +Submit-Renewal site1.example.com -Force +``` + +Renew the order for the specified site regardless of its renewal window. + +## Parameters + +### -MainDomain +The primary domain associated with an order. +This is the domain that goes in the certificate's subject. + +```yaml +Type: String +Parameter Sets: Specific +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Name +The name of the ACME order. +This can be useful to distinguish between two orders that have the same MainDomain. + +```yaml +Type: String +Parameter Sets: Specific +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -AllOrders +If specified, renew all valid orders on the current account. +Orders that have not reached the renewal window will be skipped unless -Force is used. + +```yaml +Type: SwitchParameter +Parameter Sets: AllOrders +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -AllAccounts +If specified, renew all valid orders on all valid accounts in this profile. +Orders that have not reached the renewal window will be skipped unless -Force is used. + +```yaml +Type: SwitchParameter +Parameter Sets: AllAccounts +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +If specified, an order that hasn't reached its renewal window will not throw an error and will not be skipped when using either of the -All parameters. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoSkipManualDns +If specified, orders that utilize the Manual DNS plugin will not be skipped and user interaction may be required to complete the process. +Otherwise, orders that utilize the Manual DNS plugin will be skipped. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PluginArgs +A hashtable containing an updated set of plugin arguments to use with the renewal. +So if a plugin has a `MyText` string and `MyNumber` integer parameter, you could specify them as `@{MyText='text';MyNumber=1234}`. + +```yaml +Type: Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Outputs + +### PoshACME.PACertificate +A certificate object. + +## NOTES + +Certificate objects are only returned for orders that were actually renewed successfully. Any orders that have not reached the suggested renewal window are skipped unless `-Force` is specified. + +## Related Links + +[New-PACertificate](New-PACertificate.md) + +[Get-PAOrder](Get-PAOrder.md) diff --git a/docs/Functions/Unpublish-Challenge.md b/docs/Functions/Unpublish-Challenge.md new file mode 100644 index 00000000..d4958cf2 --- /dev/null +++ b/docs/Functions/Unpublish-Challenge.md @@ -0,0 +1,157 @@ +--- +external help file: Posh-ACME-help.xml +Module Name: Posh-ACME +online version: https://poshac.me/docs/v4/Functions/Unpublish-Challenge/ +schema: 2.0.0 +--- + +# Unpublish-Challenge + +## Synopsis + +Unpublish a challenge using the specified plugin. + +## Syntax + +```powershell +Unpublish-Challenge [-Domain] [-Account] [-Token] [-Plugin] + [[-PluginArgs] ] [-DnsAlias ] [] +``` + +## Description + +Based on the type of validation plugin specified, this function will unpublish either a DNS TXT record or an HTTP challenge file for the given domain and token value that satisfies the dns-01 or http-01 challenge specification. + +Depending on the plugin, calling `Save-Challenge` may be required to commit changes made by `Unpublish-Challenge`. +If multiple challenges are being unpublished, make all `Unpublish-Challenge` calls first. +Then, `Save-Challenge` once to commit them all. + +## Examples + +### Example 1 + +```powershell +$auths = Get-PAOrder | Get-PAAuthorization +Unpublish-Challenge $auths[0].DNSId (Get-PAAccount) $auths[0].DNS01Token Manual @{} +``` + +Unpublish a DNS challenge for the first authorization in the current order using the Manual DNS plugin. + +### Example 2 + +```powershell +$pArgs = @{Param1='asdf';Param2=1234} +$acct = Get-PAAccount +Unpublish-Challenge example.com $acct MyPlugin $pArgs -Token faketoken +``` + +Unpublish a challenge for example.com using a fictitious plugin and arguments. + +## Parameters + +### -Domain +The domain name that the challenge will be unpublished for. +Wildcard domains should have the "*." removed and can only be used with DNS based validation plugins. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Account +The account object associated with the order that required the challenge. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Token +The token value from the appropriate challenge in an authorization object that matches the plugin type. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Plugin +The name of the validation plugin to use. +Use Get-PAPlugin to display a list of available plugins. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 4 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PluginArgs +A hashtable containing the plugin arguments to use with the specified plugin. +So if a plugin has a -MyText string and -MyNumber integer parameter, you could specify them as @{MyText='text';MyNumber=1234}. + +```yaml +Type: Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: 5 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DnsAlias +When using DNS Alias support with DNS validation plugins, the alias domain that the TXT record will be removed from. +This should be the complete FQDN including the '_acme-challenge.' prefix if necessary. +This field is ignored for non-DNS validation plugins. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## Related Links + +[Publish-Challenge](Publish-Challenge.md) + +[Save-Challenge](Save-Challenge.md) + +[Get-PAPlugin](Get-PAPlugin.md) diff --git a/docs/Guides/.pages b/docs/Guides/.pages new file mode 100644 index 00000000..87e1ffbd --- /dev/null +++ b/docs/Guides/.pages @@ -0,0 +1,4 @@ +nav: + - index.md + - ... + - External-Articles.md diff --git a/docs/Guides/Custom-Challenge-Validation.md b/docs/Guides/Custom-Challenge-Validation.md new file mode 100644 index 00000000..b99cc8c8 --- /dev/null +++ b/docs/Guides/Custom-Challenge-Validation.md @@ -0,0 +1,249 @@ +title: (Advanced) Custom Challenge Validation + +# Custom Challenge Validation + +## Intro + +The beauty of the ACME protocol is that it's an [open standard](https://tools.ietf.org/html/rfc8555). And while Posh-ACME primarily targets users who want to avoid understanding all of the protocol complexity, it also exposes functions that allow you to do things a bit closer to the protocol level than just running `New-PACertificate` and `Submit-Renewal`. This can enable more advanced automation scenarios such as supporting challenge types that the module doesn't directly support yet or responding to authorization challenges in a way not directly supported by existing plugins. This guide will walk through the ACME certificate request process and demonstrate how to manage the validation of authorization challenges. + +At a high level, the ACME conversation looks more or less like this: + +- Create an account +- Create a certificate order +- Prove control of the "identifiers" (DNS names or IP addresses) in the requested cert by answering challenges. +- Finalize the order by submitting an certificate request (CSR) +- Download the signed certificate and chain + +!!! warning + IP Address identifiers ([RFC 8738](https://tools.ietf.org/html/rfc8738)) are supported by Posh-ACME. But they're not yet supported by any ACME-compatible public certificate authorities that I'm aware of. If you want to test them, you'll have to use [Pebble](https://github.com/letsencrypt/pebble). + +If you're curious about what's going on under the hood during this guide, add `-Verbose` to your commands or run `$VerbosePreference = 'Continue'`. If you really want to get deep, you can also turn on debug logging by running `$DebugPreference = 'Continue'` which will also display the raw JSON requests and responses. The defaults for both of those preferences are `SilentlyContinue` if you want to change them back later. + +## Server Selection + +While testing code, you should **not** use the production Let's Encrypt server. The staging server is the easiest alternative, but still has some rate limits that you can run afoul of if your code goes crazy. There is also [Pebble](https://github.com/letsencrypt/pebble) which is a tiny ACME server you can self-host and is built for testing code against. For simplicity, we'll select the Let's Encrypt staging server. + +```powershell +Set-PAServer LE_STAGE +``` + +## Account Setup + +Requesting a certificate always starts with creating an account on the ACME server which is basically just a public/private key pair that is used to sign the protocol messages you send to the server along with some metadata like one or more email addresses to send expiration notifications to. If you've been previously using the module against the staging server, you likely already have an account. If so, you can either skip this section or create a second account which is also supported. + +```powershell +New-PAAccount -AcceptTOS -Contact 'me@example.com' +``` + +!!! warning + If you're using Pebble as your ACME server, it doesn't save accounts or order details when you shut it down. So you'll have to re-create accounts and orders if you exit and restart it. + +## Create an Order + +The only required parameter for a new order is the set of names you want included in the certificate. Optional parameters include things like `-KeyLength` to change the private key type/size, `-Install` which tells Posh-ACME to automatically store the signed cert in the Windows certificate store *(requires local admin)*, and `-PfxPass` which lets you set the decryption password for the certificate PFX file. If we were using plugins, this is also where you could set which plugin to use and the parameters associated with it. + +In this example, we'll create a typical wildcard cert that contains a root domain and the wildcard version of it. Keep in mind that wildcard names [require using DNS challenge validation](https://community.letsencrypt.org/t/acme-v2-and-wildcard-certificate-support-is-live/55579). So if you're testing HTTP challenge validation, either leave that one out or add a different non-wildcard name. + +```powershell +$domains = 'example.com','*.example.com' +New-PAOrder $domains +``` + +Assuming you didn't use names that were previously validated on this account, you should get output that looks something like this where the status is `pending`. If the status is `ready`, create an order with different names that haven't been previously validated. + +``` +MainDomain status KeyLength SANs OCSPMustStaple CertExpires Plugin +---------- ------ --------- ---- -------------- ----------- ------ +example.com pending 2048 {*.example.com} False {Manual} +``` + +## Authorizations and Challenges + +The distinction between an order, authorization, and challenge can be confusing if you're not familiar with the ACME protocol. So let's clarify first. An order is a request for a certificate that contains one or more "identifiers" (a name like `example.com`). Each identifier in an order has an authorization object associated with it that indicates whether the account that created the order is authorized to get a cert for that name. New authorizations start in a pending state awaiting the client to complete a challenge associated with that authorization. Each authorization can have multiple different challenges (DNS, HTTP, ALPN, etc) that indicate the different methods the ACME server will accept to prove ownership of the name. You only need to complete one of the offered challenges in order to satisfy an authorization. + +!!! note + Different types of identifiers may only allow a subset of challenge types. For instance, wildcard DNS names can only be validated by a DNS challenge and IP addresses can only be validated by HTTP or ALPN challenges. + +`Get-PAAuthorization` can be used with the output of `Get-PAOrder` to retrieve the current set of authorizations (and their challenges) for an order. So lets put those details into a variable and display them. + +```powershell +$auths = Get-PAOrder | Get-PAAuthorization +$auths +``` + +This should give an output that looks something like this. The first status column is the overall status of the authorization. The last two columns are the status of the `dns-01` and `http-01` challenges. Normally the challenge specific details are buried a bit deeper in a `challenges` property, but Posh-ACME tries to help by surfacing the commonly used challenge details on the root object. Notice also how the wildcard name has no `HTTP01Status` because it was not offered as a valid challenge type for that identifier. + +``` +fqdn status Expires DNS01Status HTTP01Status +---- ------ ------- ----------- ------------ +example.com pending 12/24/2020 7:14:33 PM pending pending +*.example.com pending 12/24/2020 7:14:33 PM pending +``` + +Let's take a look at the full details of one of the authorization objects by running `$auths[0] | fl`. You should get an output like this: + +``` +identifier : @{type=dns; value=example.com} +status : pending +expires : 2020-12-25T16:52:23Z +challenges : {@{type=dns-01; status=pending; url=https://acme-staging-v02.api.letsencrypt.org/acme/challenge//; token=}, + @{type=http-01; status=pending; url=https://acme-staging-v02.api.letsencrypt.org/acme/challenge//; token=}, + @{type=tls-alpn-01; status=pending; url=https://acme-staging-v02.api.letsencrypt.org/acme/challenge//; token=}} +DNSId : example.com +fqdn : example.com +location : https://acme-staging-v02.api.letsencrypt.org/acme/authz/ +DNS01Status : pending +DNS01Url : https://acme-staging-v02.api.letsencrypt.org/acme/challenge// +DNS01Token : +HTTP01Status : pending +HTTP01Url : https://acme-staging-v02.api.letsencrypt.org/acme/challenge// +HTTP01Token : +``` + +For this identifier, the ACME server has offered all three challenge types: `http-01`, `dns-01`, and `tls-alpn-01`. In addition to the type, each challenge contains a `status`, `url` and `token` property. For HTTP and DNS challenges, these can also be read from the root authorization object using the `HTTP01xxx` and `DNS01xxx` properties. We'll go over how to use the tokens in the next couple sections about publishing challenges. + + +## Publishing an HTTP Challenge + +For an HTTP challenge, the ACME server must be able send an HTTP GET request to a particular URL **on port 80** and receive a [key authorization](https://tools.ietf.org/html/rfc8555#section-8.1) value which is based on the token value in the challenge and the public key thumbprint of your account key. You can build the URL using the following template: + +```powershell +$url = 'http://{0}/.well-known/acme-challenge/{1}' -f $auths[0].DNSId,$auths[0].HTTP01Token +``` + +!!! note + Most ACME servers will follow HTTP 3xx redirect responses, but the initial request will always be non-TLS to port 80. So you must not block port 80 on your web server if you want to use HTTP challenges. + +The key authorization can be generated using `Get-KeyAuthorization` like this. + +```powershell +$keyauth = Get-KeyAuthorization $auths[0].HTTP01Token +``` + +Now it's up to you to setup your web server so it responds with the key authorization value when the URL is queried from the Internet. If it's only queryable from your internal LAN, the challenge validation will fail. + +!!! note + If you're using PowerShell functions to create the challenge files, make sure to specify ASCII/ANSI file encoding. Line endings shouldn't matter, but the encoding does in my testing. So if you're using `Out-File`, add `-Encoding ascii`. + + + +## Publishing a DNS Challenge + +For a DNS challenge, the ACME server must be able send an TXT record query for a particular record name and receive a key authorization value in the response which is similar to the value it wants for an HTTP challenge. You can build the record name using the following template: + +```powershell +$recName = '_acme-challenge.{0}' -f $auths[1].DNSId +``` + +The key authorization can be generated using `Get-KeyAuthorization` like this. Note the extra `-ForDNS` parameter compared to the HTTP challenge and the reference to `DNS01Token` instead of `HTTP01Token`. Each challenge type within an authorization has a unique token value. + +```powershell +$keyauth = Get-KeyAuthorization $auths[1].DNS01Token -ForDNS +``` + +The astute reader may have realized that in our example, this means the name of the TXT record would be the same for both identifiers, `example.com` and `*.example.com`. They both translate to `_acme-challenge.example.com`. This tends to confuse people at first, but it's really no different than having multiple A records pointing to different IPs for a website. The ACME validation server is smart enough to check all of the returned results and find the one it cares about. + +Now it's up to you to publish the record on your DNS server that is queryable from the Internet. Depending on your DNS provider and its replication topology, it may take anywhere from seconds to minutes for the records you create to be queryable from the Internet. Make sure you either know how long it's supposed to take and wait that long before proceeding, or query your authoritative external nameservers directly until they return the expected results. + +!!! warning + In DNS providers that use [anycast](https://www.cloudflare.com/learning/dns/what-is-anycast-dns/) even if you successfully query the nameserver for your record from your location, it may still fail from other locations in the world due to propagation delays. Some providers have an API you can query to know when it is fully propagated. Others don't and you just have to wait longer. + +!!! note + ACME validation servers will also follow CNAME records to validate challenges. This can be useful if your primary DNS server has no API or the security posture of your organization doesn't allow an automated process such as an ACME client to have write access to the zone you need to create TXT records within. If you know this will be the case, you can create a permanent CNAME record for the `_acme-challenge.` name that points to another FQDN somewhere else. Then write your TXT record to that other target and as long as that zone is still Internet-facing, the validation will succeed. + + +## Publishing a TLS-ALPN Challenge + +At the time of this writing, I don't know enough about ALPN to authoritatively write a section on how to use it. But I know it's dependent on the web server software you're using. Here is [Let's Encrypt's documentation](https://letsencrypt.org/docs/challenge-types/#tls-alpn-01) on the subject. + + +## Notify the ACME Server + +Now that you've published all of your key validations for all of your challenges, you're ready to ask the ACME server to check them. The requires the `url` property from the challenge you published which for HTTP/DNS challenges can also be read from `HTTP01Url` or `DNS01Url` on the root authorization object. Use the `Send-ChallengeAck` function like this. + +```powershell +# if all of your challenges were published using the same challenge type such as HTTP +$auths.HTTP01Url | Send-ChallengeAck + +# if you published challenges of different types, make sure to use the specific URLs associated with them +$auths[0].HTTP01Url | Send-ChallengeAck +$auths[1].DNS01Url | Send-ChallengeAck +``` + +The challenges are usually validated quickly. But there may be a delay if the ACME server is overloaded. You can poll the status of your authorizations by re-running `Get-PAOrder | Get-PAAuthorization`. Eventually, the status for each one will either be "valid" or "invalid". Good output should look something like this. Notice how the overall status for each challenge is `valid` while the individual challenge status is only valid for the specific challenge types we published. + +``` +fqdn status Expires DNS01Status HTTP01Status +---- ------ ------- ----------- ------------ +example.com valid 12/24/2020 7:14:33 PM valid +*.example.com valid 12/24/2020 7:14:33 PM valid +``` + +# Finishing Up + +Now that you have all of your identifiers authorized, your order status should now be "ready" which you can check with `Get-PAOrder -Refresh`. It should look something like this. + +``` +MainDomain status KeyLength SANs OCSPMustStaple CertExpires Plugin +---------- ------ --------- ---- -------------- ----------- ------ +example.com ready 2048 {*.example.com} False {Manual} +``` + +The next step is "finalization" in which you send a the actual x509 certificate request (CSR) to the ACME server. Run the following: + +``` +Submit-OrderFinalize +``` + +If you run `Get-PAOrder -Refresh` again, your order status should now be `valid` which means you're ready to download the final signed certificate. Run the following to let Posh-ACME take care of that and build the various combinations of PEM/PFX files. + +``` +Complete-PAOrder +``` + +This will also output the final certificate details that should look something like this. + +``` +Subject NotAfter KeyLength Thumbprint AllSANs +------- -------- --------- ---------- ------- +CN=example.com 3/15/2021 4:37:37 PM 2048 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX {example.com, *.example.com} +``` + +It is also the same output you get from `Get-PACertificate`. Run `Get-PACertificate | fl` to get a full list of cert properties including the filesystem paths where the files are stored. + + +## Debugging Challenge Failures + +If for some reason one or more of your challenge validations failed, you can retrieve the error details from the ACME server like this. + +```powershell +(Get-PAOrder | Get-PAAuthorization).challenges.error | fl +``` + +## Revoking Authorizations + +Let's Encrypt and other ACME CAs will generally cache authorizations associated with an account for a period of time. Let's Encrypt caches them for around 30 days which means that if you request another cert in that timeframe with an identifier/name that you've already authorized, the authorization objects won't need to be re-validated. Their status will be immediately valid. + +This can be annoying if you're trying to test your challenge validation automation. However, you can revoke your existing authorizations for a given order like this: + +```powershell +# NOTE: Without -Force, there will be a confirmation prompt for each name being revoked. +Get-PAorder | Revoke-PAAuthorization -Force +``` + +This process **does not** revoke the *certificate*. It only revokes the *authorizations* so that you need to re-validate those names when you request a new certificate that contains them. + + +## Renewals + +The concept of a renewal doesn't actually exist in the ACME protocol. What most clients call a renewal is just a new order with the same parameters as last time. So the only thing extra you need to deal with is knowing *when* to renew. When you successfully complete a certificate order, Posh-ACME will attach a `RenewAfter` property to the order object which you can use to calculate whether it's time to renew or not. The property is an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date/time string which can be parsed and checked with [`DateTimeOffset`](https://docs.microsoft.com/en-us/dotnet/api/system.datetimeoffset) like this. + +```powershell +$renewAfter = [DateTimeOffset]::Parse((Get-PAOrder).RenewAfter) +if ([DateTimeOffset]::Now -gt $renewAfter) { + # time to renew +} +``` + +!!! note + The RenewAfter value is just a suggestion based on the lifetime of the certificate. Technically, you can renew whenever you want. But if you renew the same certificate too often, you might run into rate limits with your CA. diff --git a/docs/Guides/External-Articles.md b/docs/Guides/External-Articles.md new file mode 100644 index 00000000..712bc2fc --- /dev/null +++ b/docs/Guides/External-Articles.md @@ -0,0 +1,25 @@ +# External Articles + +[Using Let's Encrypt for Active Directory Domain Controller Certificates](https://www.dvolve.net/blog/2019/12/using-lets-encrypt-for-active-directory-domain-controller-certificates/) + +[Using Let’s Encrypt certificates with Windows Admin Center](https://joakim.silverdrake.se/2018/12/05/using-lets-encrypt-certificates-with-windows-admin-center/) + +[Connect to a Windows server with RD Gateway using a Let's Encrypt certificate](https://dev.classmethod.jp/cloud/aws/how-to-setup-rdgateway-posh-acme/) + +[Certificates in the time of Let's Encrypt](https://rakhesh.com/windows/certificates-in-the-time-of-lets-encrypt/) + +[Let’s Encrypt, IIS Central Cert Store and Powershell](http://stevenmaglio.blogspot.com/2019/02/lets-encrypt-iis-central-cert-store-and.html) + +[Generate LetsEncrypt signed certificates and upload to Azure Key Vault](https://marketplace.visualstudio.com/items?itemName=cboroson.cboroson-VSTS-LetsEncrypt) + +[Automating certificate management with Azure and Let’s Encrypt](https://medium.com/@brentrobinson5/automating-certificate-management-with-azure-and-lets-encrypt-fee6729e2b78) + +[How to use Azure Automation to issue Let's Encrypt certificates](https://www.csoonline.com/article/3400950/how-to-use-azure-automation-to-issue-lets-encrypt-certificates.html) + +[Automate the Installation and Renewal of Let’s Encrypt SSL Certificates in Azure](https://www.deliveron.com/blog/automate-installation-renewal-lets-encrypt-ssl-certificates-azure/) + +[Securing VMware Horizon UAGs with Let’s Encrypt SSL certificates](https://virtualhobbit.com/2019/12/23/securing-vmware-horizon-uags-with-lets-encrypt-ssl-certificates/) + +[Automate Free SSL Certificate Replacement for vCenter 7](https://virtuallywired.io/2021/05/15/automate-free-ssl-certificate-replacement-for-vcenter-7/) + +[Automate SSL Certificates in Veeam Cloud Connect](https://vccbook.io/9.advanced/9.2-lets_encrypt.html) diff --git a/docs/Guides/Troubleshooting-DNS-Validation.md b/docs/Guides/Troubleshooting-DNS-Validation.md new file mode 100644 index 00000000..85450a70 --- /dev/null +++ b/docs/Guides/Troubleshooting-DNS-Validation.md @@ -0,0 +1,67 @@ +# Troubleshooting DNS Validation + +## Overview + +One of the more common problems using DNS challenge validation with ACME is when the server thinks your TXT records either don't exist or are invalid. There are a number of reasons why this might be the case and in this guide, we'll go over some of the possibilities. But first, let's review how to query TXT records. + +## Querying TXT records + +`nslookup` is the primary tool most people use to do DNS queries from Windows because it's installed by default and available on every Windows OS since basically forever. PowerShell has `Resolve-DnsName` but only since Windows 8/2012. So we'll focus on `nslookup` for now. + +``` +C:\>nslookup -q=txt _acme-challenge.example.com. +``` + +**Don't forget the final `.` on the domain name.** + +This is the basic command that will query your local DNS server. But it's usually wise to specifically query a public DNS resolver like Google (8.8.8.8) or CloudFlare (1.1.1.1) in case you're in a [split-brain](https://en.wikipedia.org/wiki/Split-horizon_DNS) DNS environment. However, some businesses are starting to deploy firewalls that block outbound DNS requests like this. So make sure you are able to query a known good record before tearing your hair out troubleshooting the record you're having trouble with. Here's how to explicitly query an external resolver. + +``` +C:\>nslookup -q=txt _acme-challenge.example.com. 1.1.1.1 +``` + +If the query was successful, the output might look something like this: + +``` +Server: 1dot1dot1dot1.cloudflare-dns.com +Address: 1.1.1.1 + +Non-authoritative answer: +_acme-challenge.example.com text = + + "asdfa7sdcv6qn4klav7127134" +``` + +Otherwise, it will be more like this: +``` +Server: 1dot1dot1dot1.cloudflare-dns.com +Address: 1.1.1.1 + +*** 1dot1dot1dot1.cloudflare-dns.com can't find _acme-challenge.example.com: Non-existent domain +``` + +## DNS Propagation Delays + +In many environments, the DNS server you are adding records to is not the same server that the Internet is sending queries to. Depending on the server and the DNS architecture, there may be both database replication delays and DNS zone transfer delays to slave servers. + +By default, Posh-ACME sleeps for 2 minutes after writing TXT records for a certificate before it asks the ACME server to validate them. But 2 minutes might not be long enough for your particular environment. In that case, use the `-DnsSleep` parameter to modify the default sleep time. It takes a value in seconds. So if you needed 5 minutes, you'd use `-DnsSleep 300`. + +And rather than just blindly increasing the delay when you're having a problem, it's a good idea to actually measure instead. + +- Manually create a record +- Start a timer +- Query the record every few seconds until you see the change +- Make a note of the total time +- Add a 30 second buffer or so and use that value for `-DnsSleep` + +If you never see the change, it's possible you're having a different problem. + +## Internal vs External DNS + +Particularly in business environments, it is common to have a [split-brain](https://en.wikipedia.org/wiki/Split-horizon_DNS) DNS architecture which basically means there might be two different "views" of a particular zone, one internal and one external. The internal view might resolve `example.com` to an internal IP like `10.0.0.50`. But the external view for the same name might resolve to public IP like `203.0.113.50`. + +Make sure that you only add your DNS challenge TXT records to the External view because that's the one the ACME server will be able to see. + +## CAA Record Issues + +CAA is a relatively new type of DNS record that allows site owners to specify which Certificate Authorities (CAs) are allowed to issue certificates containing their domain names. Let's Encrypt, being a well behaved CA, tries to validate CAA records before issuing a certificate for a domain. So if you have a CAA record that is not correctly set to to allow Let's Encrypt, your challenge validation would fail. But there are a number of reasons why it might fail even if you are not using CAA records in your zone. Check Let's Encrypt's [CAA document](https://letsencrypt.org/docs/caa/) for more information. diff --git a/docs/Guides/Using-Custom-Plugins.md b/docs/Guides/Using-Custom-Plugins.md new file mode 100644 index 00000000..f74724d0 --- /dev/null +++ b/docs/Guides/Using-Custom-Plugins.md @@ -0,0 +1,13 @@ +# Using Custom Plugins + +Since version 4.7.0, you can optionally have Posh-ACME load plugins from a secondary location using the `POSH_ACMEPLUGINS` environment variable. This is useful because when the module is updated, you no longer need to re-deploy you custom plugins to the module's default Plugins folder. + +Set the environment variable to the folder path where the custom plugin(s) live. The environment variable must exist when the module is first loaded. So if it has already been loaded in the current session, re-import it with the `-Force` parameter. + +```powershell +$env:POSHACME_PLUGINS = 'C:\my\plugin\path' +Import-Module Posh-ACME -Force +``` + +!!! warning + Make sure your plugin's name doesn't conflict with the name of a buit-in plugin. If it does, a warning will be thrown and that plugin will be skipped. diff --git a/docs/Guides/Using-DNS-Challenge-Aliases.md b/docs/Guides/Using-DNS-Challenge-Aliases.md new file mode 100644 index 00000000..e75e2986 --- /dev/null +++ b/docs/Guides/Using-DNS-Challenge-Aliases.md @@ -0,0 +1,56 @@ +# Using DNS Challenge Aliases + +## Background + +There are two relatively common issues that come up when people try to automate ACME certs using DNS challenges. The first is that the DNS provider hosting the zone either doesn't have an API or the ACME client doesn't have a plugin to support it. The second is that for security reasons, the business may not want to save API credentials for their critical DNS zone on an internet-facing web server. + +The workaround for both of these involves using a [CNAME record](https://support.dnsimple.com/articles/cname-record/) to redirect challenge requests to another DNS zone. When the ACME server goes to validate the challenges, it will follow the CNAME and check the challenge token from the redirected record. If the original problem was no API or no plugin, you'd put the redirected zone on a provider with an API and a supported plugin. If the original problem was security related, you'd make the redirected zone a less important one. The downside is the extra manual step required to add the CNAME for each new cert or name in a cert. But you only have to do that once ever for each name. + +## Creating CNAMEs + +So how do we do that? First, you have to understand how the ACME protocol chooses what record to query for each name in a certificate. Non-wildcard names have `_acme-challenge.` prepended to them. Wildcard names use the same prefix but it replaces the `*.` prefix. So for example: + +Cert Name | Challenge Record +--------- | ---------------- +example.com | _acme-challenge.example.com +*.example.com | _acme-challenge.example.com +sub1.example.com | _acme-challenge.sub1.example.com +*.sub1.example.com | _acme-challenge.sub1.example.com +www.sub1.sub2.example.com | _acme-challenge.www.sub1.sub2.example.com + +You may have noticed that a wildcard name and a non-wildcard for the same root domain have the same challenge record. That's not a mistake and the ACME server does actually expect to get two different values for the same TXT record. What it means for you though is that you only have one CNAME to create for both types of names. + +Where do you point the CNAMEs to? It doesn't really matter as long as the ACME server can query it from the Internet and Posh-ACME can create the necessary records there. Some choose to use the same `_acme-challenge.` prefix for clarity. Some use a different prefix because their provider doesn't allow names to start with a `_` character. Some just point all of their CNAMEs to the exact same place. Examples: + +Challenge Record | CNAME Target +---------------- | ------------ +_acme-challenge.example.com | _acme-challenge.example.net +_acme-challenge.example.com | acme.example.net +_acme-challenge.example.com | _acme-challenge.validation.example.net +_acme-challenge.example.com
_acme-challenge.sub1.example.com
_acme-challenge.sub2.example.com | acme.example.net +_acme-challenge.example.com | example.net + +!!! warning + Don't point too many CNAMES at the same target. Let's Encrypt's ACME implementation can only deal with DNS responses [up to 4096 bytes](https://github.com/letsencrypt/boulder/pull/3467) which is roughly 60-70 TXT records depending on your DNS server and query parameters. If your record is too big, the validations will fail. + +## Testing + +You should verify your CNAME was created correctly before you try and use it. If you're inside a business with a split-horizon DNS infrastructure, you might need to explicitly query a public external resolver like CloudFlare's 1.1.1.1. However, some modern firewalls can be configured to prevent this ability. So make sure you can successfully query a known-good external record first. There are also web-based resolvers such as https://www.digwebinterface.com/ if necessary. + +```doscon +C:\>nslookup -q=CNAME _acme-challenge.example.com. 1.1.1.1 +Server: 1dot1dot1dot1.cloudflare-dns.com +Address: 1.1.1.1 + +Non-authoritative answer: +_acme-challenge.example.com canonical name = acme.example.net +``` + +## Using the Challenge Alias + +Now that your CNAMEs are all setup, you just have to add one more parameter to your certificate request command, `-DnsAlias`. It works just like `-Plugin` as an array that should have one element for each domain in the request. But if all of your CNAMEs point to the same place, you can just specify the alias once and it will use that alias for all the names. + +```powershell +New-PACertificate '*.example.com','example.com' -AcceptTOS -Contact 'admin@example.com' ` + -Plugin Route53 -PluginArgs $pArgs -DnsAlias acme.example.net -Verbose +``` diff --git a/docs/Guides/Using-an-Alternate-Config-Location.md b/docs/Guides/Using-an-Alternate-Config-Location.md new file mode 100644 index 00000000..d4d40b1d --- /dev/null +++ b/docs/Guides/Using-an-Alternate-Config-Location.md @@ -0,0 +1,32 @@ +# Using an Alternate Config Location + +Since version 3.2.0, you can configure Posh-ACME to use a different config location than the default path in the current user's profile folder. To do so, set an environment variable called `POSHACME_HOME` prior to running `Import-Module` or calling your first function. This can be done directly in the PowerShell session or any other standard way of setting environment variables in your OS or config management system. If the module was already imported before setting the environment variable, re-import with the `-Force` parameter to pick up the new location. + +```powershell +$env:POSHACME_HOME = 'C:\my\path' +Import-Module Posh-ACME -Force +``` + +## Why Bother? + +The default config location is specific to the OS the module is running on. + +- Windows: `%LOCALAPPDATA%\Posh-ACME` +- Linux: `$HOME/.config/Posh-ACME` +- MacOS: `$HOME/Library/Preferences/Posh-ACME` + +While the default config location is fine for most standard use-cases, there are legitimate reasons to host the config in a more central location. A common one is to enable multiple different users to manage certificates. Another might simply be easier integration with the application using the certificate. + +## IMPORTANT: Encrypted Plugin Parameters + +On Windows OSes, most DNS plugins default to using "secure" versions of various plugin parameters like passwords and API tokens. When saved to disk, these secure parameters are encrypted so only the current user on the current computer can decrypt them. If you are using an alternate config location so that multiple users on the system can manage certificates, this can cause errors if a user tries to decrypt something that was encrypted by another user. + +In Posh-ACME 4.x, you have a few options to workaround this limitation. + +1. On each ACME account, use portable AES encryption instead of the OS native encryption with the `-UseAltPluginEncryption` switch on either `New-PAAccount` or `Set-PAAccount`. + +2. Don't use any plugin parameters that are `[SecureString]` or `[PSCredential]` types. Most plugins have "Insecure" versions of the normally secure arguments that are not encrypted on disk. However, these insecure parameter sets are deprecated and may be removed in a future major version of the module. + +3. Have each user on the system create their own ACME account that only they will use. This will technically prevent the errors as long as people don't try to accidentally renew or create new order from the wrong account. But it's not recommended. + +In Posh-ACME 3.x and earlier, you must either use option 2 or 3. diff --git a/docs/Guides/index.md b/docs/Guides/index.md new file mode 100644 index 00000000..581c0c8c --- /dev/null +++ b/docs/Guides/index.md @@ -0,0 +1,3 @@ +# Guides and Deep Dives + +This section contains a variety of guides that explain some lesser known or more complicated features of Posh-ACME. diff --git a/docs/Plugins/.pages b/docs/Plugins/.pages new file mode 100644 index 00000000..40283e04 --- /dev/null +++ b/docs/Plugins/.pages @@ -0,0 +1,4 @@ +nav: + - index.md + - Plugin-Development-Guide.md + - ... diff --git a/Posh-ACME/Plugins/AcmeDns-Readme.md b/docs/Plugins/AcmeDns.md similarity index 99% rename from Posh-ACME/Plugins/AcmeDns-Readme.md rename to docs/Plugins/AcmeDns.md index e1747842..412883ca 100644 --- a/Posh-ACME/Plugins/AcmeDns-Readme.md +++ b/docs/Plugins/AcmeDns.md @@ -1,3 +1,5 @@ +title: AcmeDns + # How To Use the AcmeDns Plugin This plugin works against [acme-dns](https://github.com/joohoi/acme-dns) which is limited DNS server implementation designed specifically to handle DNS challenges for the ACME protocol. It is useful when your actual DNS provider doesn't have a supported plugin or security policies/limitations in your environment don't allow you to use a supported plugin. Initial certificate generation requires some manual steps, but renewals can be automated just like other plugins. diff --git a/Posh-ACME/Plugins/Akamai-Readme.md b/docs/Plugins/Akamai.md similarity index 99% rename from Posh-ACME/Plugins/Akamai-Readme.md rename to docs/Plugins/Akamai.md index b7705f4e..99a0df9f 100644 --- a/Posh-ACME/Plugins/Akamai-Readme.md +++ b/docs/Plugins/Akamai.md @@ -1,3 +1,5 @@ +title: Akamai + # How To Use the Akamai Plugin This plugin works against the [Akamai Edge DNS](https://www.akamai.com/uk/en/products/security/edge-dns.jsp) provider (formerly known as Fast DNS). It is assumed that you already have an account and one or more primary zones hosted. diff --git a/Posh-ACME/Plugins/Aliyun-Readme.md b/docs/Plugins/Aliyun.md similarity index 96% rename from Posh-ACME/Plugins/Aliyun-Readme.md rename to docs/Plugins/Aliyun.md index c920e4c4..33d484ed 100644 --- a/Posh-ACME/Plugins/Aliyun-Readme.md +++ b/docs/Plugins/Aliyun.md @@ -1,3 +1,5 @@ +title: Aliyun + # How To Use the Aliyun (Alibaba Cloud) DNS Plugin This plugin works against the [Aliyun (Alibaba Cloud)](https://www.alibabacloud.com/product/dns) DNS provider. It is assumed that you have already setup an account and registered the domains or zones you will be working against. diff --git a/Posh-ACME/Plugins/All-Inkl-Readme.md b/docs/Plugins/All-Inkl.md similarity index 97% rename from Posh-ACME/Plugins/All-Inkl-Readme.md rename to docs/Plugins/All-Inkl.md index 67bc81ef..ed00fec4 100644 --- a/Posh-ACME/Plugins/All-Inkl-Readme.md +++ b/docs/Plugins/All-Inkl.md @@ -1,3 +1,5 @@ +title: All-Inkl + # How To Use the All-Inkl KAS DNS Plugin This plugin works against the [All-Inkl](https://www.all-inkl.com/) KAS DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. @@ -20,4 +22,4 @@ $pArgs = @{ KasPwd = $pwd } New-PACertificate example.com -Plugin All-Inkl -PluginArgs $pArgs -``` \ No newline at end of file +``` diff --git a/Posh-ACME/Plugins/Aurora-Readme.md b/docs/Plugins/Aurora.md similarity index 98% rename from Posh-ACME/Plugins/Aurora-Readme.md rename to docs/Plugins/Aurora.md index 1e9d513b..44ddb50b 100644 --- a/Posh-ACME/Plugins/Aurora-Readme.md +++ b/docs/Plugins/Aurora.md @@ -1,3 +1,5 @@ +title: Aurora + # How To Use the Aurora DNS Plugin This plugin works against the [PCExtreme](https://pcextreme.nl/) provider, Aurora DNS. It is assumed that you already have an account and at least one Managed zone you will be working against. diff --git a/Posh-ACME/Plugins/AutoDNS-Readme.md b/docs/Plugins/AutoDNS.md similarity index 96% rename from Posh-ACME/Plugins/AutoDNS-Readme.md rename to docs/Plugins/AutoDNS.md index 8df4bd49..4df131cc 100644 --- a/Posh-ACME/Plugins/AutoDNS-Readme.md +++ b/docs/Plugins/AutoDNS.md @@ -1,3 +1,5 @@ +title: AutoDNS + # How To Use the AutoDNS DNS Plugin This plugin works against any DNS provider that utilizes the [AutoDNS](https://help.internetx.com/x/Qwfj) XML API from [InternetX](https://www.internetx.com/). [Schlundtech](https://www.schlundtech.de/) is an example of a registrar who uses this API. It is assumed that you have already setup an account and registered the domains or zones you will be working against. diff --git a/Posh-ACME/Plugins/Azure-Readme.md b/docs/Plugins/Azure.md similarity index 99% rename from Posh-ACME/Plugins/Azure-Readme.md rename to docs/Plugins/Azure.md index 4cb0087f..64a558c9 100644 --- a/Posh-ACME/Plugins/Azure-Readme.md +++ b/docs/Plugins/Azure.md @@ -1,3 +1,5 @@ +title: Azure + # How To Use the Azure DNS Plugin This plugin works against the [Azure DNS](https://azure.microsoft.com/en-us/services/dns/) provider. It is assumed that you already have an active subscription with at least one DNS zone, associated Resource Group, and an account with access to create roles and app registrations. The setup commands used in this guide will also make use of the [Az](https://www.powershellgallery.com/packages/Az/) module. But it is not required to use the plugin normally. diff --git a/Posh-ACME/Plugins/Beget-Readme.md b/docs/Plugins/Beget.md similarity index 76% rename from Posh-ACME/Plugins/Beget-Readme.md rename to docs/Plugins/Beget.md index 0eef8d55..6c4499e2 100644 --- a/Posh-ACME/Plugins/Beget-Readme.md +++ b/docs/Plugins/Beget.md @@ -1,3 +1,5 @@ +title: Beget + # How To Use the Beget DNS Plugin This plugin works against the [Beget.com](https://beget.com/) provider. It is assumed that you already have an account and at least one domain you will be working against. @@ -8,7 +10,7 @@ It is possible to use this plugin using the same credentials that are used to lo To do this, go to your [Beget API settings](https://cp.beget.com/settings/access/api) and select "Use separate password". After setting the password, uncheck all of the Permitted Methods except for "DNS management" and click the `Apply` button. -**IMPORTANT:** There are some limitations with how the Beget API works that make it risky to use when using [DNS Challenge Aliases](https://github.com/rmbolger/Posh-ACME/blob/main/Tutorial.md#advanced-dns-challenge-aliases). If you need to use this plugin with challenge aliases, the value for the DnsAlias must not contain any other record types or TXT values because they will likely be deleted when the plugin attempts to create the TXT records. +**IMPORTANT:** There are some limitations with how the Beget API works that make it risky to use when using [DNS Challenge Aliases](../Guides/Using-DNS-Challenge-Aliases.md). If you need to use this plugin with challenge aliases, the value for the DnsAlias must not contain any other record types or TXT values because they will likely be deleted when the plugin attempts to create the TXT records. ## Using the Plugin diff --git a/Posh-ACME/Plugins/BlueCat-Readme.md b/docs/Plugins/BlueCat.md similarity index 98% rename from Posh-ACME/Plugins/BlueCat-Readme.md rename to docs/Plugins/BlueCat.md index 35ab2222..4755c1c9 100644 --- a/Posh-ACME/Plugins/BlueCat-Readme.md +++ b/docs/Plugins/BlueCat.md @@ -1,3 +1,5 @@ +title: BlueCat + # How To Use the BlueCat DNS Plugin This plugin works against the [BlueCat Address Manager](https://www.bluecatnetworks.com/platform/management/bluecat-address-manager/) DNS provider. It is assumed that you have already have an account that is an "API User" and have created the DNS zone(s) you will be working against. This plugin has been tested against version 8.1.1. diff --git a/Posh-ACME/Plugins/ClouDNS-Readme.md b/docs/Plugins/ClouDNS.md similarity index 97% rename from Posh-ACME/Plugins/ClouDNS-Readme.md rename to docs/Plugins/ClouDNS.md index e7fd55c7..92d46b34 100644 --- a/Posh-ACME/Plugins/ClouDNS-Readme.md +++ b/docs/Plugins/ClouDNS.md @@ -1,3 +1,5 @@ +title: ClouDNS + # How To Use the ClouDNS DNS Plugin This plugin works against the [ClouDNS](https://www.cloudns.net/aff/id/224075/) provider. It is assumed that you have already setup an account and registered the domains or zones you will be working against. diff --git a/Posh-ACME/Plugins/Cloudflare-Readme.md b/docs/Plugins/Cloudflare.md similarity index 99% rename from Posh-ACME/Plugins/Cloudflare-Readme.md rename to docs/Plugins/Cloudflare.md index b27cb17e..952417e6 100644 --- a/Posh-ACME/Plugins/Cloudflare-Readme.md +++ b/docs/Plugins/Cloudflare.md @@ -1,3 +1,5 @@ +title: Cloudflare + # How To Use the Cloudflare DNS Plugin This plugin works against the [Cloudflare](https://www.cloudflare.com/dns) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/Constellix-Readme.md b/docs/Plugins/Constellix.md similarity index 98% rename from Posh-ACME/Plugins/Constellix-Readme.md rename to docs/Plugins/Constellix.md index d6aaba64..428f8ab7 100644 --- a/Posh-ACME/Plugins/Constellix-Readme.md +++ b/docs/Plugins/Constellix.md @@ -1,3 +1,5 @@ +title: Constellix + # How To Use the Constellix Plugin This plugin works against the [Constellix DNS](https://constellix.com/) provider. It is assumed that you already have an account and at least one managed zone already configured. diff --git a/Posh-ACME/Plugins/DMEasy-Readme.md b/docs/Plugins/DMEasy.md similarity index 98% rename from Posh-ACME/Plugins/DMEasy-Readme.md rename to docs/Plugins/DMEasy.md index f1f8070a..f84fb99f 100644 --- a/Posh-ACME/Plugins/DMEasy-Readme.md +++ b/docs/Plugins/DMEasy.md @@ -1,3 +1,5 @@ +title: DMEasy + # How To Use the DMEasy DNS Plugin This plugin works against the [DNS Made Easy](https://dnsmadeeasy.com/) provider. It is assumed that you already have an account and at least one Managed zone you will be working against. diff --git a/Posh-ACME/Plugins/DNSPod-Readme.md b/docs/Plugins/DNSPod.md similarity index 98% rename from Posh-ACME/Plugins/DNSPod-Readme.md rename to docs/Plugins/DNSPod.md index e6843b5e..258c1488 100644 --- a/Posh-ACME/Plugins/DNSPod-Readme.md +++ b/docs/Plugins/DNSPod.md @@ -1,3 +1,5 @@ +title: DNSPod + # How To Use the DNSPod DNS Plugin This plugin works against the [DNSPod](https://dnspod.com/) provider. It is assumed that you have already setup an account and created the domain you will be working against. diff --git a/Posh-ACME/Plugins/DNSimple-Readme.md b/docs/Plugins/DNSimple.md similarity index 96% rename from Posh-ACME/Plugins/DNSimple-Readme.md rename to docs/Plugins/DNSimple.md index 0b8310e9..e5faa563 100644 --- a/Posh-ACME/Plugins/DNSimple-Readme.md +++ b/docs/Plugins/DNSimple.md @@ -1,3 +1,5 @@ +title: DNSimple + # How To Use the DNSimple DNS Plugin This plugin works against the [DNSimple](https://dnsimple.com/r/c9b80a2f227e49) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/DOcean-Readme.md b/docs/Plugins/DOcean.md similarity index 98% rename from Posh-ACME/Plugins/DOcean-Readme.md rename to docs/Plugins/DOcean.md index 1c3657cf..bc53be1a 100644 --- a/Posh-ACME/Plugins/DOcean-Readme.md +++ b/docs/Plugins/DOcean.md @@ -1,3 +1,5 @@ +title: DOcean + # How To Use the DOcean DNS Plugin This plugin works against the [Digital Ocean](https://m.do.co/c/d515942ef761) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/DeSEC-Readme.md b/docs/Plugins/DeSEC.md similarity index 98% rename from Posh-ACME/Plugins/DeSEC-Readme.md rename to docs/Plugins/DeSEC.md index d7d63553..43595ec8 100644 --- a/Posh-ACME/Plugins/DeSEC-Readme.md +++ b/docs/Plugins/DeSEC.md @@ -1,3 +1,5 @@ +title: DeSEC + # How To Use the deSEC DNS Plugin This plugin works against the [deSEC](https://desec.io/#!/en/product/dnshosting) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/DomainOffensive-Readme.md b/docs/Plugins/DomainOffensive.md similarity index 97% rename from Posh-ACME/Plugins/DomainOffensive-Readme.md rename to docs/Plugins/DomainOffensive.md index c6c33a03..07c9f8e1 100644 --- a/Posh-ACME/Plugins/DomainOffensive-Readme.md +++ b/docs/Plugins/DomainOffensive.md @@ -1,3 +1,5 @@ +title: DomainOffensive + # How To Use the Domain Offensive DNS Plugin This plugin works against the [Domain Offensive](https://www.do.de/) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/Domeneshop-Readme.md b/docs/Plugins/Domeneshop.md similarity index 98% rename from Posh-ACME/Plugins/Domeneshop-Readme.md rename to docs/Plugins/Domeneshop.md index 211f9042..ac8ee555 100644 --- a/Posh-ACME/Plugins/Domeneshop-Readme.md +++ b/docs/Plugins/Domeneshop.md @@ -1,3 +1,5 @@ +title: Domeneshop + # How To Use the Domeneshop DNS Plugin This plugin works against the [Domeneshop](https://domene.shop/) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/Dreamhost-Readme.md b/docs/Plugins/Dreamhost.md similarity index 98% rename from Posh-ACME/Plugins/Dreamhost-Readme.md rename to docs/Plugins/Dreamhost.md index 72bb6272..0d001f53 100644 --- a/Posh-ACME/Plugins/Dreamhost-Readme.md +++ b/docs/Plugins/Dreamhost.md @@ -1,3 +1,5 @@ +title: Dreamhost + # How To Use the Dreamhost DNS Plugin This plugin works against the [Dreamhost](https://www.dreamhost.com/) API. It is assumed that you already have web hosting through Dreamhost and are using Dreamhost to manage DNS for your domain(s). diff --git a/Posh-ACME/Plugins/DuckDNS-Readme.md b/docs/Plugins/DuckDNS.md similarity index 99% rename from Posh-ACME/Plugins/DuckDNS-Readme.md rename to docs/Plugins/DuckDNS.md index 19c98fd4..fec63f92 100644 --- a/Posh-ACME/Plugins/DuckDNS-Readme.md +++ b/docs/Plugins/DuckDNS.md @@ -1,3 +1,5 @@ +title: DuckDNS + # How To Use the DuckDNS Plugin This plugin works against the [Duck DNS](https://www.duckdns.org/) provider. It is assumed that you have already setup an account and created the domain(s) you will be working against. diff --git a/Posh-ACME/Plugins/Dynu-Readme.md b/docs/Plugins/Dynu.md similarity index 99% rename from Posh-ACME/Plugins/Dynu-Readme.md rename to docs/Plugins/Dynu.md index ae1651e4..e178d73c 100644 --- a/Posh-ACME/Plugins/Dynu-Readme.md +++ b/docs/Plugins/Dynu.md @@ -1,3 +1,5 @@ +title: Dynu + # How To Use the Dynu DNS Plugin This plugin works against the [Dynu](https://www.dynu.com) DNS provider. It is assumed that you have already setup an account configured at least one DDNS domain to work against. diff --git a/Posh-ACME/Plugins/EasyDNS-Readme.md b/docs/Plugins/EasyDNS.md similarity index 97% rename from Posh-ACME/Plugins/EasyDNS-Readme.md rename to docs/Plugins/EasyDNS.md index 76461286..913747a9 100644 --- a/Posh-ACME/Plugins/EasyDNS-Readme.md +++ b/docs/Plugins/EasyDNS.md @@ -1,3 +1,5 @@ +title: EasyDNS + # How To Use the EasyDNS Plugin This plugin works against the [EasyDNS](https://www.easydns.com) provider. It is assumed that you have already setup an account with a domain registered. diff --git a/Posh-ACME/Plugins/Easyname-Readme.md b/docs/Plugins/Easyname.md similarity index 96% rename from Posh-ACME/Plugins/Easyname-Readme.md rename to docs/Plugins/Easyname.md index 30be1208..35c774db 100644 --- a/Posh-ACME/Plugins/Easyname-Readme.md +++ b/docs/Plugins/Easyname.md @@ -1,3 +1,5 @@ +title: Easyname + # How To Use the Easyname Plugin This plugin works against the [Easyname](https://www.easyname.com) hosting provider. It is assumed that you have already setup an account and have at least one domain registered. diff --git a/Posh-ACME/Plugins/FreeDNS-Readme.md b/docs/Plugins/FreeDNS.md similarity index 87% rename from Posh-ACME/Plugins/FreeDNS-Readme.md rename to docs/Plugins/FreeDNS.md index 62460f93..a7ffa9e6 100644 --- a/Posh-ACME/Plugins/FreeDNS-Readme.md +++ b/docs/Plugins/FreeDNS.md @@ -1,3 +1,5 @@ +title: FreeDNS + # How To Use the FreeDNS Plugin This plugin works against [Free DNS](https://freedns.afraid.org/). It is assumed that you have an existing account. Free and [Premium](https://freedns.afraid.org/premium/) accounts are both supported, but there are limitations on Free accounts unless the domain you're using is actually owned by you. There are also limitations on Premium accounts if you do not own the domain you're using. @@ -16,7 +18,7 @@ Solving a CAPTCHA is required in order to create any records on domains you don' Regardless of your account status, Free DNS does not currently allow you to create records beginning with an underscore (`_`) unless you own the underlying domain you're creating the records on. Because Let's Encrypt DNS challenges require creating a TXT record that starts with `_acme-challenge`, you will be unable to generate a certificate for a Free DNS hosted domain unless you own it. -The only thing you can use a non-owned domain for are [challenge aliases](https://github.com/rmbolger/Posh-ACME/blob/main/Tutorial.md#advanced-dns-challenge-aliases). But due to the CAPTCHA limitation on Free accounts, only Premium accounts can do this. If using challenge aliases, make sure your CNAME points to a record that does *not* start with `_`. +The only thing you can use a non-owned domain for are [challenge aliases](../Guides/Using-DNS-Challenge-Aliases.md). But due to the CAPTCHA limitation on Free accounts, only Premium accounts can do this. If using challenge aliases, make sure your CNAME points to a record that does *not* start with `_`. ## Using the Plugin diff --git a/Posh-ACME/Plugins/GCloud-Readme.md b/docs/Plugins/GCloud.md similarity index 99% rename from Posh-ACME/Plugins/GCloud-Readme.md rename to docs/Plugins/GCloud.md index 141485ef..25045573 100644 --- a/Posh-ACME/Plugins/GCloud-Readme.md +++ b/docs/Plugins/GCloud.md @@ -1,3 +1,5 @@ +title: GCloud + # How To Use the GCloud DNS Plugin This plugin works against the [Google Cloud DNS](https://cloud.google.com/dns) provider. It is assumed that you have already setup a project, billing, and created the DNS zone(s) you will be working against. If not, check the [Cloud DNS Quickstart](https://cloud.google.com/dns/quickstart). diff --git a/Posh-ACME/Plugins/Gandi-Readme.md b/docs/Plugins/Gandi.md similarity index 96% rename from Posh-ACME/Plugins/Gandi-Readme.md rename to docs/Plugins/Gandi.md index 2ac19f59..fdc82f5d 100644 --- a/Posh-ACME/Plugins/Gandi-Readme.md +++ b/docs/Plugins/Gandi.md @@ -1,3 +1,5 @@ +title: Gandi + # How To Use the Gandi DNS Plugin This plugin works against the [Gandi](https://www.gandi.net) DNS provider. It is assumed that you have already setup an account and have a registered domain with an associated DNS zone you will be working against. diff --git a/Posh-ACME/Plugins/GoDaddy-Readme.md b/docs/Plugins/GoDaddy.md similarity index 98% rename from Posh-ACME/Plugins/GoDaddy-Readme.md rename to docs/Plugins/GoDaddy.md index 968eb5f7..36f2b9ed 100644 --- a/Posh-ACME/Plugins/GoDaddy-Readme.md +++ b/docs/Plugins/GoDaddy.md @@ -1,3 +1,5 @@ +title: GoDaddy + # How To Use the GoDaddy DNS Plugin This plugin works against the [GoDaddy DNS](https://www.godaddy.com) provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/Hetzner-Readme.md b/docs/Plugins/Hetzner.md similarity index 96% rename from Posh-ACME/Plugins/Hetzner-Readme.md rename to docs/Plugins/Hetzner.md index 3c402650..c2f4454b 100644 --- a/Posh-ACME/Plugins/Hetzner-Readme.md +++ b/docs/Plugins/Hetzner.md @@ -1,3 +1,5 @@ +title: Hetzner + # How To Use the Hetzner DNS Plugin This plugin works against the [Hetzner](https://www.hetzner.de/) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/HostingDe-Readme.md b/docs/Plugins/HostingDe.md similarity index 95% rename from Posh-ACME/Plugins/HostingDe-Readme.md rename to docs/Plugins/HostingDe.md index 47fc9692..a718f252 100644 --- a/Posh-ACME/Plugins/HostingDe-Readme.md +++ b/docs/Plugins/HostingDe.md @@ -1,3 +1,5 @@ +title: HostingDe + # How To Use the HostingDe Plugin This plugin works against the [Hosting.de](https://hosting.de/) provider. It is assumed that you already have an account and at least one managed zone already configured. diff --git a/Posh-ACME/Plugins/HurricaneElectric-Readme.md b/docs/Plugins/HurricaneElectric.md similarity index 96% rename from Posh-ACME/Plugins/HurricaneElectric-Readme.md rename to docs/Plugins/HurricaneElectric.md index 9ebe81e0..a9733b81 100644 --- a/Posh-ACME/Plugins/HurricaneElectric-Readme.md +++ b/docs/Plugins/HurricaneElectric.md @@ -1,3 +1,5 @@ +title: HurricaneElectric + # How To Use the HurricaneElectric Plugin This plugin works against [Hurricane Electric DNS](https://dns.he.net/). It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/IBMSoftLayer-Readme.md b/docs/Plugins/IBMSoftLayer.md similarity index 96% rename from Posh-ACME/Plugins/IBMSoftLayer-Readme.md rename to docs/Plugins/IBMSoftLayer.md index ad13d081..05e0d88a 100644 --- a/Posh-ACME/Plugins/IBMSoftLayer-Readme.md +++ b/docs/Plugins/IBMSoftLayer.md @@ -1,3 +1,5 @@ +title: IBMSoftLayer + # How To Use the IBMSoftlayer DNS Plugin This plugin works against the [IBM Cloud](https://www.ibm.com/cloud/dns) DNS provider (formerly known as SoftLayer). It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/Infoblox-Readme.md b/docs/Plugins/Infoblox.md similarity index 96% rename from Posh-ACME/Plugins/Infoblox-Readme.md rename to docs/Plugins/Infoblox.md index f9f4cced..5194f4fd 100644 --- a/Posh-ACME/Plugins/Infoblox-Readme.md +++ b/docs/Plugins/Infoblox.md @@ -1,3 +1,5 @@ +title: Infoblox + # How To Use the Infoblox DNS Plugin This plugin works against [Infoblox DDI](https://www.infoblox.com/products/ddi/). It is assumed that you have a set of credentials and permissions to modify TXT records for the zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/Infomaniak-Readme.md b/docs/Plugins/Infomaniak.md similarity index 98% rename from Posh-ACME/Plugins/Infomaniak-Readme.md rename to docs/Plugins/Infomaniak.md index 0cd3d6e9..39d854cd 100644 --- a/Posh-ACME/Plugins/Infomaniak-Readme.md +++ b/docs/Plugins/Infomaniak.md @@ -1,3 +1,5 @@ +title: Infomaniak + # How To Use the Infomaniak DNS Plugin This plugin works against the [Infomaniak](https://www.infomaniak.com) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/Linode-Readme.md b/docs/Plugins/Linode.md similarity index 97% rename from Posh-ACME/Plugins/Linode-Readme.md rename to docs/Plugins/Linode.md index 0c93f472..fadd8cbd 100644 --- a/Posh-ACME/Plugins/Linode-Readme.md +++ b/docs/Plugins/Linode.md @@ -1,3 +1,5 @@ +title: Linode + # How To Use the Linode DNS Plugin This plugin works against the [Linode](https://www.linode.com/?r=4dfd67cf6f1e384ce626f2943620186344bb2ccf) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/Loopia-Readme.md b/docs/Plugins/Loopia.md similarity index 99% rename from Posh-ACME/Plugins/Loopia-Readme.md rename to docs/Plugins/Loopia.md index b611c3ea..27395888 100644 --- a/Posh-ACME/Plugins/Loopia-Readme.md +++ b/docs/Plugins/Loopia.md @@ -1,3 +1,5 @@ +title: Loopia + # How to use the Loopia Plugin This plugin works against the [Loopia](https://www.loopia.com/loopiadns/) DNS provider. It presumes diff --git a/Posh-ACME/Plugins/LuaDns-Readme.md b/docs/Plugins/LuaDns.md similarity index 95% rename from Posh-ACME/Plugins/LuaDns-Readme.md rename to docs/Plugins/LuaDns.md index 7b5a4e39..f758d291 100644 --- a/Posh-ACME/Plugins/LuaDns-Readme.md +++ b/docs/Plugins/LuaDns.md @@ -1,3 +1,5 @@ +title: LuaDns + # How To Use the LuaDns DNS Plugin This plugin works against the [LuaDns](https://www.luadns.com/) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/NS1-Readme.md b/docs/Plugins/NS1.md similarity index 96% rename from Posh-ACME/Plugins/NS1-Readme.md rename to docs/Plugins/NS1.md index f2b2bf19..ab4b63c6 100644 --- a/Posh-ACME/Plugins/NS1-Readme.md +++ b/docs/Plugins/NS1.md @@ -1,3 +1,5 @@ +title: NS1 + # How To Use the NS1 DNS Plugin This plugin works against the [NS1](https://ns1.com) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/NameCom-Readme.md b/docs/Plugins/NameCom.md similarity index 96% rename from Posh-ACME/Plugins/NameCom-Readme.md rename to docs/Plugins/NameCom.md index ac903ea3..295bdea2 100644 --- a/Posh-ACME/Plugins/NameCom-Readme.md +++ b/docs/Plugins/NameCom.md @@ -1,3 +1,5 @@ +title: NameCom + # How To Use the NameCom DNS Plugin This plugin works against the [name.com](https://www.name.com/) domain registrar and DNS provider. It is assumed that you have already setup an account and purchased domain you will be working against. You must also be using name.com's own DNS hosting. diff --git a/Posh-ACME/Plugins/NameSilo-Readme.md b/docs/Plugins/NameSilo.md similarity index 98% rename from Posh-ACME/Plugins/NameSilo-Readme.md rename to docs/Plugins/NameSilo.md index 3316226e..e25a6f20 100644 --- a/Posh-ACME/Plugins/NameSilo-Readme.md +++ b/docs/Plugins/NameSilo.md @@ -1,3 +1,5 @@ +title: NameSilo + # How To Use the NameSilo DNS Plugin This plugin works against the [NameSilo](https://www.namesilo.com) domain registrar. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/Namecheap-Readme.md b/docs/Plugins/Namecheap.md similarity index 97% rename from Posh-ACME/Plugins/Namecheap-Readme.md rename to docs/Plugins/Namecheap.md index f3b25827..a77b1c6b 100644 --- a/Posh-ACME/Plugins/Namecheap-Readme.md +++ b/docs/Plugins/Namecheap.md @@ -1,3 +1,5 @@ +title: Namecheap + # How To Use the Namecheap DNS Plugin This plugin works against the [Namecheap FreeDNS](https://www.namecheap.com/domains/freedns/) provider. It is assumed that you have already setup an account and registered the domains you will be working against. The domains must not be using custom DNS servers. diff --git a/Posh-ACME/Plugins/OVH-Readme.md b/docs/Plugins/OVH.md similarity index 98% rename from Posh-ACME/Plugins/OVH-Readme.md rename to docs/Plugins/OVH.md index 95719598..c9697466 100644 --- a/Posh-ACME/Plugins/OVH-Readme.md +++ b/docs/Plugins/OVH.md @@ -1,3 +1,5 @@ +title: OVH + # How To Use the OVH DNS Plugin This plugin works against the [OVH](https://www.ovh.com) DNS provider. It is assumed that you have already setup an account and created the domain(s) you will be working against. diff --git a/docs/Plugins/Plugin-Development-Guide.md b/docs/Plugins/Plugin-Development-Guide.md new file mode 100644 index 00000000..50e067ad --- /dev/null +++ b/docs/Plugins/Plugin-Development-Guide.md @@ -0,0 +1,210 @@ +# Plugin Development Guide + +## Introduction + +A validation plugin for Posh-ACME is a standard PowerShell PS1 script file located in the module's `Plugins` folder. It can also be in a folder outside the module and referenced using the `POSHACME_PLUGINS` environment variable. The file name is what users will use to reference it when specifying a plugin, so it should be related to the provider it is publishing against. + +All plugins must contain a function called `Get-CurrentPluginType` which returns a string indicating the type of ACME challenge they support. Posh-ACME currently supports the `dns-01` and `http-01` challenge types. + +DNS plugins must contain the following additional functions: + +- `Add-DnsTxt` +- `Remove-DnsTxt` +- `Save-DnsTxt` + +HTTP plugins must contain the following additional functions: + +- `Add-HttpChallenge` +- `Remove-HttpChallenge` +- `Save-HttpChallenge` + +The easiest way to get started is to make a copy of `_Example-DNS.ps1` or `_Example-HTTP.ps1` depending on the type of plugin you are making and rename it for your purposes. + +**Pull Requests for new plugins are quite welcome.** + + +## Function Details + +### `Add-DnsTxt` and `Remove-DnsTxt` + +These are responsible for adding/removing TXT records to/from a DNS server/provider. There are two mandatory and positional string parameters, `$RecordName` and `$TxtValue`. RecordName is the fully qualified domain name (FQDN) of the record we will be adding a TXT value for. TxtValue is the actual value that will be set in the TXT record. Do not modify or remove these first +two parameters. + +Additional parameters should be added as necessary for the specific DNS provider such as credentials or API keys. In addition to standard PowerShell naming standards, their names must also not conflict with any other plugin's parameters. A good way to do that is to use a unique prefix on all of the parameters. It doesn't have to match the plugin name exactly as long as it's unique and reasonably related to the plugin. Common parameters that can be shared between this plugin's functions should be named the same as each other. + +The last parameter should always be `$ExtraParams` with the `ValueFromRemainingArguments` parameter attribute. This allows callers to [splat](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting?view=powershell-5.1) the combined collection of plugin parameters to each plugin without errors for parameters that don't exist. + +Many DNS providers will only need the Add and Remove functions. In those cases, remember to remove all but the `$ExtraParams` parameter in the Save function and just leave the function body empty. For other providers, it is may be more efficient to stage changes in bulk and then perform what is effectively a Save or Commit operation on those changes. In those cases, implement the Save function as described below. + +### `Add-HttpChallenge` and `Remove-HttpChallenge` + +These are responsible for publishing/unpublishing the ACME challenge body text at a specific HTTP URL. There are three mandatory and positional string parameters, `$Domain`, `$Token`, and `$Body`. Domain and Token are what the validation server will use to build the URL it will check against (`http:///.well-known/acme-challenge/`). Body is the text value it expects to get in response to that query. Do not modify or remove these first three parameters. + +Additional parameters should be added as necessary for the specific HTTP provider such as filesystem paths, credentials, or API keys. In addition to standard PowerShell naming standards, their names must also not conflict with any other plugin's parameters. A good way to do that is to use a unique prefix on all of the parameters. It doesn't have to match the plugin name exactly as long as it's unique and reasonably related to the plugin. Common parameters that can be shared between this plugin's functions should be named the same as each other. + +The last parameter should always be `$ExtraParams` with the `ValueFromRemainingArguments` parameter attribute. This allows callers to [splat](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting?view=powershell-5.1) the combined collection of plugin parameters to each plugin without errors for parameters that +don't exist. + +Many HTTP providers will only need the Add and Remove functions. In those cases, remember to remove all but the `$ExtraParams` parameter in the Save function and just leave the function body empty. For other providers, it is may be more efficient to stage changes in bulk and then perform what is effectively a Save or Commit operation on those changes. In those cases, implement the Save function as described below. + +### `Save-DnsTxt` and `Save-HttpChallenge` + +These functions are optional for DNS/HTTP plugins where it is more efficient to stage changes in bulk before Saving or Committing the changes. There are no required parameters except `$ExtraParams` which should always be last and have the `ValueFromRemainingArguments` parameter attribute. + +### Parameter Types + +Try to limit parameters to simple data types like `[string]`, `[int]`, and `[switch]`. Arrays and Hashtables are fine as long as the contents are also simple types. Hashtables in particular should not be nested. The parameters should be able to convert nicely back and forth using `Convert-ToJson` and `Convert-FromJson`. + +Secrets such as passwords and API keys/tokens should use `[SecureString]` or `[PSCredential]` parameters even if you ultimately need them in plain text within the plugin. This ensures the values are encrypted when saved to disk for later renewals. Here are some examples for how to convert them back to plain text in the plugin code. + +```powershell +# get the username and password from a PSCredential called $cred +$username = $cred.Username +$password = $cred.GetNetworkCredential().Password + +# get the plain text from a SecureString called $secString +$plainText = [pscredential]::new('a',$secString).GetNetworkCredential().Password +``` + +## Usage Guides + +In addition to the native function help, it can be very helpful to new users to have a plugin specific readme. It should be a [Markdown](https://www.markdowntutorial.com/) formatted file in the [docs/Plugins](https://github.com/rmbolger/Posh-ACME/tree/main/docs/Plugins) folder called `.md`. It's usually easiest to copy an existing guide and modify it. + +For people who may be setting up automation against their provider for the first time, it can be helpful to add guidance on creating service accounts, limited access roles, or any prerequisite setup that the plugin requires to work properly. It should also have a section with an example on how to use the plugin with `New-PACertificate`. + + +## General Development Tips and Tricks + +### No Write-Host + +Unless your plugin requires interactive user input which should be rare, do not use `Write-Host` to display informational messages or debug output. Use `Write-Verbose` for messages you would want a potential user to see. Use `Write-Debug` for things only the plugin developer would likely care about or a user trying to troubleshoot a plugin that is not working. + +When testing your module, use `-Verbose` to see your verbose messages. And run `$DebugPreference = 'Continue'` to make the debug messages show up without prompting for confirmation *(which happens if you use `-Debug`)*. + +### No Pipeline Output + +Do not output any objects to the pipeline from your plugin. This will interfere with scripts and workflows that use the normal output of public functions. You can use `Out-Null` on internal calls that would normally output to the pipeline when you don't care about that data. + +### UseBasicParsing + +Any time you call `Invoke-WebRequest` or `Invoke-RestMethod`, you should always add `@script:UseBasic` to the end. + +By default in PowerShell 5.1, those two functions use Internet Explorer's DOM parser to process the response body which can cause errors in cases where IE is not installed or hasn't gone through its first-run sequence yet. Both functions have a `-UseBasicParsing` parameter that switches the parser to a PowerShell native parser and is the new default functionality in PowerShell 6+. The parameter is also deprecated because they don't plan on bringing back IE DOM parsing in future PowerShell versions. So the module creates a variable when it is first loaded that checks whether `-UseBasicParsing` is still available or not and adds it to the `$script:UseBasic` hashtable. That way, you can just [splat](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting) it on all your calls to those two functions which will future proof your plugin. + +### Testing Plugins + +If the module is already loaded in the session, you will need to re-import it using `Import-Module -Force`. There is a helper script called `instdev.ps1` in the root of the git repository that can make this process a lot easier as you are developing the plugin. + +First make sure any existing copies of the module are uninstalled (or at least don't reside in your `$env:PSModulePath`). Clone the git repository (or your fork) to a folder on your local system and add your plugin file to the `Posh-Acme\Plugins` folder if it's not already there. Open a new PowerShell session to the repository root folder and run `.\instdev.ps1` which will do the following: + +- Copy the module files to the current user's default PowerShell modules folder. +- Run `Import-Module Posh-ACME -Force` +- Display the available module commands + +If there are no problems, your plugin should now be listed in the output of `Get-PAPlugin`. + +Testing a plugin can be done without requesting a new certificate. All you need is an existing ACME account created with `New-PAAccount` and the `Publish-Challenge`, `Unpublish-Challenge`, and `Save-Challenge` functions. They call the Add, Remove, and Save functions from the plugin. Here are some examples of how I generally call them while testing. + +```powershell +$DebugPreference = 'Continue' +$pArgs = @{MyParam1='asdf';MyParam2='qwer'} + +# multiple calls to publish/unpublish are generally more useful for DNS plugins +Publish-Challenge example.com (Get-PAAccount) test1 MyPlugin $pArgs -Verbose +Publish-Challenge example.com (Get-PAAccount) test2 MyPlugin $pArgs -Verbose +Publish-Challenge example.com (Get-PAAccount) test3 MyPlugin $pArgs -Verbose + +# save is only necessary if your plugin implements it +Save-Challenge MyPlugin $pArgs -Verbose + +Unpublish-Challenge example.com (Get-PAAccount) test1 MyPlugin $pArgs -Verbose +Unpublish-Challenge example.com (Get-PAAccount) test2 MyPlugin $pArgs -Verbose +Unpublish-Challenge example.com (Get-PAAccount) test3 MyPlugin $pArgs -Verbose + +# save is only necessary if your plugin implements it +Save-Challenge MyPlugin $pArgs -Verbose +``` + +Alternatively, you can [dot source](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_scripts?view=powershell-5.1#script-scope-and-dot-sourcing) the plugin file and call the functions directly. But this can be difficult if the functions depend on module-scoped variables like `$script:UseBasic` or internal module functions. Also, remember to dot source again each time you make a change to the plugin. + +## DNS Specific Tips and Tricks + +### Multiple TXT Values Per Record + +It is both supported and expected that a given TXT record may have multiple values. It's most common with wildcard certificates that contain both the wildcard name (`*.example.com`) and the root domain (`example.com`). Both names require TXT records be added for the same FQDN (`_acme-challenge.example.com`). This can also happen if the user is using CNAME challenge aliases. + +The Add/Remove functions need to support all potential states of the particular TXT record. But how the record is represented by a given provider seems to vary. Some represent it as a single record with multiple values that you need to add to or remove from. Others have distinct records for each value that can be created/deleted individually. So make sure you can both create a new record that doesn't exist *and* add a value to a record that already does. + +### Remove Only Specific TxtValue + +Related to having multiple TXT values per record, the remove function must not blindly delete any record that matches `$RecordName`. It should be able to remove only the `$TxtValue` on a record that may have multiple values. But if the record only contains a single value, the record should be deleted entirely. + +### Zone Matching + +A particular DNS provider may be hosting both domain apex zones (`example.com`) and sub-zones (`sub1.example.com`). One of the first things a plugin usually has to do is figure out which zone `$RecordName` needs to be added to. This should be the deepest sub-zone that would still contain `$RecordName`. Here are some examples assuming only the two previously mentioned zones exist. + +`$RecordName` | Matching Zone +------------- | ------------- +_acme-challenge.example.com | example.com +_acme-challenge.site1.example.com | example.com +_acme-challenge.sub1.example.com | sub1.example.com +_acme-challenge.site1.sub1.example.com | sub1.example.com +_acme-challenge.site1.sub3.sub2.sub1.example.com | sub1.example.com + +Many of the existing plugins have a helper function to handle this. Copy and modify their code where it makes sense but make sure helper function names are unique. + +### DNS Aliases and Domain Apex + +Don't forget to test your functions against the domain apex which can happen when users are using DNS challenge aliases. There's often a special way to represent records in the domain apex from an API perspective, commonly with the `@` character or an empty string instead of a record short name. + +```powershell +# The my.cname.tld record doesn't actually need to exist for the test to work. +# The plugin will only be writing to example.com +Publish-Challenge my.cname.tld (Get-PAAccount) test1 MyPlugin $pArgs -DnsAlias example.com -Verbose +Unpublish-Challenge my.cname.tld (Get-PAAccount) test1 MyPlugin $pArgs -DnsAlias example.com -Verbose +``` + +### Deriving Object IDs + +Many providers assign ID values to object types like zones and records that you need to use to manipulate those objects. A user should ideally not have to know or provide any zone, record, or object IDs in order to use the plugin. All of that should be discovered by the plugin code and the only thing the user should need to provide is whatever credentials or tokens the API requires for authentication. + +In the rare cases that you do need the user to provide something like a zone ID, make sure you allow for multiple values. A single certificate can contain names from many different zones and the plugin parameters that get passed to the plugin are the same for each TXT record that needs to be created. + +### Trailing Dots + +Be aware how your particular DNS provider represents zone and record names. Some include the trailing dot (`example.com.`). Others don't. This can affect string matching when finding zones and existing records. + +### Internationalized Domain Name (IDN) + +Many DNS providers and registrars support [IDN domains](https://en.wikipedia.org/wiki/Internationalized_domain_name) which contain non-ascii unicode characters (or even emojis). When using IDN domains with ACME, the IDN names must be specified as [Punycode](https://en.wikipedia.org/wiki/Punycode). But the DNS providers may still send or receive the unicode version of the name. Particularly if your provider is not US-based, be aware of and try to account for how the provider handles IDN names. + +The .NET [System.Globalization.IdnMapping](https://docs.microsoft.com/en-us/dotnet/api/system.globalization.idnmapping) class can help convert back and for between IDN and punycode names like this: + +```powershell +# create an instance of the class +$idn = [System.Globalization.IdnMapping]::new() + +# convert an IDN name to punycode +$idn.GetAscii('bücher.example') + +# convert a punycode name back to IDN +$idn.GetUnicode('xn--bcher-kva.example') +``` + +## HTTP Specific Tips and Tricks + +### Validation Timing + +When DNS plugins are used, there's a user customizable sleep timer between when the TXT records are published and the module asks the ACME server to validate those records because records are not typically available instantaneously worldwide. However, that sleep timer does not exist when an order is only using HTTP plugins because HTTP resources are typically available instantly. + +If your particular HTTP provider requires a delay between when the challenges are published and when they are validated, you should add that delay in the `Save-HttpChallenge` function of your plugin. + +## Migrating DNS Plugins from 3.x to 4.x + +In case you have been using your own private DNS plugin in 3.x, here's how to migrate it to the 4.x format. + +* Add `function Get-CurrentPluginType { 'dns-01' }` to the top of the file. +* Replace instances of `Add-DnsTxt` with `Add-DnsTxt` +* Replace instances of `Remove-DnsTxt` with `Remove-DnsTxt` +* Replace instances of `Save-DnsTxt` with `Save-DnsTxt` +* Replace instances of `-DnsPlugin` with `-Plugin` in usage guides. diff --git a/Posh-ACME/Plugins/PointDNS-Readme.md b/docs/Plugins/PointDNS.md similarity index 98% rename from Posh-ACME/Plugins/PointDNS-Readme.md rename to docs/Plugins/PointDNS.md index 5c7d861c..8506d16b 100644 --- a/Posh-ACME/Plugins/PointDNS-Readme.md +++ b/docs/Plugins/PointDNS.md @@ -1,3 +1,5 @@ +title: PointDNS + # How to use the PointDNS Plugin This plugin works against the [PointDNS](https://pointhq.com) DNS provider. It presumes diff --git a/Posh-ACME/Plugins/RFC2136-Readme.md b/docs/Plugins/RFC2136.md similarity index 99% rename from Posh-ACME/Plugins/RFC2136-Readme.md rename to docs/Plugins/RFC2136.md index 8ea866a5..1792268d 100644 --- a/Posh-ACME/Plugins/RFC2136-Readme.md +++ b/docs/Plugins/RFC2136.md @@ -1,3 +1,5 @@ +title: RFC2136 + # How to use the RFC2136 Plugin This plugin works against any DNS provider that supports dynamic updates using the protocol specified in [RFC 2136](https://tools.ietf.org/html/rfc2136). Both unauthenticated and TSIG authenticated updates are supported. diff --git a/Posh-ACME/Plugins/Rackspace-Readme.md b/docs/Plugins/Rackspace.md similarity index 95% rename from Posh-ACME/Plugins/Rackspace-Readme.md rename to docs/Plugins/Rackspace.md index 846eab9f..226908a4 100644 --- a/Posh-ACME/Plugins/Rackspace-Readme.md +++ b/docs/Plugins/Rackspace.md @@ -1,3 +1,5 @@ +title: Rackspace + # How To Use the Rackspace DNS Plugin This plugin works against the [Rackspace Cloud DNS](https://www.rackspace.com/cloud/dns) provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/Regru-Readme.md b/docs/Plugins/Regru.md similarity index 99% rename from Posh-ACME/Plugins/Regru-Readme.md rename to docs/Plugins/Regru.md index ebfe4f8d..8c3aa520 100644 --- a/Posh-ACME/Plugins/Regru-Readme.md +++ b/docs/Plugins/Regru.md @@ -1,3 +1,5 @@ +title: Regru + # How To Use the Reg.ru Plugin This plugin works against the [Reg.ru](https://reg.ru) and [Reg.com](https://reg.com) provider. diff --git a/Posh-ACME/Plugins/Route53-Readme.md b/docs/Plugins/Route53.md similarity index 99% rename from Posh-ACME/Plugins/Route53-Readme.md rename to docs/Plugins/Route53.md index 44f38f0c..bf7c41bf 100644 --- a/Posh-ACME/Plugins/Route53-Readme.md +++ b/docs/Plugins/Route53.md @@ -1,3 +1,5 @@ +title: Route53 + # How To Use the Route53 DNS Plugin This plugin works against the [AWS Route53](https://aws.amazon.com/route53/) DNS provider. It is assumed that you already have an AWS account with at least one DNS zone. The setup portion of this guide also assumes you have access to create IAM users/roles. If you have been given access credentials by your AWS admin, you may need the admin to create the IAM policies necessary for you to edit the zone TXT records. diff --git a/Posh-ACME/Plugins/Selectel-Readme.md b/docs/Plugins/Selectel.md similarity index 98% rename from Posh-ACME/Plugins/Selectel-Readme.md rename to docs/Plugins/Selectel.md index b569174f..fedcfa3d 100644 --- a/Posh-ACME/Plugins/Selectel-Readme.md +++ b/docs/Plugins/Selectel.md @@ -1,3 +1,5 @@ +title: Selectel + # How To Use the Selectel DNS Plugin This plugin works against the [Selectel](https://selectel.ru/) provider. It is assumed that you have already setup an account and delegated the domain you will be working against. diff --git a/Posh-ACME/Plugins/SimpleDNSPlus-Readme.md b/docs/Plugins/SimpleDNSPlus.md similarity index 99% rename from Posh-ACME/Plugins/SimpleDNSPlus-Readme.md rename to docs/Plugins/SimpleDNSPlus.md index 48fa8d1f..a511a891 100644 --- a/Posh-ACME/Plugins/SimpleDNSPlus-Readme.md +++ b/docs/Plugins/SimpleDNSPlus.md @@ -1,3 +1,5 @@ +title: SimpleDNSPlus + # How To Use the Simple DNS Plus Plugin This plugin works with [Simple DNS Plus](https://simpledns.com/) which is a self-hosted DNS server for Windows. It is assumed you have already setup your server(s) and are properly serving the necessary Internet facing DNS zones for the certificates you will request. diff --git a/Posh-ACME/Plugins/Simply-Readme.md b/docs/Plugins/Simply.md similarity index 98% rename from Posh-ACME/Plugins/Simply-Readme.md rename to docs/Plugins/Simply.md index 1457adb9..7ba2af0c 100644 --- a/Posh-ACME/Plugins/Simply-Readme.md +++ b/docs/Plugins/Simply.md @@ -1,3 +1,5 @@ +title: Simply + # How To Use the Simply.com DNS Plugin This plugin works against the [Simply.com](https://www.simply.com/) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/UKFast-Readme.md b/docs/Plugins/UKFast.md similarity index 98% rename from Posh-ACME/Plugins/UKFast-Readme.md rename to docs/Plugins/UKFast.md index ebef0095..7209e331 100644 --- a/Posh-ACME/Plugins/UKFast-Readme.md +++ b/docs/Plugins/UKFast.md @@ -1,3 +1,5 @@ +title: UKFast + # How To Use the UKFast SafeDNS Plugin This plugin works against the [UKFast](https://ukfast.co.uk/) provider. It is assumed that you have already setup an account and created the zone in SafeDNS you will be working against. diff --git a/Posh-ACME/Plugins/WebRoot-Readme.md b/docs/Plugins/WebRoot.md similarity index 97% rename from Posh-ACME/Plugins/WebRoot-Readme.md rename to docs/Plugins/WebRoot.md index 45907ec4..3ab87e6a 100644 --- a/Posh-ACME/Plugins/WebRoot-Readme.md +++ b/docs/Plugins/WebRoot.md @@ -1,3 +1,5 @@ +title: WebRoot + # How To Use the WebRoot Plugin This is an HTTP challenge plugin that works by writing challenge files to the local filesystem or a network share. It is generally used when you have an existing web server hosting the content for your domain and you would prefer not to stop it during the certificate issuance process. diff --git a/Posh-ACME/Plugins/WebSelfHost-Readme.md b/docs/Plugins/WebSelfHost.md similarity index 97% rename from Posh-ACME/Plugins/WebSelfHost-Readme.md rename to docs/Plugins/WebSelfHost.md index bb5b7f58..6ff1a206 100644 --- a/Posh-ACME/Plugins/WebSelfHost-Readme.md +++ b/docs/Plugins/WebSelfHost.md @@ -1,3 +1,5 @@ +title: WebSelfHost + # How To Use the WebSelfHost Plugin This is an HTTP challenge plugin that works by temporarily running an HTTP listener to directly respond to challenge requests from the ACME server. It is commonly used when your certificate will not be used with an existing web server or the server is not listening on port 80. It can also be used with an existing web server if you are willing to temporarily stop the server during the certificate issuance process, but this requires additional scripting. The plugin will not automatically stop and restart the other web server. diff --git a/Posh-ACME/Plugins/Windows-Readme.md b/docs/Plugins/Windows.md similarity index 97% rename from Posh-ACME/Plugins/Windows-Readme.md rename to docs/Plugins/Windows.md index 45333d8c..c9af2335 100644 --- a/Posh-ACME/Plugins/Windows-Readme.md +++ b/docs/Plugins/Windows.md @@ -1,10 +1,12 @@ +title: Windows + # How To Use the Windows DNS Plugin This plugin works against the Microsoft Windows DNS server. It doesn't matter whether it's hosted on-premises or in the cloud, physical or virtual, domain joined or standalone. As long as it can be managed via the standard [DnsServer PowerShell module](https://docs.microsoft.com/en-us/powershell/module/dnsserver), it should be supported. This does **not** work against [Azure DNS](https://azure.microsoft.com/en-us/services/dns/). Use the Azure plugin for that. **The DnsServer module is not available on Windows versions prior to Windows 8 and Windows Server 2012. So this plugin will only work on those OSes or newer. Using Zone Scopes requires the Windows 10 or Windows Server 2016 version of the module or newer.** -**This plugin currently does not work on non-Windows OSes in PowerShell Core. [Click here](https://github.com/rmbolger/Posh-ACME/wiki/List-of-Supported-DNS-Providers) for details.** +**This plugin currently does not work on non-Windows OSes in PowerShell Core. On Windows, it requires at least PowerShell 7.** ## Setup diff --git a/Posh-ACME/Plugins/Yandex-Readme.md b/docs/Plugins/Yandex.md similarity index 98% rename from Posh-ACME/Plugins/Yandex-Readme.md rename to docs/Plugins/Yandex.md index 9a491593..18e57ca5 100644 --- a/Posh-ACME/Plugins/Yandex-Readme.md +++ b/docs/Plugins/Yandex.md @@ -1,3 +1,5 @@ +title: Yandex + # How To Use the Yandex DNS Plugin This plugin works against the [Yandex DNS](https://connect.yandex.com) provider. It is assumed that you have already setup an account and delegated and confirmed the domain you will be working against. diff --git a/Posh-ACME/Plugins/Zilore-Readme.md b/docs/Plugins/Zilore.md similarity index 98% rename from Posh-ACME/Plugins/Zilore-Readme.md rename to docs/Plugins/Zilore.md index 9b348d4e..047903b9 100644 --- a/Posh-ACME/Plugins/Zilore-Readme.md +++ b/docs/Plugins/Zilore.md @@ -1,3 +1,5 @@ +title: Zilore + # How To Use the Zilore DNS Plugin This plugin works against the [Zilore](https://zilore.com/?r=1f752c82378516890a5200006eae8469) DNS provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/Posh-ACME/Plugins/Zonomi-Readme.md b/docs/Plugins/Zonomi.md old mode 100755 new mode 100644 similarity index 96% rename from Posh-ACME/Plugins/Zonomi-Readme.md rename to docs/Plugins/Zonomi.md index d5240271..9c46fc13 --- a/Posh-ACME/Plugins/Zonomi-Readme.md +++ b/docs/Plugins/Zonomi.md @@ -1,3 +1,5 @@ +title: Zonomi + # How To Use the Zonomi DNS Plugin This plugin works against the [Zonomi DNS](https://zonomi.com) provider. It is assumed that you have already setup an account and created the DNS zone(s) you will be working against. diff --git a/docs/Plugins/index.md b/docs/Plugins/index.md new file mode 100644 index 00000000..6c6a834d --- /dev/null +++ b/docs/Plugins/index.md @@ -0,0 +1,98 @@ +# Supported Plugins + +## DNS Plugins + +To request support for a particular DNS provider, please submit an [issue](https://github.com/rmbolger/Posh-ACME/issues). Pull requests for new plugins are also welcome and appreciated. See the [plugin development guide](Plugin-Development-Guide.md) for more info. + +If you are running Posh-ACME on PowerShell Core from a non-Windows OS, check the `PS Core Compatible` column to make sure the plugin is supported. Also check the usage guide for non-Windows specific instructions. + +*NOTE: Some of the provider links below are affiliate links which help reduce my out of pocket costs maintaining these plugins. I'd be most grateful if you use them when signing up for new service.* + +### Released + +Plugin | Provider | Guide | PS Core Compatible +------ | -------- | ----- | :----------------: +AcmeDns | [acme-dns](https://github.com/joohoi/acme-dns) | [Usage Guide](AcmeDns.md) | :white_check_mark: +Akamai | [Akamai Edge DNS](https://www.akamai.com/products/edge-dns) | [Usage Guide](Akamai.md) | :white_check_mark: +Aliyun | [Aliyun (Alibaba Cloud)](https://www.alibabacloud.com/product/dns) | [Usage Guide](Aliyun.md) | :white_check_mark: +All-Inkl | [All-Inkl](https://all-inkl.com/) | [Usage Guide](All-Inkl.md) | :white_check_mark: +Aurora | [PCExtreme](https://pcextreme.nl/) | [Usage Guide](Aurora.md) | :white_check_mark: +AutoDNS | [AutoDNS](https://help.internetx.com/x/Qwfj) XML Gateway | [Usage Guide](AutoDNS.md) | :white_check_mark: +Azure | [Microsoft Azure DNS](https://azure.microsoft.com/en-us/services/dns/) | [Usage Guide](Azure.md) | :white_check_mark: +Beget | [Beget.com](https://beget.com) | [Usage Guide](Beget.md) | :white_check_mark: +BlueCat | [BlueCat Address Manager](https://www.bluecatnetworks.com/platform/management/bluecat-address-manager/) | [Usage Guide](BlueCat.md) | :x: +Cloudflare | [Cloudflare DNS](https://www.cloudflare.com/dns) | [Usage Guide](Cloudflare.md) | :white_check_mark: +ClouDNS | [ClouDNS](https://www.cloudns.net/aff/id/224075/) | [Usage Guide](ClouDNS.md) | :white_check_mark: +Constellix | [Constellix](https://constellix.com/) | [Usage Guide](Constellix.md) | :white_check_mark: +DeSEC | [DeSEC DNS](https://desec.io/#!/en/product/dnshosting) | [Usage Guide](DeSEC.md) | :white_check_mark: +DMEasy | [DNS Made Easy](https://dnsmadeeasy.com/) | [Usage Guide](DMEasy.md) | :white_check_mark: +DNSimple | [DNSimple DNS](https://dnsimple.com/r/c9b80a2f227e49) | [Usage Guide](DNSimple.md) | :white_check_mark: +DNSPod | [DNSPod](https://www.dnspod.com/) | [Usage Guide](DNSPod.md) | :white_check_mark: +DOcean | [Digital Ocean](https://m.do.co/c/d515942ef761) | [Usage Guide](DOcean.md) | :white_check_mark: +DomainOffensive | [Domain Offensive](https://do.de) | [Usage Guide](DomainOffensive.md) | :white_check_mark: +Domeneshop | [Domeneshop DNS](https://domene.shop/) | [Usage Guide](Domeneshop.md) | :white_check_mark: +Dreamhost | [Dreamhost DNS](https://www.dreamhost.com/) | [Usage Guide](Dreamhost.md) | :white_check_mark: +DuckDNS | [Duck DNS](https://www.duckdns.org/) | [Usage Guide](DuckDNS.md) | :white_check_mark: +Dynu | [Dynu DNS](https://www.dynu.com) | [Usage Guide](Dynu.md) | :white_check_mark: +EasyDNS | [EasyDNS](https://easydns.com/) | [Usage Guide](EasyDNS.md) | :white_check_mark: +Easyname | [easyname.com](https://www.easyname.com/) | [Usage Guide](Easyname.md) | :white_check_mark: +FreeDNS | [Free DNS](https://freedns.afraid.org) | [Usage Guide](FreeDNS.md) | :white_check_mark: +Gandi | [Gandi LiveDNS](https://www.gandi.net) | [Usage Guide](Gandi.md) | :white_check_mark: +GCloud | [Google Cloud DNS](https://cloud.google.com/dns) | [Usage Guide](GCloud.md) | :white_check_mark: +GoDaddy | [GoDaddy](https://www.godaddy.com) | [Usage Guide](GoDaddy.md) | :white_check_mark: +Hetzner | [Hetzner](https://hetzner.de/) | [Usage Guide](Hetzner.md) | :white_check_mark: +HostingDe | [Hosting.de](https://hosting.de) | [Usage Guide](HostingDe.md) | :white_check_mark: +HurricaneElectric | [Hurricane Electric DNS](https://dns.he.net/) | [Usage Guide](HurricaneElectric.md) | :white_check_mark: +IBMSoftLayer | [IBM Cloud DNS](https://www.ibm.com/cloud/dns) | [Usage Guide](IBMSoftLayer.md) | :white_check_mark: +Infoblox | [Infoblox NIOS](https://www.infoblox.com) | [Usage Guide](Infoblox.md) | :white_check_mark: +Infomaniak | [Infomaniak](https://www.infomaniak.com) | [Usage Guide](Infomaniak.md) | :white_check_mark: +Linode | [Linode DNS](https://www.linode.com/?r=4dfd67cf6f1e384ce626f2943620186344bb2ccf) | [Usage Guide](Linode.md) | :white_check_mark: +Loopia | [LoopiaDNS](https://www.loopia.com/loopiadns/) | [Usage Guide](Loopia.md) | :white_check_mark: +LuaDns | [LuaDns](https://www.luadns.com) | [Usage Guide](LuaDns.md) | :white_check_mark: +Manual | Manual Record Creation | | :white_check_mark: +Namecheap | [Namecheap FreeDNS](https://www.namecheap.com/domains/freedns/) | [Usage Guide](Namecheap.md) | :white_check_mark: +NameCom | [Name.com](https://www.name.com/) | [Usage Guide](NameCom.md) | :white_check_mark: +NS1 | [NS1 DNS](https://ns1.com) | [Usage Guide](NS1.md) | :white_check_mark: +OVH | [OVH.com](https://www.ovh.com) | [Usage Guide](OVH.md) | :white_check_mark: +PointDNS | [PointDNS](https://pointhq.com/) | [Usage Guide](PointDNS.md) | :white_check_mark: +Rackspace | [Rackspace Cloud DNS](https://www.rackspace.com/cloud/dns) | [Usage Guide](Rackspace.md) | :white_check_mark: +Regru | [Reg.ru](https://reg.ru/) and [Reg.com](https://reg.com/) | [Usage Guide](Regru.md) | :white_check_mark: +RFC2136 | [RFC 2136](https://tools.ietf.org/html/rfc2136) | [Usage Guide](RFC2136.md) | :white_check_mark: +Route53 | [AWS Route53](https://aws.amazon.com/route53/) | [Usage Guide](Route53.md) | :white_check_mark: +Selectel | [Selectel.ru](https://selectel.ru/en/services/additional/dns/) | [Usage Guide](Selectel.md) | :white_check_mark: +SimpleDNSPlus | [Simple DNS Plus](https://simpledns.com/) | [Usage Guide](SimpleDNSPlus.md) | :white_check_mark: +Simply | [Simply](https://www.simply.com/) (formerly UnoEuro) | [Usage Guide](Simply.md) | :white_check_mark: +UKFast | [UKFast](https://ukfast.co.uk) | [Usage Guide](UKFast.md) | :white_check_mark: +Windows | [Microsoft Windows DNS](https://www.microsoft.com/en-us/cloud-platform/windows-server) | [Usage Guide](Windows.md) | Windows-Only[1](#windows) +Yandex | [Yandex DNS](https://connect.yandex.com/) | [Usage Guide](Yandex.md) | :white_check_mark: +Zilore| [Zilore](https://zilore.com/?r=1f752c82378516890a5200006eae8469) | [Usage Guide](Zilore.md) | :white_check_mark: +Zonomi | [Zonomi DNS](https://zonomi.com) | [Usage Guide](Zonomi.md) | :white_check_mark: + +### In Development + +These plugins have been committed to the main development branch and are pending inclusion in an official release. + +Plugin | Provider | Guide | Core Compatible +------ | -------- | ----- | --------------- + +### Notes + + - 1: When using the Windows DNS plugin on Windows from PowerShell Core, you must be on PowerShell 7+ to use the DnsServer module via implicit remoting. + +## HTTP Plugins + +HTTP plugins were added in Posh-ACME 4.x. To request support for a particular web server or provider, please submit an [issue](https://github.com/rmbolger/Posh-ACME/issues). Pull requests for new plugins are also welcome and appreciated. See the [plugin development guide](index.md) for more info. + +### Released + +Plugin | Notes | Guide +------ | ----- | ----- +WebRoot | Copies challenge files to a location on the filesystem. | [Usage Guide](WebRoot.md) +WebSelfHost | Runs a self-hosted web server to answer challenge requests | [Usage Guide](WebSelfHost.md) + +### In Development + +These plugins have been committed to the main repo and are pending inclusion in an official release. + +Plugin | Notes | Guide +------ | ----- | ----- diff --git a/Tutorial.md b/docs/Tutorial.md similarity index 57% rename from Tutorial.md rename to docs/Tutorial.md index 0dcf9054..9814794a 100644 --- a/Tutorial.md +++ b/docs/Tutorial.md @@ -1,287 +1,250 @@ -# Posh-ACME Tutorial - -- [Picking a Server](#picking-a-server) -- [Your First Certificate](#your-first-certificate) -- [DNS Plugins](#dns-plugins) -- [Renewals and Deployment](#renewals-and-deployment) -- [Going Into Production](#going-into-production) -- [(Advanced) DNS Challenge Aliases](#advanced-dns-challenge-aliases) - -## Picking a Server - -Before we begin, let's configure our ACME server to be the Let's Encrypt *Staging* server. This will let us figure out all of the commands and parameters without likely running into the production server's [rate limits](https://letsencrypt.org/docs/rate-limits/). - -```powershell -Set-PAServer LE_STAGE -``` - -> **_NOTE:_** `LE_STAGE` is a shortcut for the Let's Encrypt Staging server's directory URL. You could do the same thing by specifying the actual URL which is https://acme-staging-v02.api.letsencrypt.org/directory and this module should work with any ACME compliant directory URL. Other currently supported shortcuts include -> - `LE_PROD` (Let's Encrypt Production) -> - `BUYPASS_PROD` (BuyPass.com Production) -> - `BUYPASS_TEST` (BuyPass.com Testing) -> - `ZEROSSL_PROD` (ZeroSSL.com Production) - -Once you set a server, the module will continue to perform future actions against that server until you change it with another call to `Set-PAServer`. The first time you connect to a server, a link to its Terms of Service will be displayed. You should review it before continuing. - -## Your First Certificate - -The bare minimum you need to request a certificate is just the domain name. - -```powershell -New-PACertificate site1.example.com -``` - -Since you haven't created an ACME account on this server yet, the command will attempt to create one for you using default settings and you'll get an error about having not agreed to the Terms of Service. Assuming you've reviewed the TOS link from before, add `-AcceptTOS` to the original command to proceed. You only need to do this once when creating a new account. You also probably want to associate an email address with this account so you can receive certificate expiration notifications. So let's do that even though it's not required. - -> **_NOTE:_** Multiple email addresses per account are supported. Just pass it an array of addresses. - -```powershell -New-PACertificate site1.example.com -AcceptTOS -Contact 'admin@example.com' -``` - -Because you didn't specify a plugin, it will default to using the `Manual` DNS plugin. That manual plugin will also be prompting you to create a DNS TXT record to answer the ACME server's validation challenge for the domain. - -At this point, you can either press `Ctrl+C` to cancel the process and modify your command or go ahead and create the requested TXT record and hit any key to continue. We'll cover plugins next, so for now create the record manually and press a key to continue. If you run into problems creating the TXT record, check out the [Troubleshooting DNS Challenge Validation](https://github.com/rmbolger/Posh-ACME/wiki/Troubleshooting-DNS-Challenge-Validation) wiki page. - -The command will sleep for 2 minutes by default to allow the DNS changes to propagate. Then if the ACME server is able to properly validate the TXT record, the final certificate files are generated and the command should output the details of your new certificate. Only a subset of the details are displayed by default. To see them all, run `Get-PACertificate | fl`. The files generated in the output folder should contain the following: - -- **cert.cer** (Base64 encoded PEM certificate) -- **cert.key** (Base64 encoded PEM private key) -- **cert.pfx** (PKCS12 container with cert+key) -- **chain.cer** (Base64 encoded PEM with the issuing CA chain) -- **chainX.cer** (Base64 encoded PEM with alternate issuing CA chains) -- **fullchain.cer** (Base64 encoded PEM with cert+chain) -- **fullchain.pfx** (PKCS12 container with cert+key+chain) - -Posh-ACME is only designed to *obtain* certificates, not deploy them to your web server or service. The certificate details are written to the pipeline so you can either save them to a variable or pipe the output to another command. [Posh-ACME.Deploy](https://github.com/rmbolger/Posh-ACME.Deploy) is a sister module containing some example deployment functions for common services to get you started. But ultimately, it's up to you how you want to deploy your certificates. - -The password on the PFX files is `poshacme` because we didn't override the default with `-PfxPass` or `-PfxPassSecure`. If you're running PowerShell with elevated privileges on Windows, you can also add the `-Install` switch to automatically import the certificate into the local computer's certificate store. - -So now you've got a certificate and that's great! But Let's Encrypt certificates expire relatively quickly (90 days). And you won't be able to renew this certificate without going through the manual DNS TXT record hassle again. So let's add a validation plugin to the process. - -## Plugins - -The ACME protocol currently supports three types of challenges to prove you control the domain you're requesting a certificate for: `dns-01`, `http-01`, and `tls-alpn-01`. We are going to focus on `dns-01` because it is the only one that can be used to request wildcard (*.example.com) certificates and the majority of Posh-ACME plugins are for [DNS providers](https://github.com/rmbolger/Posh-ACME/wiki/List-of-Supported-DNS-Providers). - -The ability to use a DNS plugin is going to depend on whether your DNS provider has a supported plugin in the current version of the module. If not, please [submit an issue](https://github.com/rmbolger/Posh-ACME/issues) requesting support. If you have PowerShell development skills, you might also try writing a plugin yourself. Instructions can be found in the [Plugins README](/Posh-ACME/Plugins/README.md). Pull requests for new plugins are both welcome and appreciated. It's also possible to redirect ACME DNS validations using a [CNAME record](https://support.dnsimple.com/articles/cname-record/) in your primary zone pointing to another DNS server that is supported. More on that later. - -The first thing to do is figure out which DNS plugin to use and how to use it. Start by listing the available plugins. - -```powershell -Get-PAPlugin -``` - -Most plugins have a detailed usage guide in the project wiki. In these examples, we'll use the AWS Route53 plugin. Here's a quick shortcut to get to the usage guide. This will open the default browser to the page on Windows and just display the URL on non-Windows. - -```powershell -Get-PAPlugin Route53 -Guide -``` - -> **_NOTE:_** The usage guides are also stored locally with the module in the Plugins folder. They're Markdown formatted and called `-Readme.md`. - -Using a plugin will almost always require creating a hashtable with required plugin parameters. To see a quick reference of the available parameter sets try this: - -```powershell -Get-PAPlugin Route53 -Params -``` - -You should get output that looks like this: - -``` - Set Name: Keys (Default) - -Parameter Type IsMandatory ---------- ---- ----------- -R53AccessKey String True -R53SecretKey SecureString True - - Set Name: KeysInsecure - -Parameter Type IsMandatory ---------- ---- ----------- -R53AccessKey String True -R53SecretKeyInsecure String True - - Set Name: Profile - -Parameter Type IsMandatory ---------- ---- ----------- -R53ProfileName String True - - Set Name: IAMRole - -Parameter Type IsMandatory ---------- ---- ----------- -R53UseIAMRole SwitchParameter True -``` - -We can see there are four different parameter sets we can use: `Keys`, `KeysInsecure`, `Profile`, and `IAMRole`. The `Keys` set requires `R53AccessKey` and `R53SecretKey`. These are API credentials for AWS and presumably as an AWS user, you already know how to generate them. The access key is just a normal String variable. But the secret key is a `SecureString` which takes a bit more effort to setup. So let's create the hashtable we need. - -```powershell -$r53Secret = Read-Host 'Enter Secret' -AsSecureString -$pArgs = @{R53AccessKey='ABCD1234'; R53SecretKey=$r53Secret} -``` - -This `$pArgs` variable is what we'll pass to the `-PluginArgs` parameter on functions that use it. - -Now we know what plugin we're using and we have our plugin arguments in a hashtable. If this is the first time using a particular plugin, it's usually wise to test it before actually trying to use it for a new certificate. So let's do that. The command has no output unless we add the `-Verbose` switch to show what's going on under the hood. - -```powershell -# get a reference to the current account -$acct = Get-PAAccount - -Publish-Challenge site1.example.com -Account $acct -Token faketoken -Plugin Route53 -PluginArgs $pArgs -Verbose -``` - -Assuming there was no error, you should be able to validate that the TXT record was created in the Route53 management console. If so, go ahead and unpublish the record. Otherwise, troubleshoot why it failed and get it working before moving on. - -```powershell -Unpublish-Challenge site1.example.com -Account $acct -Token faketoken -Plugin Route53 -PluginArgs $pArgs -Verbose -``` - -All we have left to do is add the necessary plugin parameters to our original certificate request command. But let's get crazy and change it up a bit by making the cert a wildcard cert with the root domain as a [subject alternative name (SAN)](https://en.wikipedia.org/wiki/Subject_Alternative_Name). - -```powershell -New-PACertificate '*.example.com','example.com' -AcceptTOS -Contact 'admin@example.com' -Plugin Route53 ` - -PluginArgs $pArgs -Verbose -``` - -> **_NOTE:_** According to current Let's Encrypt [rate limits](https://letsencrypt.org/docs/rate-limits/), a single certificate can have up to 100 names. The only caveat is that wildcard certs may not contain any SANs that would overlap with the wildcard entry. So you'll get an error if you try to put `*.example.com` and `site1.example.com` in the same cert. But `*.example.com` and `example.com` or `site1.sub1.example.com` are just fine. - -We included the `-Verbose` switch again so we can see what's going on. But normally, that wouldn't be necessary. Assuming everything went well, you should now have a fresh new wildcard cert that required no user interaction. Keep in mind, HTTP plugins work the exactly the same way as DNS plugins. They just can't be used to validate wildcard names in certs from Let's Encrypt. - -## Renewals and Deployment - -Now that you have a cert order that can successfully answer DNS challenges via a plugin, it's even easier to renew it. - -```powershell -Submit-Renewal -``` - -The module saves all of the parameters associated with an order and re-uses the same values to renew it. It will throw a warning right now because the cert hasn't reached the suggested renewal window. But you can use `-Force` to do it anyway if you want to try it. Let's Encrypt currently caches authorizations for roughly 30 days, so the forced renewal won't need to go through validating the challenges again. But you can de-authorize your existing challenges using the following command if you want to test the validation process again. - -> **_NOTE:_** Be aware that renewals don’t count against your Certificates per Registered Domain limit, but they are subject to a [Duplicate Certificate limit of 5 per week](https://letsencrypt.org/docs/rate-limits/) - -```powershell -# deauthorize the validations associated with the current order -Get-PAOrder | Revoke-PAAuthorization -``` - -If you have multiple orders on an account or even multiple accounts, there are flags to renew all of those as well. - -```powershell -# renew all orders on the current account -Submit-Renewal -AllOrders - -# renew all orders across all accounts in the current profile -Submit-Renewal -AllAccounts - -# The -Force parameter works with these as well. -``` - -Because PowerShell has no native way to run recurring tasks, you'll need to set something up using whatever job scheduling utility your OS provides like Task Scheduler on Windows or cron on Linux. It is suggested to run the job once or twice a day at ideally randomized times. At the very least, try not to run them directly on any hour marks to avoid potential load spikes on the ACME server. Generally, **the task must run as the same user you're currently logged in as** because the Posh-ACME config is stored in your local user profile. However, it's possible to [change the default config location](https://github.com/rmbolger/Posh-ACME/wiki/%28Advanced%29-Using-an-Alternate-Config-Location). - -As mentioned earlier, Posh-ACME doesn't handle certificate deployment. So you'll likely want to create a script to both renew the cert and deploy it to your service/application. All the details you should need to deploy the cert are in the PACertificate object that is returned by `Submit-Renewal`. It's also the same object returned by `New-PACertificate` and `Get-PACertificate`; the latter being useful to test deployment scripts with. - -`Submit-Renewal` will only return PACertificate objects for certs that were actually renewed successfully. So the typical template for a renew/deploy script might look something like this. - -```powershell -Set-PAOrder example.com -if ($cert = Submit-Renewal) { - # do stuff with $cert to deploy it -} -``` - -For a job that is renewing multiple certificates, it might look more like this. - -```powershell -Submit-Renewal -AllOrders | ForEach-Object { - $cert = $_ - if ($cert.MainDomain -eq 'example.com') { - # deploy for example.com - } elseif ($cert.MainDomain -eq 'example.net') { - # deploy for example.com - } else { - # deploy for everything else - } -} -``` - - -### Updating Plugin Parameters on Renewal - -Credentials and Tokens can change over time and some plugins can be used with purposefully short-lived access tokens. In these cases, you can specify the new plugin parameters using the `-PluginArgs` parameter on either `Set-PAOrder` or `Submit-Renewal`. **The full set of plugin arguments must be specified.** - -As an example, consider the case for the Azure DNS plugin: - -```powershell -# renew specifying new plugin arguments -Submit-Renewal -PluginArgs @{AZSubscriptionId='mysubscriptionid';AZAccessToken='myaccesstoken'} -``` - -## Going Into Production - -Now that you've got everything working against the Let's Encrypt staging server, all you have to do is switch over to the production server and re-run your `New-PACertificate` command to get your shiny new publicly trusted certificate. - -```powershell -Set-PAServer LE_PROD - -New-PACertificate '*.example.com','example.com' -AcceptTOS -Contact admin@example.com -Plugin Route53 ` - -PluginArgs $pArgs -Verbose -``` - -## (Advanced) DNS Challenge Aliases - -### Background - -There are two relatively common issues that come up when people try to automate ACME certs using DNS challenges. The first is that the DNS provider hosting the zone either doesn't have an API or the ACME client doesn't have a plugin to support it. The second is that for security reasons, the business may not want to save API credentials for their critical DNS zone on an internet-facing web server. - -The workaround for both of these involves using a [CNAME record](https://support.dnsimple.com/articles/cname-record/) to redirect challenge requests to another DNS zone. When the ACME server goes to validate the challenges, it will follow the CNAME and check the challenge token from the redirected record. If the original problem was no API or no plugin, you'd put the redirected zone on a provider with an API and a supported plugin. If the original problem was security related, you'd make the redirected zone a less important one. The downside is the extra manual step required to add the CNAME for each new cert or name in a cert. But you only have to do that once ever for each name. - -### Creating CNAMEs - -So how do we do that? First, you have to understand how the ACME protocol chooses what record to query for each name in a certificate. Non-wildcard names have `_acme-challenge.` prepended to them. Wildcard names use the same prefix but it replaces the `*.` prefix. So for example: - -Cert Name | Challenge Record ---- | --- -example.com | _acme-challenge.example.com -*.example.com | _acme-challenge.example.com -sub1.example.com | _acme-challenge.sub1.example.com -*.sub1.example.com | _acme-challenge.sub1.example.com -site1.sub1.sub2.example.com | _acme-challenge.site1.sub1.sub2.example.com - -You may have noticed that a wildcard name and a non-wildcard for the same root domain have the same challenge record. That's not a mistake and the ACME server does actually expect to get two different values for the same TXT record. What it means for you though is that you only have one CNAME to create for both types of names. - -Where do you point the CNAMEs to? It doesn't really matter as long as the ACME server can query it from the Internet and Posh-ACME can create the necessary records there. Some choose to use the same `_acme-challenge.` prefix for clarity. Some use a different prefix because their provider doesn't allow names to start with a `_` character. Some just point all of their CNAMEs to the exact same place. Examples: - -Challenge Record | CNAME Target ---- | --- -_acme-challenge.example.com | _acme-challenge.example.net -_acme-challenge.example.com | acme.example.net -_acme-challenge.example.com | _acme-challenge.validation.example.net -_acme-challenge.example.com
_acme-challenge.sub1.example.com
_acme-challenge.sub2.example.com | acme.example.net -_acme-challenge.example.com | example.net - -> **_IMPORTANT:_** Don't point too many CNAMES at the same target. Let's Encrypt's ACME implementation can only deal with DNS responses [up to 4096 bytes](https://github.com/letsencrypt/boulder/pull/3467) which is roughly 60-70 TXT records depending on your DNS server and query parameters. If your record is too big, the validations will fail. - -### Testing - -You should verify your CNAME was created correctly before you try and use it. If you're inside a business with a split-horizon DNS infrastructure, you might need to explicitly query a public external resolver like CloudFlare's 1.1.1.1. However, some modern firewalls can be configured to prevent this ability. So make sure you can successfully query a known-good external record first. There are also web-based resolvers such as https://www.digwebinterface.com/ if necessary. - -``` -C:\>nslookup -q=CNAME _acme-challenge.example.com. 1.1.1.1 -Server: 1dot1dot1dot1.cloudflare-dns.com -Address: 1.1.1.1 - -Non-authoritative answer: -_acme-challenge.example.com canonical name = acme.example.net -``` - -### Using the Challenge Alias - -Now that your CNAMEs are all setup, you just have to add one more parameter to your certificate request command, `-DnsAlias`. It works just like `-Plugin` as an array that should have one element for each domain in the request. But if all of your CNAMEs point to the same place, you can just specify the alias once and it will use that alias for all the names. - -```powershell -New-PACertificate '*.example.com','example.com' -AcceptTOS -Contact admin@example.com -Plugin Route53 ` - -PluginArgs $pArgs -DnsAlias acme.example.net -Verbose -``` +# Tutorial + +## Picking a Server + +Before we begin, let's configure our ACME server to be the Let's Encrypt *Staging* server. This will let us figure out all of the commands and parameters without likely running into the production server's [rate limits](https://letsencrypt.org/docs/rate-limits/). + +```powershell +Set-PAServer LE_STAGE +``` + +!!! note + `LE_STAGE` is a shortcut for the Let's Encrypt Staging server's directory URL. You could do the same thing by specifying the actual URL which is `https://acme-staging-v02.api.letsencrypt.org/directory` and this module should work with any ACME compliant directory URL. Other currently supported shortcuts include `LE_PROD`, `BUYPASS_PROD`, `BUYPASS_TEST`, and `ZEROSSL_PROD`. + +Once you set a server, the module will continue to perform future actions against that server until you change it with another call to `Set-PAServer`. The first time you connect to a server, a link to its Terms of Service will be displayed. You should review it before continuing. + +## Your First Certificate + +The bare minimum you need to request a certificate is just the domain name. + +```powershell +New-PACertificate example.com +``` + +Since you haven't created an ACME account on this server yet, the command will attempt to create one for you using default settings and you'll get an error about having not agreed to the Terms of Service. Assuming you've reviewed the TOS link from before, add `-AcceptTOS` to the original command to proceed. You only need to do this once when creating a new account. You also probably want to associate an email address with this account so you can receive certificate expiration notifications. So let's do that even though it's not required. + +```powershell +New-PACertificate example.com -AcceptTOS -Contact 'admin@example.com' +``` + +!!! note + Multiple email addresses per account are supported. Just pass it an array of addresses. + +Because you didn't specify a plugin, it will default to using the `Manual` DNS plugin. That manual plugin will also be prompting you to create a DNS TXT record to answer the ACME server's validation challenge for the domain. + +At this point, you can either press `Ctrl+C` to cancel the process and modify your command or go ahead and create the requested TXT record and hit any key to continue. We'll cover plugins next, so for now create the record manually and press a key to continue. If you run into problems creating the TXT record, check out [Troubleshooting DNS Validation](Guides/Troubleshooting-DNS-Validation.md). + +The command will sleep for 2 minutes by default to allow the DNS changes to propagate. Then if the ACME server is able to properly validate the TXT record, the final certificate files are generated and the command should output the details of your new certificate. Only a subset of the details are displayed by default. To see them all, run `Get-PACertificate | fl`. The files generated in the output folder should contain the following: + +- **cert.cer** (Base64 encoded PEM certificate) +- **cert.key** (Base64 encoded PEM private key) +- **cert.pfx** (PKCS12 container with cert+key) +- **chain.cer** (Base64 encoded PEM with the issuing CA chain) +- **chainX.cer** (Base64 encoded PEM with alternate issuing CA chains) +- **fullchain.cer** (Base64 encoded PEM with cert+chain) +- **fullchain.pfx** (PKCS12 container with cert+key+chain) + +Posh-ACME is only designed to *obtain* certificates, not deploy them to your web server or service. The certificate details are written to the pipeline so you can either save them to a variable or pipe the output to another command. [Posh-ACME.Deploy](https://github.com/rmbolger/Posh-ACME.Deploy) is a sister module containing some example deployment functions for common services to get you started. But ultimately, it's up to you how you want to deploy your certificates. + +The password on the PFX files is `poshacme` because we didn't override the default with `-PfxPass` or `-PfxPassSecure`. If you're running PowerShell with elevated privileges on Windows, you can also add the `-Install` switch to automatically import the certificate into the local computer's certificate store. + +So now you have a certificate and that's great! But Let's Encrypt certificates expire relatively quickly (90 days). And you won't be able to renew this certificate without going through the manual DNS TXT record hassle again. So let's add a validation plugin to the process. + +## Plugins + +The ACME protocol currently supports three types of challenges to prove you control the domain you're requesting a certificate for: `dns-01`, `http-01`, and `tls-alpn-01`. We are going to focus on `dns-01` because it is the only one that can be used to request wildcard (*.example.com) certificates and the majority of Posh-ACME plugins are for [DNS providers](Plugins/index.md#dns-plugins). + +The ability to use a DNS plugin is going to depend on whether your DNS provider has a supported plugin in the current version of the module. If not, please [submit an issue](https://github.com/rmbolger/Posh-ACME/issues) requesting support. If you have PowerShell development skills, you might also try writing a plugin yourself. Instructions can be found in the [Plugins README](https://github.com/rmbolger/Posh-ACME/blob/main/Posh-ACME/Plugins/README.md). Pull requests for new plugins are both welcome and appreciated. It's also possible to redirect ACME DNS validations using a [CNAME record](https://support.dnsimple.com/articles/cname-record/) in your primary zone pointing to another DNS server that is supported. More on that later. + +The first thing to do is figure out which DNS plugin to use and how to use it. Start by listing the available plugins. + +```powershell +Get-PAPlugin +``` + +Most plugins have a detailed usage guide [here](Plugins/index.md). In these examples, we'll use the AWS Route53 plugin. Here's a quick shortcut to get to the usage guide. This will open the default browser to the page on Windows and just display the URL on non-Windows. + +```powershell +Get-PAPlugin Route53 -Guide +``` + +Using a plugin will almost always require creating a hashtable with required plugin parameters. To see a quick reference of the available parameter sets try this: + +```ps1con +PS> Get-PAPlugin Route53 -Params + + Set Name: Keys (Default) + +Parameter Type IsMandatory +--------- ---- ----------- +R53AccessKey String True +R53SecretKey SecureString True + + Set Name: KeysInsecure + +Parameter Type IsMandatory +--------- ---- ----------- +R53AccessKey String True +R53SecretKeyInsecure String True + + Set Name: Profile + +Parameter Type IsMandatory +--------- ---- ----------- +R53ProfileName String True + + Set Name: IAMRole + +Parameter Type IsMandatory +--------- ---- ----------- +R53UseIAMRole SwitchParameter True +``` + +We can see there are four different parameter sets we can use: `Keys`, `KeysInsecure`, `Profile`, and `IAMRole`. The `Keys` set requires `R53AccessKey` and `R53SecretKey`. These are API credentials for AWS and presumably as an AWS user, you already know how to generate them. The access key is just a normal String variable. But the secret key is a `SecureString` which takes a bit more effort to setup. So let's create the hashtable we need. + +```powershell +$r53Secret = Read-Host 'Enter Secret' -AsSecureString +$pArgs = @{R53AccessKey='ABCD1234'; R53SecretKey=$r53Secret} +``` + +This `$pArgs` variable is what we'll pass to the `-PluginArgs` parameter on functions that use it. + +Now we know what plugin we're using and we have our plugin arguments in a hashtable. If this is the first time using a particular plugin, it's usually wise to test it before actually trying to use it for a new certificate. So let's do that. The command has no output unless we add the `-Verbose` switch to show what's going on under the hood. + +```powershell +# get a reference to the current account +$acct = Get-PAAccount + +Publish-Challenge example.com -Account $acct -Token faketoken -Plugin Route53 -PluginArgs $pArgs -Verbose +``` + +Assuming there was no error, you should be able to validate that the TXT record was created in the Route53 management console. If so, go ahead and unpublish the record. Otherwise, troubleshoot why it failed and get it working before moving on. + +```powershell +Unpublish-Challenge example.com -Account $acct -Token faketoken -Plugin Route53 -PluginArgs $pArgs -Verbose +``` + +All we have left to do is add the necessary plugin parameters to our original certificate request command. But let's get crazy and change it up a bit by making the cert a wildcard cert with the root domain as a [subject alternative name (SAN)](https://en.wikipedia.org/wiki/Subject_Alternative_Name). + +```powershell +New-PACertificate '*.example.com','example.com' -AcceptTOS -Contact 'admin@example.com' -Plugin Route53 ` + -PluginArgs $pArgs -Verbose +``` + +!!! warning + According to current Let's Encrypt [rate limits](https://letsencrypt.org/docs/rate-limits/), a single certificate can have up to 100 names. The only caveat is that wildcard certs may not contain any SANs that would overlap with the wildcard entry. So you'll get an error if you try to put `*.example.com` and `www.example.com` in the same cert. But `*.example.com` and `example.com` or `www.sub.example.com` are just fine. + +We included the `-Verbose` switch again so we can see what's going on. But normally, that wouldn't be necessary. Assuming everything went well, you should now have a fresh new wildcard cert that required no user interaction. Keep in mind, HTTP plugins work the exactly the same way as DNS plugins. They just can't be used to validate wildcard names in certs from Let's Encrypt. + +## Renewals and Deployment + +Now that you have a cert order that can successfully answer DNS challenges via a plugin, it's even easier to renew it. + +```powershell +Submit-Renewal +``` + +!!! note + Be aware that renewals don’t count against your Certificates per Registered Domain limit, but they are subject to a Duplicate Certificate limit of 5 per week. + +The module saves all of the parameters associated with an order and re-uses the same values to renew it. It will throw a warning right now because the cert hasn't reached the suggested renewal window. But you can use `-Force` to do it anyway if you want to try it. Let's Encrypt currently caches authorizations for roughly 30 days, so the forced renewal won't need to go through validating the challenges again. But you can de-authorize your existing challenges using the following command if you want to test the validation process again. + +```powershell +Get-PAOrder | Revoke-PAAuthorization +``` + +If you have multiple orders on an account or even multiple accounts, there are flags to renew all of those as well. + +```powershell +# renew all orders on the current account +Submit-Renewal -AllOrders + +# renew all orders across all accounts in the current profile +Submit-Renewal -AllAccounts +``` + +!!! note + The `-Force` parameter works with these as well. + +### Task Scheduler / Cron + +Because PowerShell has no native way to run recurring tasks, you'll need to set something up using whatever job scheduling utility your OS provides like Task Scheduler on Windows or cron on Linux. It is suggested to run the job once or twice a day at ideally randomized times. At the very least, try not to run them directly on any hour marks to avoid potential load spikes on the ACME server. Generally, **the task must run as the same user you're currently logged in as** because the Posh-ACME config is stored in your local user profile. However, it's possible to [change the default config location](Guides/Using-an-Alternate-Config-Location.md). + +As mentioned earlier, Posh-ACME doesn't handle certificate deployment. So you'll likely want to create a script to both renew the cert and deploy it to your service/application. All the details you should need to deploy the cert are in the PACertificate object that is returned by `Submit-Renewal`. It's also the same object returned by `New-PACertificate` and `Get-PACertificate`; the latter being useful to test deployment scripts with. + +`Submit-Renewal` will only return PACertificate objects for certs that were actually renewed successfully. So the typical template for a renew/deploy script might look something like this. + +```powershell +Set-PAOrder example.com +if ($cert = Submit-Renewal) { + # do stuff with $cert to deploy it +} +``` + +For a job that is renewing multiple certificates, it might look more like this. + +```powershell +Submit-Renewal -AllOrders | ForEach-Object { + $cert = $_ + if ($cert.MainDomain -eq 'example.com') { + # deploy for example.com + } elseif ($cert.MainDomain -eq 'example.net') { + # deploy for example.com + } else { + # deploy for everything else + } +} +``` + +### Updating Plugin Parameters on Renewal + +Credentials and Tokens can change over time and some plugins can be used with purposefully short-lived access tokens. In these cases, you can specify the new plugin parameters using the `-PluginArgs` parameter on either `Set-PAOrder` or `Submit-Renewal`. **The full set of plugin arguments must be specified.** + +As an example, consider the case for the Azure DNS plugin: + +```powershell +# renew specifying new plugin arguments +Submit-Renewal -PluginArgs @{AZSubscriptionId='mysubscriptionid';AZAccessToken='myaccesstoken'} +``` + +## Going Into Production + +Now that you've got everything working against the Let's Encrypt staging server, all you have to do is switch over to the production server and re-run your `New-PACertificate` command to get your shiny new publicly trusted certificate. + +```powershell +Set-PAServer LE_PROD + +New-PACertificate '*.example.com','example.com' -AcceptTOS -Contact 'admin@example.com' ` + -Plugin Route53 -PluginArgs $pArgs -Verbose +``` + +## Modifying Certificate Names + +You may eventually need to add or remove names from your certificate to accommodate changes in the services you're hosting. But certificates can't be modified after they're generated. So you need to request a new certificate with the updated set of names. + +While you could just re-run your `New-PACertificate` command with a modified domain list and all the other original parameters and plugin details, that can be a hassle if it has been a while since you originally setup the certificate and don't remember exactly what you ran. However, all you really need is the modified domain list and the order name. + +Grab the the order details for the order you'll be modifying and create a hashtable for splatting with the `Name` and `Domain` parameters. + +```powershell +$o = Get-PAOrder -Name example.com +$newCertParams = @{ Name = $o.Name; Domain = @($o.MainDomain)+@($o.SANs) } +``` + +Now modify the Domain parameter in the hashtable however you need to. Here are a couple examples. + +```powershell +# add a new name +$newCertParams.Domain += 'blog.example.com' + +# remove an existing name +$newCertParams.Domain = $newCertParams.Domain | ?{ $_ -ne 'oldsite.example.com' } +``` + +Finally, run `New-PACertificate` and splat your updated parameters. + +```powershell +New-PACertificate @newCertParams -Verbose +``` + +The function should pick up all the old parameters from the previous order (finding it via the `Name` parameter) and create a new order/cert that overwrites the old one. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..af2f4123 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,95 @@ +title: Home + +# Posh-ACME + +A [PowerShell](#requirements-and-platform-support) module and [ACME](https://tools.ietf.org/html/rfc8555) client to create publicly trusted SSL/TLS certificates from an ACME capable certificate authority such as [Let's Encrypt](https://letsencrypt.org/). + +## Features + +- Multi-domain (SAN) and wildcard (*.example.com) certificates supported +- IP Address certificates ([RFC 8738](https://tools.ietf.org/html/rfc8738)) *(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](Plugins/index.md) 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)](FAQ.md#does-posh-acme-work-cross-platform-on-powershell-core) +- Account key rollover support +- [OCSP Must-Staple](https://scotthelme.co.uk/ocsp-must-staple/) support +- DNS challenge [CNAME support](Guides/Using-DNS-Challenge-Aliases.md) +- Multiple ACME accounts supported per ACME CA. +- External Account Binding support for ACME CAs that require it +- Preferred Chain support to use alternative CA trust chains + +## Installation (Stable) + +The latest release can found in the [PowerShell Gallery](https://www.powershellgallery.com/packages/Posh-ACME/) or the [GitHub releases page](https://github.com/rmbolger/Posh-ACME/releases). Installing is easiest from the gallery using `Install-Module`. *See [Installing PowerShellGet](https://docs.microsoft.com/en-us/powershell/scripting/gallery/installing-psget) if you run into problems with it.* + +```powershell +# 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 +``` + +!!! warning + 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](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/). + +## Installation (Development) + +[![Pester Tests badge](https://github.com/rmbolger/Posh-ACME/workflows/Pester%20Tests/badge.svg)](https://github.com/rmbolger/Posh-ACME/actions) + +Use the following PowerShell command to install the latest *development* version from the git `main` branch. This method assumes a default [`PSModulePath`](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_psmodulepath) environment variable and installs to the CurrentUser scope. + +```powershell +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. + +```powershell +New-PACertificate example.com -AcceptTOS +``` + +!!! warning + On Windows, you may need to set a less restrictive PowerShell execution policy before you can import the module. + + ```powershell + 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. + +```powershell +$certNames = '*.example.com','example.com' +$email = 'admin@example.com' +$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 -Guide`. There's also a [tutorial](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](https://docs.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell)) on all supported OS platforms. +* Requires `FullLanguage` [language mode](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_language_modes) + +!!! 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](https://github.com/rmbolger/Posh-ACME/blob/main/CHANGELOG.md) diff --git a/gen-maml.ps1 b/gen-maml.ps1 new file mode 100644 index 00000000..162c4dc0 --- /dev/null +++ b/gen-maml.ps1 @@ -0,0 +1,17 @@ +#Requires -Modules platyPS + +[CmdletBinding()] +param() + +# Generate new MAML from the markdown +New-ExternalHelp .\docs\Functions\ -OutputPath .\Posh-ACME\en-US\ -Force | Out-Null + +# Fix the spacing on examples +$maml = Get-Content .\Posh-ACME\en-US\Posh-ACME-help.xml +$maml | ForEach-Object { + # insert a blank paragraph before the end of the example "remarks" + if ($_ -like '*') { + ' ' + } + $_ +} | Out-File .\Posh-ACME\en-US\Posh-ACME-help.xml -Encoding utf8 -Force diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..071b1c20 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,77 @@ +# Project information +site_name: Posh-ACME +site_url: https://poshac.me/docs +site_author: "Ryan Bolger" +site_description: "Documentation for the Posh-ACME PowerShell module" +site_dir: ..\Posh-ACME.docs\docs + +# Repository +repo_name: rmbolger/Posh-ACME +repo_url: https://github.com/rmbolger/Posh-ACME +edit_uri: edit/main/docs/ + +# Copyright +copyright: "Copyright © 2021 Ryan Bolger" + +# Configuration +theme: + # https://squidfunk.github.io/mkdocs-material/ + name: material + + # Don't include MkDocs' JavaScript + include_search_page: false + search_index_only: true + + features: + - navigation.instant + - navigation.tracking + - navigation.tabs + - navigation.sections + - navigation.expand + + icon: + repo: fontawesome/brands/github + + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/weather-sunny + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: blue + accent: blue + toggle: + icon: material/weather-night + name: Switch to light mode + +# Plugins +plugins: + - search + # Using awesome-pages for semi-auto sub-sections until this issue is resolved + # https://github.com/mkdocs/mkdocs/issues/714 + - awesome-pages + +# Customization +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/rmbolger + - icon: fontawesome/brands/twitter + link: https://twitter.com/rmbolger + - icon: fontawesome/brands/linkedin + link: https://linkedin.com/in/rmbolger/ + version: + provider: mike + +# Extensions +markdown_extensions: + - admonition + - pymdownx.highlight + - pymdownx.superfences + - toc: + permalink: true + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg