APIv2.md

API for ACME v2

This document details the API exposed for handling ACME flows, as of draft-12.

Initialization

Create the context with specific ACME server by providing the directory URI.

var context = new AcmeContext(WellKnownServers.LetsEncryptStagingV2);

Use specific key for existing account or creating new account.

var context = new AcmeContext(
    WellKnownServers.LetsEncryptStagingV2,
    KeyFactory.FromPem("account-key.pem"));

Export the account key for later use.

var pem = context.AccountKey.ToPem();
var der = context.AccountKey.ToDer();

Accounts

Get the url to Terms of Service for user to review.

var tos = context.TermsOfService();

Create new account.

var account = await context.NewAccount(
    new [] { "mailto:admin@example.com", "mailto:it@example.com" }, true);
var account = await context.NewAccount("admin@example.com", true);

// external account binding
var account = await context.NewAccount("admin@example.com", true, "(EAB Key Identifier)","(EAB Key)");
var account = await context.NewAccount("admin@example.com", true, "(EAB Key Identifier)","(EAB Key)","(EAB Key Algorithm e.g.HS256)");

Fetch existing account from server.

var account = await context.Account();

Fetch the account info from server.

var accountInfo = await account.Resource();

Update contacts, or accept Terms of Service again if it's updated.

await account.UpdateUpdate(
    contact: new[] { $"mailto:support@example.com" },
    agreeTermsOfService: true);

Update the account key.

var newKey = KeyFactory.NewKey(KeyAlgorithm.ES256);
await account.ChangeKey(newKey);
 
File.WriteAllText("new-key.pem", newKey.ToPem());

Deactivate account.

await account.Deactivate();

Orders

Apply for certificate issuance.

var order = await context.NewOrder(new [] { "*.example.com" });
var orderUri = order.Location;

Retrieve order by URI.

var order = context.Order(orderUri);

Finalize the order.

var certKey = KeyFactory.NewKey(KeyAlgorithm.RS256);
await orderCtx.Finalize(
    new CsrInfo
    {
        CountryName = "CA",
        State = "State",
        Locality = "City",
        Organization = "Dept",
    }, certKey);

Send customized CSR to finalize the order.

var csr = new CertificationRequestBuilder();
csr.AddName($"C=CA, ST=State, L=City, O=Dept, CN=*.example.com");

await orderCtx.Finalize(csr.Generate());

Download the certificate PEM.

var certChain = await order.Download();

Download the certificate PEM signed with a specific root certificate

var certChain = await order.Download("ISRG X1 Root");

Finalize and download the certificate.

var certKey = KeyFactory.NewKey(KeyAlgorithm.RS256);
var cert = await order.Generate(
    new CsrInfo
    {
        CountryName = "CA",
        State = "State",
        Locality = "City",
        Organization = "Dept",
    }, certKey);

Finalize and download the certificate signed with a specific root certificate.

var certKey = KeyFactory.NewKey(KeyAlgorithm.RS256);
var cert = await order.Generate(
    new CsrInfo
    {
        CountryName = "CA",
        State = "State",
        Locality = "City",
        Organization = "Dept",
    }, certKey, "ISRG X1 Root");

Authorizations

Retrieve authorizations of the order.

var authorizations = await order.Authorizations();

Search authorization by domain name.

var authz = await order.Authorization("*.example.com");
var authzUri = authz.Location;

Retrieve authorization by URI.

var authz = await context.Authorization(authzUri);

Challenges

Retrieve challenges of the authorzation.

var challenges = await authz.Challenges();
var dnsChallenge = await authz.Dns();
var httpChallenge = await authz.Http();
var tlsAlpnChallenge = await authz.TlsAlpn();

Create the respone file for provisioning to /.well-know/acme-challenge/.

var keyAuth = httpChallenge.KeyAuthz;
File.WriteAllText(httpChallenge.Token, keyAuth);

Compute the value for DNS TXT record.

var dnsTxt = context.AccountKey.DnsTxt(challenge.Token);

Generate certificate with X509 ACME validation extension.

var alpnCertKey = KeyFactory.NewKey(KeyAlgorithm.ES256);
var alpnCert = context.AccountKey.TlsAlpnCertificate(challenge.Token, "www.my-domain.com", alpnCertKey);

Let the ACME server to validate the challenge once it is ready.

await challenge.Validate();

Certificates

Download certificate for a pending order.

var cert = await order.Generate(
    new CsrInfo
    {
        CountryName = "CA",
        State = "State",
        Locality = "City",
        Organization = "Dept",
    });

Download the certifcate for a finalized order.

var certChain = await order.Download();

Export the certificate to PEM, DER, or PFX.

var cert = new CertificateInfo(certChain, certKey);

var pem = cert.ToPem();
var der = cert.ToDer();
var pfx = cert.ToPfx("cert-name", "abcd1234");

var keyPem = cert.Key.ToPem();

Revoke certificate with account key.

context.RevokeCertificate(cert.ToDer(), RevocationReason.KeyCompromise);

Revoke certificate with certificate private key.

context.RevokeCertificate(cert.ToDer(), RevocationReason.KeyCompromise, certKey);