Library Guide

This guide describes the changes between the v4 and v5 versions of the library.

Context

Most of the functions and methods are now using a context.

Example:

// Before
client.Certificate.Obtain(request)

// After
client.Certificate.Obtain(context.TODO(), request)

Logger

The logger is now slog and can be set using the log.SetDefault(logger) function.

DNS core client

The function dns01.ParseNameservers() is removed.

The function dns01.RecursiveNSsPropagationRequirement() is removed and replaced by dns01.DisableAuthoritativeNssPropagationRequirement().

The function dns01.AddRecursiveNameservers() is removed and replaced by an option dns01.Options.RecursiveNameservers.

opts := &dns01.Options{RecursiveNameservers: []string{"8.8.8.8"}}

dns01.SetDefaultClient(dns01.NewClient(opts))

The function dns01.AddDNSTimeout() is removed and replaced by an option dns01.Options.DNSTimeout.

opts := &dns01.Options{Timeout: 2*time.Second}

dns01.SetDefaultClient(dns01.NewClient(opts))

Method and function changes

The functions and methods related to the private key are now using the crypto.Signer interface instead of the crypto.PrivateKey type.

The following methods now return an *acme.ExtendedAccount instead of an *registration.Ressouce.

• registration.Registrar.Register
• registration.Registrar.RegisterWithExternalAccountBinding
• registration.Registrar.QueryRegistration
• registration.Registrar.UpdateRegistration
• registration.Registrar.ResolveAccountByKey

The structure registration.Ressouce has been removed.

The method http01.ProviderServer.SetProxyHeader() is removed and replaced by an option http01.Options.ProxyHeaderName.

The function dns01.RecursiveNSsPropagationRequirement() is removed and replaced by dns01.DisableAuthoritativeNssPropagationRequirement().

Field changes

The field RetryAfter of acme.RateLimitedError and acme.ExtendedChallenge is now a time.Duration instead of a string.

CertifierOptions

CommonName

The support of the common name is disabled by default.

The field DisableCommonName of certificate.CertifierOptions has been removed.

The option is now determined by the EnableCommonName field of the certificate.ObtainRequest and certificate.ObtainForCSRRequest.

KeyType

The field KeyType of certificate.CertifierOptions has been removed.

The key type is now determined by the KeyType field of the certificate.ObtainRequest.

certcrypto.KeyType

The string values of the certcrypto.KeyType enum have been changed:

Removed elements

The following elements have been removed without replacements:

• selectel.Config.BaseURL
• selectel.EnvBaseURL
• SELECTEL_BASE_URL
• vscale.Config.BaseURL
• vscale.EnvBaseURL
• VSCALE_BASE_URL
• ipv64.Config.SequenceInterval
• netcup.Config.TTL
• netcup.EnvTTL
• vultr.Config.HTTPTimeout

Package changes

The package platform/config/env has been moved to platform/env.

The following packages have been removed:

• platform/tester
• platform/wait

PEM encoding

It uses PKCS#8 instead of PKCS#1 for PEM encoding.

Default resolver/nameserver fallbacks

The default resolver/nameserver fallbacks have been changed.

{{< tabs groupid="migration-examples" >}} {{% tab title="v4" %}}

• google-public-dns-a.google.com:53
• google-public-dns-b.google.com:53

{{% /tab %}} {{% tab title="v5" %}}

• 1.1.1.1:53
• 1.0.0.1:53
• [2606:4700:4700::1111]:53
• [2606:4700:4700::1001]:53

{{% /tab %}} {{< /tabs >}}