PowerShell Module Design

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

• TODO: Come up with a better term for the "store"

  • Store
  • Repo/Repository
  • Registry
  • Vault
  • Trove

• 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
  • Subsequent providers may support accessing a centralized storage, such as a SQL or NoSQL data store, either on-prem or in the cloud

• Should we implement a POSH Provider?

  • Allow us to navigate the "store" and its entities:
    • Registration(s)
      • CA Cert(s) (Root, Intermediary)
      • Identifiers
        • Challenges
        • Certificates
          • Revocations

• Future enhancements may include the ability to add a win service or scheduled task that runs and operates on expiring certs, such as sending out reminders or automatically renewing and reinstalling certs

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 0-based sequence number assigned to the entity when it was created or realized in the store; this can also be a negative number to specify an index relative to the end of the entire sequence (-1 => last, -2 => second to last, etc.)
  • 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 ACME server for latest status

• Identifiers/Challenges - create and submit request to authorize an identifier; manage authorization challenges

  • Authorize-ACMEIdentifier
    • -Alias <string> - optional/unique
    • -DNS <dns-name> - required for DNS-based Identifier
  • Get-ACMEIdentifier -Ref <identifier-ref> - gets status of Identifier and associated Challenges
    • -UseBaseURI [switch] - by default uses the URI in the initial request; this overrides to use the base of the store
    • -LocalOnly [switch] - don't call to server, only provide status from local store; without this calls into the associated ACME server for latest status
  • Handling challenges and submitting/responding - provider-based
    • Handle-ACMEChallenge -Ref <identifier-ref> -Challenge <type>
      • -Provider <provider-ref> - overrides the default provider implementation of a challenge handler for the requested challeng type
      • -Args [hashtable] - provider-specific args to handle the Challenge of the store
    • Submit-ACMEChallenges -Ref <identifier-ref>
      • -UseBaseURI [switch] - by default uses the URI in the initial request; this overrides to use the base

• Certificates

  • Request-ACMECertificate -Identifier <identifier-ref> - request a new cert for an authorized Identifier
    • -Csr <csr-details> - either a hashtable or a CsrDetails instance
  • Get-ACMECertificate -Ref <cert-ref>

• Configure/install certs

  • Install-ACMECertificateToIIS -Ref <cert-ref>
    • -ComputerName <target-server> - optional (defaults to local)
    • -Website <website-name> - required
    • -HostHeader <hostheader-name> - optional (defaults to none)
    • -IPAddress <ip-address> - optional (defaults to all)
    • -Port <port-num> - optional (defaults to 443)
  • Install-ACMECertificateToAWS -Ref <cert-ref>
    • -IAMPath <path> - optional, prefix with /cloudfront/ to use with CloudFront
    • -IAMName <path> - required
    • -ELBName <elb-name> - optional to install on ELB
    • -ELBPort <elb-port> - required if elb-name is specified

Misc

External libs/tools/projects that we may borrow or reference:

• (NTSFSecurity POSH Module](https://gallery.technet.microsoft.com/scriptcenter/1abd77a5-9c0b-4a2b-acef-90dbb2b84e85)
• AlphaFS

Proxy Support Implementation:

• CredentialCache
• NetworkCredential
• ICredentials
• WebProxy
• No Proxy
• WebRequest.Proxy