Skip to content

PowerShell Module Design

ebekker edited this page Sep 30, 2015 · 14 revisions

This is a place to brainstorm about design and implementation ideas.

General 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

POSH Module

General

  • 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
  • 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

Local Store Management and Configuration

  • 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]

ACME Actions

  • 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

Misc

Proxy Support Implementation:

Clone this wiki locally