ACME PROVIDED BY TELIA CERTIFICATE SERVICE

General Info on ACME Protocol

ACME (Automatic Certificate Management Environment) is a way to enroll and renew server certificates full automatically defined in Internet standard RFC8555. ACME contains a certificate service run by a Certification Authority and a client software on customer servers. Customer client interacts with CA ACME service when a server certificate is enroll for the first time, renewed or revoked.

ACME Service at Telia

Telia offers ACME service for enrollment of Domain Validated (DV), Organization Validated (OV) and private type certificates. The service is part of a self-service certificate portal called FullSSL. Customer makes an agreement with Telia for certificate self-service. Self-service portal is free of monthly fees. Telia checks customer company and administrator details at service delivery. After checks have been completed, the customer is able to enroll certificates with Secure Manager self-service portal. Created certificates are invoiced during next month. FullSSL service contains also possibility to create certificates with traditional CSR method using manual process at self-service portal.

As with CSR method, when domain prefix www. is used, the certificate will contain a free domain name variant without www. prefix. Example: When a certificate with DNS-name www.company.com is being enrolled, the final certificate will contain DNS-name company.com. This kind of certificate will work when a visitor enters the website with prefix www.company.com or just using plain domain name and TLD company.com.

Authentication is done using an authentication method called Extended Account Binding. This method consists of a customer ID called KID and a key string called HMAC. These credentials are made with Secure Manager self-service portal and when used for the first time, they will create a special key to be used in later authentications.

Client Software

Automated service ACME requires a client software to be installed to manage certificates on the customer server. There are several client software available and they are mostly free software found from services like Github. Best known software are called lego and certbot. You will need to manually configure ACME client software to use Telia Certiticate Service. Lego is recommended to be deployed as a Docker container.

Validation and Certificate Enrollment using ACME

Public certificates require always domain control validation using methods defined by international certificate community. Telia ACME supports two methods:

• Http-challenge



With http-challenge ACME service checks the control of a domain using ACME client software. The client software authenticates with ACME credentials, registers an user account, receives validation data string and sets the validation data to be read by Telia ACME service. ACME client software must be run on a server which has the domain undergoing check configured. Please note that port 80 must be open to Internet and webserver software must be down in order to complete the check. Http-challenge cannot be used with networks which are not accessible from the Internet. Also a manual validation using server's own webserver software is not supported.

An example using lego:

lego -s https://acme.trust.telia.com/directory -m test.address@company.com -a --eab --kid x50y04z3-3d34-429e-00fa-b4c8d04e3471 --hmac ObzSkX2tq3PdSxPuA-iqw6fooPdA2aZRbarER739OPM -d www.acmedemodomain.fi --http

• -s https://acme.trust.telia.com/directory

  Telia ACME service address

• -m test.address@company.com

  Sets ACME contact value to your own email address

• -a

  Accepts automatically ACME terms of service

• --eab

  Uses EAB method for account creation

• --kid x50y04z3-3d34-429e-00fa-b4c8d04e3471

  EAB customer ID, which is known in ACME standard as a KID

• --hmac ObzSkX2tq3PdSxPuA-iqw6fooPdA2aZRbarER739OPM

  EAB key, which is known in ACME standard as a HMAC

• -d www.acmedemodomain.fi

  The domain receiving the certificate

• --http

  Challenge method

• run

  Lego command, which runs a user account registration (in case of the first run) and requests a certificate

• DNS-challenge



With DNS-challenge the validation data is entered into DNS service. ACME reads the data from DNS service and confirms domain control. This method works is most conveniently with DNS services, which support a DNS API supported by ACME client software. Lego supports several DNS services by default. Domains managed by Telia cannot use an API for validation. In cases, where DNS service does not offer an API, it is possible to build an API using Designate DNSaaS for OpenStack software. If API cannot be build using OpenStack, manual process can be used with DNS-challenge.

Example with lego using Amazon Route53 DNS service:

lego -s https://acme.trust.telia.com/directory -m test.address@company.com -a --eab --kid x50y04z3-3d34-429e-00fa-b4c8d04e3471 --hmac ObzSkX2tq3PdSxPuA-iqw6fooPdA2aZRbarER739OPM -d www.acmedemodomain.fi --dns route53 run

• -s https://acme.trust.telia.com/directory

  Telia ACME service address

• -m test.address@company.com

  Sets ACME contact value to your own email address

• -a

  Accepts automatically ACME terms of service

• --eab

  Uses EAB method for account creation

• --kid x50y04z3-3d34-429e-00fa-b4c8d04e3471

  EAB customer ID, which is known in ACME standard as a KID

• --hmac ObzSkX2tq3PdSxPuA-iqw6fooPdA2aZRbarER739OPM

  EAB key, which is known in ACME standard as a HMAC

• -d www.acmedemodomain.fi

  The domain receiving the certificate

• --dns route53

  Challenge method and identifier for DNS service. Plugin using Amazon DNS service fetches credentials either from file ~/.aws/credentials or from a shell environment variable.

• run

  Lego command, which runs a user account registration (in case of the first run) and requests a certificate

An example with lego using manual DNS-challenge:

lego -s https://acme.trust.telia.com/directory -m test.address@company.com -a --eab --kid x50y04z3-3d34-429e-00fa-b4c8d04e3471 --hmac ObzSkX2tq3PdSxPuA-iqw6fooPdA2aZRbarER739OPM -d www.acmedemodomain.fi --dns manual -a run

The command is otherwise similar to DNS API command except DNS service identifier is replaced by 'manual'. In manual method lego presents validation data this way:

[INFO] [acmedemodomain.fi] acme: use dns-01 solver
[INFO] [acmedemodomain.fi] acme: Preparing to solve DNS-01
lego: Please create the following TXT record in your acmedemodomain.fi. zone:
_acme-challenge.acmedemodomain.fi. 120 IN TXT "dry1RBuUONWZ31n9sF-awbcLdognozJbFV284oAI"
lego: Press 'Enter' when you are done

When validation data has been set using DNS service management as a TXT record for your domain, pressing the enter launches DNS validation and ACME returns a certificate to the client.

Other Functions in Client Software

An ACME client software can perform other functions in addition to requesting a new certificate. Lego offers these additional commands:

• revoke - revoke a certificate
• renew - renew a certificate
• dnshelp - list DNS services supported by lego
• list - list certificates found by lego and their info

Installation of a Certificate

Actions needed to install a certificate depend on server type and service run on the server. A certificate saved by ACME client can be installed using scripts or a cron job immediately or as a timed job to an application using the certificate. Root and intermediate certificates are included in the certificate file when using lego.