Symantec Website Security Partner Program

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@symantec.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

What does the new process look like on the SOAP API?

Example case: You place an order on 7th March for CN=symantec.com and SAN=ws.symantec.com and choose the DNS Authentication method.

File Auth:
If you are NOT using a shared key for Domain Validation

  • For the file content, our QuickOrder and Reissue APIs return a random value in the following format:
<timestamp><50 character random value>

Example: 20170301123456hzy62enkk40196jxsrs8ykc2zssk206g


For the file name, the API will always return “fileauth.txt”

  • Create a file with the following content:
20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g.

Name the file “fileauth.txt” and place it in the following directory:
http://www.symantec.com /.well-known/pki-validation/fileauth.txt

  • Symantec’s platform checks for the file periodically within the same frequency as before. However, from now on, we will only check for 30 days whether the expected file is present on the web server.
  • The authentication will pass, once Symantec finds the file on the web server.

If you are using a shared key for Domain Validation

  • Our QuickOrder and Reissue API will NOT return the expected file content value.

The partner creates the file content based on the following parameters:

  • Pre-shared-key
  • CSR
  • Current Timestamp

Since the partner places the order on March 7th, the timestamp should be between March 1st and March 7th in yyyyMMddhhmmss format. This check is always done on the Coordinated Universal Time (UTC) timezone.

The code generates the request token in the following format:


<timestamp><50 character random value>

Example: 20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g


  • Create a file with the following content:

20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g.

Name the file “fileauth.txt” and place it in the following directory:
http://www.symantec.com /.well-known/pki-validation/fileauth.txt

  • Symantec’s platform checks for the file periodically within the same frequency as before. However, from now on, we will only check for 30 days whether the expected file is present on the web server.
  • The authentication will pass, once Symantec finds the file on the web server.

DNS Auth:
If you are NOT using a shared key for Domain Validation

  • Our QuickOrder and Reissue APIs return a random value in the following format:
<timestamp><50 character random value>

Example: 20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g

  • Create a DNS TXT record on symantec.com with value 20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g.

Example:
symantec.com.     3595  IN    TXT   "20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g"

  • Symantec’s platform checks for the entry periodically within the same frequency as before. However, from now on, we will only check for 30 days whether the expected value is present on the DNS TXT entry.

If you are using a shared key for Domain Validation

  • Our QuickOrder and Reissue API will NOT return the expected DNS string value.

The partner creates the request token based on the following parameters:

  • Pre-shared-key
  • CSR
  • Current Timestamp

Since the partner places the order on March 7th, the timestamp should be between March 1st and March 7th in yyyyMMddhhmmss format. This check is always done on the Coordinated Universal Time (UTC) timezone.

The code generates the request token in the following format:


<timestamp><50 character random value>

Example: 20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g

  • Create a DNS TXT record on symantec.com with value 20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g.

Example:
symantec.com.     3595  IN    TXT   "20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g"

  • Symantec’s platform checks periodically within the same frequency as before. However, from now on, we will only check for 30 days whether the expected value is present on the DNS TXT entry.
  • The authentication will pass, once the system can find the TXT entry.

What does the new process look like on the REST API?

Example case: You place an order on 7th March for CN=symantec.com and SAN=ws.symantec.com and choose the DNS Authentication method.

File Auth:

  • The partner creates the request token based on the following parameters:
  • Pre-shared-key
  • CSR
  • Current Timestamp
  • Since the partner places the order on March 7th, the timestamp should be between March 1st and March 7th in yyyyMMddhhmmss format. This check is always done on the Coordinated Universal Time (UTC) timezone.

The code generates the request token in the following format:


<timestamp><50 character random value>

Example: 20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g

  • Create a file with the following content:

20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g.


Name the file “fileauth.txt” and place it in the following directory:
http://www.symantec.com /.well-known/pki-validation/fileauth.txt

  • Place an “Enroll” Request
  • If the file can be found, the certificate will be issued instantly. If the file cannot be found, the order will be rejected immediately.

DNS Auth:

  • The partner creates the request token based on the following parameters:
  • Pre-shared-key
  • CSR
  • Current Timestamp
  • Since the partner places the order on March 7th, the timestamp should be between March 1st and March 7th in yyyyMMddhhmmss format. This check is always done on the Coordinated Universal Time (UTC) timezone.

The code generates the request token in the following format:


<timestamp><50 character random value>

Example: 20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g

  • Create a DNS TXT record on symantec.com with value 20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g.

 

Example:
symantec.com. 3595  IN    TXT
"20170301123456hzy62exrfy72mmi35axavz5hnkk40196jxsrs8ykc2zssk206g"

  • Place an “Enroll” Request
  • If the TXT record can be found, the certificate will be issued instantly. If the TXT record cannot be found, the order will be rejected immediately.

What date will Symantec start enforcing the updated domain validation policies?

Symantec will implement the new domain validation procedures on March 1st 2017.

What date will the test environment be available to test the new domain validation procedures?

Symantec will implement the changes in our pre-production (test) environment on March 1st 2017.

How can I determine if I am affected by the new domain validation procedures?

Partners that have implemented API support for Symantec’s DNS and/or File authentication methods to fulfil DV SSL/TLS products, will need to update their API implementation to support the changes.

Partners that offer EV and OV SSL/TLS products, two less-frequently used, but previously allowed domain validation methods will no longer be allowed for OV, EV, and Ready Issuance orders.

Which products are impacted by the updated domain validation procedures?

All EV, OV and DV SSL/TLS products are impacted by the changes. EV and OV products are subject to deprecation of two less-frequently used, but previously allowed domain validation methods,whereas the DV products require updates to the API.

Which order flows are impacted by the updated domain validation procedures?

All brands of DV SSL/TLS products that are validated via Symantec’s DNS or File Authentication methods using our SOAP and REST APIs will require updates to the enrolment, renewal, reissue, revoke and cancel flows.

When will the updated API changes be available?

The updated API changes will be available on March 1st, 2017 in our test (pre-production) environment. Please visit go.Symantec.com/api to get access to the details of the SOAP and REST API updates.

Will I need to reset my key if I use the DNS or File Auth pre-shared key method?

There is no requirement to reset your shared key.

What are the new policies for OV and EV products?

Symantec will no longer support Professional Opinion Letters (POLs) and practical demonstrations for domain validation.

When will the new policies come into effect?

Although the system changes don’t go into effect until later in the month, Symantec’s Customer Support Team is going to stop accepting Professional Opinion Letters (POL) and practical demonstration for domain validation starting March 1st, 2017.

What will happen to my pending orders?

  • Orders that are enrolled before March 15th, 2017, but still not issued as of March 15th will need to comply with the updated domain validation processes. WHOIS/email authentication: Because the approval links are being updated, the partner or end user will need to resend the approval email and proceed with domain approval/rejection as normal. 
  • DNS Authentication with pre-shared key: Partner will need to re-generate the secret code with the new logic and create the DNS entry.  See the API documentation for details.
  • DNS/File Authentication without pre-shared key: Partners will need to switch validation to WHOIS authentication or re-enroll.

Are other Certificate Authorities affected by these changes?

The changes to the domain validation processes represent industry and security best practice and are therefore being implemented by other Certificate Authorities.

Can Symantec support multiple random value entries in both FILE and DNS Authentication?

Yes, Symantec can support multiple random value entries in both FILE and DNS authentication.

One fileauth.txt file can have multiple random values for different orders and the file authentication will pass for those orders that the corresponding random value.