FAQ

In addition to the list of questions below, you may also want to check the tickets marked as FAQ which include common issues or questions that have not yet been curated and added to the official FAQ.

• What is ACMESharp? ACMESharp is a project to provide (1) a .NET library implementation for the ACME protocol and (2) a set of tools in the form of a PowerShell module that use that library to manage certificate requests and issuance.

• What is ACME? ACME is the protocol spearheaded by the Let's Encrypt project, and submitted to the IETF for standardization which defines an automated process for requesting PKI certificates and all the related operations needed to support that function.

• What is Let's Encrypt? Let's Encrypt is a project to establish a trusted Certificate Authority (CA) which can be used to issue free PKI certificates for securing access to web sites.

• What are the limits and limitations of the Let's Encrypt CA? We have compiled a short reference sheet specific to the Let's Encrypt CA service which also includes links to more detailed official material: Let's Encrypt Reference Sheet

• What is a domain-validated (DV) certificate? A domain-validated certificate is a PKI certificate where the ownership of the DNS name on the certificate has been verified by the issuing part (i.e. the Certificate Authority (CA)). It is just one of several standard types of certificates, such as organization-validated (OV) and extended validation (EV) certificates. DV certificates are the only ones supported by the Let's Encrypt project because they are the only ones that can be easily automated and made cost-effective for free issuance on a grand scale.

• Is ACMESharp FIPS-compliant? ACMESharp relies on a combination of the underlying Windows and .NET crypto services, and externalized crypto functions of various providers, by default the OpenSSL port to Windows. These providers can be configured to require the use of FIPS-compliant primitives or can be swapped out with providers that guarantee FIPS-compliance. See this comment and this issue for more details.

• What are the crypto functions in use by ACMESharp? The crypto primitives used in ACMESharp can be split between those supporting the ACME protocol itself, namely support of JWS, and those that are used in support of certificate operations, such as private key and CSR generation. They are isolated in a few base classes with various provider derivatives as described in this comment.

• On PowerShell v5+ I get an error like 'override the existing command' when trying to install or load the ACMESharp module! You may encounter an error that says "A command with name 'Get-Certificate' is already available on this system. This module 'ACMESharp' may override the existing commands. If you still want to install this module 'ACMESharp', use -AllowClobber parameter." See this article for an explanation and solution for this issue. Also, see this issue and this issue for details of how this is encountered.

• How do I use my own custom CSR, with my org and other certificate information? The cmdlet that's used to start a new certificate request (New-ACMESharp) can be used to either generate all the required initial assets or can import existing ones that you have generated outside of ACMESharp (i.e. using OpenSSL, Windows CA, Java Keystore, Bouncy Castle, etc.). There are two assets that are required, a private key file (for example for RSA-based certificate, you would need an RSA private key) and a Certificate Signing Request (CSR). Both of these need to be available in the PEM-encoding format and then you would provide these using the cmdlet parameters -KeyPemFile and -CsrPemFile respectively. See this issue for more details.

• My email client on iOS 9 is complaining about the server identity! This could be a mis-configuration of the DNS records and/or a missing SAN record in the generated cert. See this issue for more details.

• Error resolving type specified in JSON Some users have discovered that the Newtonsoft.Json library upon which ACMESharp depends has been installed into the system GAC, and this breaks the dependency resolution when do serialization and parsing of JSON streams. See this issue for more details.

• How do I do renewals? Official support for renewals has not yet been implemented (i.e. via the renewal support of the underlying ACME protocol). However a workable kludge is to simply request a new certificate using the existing Validated Identifier (i.e. the same DNS name that you have already proven that you are the owner of). Once a DNS Identifier is verified, the verification is valid for a little over a year (after that time, you'll need to re-verify your ownership). Simply, create a new Certificate Request and reference the same Identifier as before. See this issue for more details. Update: due to the recent changes in Authorization process - this kludge is no longer working (see few last comments on issue 167 ). Domain authorization expires after 60 day and default domain certificate expiration is 90 days.

• I get an exception when I try to create an alias that starts with a number! This is by design in order to distinguish an alias for some entity (e.g. Identifier, Certificate, Vault Profile, etc.) from a sequence number whenever a an entity reference is used. A reference can be specified as a sequence, a GUID or an optional alias. See this description or this issue for more details.

• I get an UnauthorizedAccessException! If you get an access exception or an error that says that you cannot write to a part of the Vault's local directory structure, such as C:\ProgramData\ACMESharp\sysVault\45-KEYPM, first make sure that you're running as an elevated user (admin) who has permission to write to this path. If so, then make sure your environment supports the use of EFS. The local Vault uses EFS to write sensitive file assets. You can read more about this issue here.