-
Notifications
You must be signed in to change notification settings - Fork 184
PowerShell Module Design
ebekker edited this page Sep 30, 2015
·
14 revisions
This is a place to brainstorm about design and implementation ideas.
- Oriented around a local "store" of information
- Server Directory (endpoint mapping and config)
- Registration details
- Contact Info
- Local copy of ToS
- Identifiers
- Authorization details
- Some sensitive details
- Certs
- CSRs
- Private Keys - sensitive
- Public Certs
- Revocations
- The "store" will use a provider model
- Need to support storing or classifying of sensitive details
- Initial implementation supporting file-based storage
- Using file perms (and maybe EFS?) to store sensitive elements
- In the cmdlets below, for many of the entities that are created or managed, there are multiple instances that can be acted upon. Therefore we typically have to reference a particular instance in which case we can usually support 3 different notations for an entity reference or Ref:
-
GUID - the one true unique identifier for any artifact is its assigned GUID; when specified as a reference, it is prefixed with an equals character (
=
), then immediately followed by a string that can be successfully parsed with the.NET Guid type
- SeqNum - a 1-based sequence number assigned to the entity when it was created or realized in the store
-
Alias - an alias is an optional, alphanumeric alternate identifier that can be assigned to an artifact that must obey the following naming convention regex:
[A-Za-z][A-Za-z0-9_-/+]{0,49}
- 1-50 chars long
- Must start with an alpha (to disambiguate it from a seqnum)
- Can contain any combination of lower/upper/number and a few special chars
-
GUID - the one true unique identifier for any artifact is its assigned GUID; when specified as a reference, it is prefixed with an equals character (
- We also support a few other common attributes of entities
- Label - an optional, friendly display name, let's say 250 chars
- Memo - an optional, free-form field for notes/comments/description, let's assume no limit for now
-
Init-ACMEStore - create and initialize a local store
Init-ACMEStore -Base <base-URI> -Signer <sign-provider> -Label <store-label> -Memo <store-memo>
-
Update-ACMEStore
- supports all the same CLI options as Init
-
Set-ACMEServerDirectory - manage ACME server URI endpoints and related configuration
Set-ACMEServerDirectory -Base <base-URI> -IssuerCert <URI> -ResourceMap @{ Id=Path; Id=Path }
Set-ACMEServerDirectory -Resource <res-id> -Path <res-path>
- Proxy configuration
- By default .NET will utilize the system-configured proxy settings
-
Set-ACMEProxy -UseSystem
- use system-configured proxy settings -
Set-ACMEProxy -UseNoProxy
- sets to use no proxy -
Set-ACMEProxy -UseProxy <proxy-uri>
-
-DefaultCredentials
[switch] -
-Credential <cred>
[pscredential]
-
-
Registration
- We may support multiple registrations per store in the future, so the cmdlets may require an optional registration Ref to operate on, but there is a notion of a default registration (say, the first or only one in the local store) when unspecified
-
New-ACMERegistration
- submit a new registration request-
-Contacts <string[]>
[string[]] - required, one or more contact references (email, phone, etc.) -
-AcceptTOS
[switch] - accept the Terms Of Service and complete the registration -Alias
-Label
-Memo
-
-
Update-ACMERegistration
-
-AcceptTOS
[switch] -
-Contacts <contacts-list>
[string[]] - updates (replaces) contact references -
-UseBaseURI
[switch] - by default uses the Reg URI in the initial request; this overrides to use the base URI configured in the local store
-
-
Get-ACMERegistration
- returns Registration details and status-
-LocalOnly
[switch] - don't call to server, only provide status from local store; without this calls into the associated
-
-
Identifiers/Challenges - create and submit request to authorize an identifier; manage authorization challenges
-
New-ACMEIdentifier
-
-Alias <string>
- optional/unique -
-DNS <dns-name>
- required for DNS-based Identifier
-
- Get-ACMEChallenge - updates the status of an Identifier Authorization Challenge
-
Get-ACMEChallenge
-Ref
-
-UseBaseURI
[switch] - by default uses the URI in the initial request; this overrides to use the base
-
- Handling challenges - provider based
Handle-ACMEChallenge -Ref <identifier-ref> -Challenge <num-or-type>
-
-
Certificates
- New-ACMECertificate
Docs
- Overview
- FAQ
- Let's Encrypt Reference Sheet
- Quick Start
- Requirements
- Basic Concepts
- Vaults, Vault Providers and Vault Profiles
- Challenge Types, Challenge Handlers and Providers
- Troubleshooting
- Contributions
Legacy Docs - out of date
Reference
- Good to Know
- Proposed Extension Mechanism
- PowerShell Module Design
- Style Guides and Conventions
- Documentation Resources
A bit dated