Vaults, Vault Providers and Vault Profiles

ACMESharp makes use of a Vault which is a repository to store and manage the state of the ACME protocol and persist various artifacts supporting different ACME operations.

The Vault Provider model allows different implementations of the Vault store to be supported. A Vault Provider can manifest a concrete Vault implementation with specific operational characteristics (such as credentials, file paths or security attributes) by providing parameters to the Provider.

The combination of a specific Vault Provider along with specific Vault Parameters are captured in a Vault Profile. Vault Profiles can be defined on a per-user basis and multiple Profiles can indicate the same Provider with different Vault parameters yielding different Vault instances.

Vault Profiles are managed with the following ACMESharp POSH Module cmdlets:

• Get-ACMEVaultProfile
• Set-ACMEVaultProfile

While a user can define any number of Vault Profiles, two built-in Profiles are implicitly defined and resolve to a well-known set of default parameters (built-in profiles begin with the colon (:) character).

• :sys - the default system-wide Vault Profile which:
  • is based on the local Vault Provider
  • stores its content on disk at the path %ALLUSERSPROFILE%\ACMESharp\sysVault
• :user - the default user-specific Vault Profile which:
  • is based on the local Vault Provider
  • stores its content on disk at the path %LOCALAPPDATA%\ACMESharp\userVault

| Vault Providers, Now and in the Future

| At this time, only a local Vault Provider is defined which stores its repository content as local folders and files. In the future, Vault Providers supporting remote storage, such as cloud storage (e.g. S3, OneDrive, GDrive), SQL databases (e.g. SQLServer, PGSQL, MySQL, NuoDB) or NoSQL databases (e.g. DocumentDB, RavenDB, DynamoDB, Mongo) are planned. | Remote storage Providers will allow supporting a single, centralized Vault to store the ACME assets across multiple domains and across multiple hosts or nodes using those certificates. While this is unnecessary for most simple use-cases, any environment which implements redundancy or scalability will find this a necessity.

Resolving and Referencing Vault Profiles

Every ACMESharp POSH Module cmdlet that operates against a Vault (almost all of them) takes an optional VaultProfile parameter that allows you to override or explicitly specify which Vault Profile is to be used for the execution of the related operation. The value specified here feeds into the Vault Profile name resolution process which is defined as follows:

1. If Vault Profile name is explicitly specified, use that Profile name
2. If a name value is found for the environment variable ACMESHARP_VAULT_PROFILE use that Profile name
3. If the current process is executing with elevated privileges (RunAs Administrator), use the built-in Profile name :sys
4. Otherwise, use the built-in Profile name :user

It is an error if the resolved Profile name results in an invalid or undefined Profile.

In most cases, you can simply leave the Vault Profile unspecified and allow the default resolution rules to resolve to one of the built-in Profiles, but take care to be aware of the different when running as an elevated user (Administrator) versus a normal, non-admin user.