URGENT: Domain Validation Changes that Impact Partners

The Certification Authority Browser Forum (CA/Browser Forum), is moving towards a standard set of clearly-defined domain validation processes.

In preparation for these updates, Symantec is making changes to its own domain validation procedures. The changes will apply to DV, OV and EV SSL/TLS certificates and will become effective on March 15th, 2017.

Between now and the middle of March, Symantec will be updating our FILE, DNS and WHOIS authentication methods available throughout SOAP and REST APIs These changes will impact all DV SSL/TLS products across all our brands.

Our EV, OV and Ready Issuance products will also be subject to icy changes. In practice, this will mean that Symantec will no longer support Professional Opinion Letters (POL) and practical demonstrations to approve domain names.

As a partner, you will be required to make the following changes:

  • Modify your SOAP and REST APIs. In particular, you will need to amend your DNS and File Authentication workflows.
  • Test your API updates to support the new domain validation processes in Symantec’s test environment which will be available beginning March 1st, 2017.
  • Ensure your API updates are ready for production on March 15th, 2017.

We will be giving our partners two weeks to test all of the updates to their platforms. As the changes are aimed at supporting industry guidelines and best security practices, it is not possible for us to provide an extension to the dates. To keep pace with the schedule, we recommend that partners start testing the updates when we go live with our test environment on March 1st, 2017.

Please note that there will be no transition period, and starting March 15th, 2017, Symantec will only support the updated API implementations and domain validation processes. The changes are mandatory and failure to implement them risks breaking existing API implementations.

Please check this microsite regularly for any changes to the time line or any new updates.

For technical support please email: apisupport@digicert.com.
API Developer Portal: go.symantec.com/api

Timeline of Changes: See below
What is Changing?: See below
FAQ: See below

Timeline of changes

Symantec will be implementing the changes to support the new domain validation procedures in our test environment on March 1st, 2017 and in our production environment on March 15th, 2017.

What is changing?

Updates to DNS, File and WHOIS Authentication Methods
In accordance with industry guide lines Symantec is making several updates to the way that we authenticate domain validated SSL products via DNS, File and WHOIS authentication methods.

DNS Authentication

  • The record types are changing, the entropy of the secret code is increasing, and the time stamp duration and format is changing. Symantec is increasing our security posture around the approach we take to generating the shared key.

File Authentication

  • The file types are changing, the file entropy is increasing, and the time stamp duration and format is changing. Symantec is increasing our security posture around the approach we take to generating the shared key.

WHOIS Authentication

  • The unique link within the approval email will have increased entropy and a reduced validity time.

What Domain Authentication Policies Are Changing?

EV, OV and Ready Issuance Products

  • Today Symantec makes use of the following domain validation options when the standard methods have not sufficed:
    • Professional Opinion Letters (POL)
    • Practical Demonstration
  • As of March 1st 2017, Symantec will no longer be supporting the above authentication methods.
  • To offset the above changes and to improve efficiency in the EV, OV and Ready Issuance domain authentication process, Symantec is implementing an online domain authorization workflow similar to that of DV, whereby a domain contact (e.g. a WHOIS contact) will follow a link to authorize a domain name’s use in the SSL/TLS certificate in question.
  • Orders that are enrolled before March 1st, where one of the above methods was used and the order is pending issuance, will have to follow an alternative process to authenticate their domain name.
  • Any domains included as part of Ready Issuance orders that were fulfilled using the above domain authentication methods will be invalidated on or after the March 1st 2017.

What Is Changing On The SOAP API?

DNS Authentication – Pre-Shared Key Method

Workflow Updates (SOAP API)

Current Value / Behavior

New Value / Behavior

Record Type

CNAME Record

TXT Record

Secret Code Length

31-32 characters

64 characters

DNS Auth Code Location

s<random string>.domain

Random String in Txt Record

DNS Auth Time Stamp Duration

Time of order submission +/- 24 hours

Order date minus 7 days

DNS Auth Polling Duration

365 days

30 days

Subject Common Name Authentication

DNS Entry Is Required

DNS Entry is Required

SAN Field Authentication

No DNS Entry Required

No DNS Entry Required

Shared Key Generation Process

HMAC with SHA1

HMAC with SHA2

Order, Reissue and Revoke APIS

Code returned in response

Code removed from response

DNS Authentication – Random String Method

Workflow Updates (SOAP API)

Current Value / Behavior

New Value / Behavior

Record Type

CNAME Record

TXT Record

Secret Code Length

31-32 characters

64 characters

DNS Auth Code Location

s<random string>.domain

Random String in Txt Record

DNS Auth Time Stamp Duration

Time of order submission +/- 24 hours

Order date minus 7 days

DNS Auth Polling Duration

365 days

30 days

Subject Common Name Authentication

DNS Entry Is Required

DNS Entry is Required

SAN Field Authentication

No DNS Entry Required

No DNS Entry Required

Shared Key Generation Process

Not Applicable

Not Applicable

Order, Reissue and Revoke APIS

Random string returned in response

No change in current Behavior

File Authentication – Random String Method

Workflow Updates (SOAP API)

Current Value / Behavior

New Value / Behavior

File Type

.html file

.txt file

File Content Length

31-32 characters

64 characters

File Authentication Path

<https:// or http://><domain>/<random file name>.html

<https:// or http://><domain>/.well-known/pki-validation/fileauth.txt

File Authentication Retrieval Logic

1. http://<domain>/<random file name>.html
2. https://<domain>/<random file name>.html

No change in current Behavior

File Auth Polling Duration

365 days

30 days

Subject Common Name Authentication

The file must be placed and retrieved for the
Common Name

No change in current Behavior

SAN Field Authentication

Not Applicable

No change in current Behavior

Shared Key Generation Process

Not Applicable

Not Applicable

Order and Reissue APIS

Random string returned in response

No change in current Behavior

WHOIS Authentication – Random String Method

Workflow Updates

WHOIS Authentication

The entropy within the approval link will increase to 24 characters and the validity period of the approval link will decrease to 30 days.
Any customers that have any pending DV orders where the approval link was not selected and attempt to click on the approval link after the cut over will see the following error:

Expired PIN

Unfortunately, the submitted PIN is expired. Please resend approval email to get the new link. We are sorry for any inconvenience. Please contact GeoTrust Support.

To overcome the error above customers can resend the approval email which will send out a new approval email that meets the requirements above.

Managing the Cutover of Authentication Methods

SOAP API

DNS Auth Shared Key Method

  • There will be no transition from the old authentication workflows to the new authentication workflows.
  • Symantec recommends that partners update their systems to make a double entry and support using both the old logic and new logic for the duration of the cutover.

File Auth and DNS Random String Methods

  • As there will be no transition from the old authentication workflow to the new authentication workflow.
  • Partners will have to submit their orders again after the new authentication method is implemented.
  • Alternatively, switch over to the DNS Shared Key authentication method to minimize disruption to their operations and customers.

WHAT IS CHANGING ON THE REST API?

DNS Authentication – Pre-Shared Key Method

Workflow Updates (REST API)

Current Value / Behavior

New Value / Behavior

Record Type

CNAME Record

TXT Record

Secret Code Length

31-32 characters

64 characters

DNS Auth Secret Code Location

s<random string>.domain

Random String in Txt Record

DNS Auth Time Stamp Format

yyyyMMddHHmmss.<domain name>

yyyyMMddHHmmss

DNS Auth Time Stamp Duration

Order date +/- 7 days

Order date minus 7 days

DNS Auth Pulling Duration

Not Applicable

Not Applicable

Subject Common Name Authentication

DNS entry is Required

No change in current Behavior

SAN Field Authentication

DNS entry is Required

No change in current Behavior

Shared Key Generation Process

HMAC with SHA1

HMAC with SHA2

Order, Reissue and Revoke APIS

Code returned in response

Code removed from response

File Authentication – Pre-Shared Key Method

Workflow Updates (REST API)

Current Value / Behavior

New Value / Behavior

Record Type

.html file

.txt file

Secret Code Length

31-32 characters

64 characters

File Authentication Path

<https:// or http://><domain>/<random file name>.html

<https:// or http://><domain>/.well-known/pki-validation/fileauth.txt

File Authentication Retrieval Logic

1. https://<domain>/<random file name>.html
2. http://<domain>/<random file name>.html

1. https://<domain>/.well-known/pki-validation/fileauth.txt
2. http://<domain>/.well-known/pki-validation.fileauth.txt

File Auth Pulling Duration

Not Applicable

Not Applicable

File Auth Time Stamp Duration

Time of order submission +/- 24 hours

Order date minus 7 days

Subject Common Name Authentication

The file must be placed and retrieved for the Common Name

No change in current Behavior

SAN Field Authentication

The file must be placed and retrieved for the SAN Value

No change in current Behavior

Shared Key Generation Process

HMAC with SHA1

HMAC with SHA2

Order, Reissue and Revoke APIS

Code returned in response

Code removed from response

Managing the Cutover of Authentication Methods

REST API

File Auth and DNS Auth Shared Key Methods

  • There will be no transition from the old authentication workflows to the new authentication workflows.
  • Symantec recommends that partners update their systems to make a double entry and support using both the old logic and new logic for the duration of the cutover.

MANAGING UPDATES FOR THE SHARED KEY METHODS

Across SOAP and REST APIS

  • After the cutover of authentication methods, Symantec will no longer return the code in the order response where a partner is making use of the DNS authentication – Pre-shared key method or File authentication – Pre-shared key method.
  • To determine the secret code a partner can make use of an updated utility available in Java, PHP available through Symantec’s Sales Engineers.

Example cases for different Common Name types

The CAB Forum states that the authentication shall happen on an authorized domain name for the domain for which the certificate is being issued and therefore the authentication will happen in the following locations as per the example below:

  1. CN = *.bar.com then DNS and file authentication will happen on bar.com
  2. CN = foo.bar.com then DNS and file authentication will happen on foo.bar.com
  3. CN = www.foo.bar.com DNS authentication will happen on foo.bar.com, file authentication will happen on www.foo.bar.com

FAQs